Relay Spec

This page proposes a TOML format for relay token lifetimes, visitor sessions and resource limits. Not built yet: the relay reads no spec file, and today's limits are code constants except domains_per_user, supplied with --domains-per-user.

Every option

Every key is optional. A relay's spec holds opinions, not grants, so a key left out is Link's, the value shown, and an empty file is the relay Local Link runs.

# relay.toml

# The spec itself: a name and a number, yours.
name = "local-link"
version = 1

# Access tokens the relay takes from the account service it trusts.
[tokens]
max_life = "15 min"        # the longest a token may last, from its making to its end

# Visitors let in to tunnels that let in only some accounts.
[visitors]
pass_life = "1 day"        # how long a visitor's sign-in lasts at a tunnel
per_tunnel = 100           # accounts and emails one tunnel's list may name

# Each user's tunnels.
[tunnels]
per_user = 10              # open at once, from all their machines; standbys waiting aren't counted
domains_per_user = 1       # domains of their own a user may serve tunnels at; 0 turns them off
certificates_per_day = 7   # new tunnel hosts given a certificate, per user

# Requests to one user's tunnels, from anyone.
[requests]
per_second = 50            # sustained
burst = 200                # at once, as a page with many files loads
in_flight = 256            # waiting for an answer at once
visitor_share = 0.25       # one visitor's part of each, so one can't use up a user's

# Each user's share links.
[shares]
per_user = 100             # live at once
max_life = "7 days"        # the longest one may last; at most 7 days, S3's longest

Flags and the file

Each key is a flag of link-relay, and a flag wins over the file. A file is at most 64 KB. An unknown key, an empty table, or a value that isn't one is refused when the file is read, the error naming its line.

Values

A time is a string with its unit, as "15 min", "1 hour", "1 day" or "7 days"; a bare number is refused. A count is a whole number, and a rate or a share a number.

Top level

The spec's own name and number, which are yours and none by default.

name and version

The name is lowercase letters, digits and dashes, starting with a letter (--spec-name), and the version a whole number (--spec-version).

[tokens]

The access tokens the relay takes from the account service it trusts.

max_life

A time, from 1 minute to 1 hour, 15 minutes unless set (--tokens-max-life). The relay refuses an access token whose end is further than this from its making, or from now (The access token). The account service decides how long it makes them, and Local Link's makes them for 5 minutes; this is the longest the relay takes from any service it trusts.

[visitors]

The visitors let in to tunnels that let in only some accounts.

pass_life

A time, from 1 minute to 30 days, 1 day unless set (--pass-life): how long a visitor's pass lasts before they sign in again. The relay checks the tunnel's list at every request whatever this says.

per_tunnel

A whole number, at least 1, 100 unless set (--visitors-per-tunnel). A tunnel's list (lnk tunnel open --account) names at most this many accounts and emails, and a longer one is refused when the tunnel connects.

[tunnels]

Each user's tunnels, from all their machines.

per_user

A whole number, at least 1, 10 unless set (--tunnels-per-user): the tunnels open at once, from all their machines; standbys waiting aren't counted.

domains_per_user

A whole number, 1 unless set (--domains-per-user): the domains of their own a user may serve tunnels at; 0 turns them off.

certificates_per_day

A whole number, at least 1, 7 unless set (--certificates-per-day): the new tunnel hosts given a certificate, per user, a day.

[requests]

Requests to one user's tunnels, from anyone. Two buckets apply to each request: the visitor's, checked first, at visitor_share of each of the user's, then the user's across all their tunnels. Over the rate is 429; over in_flight is 503 (Limits).

per_second and burst

The sustained rate, a number over 0, 50 unless set (--requests-per-second), and how many at once, a whole number, at least 1, 200 unless set (--request-burst), as a page with many files loads.

in_flight

A whole number, at least 1, 256 unless set (--requests-in-flight): the requests waiting for an answer at once.

visitor_share

A number over 0, at most 1, 0.25 unless set (--visitor-share): one visitor's part of each, so one can't use up a user's.

[shares]

Each user's share links.

per_user

A whole number, at least 1, 100 unless set (--shares-per-user): the share links live at once.

max_life

A time, from 1 minute to 7 days, 7 days unless set (--shares-max-life): the longest one may last, at most 7 days, S3's longest.

What isn't in it

What a relay's spec never holds, and where each lives instead. Why it works this way: Decisions.

Where it is and whom it trusts

Its domain, its account service and that service's keys, its users file and its state folder are link-relay's flags (Configuration), never a spec's, so a spec can be handed to another operator.

Secrets and decisions

A spec holds no secrets (its secrets). What anyone with the facts would choose is a constant in the code, not a key: the size of a protocol message, flow control's windows, how long the relay waits for a slow request's headers, and the budgets that keep one party's buffers from filling the relay's memory (Limits).