Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve "welcome" message #6

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Improve "welcome" message #6

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bd5ae8b
Server protocol: Improvements on `welcome` message
piegamesde May 7, 2021
5b50b36
Server protocol: Advertize relay servers in welcome message
piegamesde Jul 27, 2021
ea4ca2f
Be a lot more specific on the fields' format
piegamesde Jul 28, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 30 additions & 9 deletions server-protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,19 +72,40 @@ messages. Clients must ignore unrecognized message types from the Server.

The first thing the server sends to each client is the `welcome` message.
This is intended to deliver important status information to the client that
might influence its operation. The Python client currently reacts to the
following keys (and ignores all others):
might influence its operation. Clients should look out for the following fields,
and handle them accordingly, if present:

* `current_cli_version`: prompts the user to upgrade if the server's
* `current_cli_version`: *(deprecated)* prompts the user to upgrade if the server's
advertised version is greater than the client's version (as derived from
the git tag)
* `motd`: prints this message, if present; intended to inform users about
* `motd`: This message is intended to inform users about
performance problems, scheduled downtime, or to beg for donations to keep
the server running
* `error`: causes the client to print the message and then terminate. If a
future version of the protocol requires a rate-limiting CAPTCHA ticket or
other authorization record, the server can send `error` (explaining the
requirement) if it does not see this ticket arrive before the `bind`.
the server running. Clients should print it or otherwise display prominently
to the user. The value *should* be a plain string.
* `error`: The client should show this message to the user and then terminate.
The value *should* be a plain string.
* `relays`: An advertizement list of relay servers. It is a JSON list of which each
entry may look like this:
```json
{
"url": "tcp://myrelay.example.org:12345/",
"country": "IT",
"continent": "EU",
}
```
* The only mandatory key is `url`, all others are optional information to help the client
choose an appropriate one.
* Clients must not expect the protocol to be `tcp` (expect websockets support in the future).
* A `tcp`-schemed URL only has the `scheme` and `authority` part (`path` is empty, no `query`
and `fragment`), and the `authority` part only has `host` and `port` (no `userinfo`). There is
no default port number. Thus, it looks like `tcp://host:port/`, nothing more.
* `country` and `continent` are two-letter capitalized country/continent codes following ISO 3166.
* Further keys may be added in the future.

Clients should make a preselection of viable relay servers (which may include entries from other
sources as well), and randomly select one or two (together with the other side's, this
makes up to four, which should be enough to have a high probability of at least one being
reachable).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How do the two sides determine which relay to use?

Not necessarily to derail this further, but it might not be best to encode the protocol into the URL; the current transit-relay implementation does support both TCP and WebSockets (for example) and can inter-operate. So a client with only websocket support can contact a client with only tcp support so long as they use the same relay.

Perhaps this implies something like this:

    {
        "host": "example.com",
        "port": 4321,
        "transports": ["tcp", "ws", "wss", "tls"]
    }

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe the "transports" wants to be a list of two-tuples, like [ ["tcp", 4321], ["wss", 443] ] and get rid of the "port"?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How do the two sides determine which relay to use?

This is specified in the application layer protocol. For transfer, the sender side decides, for symmetric applications the higher side value chooses.

I think clients need not know which relay endpoints are connected together beforehand, they will find out anyways during the transit connection setup. Thus, simply adding one server entry for each supported protocol should do. But if you want, I can make the url field a list of strings instead, so at least they are grouped.

Copy link
Member

@meejah meejah Aug 10, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here's a concrete example: if there's a Web based client and a Python client, the Web one will only ever choose a "wss://" relay. The Python one will only ever choose a "tcp://" one. But if they're using the same relay (i.e. same host) that's fine, and they can communicate (one via WebSockets and one via TCP).

So if they indicated their choice via URL they will never inter-op. But if they say "use the server at relay.wormhole.io" and it happens to support wss and tcp, then they can talk...

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The problem is that there is not "the server at example.com". WebSockets endpoints are arbitrary HTTP paths, only TCP is the exception there (it really only has a port). I don't remember how I thought this ought to work with my proposal, but by your example it clearly doesn't.

We could indeed make urls a list or dict of connected endpoints of that server. An alternative would be to craft a new custom URL scheme that encodes all relevant information for all supported schemes of the server.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, yeah. Maybe what we really want is some meta-information about the server (arbitrary name, maybe more), and a transports: [ ... ] list consisting of dicts describing the transport. Something like:

{
    "type": "tcp",
    "host": "example.com",
    "port": 1234
}

or

{
    "type": "websocket",
    "url": "wss://example.com:4321/"
}

Thus, clients select "a transit relay" which has some collection of "transports" / ways to connect (at least 1). This allows clients with distinct support for transports to still connect (given that the transit relay supports that). This could also support multi-homed hosts that e.g. have multiple public IP addresses (or hostnames) that can be contacted. It would also nicely allow Tor and/or I2P support (from one or both sides). (Of course, one "pro" of tor/i2p is that you don't need a transit-relay in those cases, but only if both sides support and choose Tor .. which they might not).

(Also: I'm offline until Friday starting shortly so will probably be silent on this until then ...)

* `permission-required`: a set of available authentication methods,
proof of work challenges etc. The client needs to "solve" one of
them in order to get access to the service.
Expand Down