open.source/magic-wormhole
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update API docs

Browse Source
This commit is contained in:
Brian Warner 2015-03-25 17:02:57 -07:00
parent 0217a13da6
commit beb9e240d4
1 changed files with 25 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
docs/api.md
View File

@ -1,4 +1,4 @@
# wormhole-sync # Magic-Wormhole
This library provides a primitive function to securely transfer small amounts This library provides a primitive function to securely transfer small amounts
of data between two computers. Both machines must be connected to the of data between two computers. Both machines must be connected to the
@ -29,25 +29,30 @@ The synchronous+blocking flow looks like this:
```python ```python
from wormhole.transcribe import Initiator from wormhole.transcribe import Initiator
data = b"initiator's data" from wormhole.public_relay import RENDEZVOUS_RELAY
i = Initiator("appid", data) mydata = b"initiator's data"
i = Initiator("appid", RENDEZVOUS_RELAY)
code = i.get_code() code = i.get_code()
print("Invitation Code: %s" % code) print("Invitation Code: %s" % code)
theirdata = i.get_data() theirdata = i.get_data(mydata)
print("Their data: %s" % theirdata.decode("ascii")) print("Their data: %s" % theirdata.decode("ascii"))
``` ```
```python ```python
import sys import sys
from wormhole.transcribe import Receiver from wormhole.transcribe import Receiver
data = b"receiver's data" from wormhole.public_relay import RENDEZVOUS_RELAY
mydata = b"receiver's data"
code = sys.argv[1] code = sys.argv[1]
r = Receiver("appid", code, data) r = Receiver("appid", RENDEZVOUS_RELAY)
theirdata = r.get_data() r.set_code(code)
theirdata = r.get_data(mydata)
print("Their data: %s" % theirdata.decode("ascii")) print("Their data: %s" % theirdata.decode("ascii"))
``` ```
The Twisted-friendly flow looks like this: ## Twisted (TODO)
The Twisted-friendly flow, which is not yet implemented, may look like this:
```python ```python
from twisted.internet import reactor from twisted.internet import reactor
@ -80,7 +85,7 @@ reactor.run()
## Application Identifier ## Application Identifier
Applications using this library should provide an "application identifier", a Applications using this library must provide an "application identifier", a
simple bytestring that distinguishes one application from another. To ensure simple bytestring that distinguishes one application from another. To ensure
uniqueness, use a domain name. To use multiple apps for a single domain, just uniqueness, use a domain name. To use multiple apps for a single domain, just
use a string like `example.com/app1`. This string must be the same on both use a string like `example.com/app1`. This string must be the same on both
@ -92,13 +97,18 @@ ten initiators are active for a given app-id, the connection-id will only
need to contain a single digit, even if some other app-id is currently using need to contain a single digit, even if some other app-id is currently using
thousands of concurrent sessions. thousands of concurrent sessions.
## Custom Rendezvous Server ## Rendezvous Relays
The library uses a baked-in rendezvous server hostname. This must be the same The library depends upon a "rendezvous relay", which is a server (with a
for both clients. To use a different hostname provide it as the `rendezvous=` public IP address) that delivers small encrypted messages from one client to
argument to the `Initiator`/`Receiver` constructor. the other. This must be the same for both clients, and is generally baked-in
to the application source code or default config.
## Polling and Shutdown This library includes the URL of a public relay run by the author.
Application developers can use this one, or they can run their own (see
src/wormhole/servers/relay.py) and configure their clients to use it instead.
## Polling and Shutdown (TODO)
The reactor-based (Twisted-style) forms of these objects need to establish The reactor-based (Twisted-style) forms of these objects need to establish
TCP connections, re-establish them if they are lost, and sometimes (for TCP connections, re-establish them if they are lost, and sometimes (for
@ -125,7 +135,7 @@ sync will be abandoned, and all callbacks will errback with a TimeoutError.
Both have defaults suitable for face-to-face realtime setup environments. Both have defaults suitable for face-to-face realtime setup environments.
## Serialization ## Serialization (TODO)
You may not be able to hold the Initiator/Receiver object in memory for the You may not be able to hold the Initiator/Receiver object in memory for the
whole sync process: maybe you allow it to wait for several days, but the whole sync process: maybe you allow it to wait for several days, but the