Core and Features

How the relay server is built: a core that names no feature, and each feature behind one of two interfaces, so one can be added or deleted on its own.

The core

The core takes agents' connections, checks their tokens, names each connection's tunnel, routes each request to a connection, and applies flow control and limits. It knows a connection's tunnel by its address, <app>.<user>, and asks the registered features everything else: which connection a request goes to, and what a visitor must pass first. Share links are still the core's own, beside it.

Naming schemes

A naming scheme says how a request's host and path pick a connection, and what names a connection may claim. It answers the requests that are its own, tells the relay which hosts it serves now for certificates, and reads a connection's Hello for its tunnel's name, how many one user holds and where each is served. A scheme may also refuse an account outright, or count totals for the relay's measures.

The schemes

The relay registers four, each a module in src/schemes/.

  • Tunnel hosts (hosts): <app>.<user>.<domain>, a name the agent asks for or a random one.
  • Custom domains (domains): a user's own domain, proven by a TXT record, served by the tunnel that asked for it with --domain.
  • Machines by ID (machines): /_link/machines/<id>/<path>, a machine signed in to its owner's account.
  • The webhooks tunnel (webhooks): /h/<path>, the one tunnel of the one owner the relay's settings name.

Visitor checks

A visitor check says what a request must pass before it reaches its connection. When an agent connects, each check reads the tunnel options in its Hello and gives the connection a gate if it asked for one. Each request then passes the connection's gates in turn, and the core runs them without naming any. A check may also answer pages of its own, and names its cookies, which never reach an app and which no app may set.

The checks

The relay registers three, each a module in src/checks/.

  • Sign-in (signin): --account, visitors who sign in with the account service first.
  • Password (password): --auth, a password every visitor presents, its wrong guesses limited.
  • Warning page (warning): a page saying whose computer a browser is about to reach, for tunnels of open-signup accounts.

Registration

The relay's role is the set of schemes and checks it serves, and src/features.rs is the one place that names them. A tunnels relay serves tunnel hosts and custom domains with all three checks, a remote relay serves machines by ID, and a hooks relay the webhooks tunnel. A Hello option that no registered scheme or check takes is refused.

The delete test

Deleting any one feature deletes its module and its registration, and nothing else in the relay breaks or goes dead. A feature's registration is its mod line in schemes.rs or checks.rs, its lines in features.rs, its pub use in lib.rs, and its settings. Two parts stay outside it: the tunnel options Hello carries, which the protocol names, and share links.