diff --git a/dart/moq/lib/socket.dart b/dart/moq/lib/socket.dart index b815734f4da..366c43d69f2 100644 --- a/dart/moq/lib/socket.dart +++ b/dart/moq/lib/socket.dart @@ -3,7 +3,8 @@ library; import 'package:moq_ffi/moq_ffi.dart'; -/// Announces one hidden endpoint and dials or accepts sessions. +/// A server, a client, or both: its first dial announces it as a client, and its +/// first accept as a server. typedef Endpoint = MoqSocketEndpoint; /// An incoming TCP dial, consumed by accepting or rejecting it. diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 0e3d8f638e7..d8389f01404 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -24754,13 +24754,13 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqsocketendpoint_accept_track() != 3641) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqsocketendpoint_close() != 33296) { + if (uniffi_moq_ffi_checksum_method_moqsocketendpoint_close() != 18581) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqsocketendpoint_dial_tcp() != 61959) { + if (uniffi_moq_ffi_checksum_method_moqsocketendpoint_dial_tcp() != 44736) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqsocketendpoint_dial_track() != 5972) { + if (uniffi_moq_ffi_checksum_method_moqsocketendpoint_dial_track() != 54786) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqsocketendpoint_id() != 2699) { @@ -24965,7 +24965,7 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_constructor_moqclient_new() != 48355) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_constructor_moqsocketendpoint_new() != 7442) { + if (uniffi_moq_ffi_checksum_constructor_moqsocketendpoint_new() != 25288) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_constructor_moqvideoconsumer_subscribe() != diff --git a/demo/carla/README.md b/demo/carla/README.md index 9445197e29c..619a2a2af50 100644 --- a/demo/carla/README.md +++ b/demo/carla/README.md @@ -53,12 +53,12 @@ carla/{truck}/{camera}.hang <- one media broadcast per camera (hang catalo hd 720p H.264, for the focused view status JSON Snapshot telemetry -carla/.socket/{truck} <- the truck's socket endpoint, which drivers dial -carla/.socket/driver-{id} <- one endpoint per driver lease +carla/.server/{truck} <- the truck's server socket endpoint, which drivers dial +carla/.client/{id} <- one client endpoint per driver lease ``` -Each truck accepts `track` sessions on its endpoint. A driver dials from an -endpoint of its own, one session per lease, and sends one control per message; +Each truck accepts `track` sessions on its server endpoint. A driver dials from +a client endpoint of its own, one session per lease, and sends one control per message; the truck answers each control it accepted from the lease holder on the same session. Cameras are sibling broadcasts, so switching views never creates a second claim on the same wheel. @@ -150,16 +150,16 @@ The worker's gate (`sim/moq_carla_sim/drive.py`) owns every truck's controls: returns to a free spawn point under autonomy, its e-stop cleared. The lease is cooperative. Anonymous drivers share one grant to publish -`carla/.socket/driver-*`, so an endpoint id is all it takes to announce in a -driver's place and win the relay's route to its next dial. Each driver's id is +`carla/.client/*`, so an endpoint id is all it takes to announce in a driver's +place and win the relay's route to its next session. Each driver's id is therefore 128 random bits, and `status` names the holder and the e-stop's sender by a handle instead: `driver-` and 8 hex digits of the SHA-256 of the session's secret id, which the driver derives the same way to recognize its -own lease. Truck names must not look like driver ids, or the same grant would -let anyone impersonate a truck; the worker refuses one. Anyone may still claim -a free truck or press its e-stop, so the lease stops two honest drivers -fighting over a truck, not a deliberate disruption. Anything beyond a simulator -needs per-driver tokens scoped to the driver's own endpoint. +own lease. The grant covers only client endpoints, so no driver can announce a +truck's server endpoint, whatever its name. Anyone may still claim a free truck +or press its e-stop, so the lease stops two honest drivers fighting over a +truck, not a deliberate disruption. Anything beyond a simulator needs +per-driver tokens scoped to the driver's own endpoint. ## The simulator @@ -222,7 +222,7 @@ just carla venv just carla service-install # The units read this. MOQ_URL carries a token allowed to publish `carla/**`, -# which covers the trucks' endpoints, and subscribe `carla/.socket/driver-*`, +# which covers the trucks' server endpoints, and subscribe `carla/.client/**`, # the endpoints drivers dial from; keeping it here keeps it off the command # line. CARLA_IMAGE is the tag the moq-dev/carla build printed, since the worker # refuses a stock simulator. diff --git a/demo/carla/sim/moq_carla_sim/main.py b/demo/carla/sim/moq_carla_sim/main.py index 2993e64e914..6d77d0c3ae6 100644 --- a/demo/carla/sim/moq_carla_sim/main.py +++ b/demo/carla/sim/moq_carla_sim/main.py @@ -42,10 +42,6 @@ # peer. The web player offers the same list. VERSIONS = ("moq-lite-07-wip", "moq-transport-22") -# The id form anonymous drivers may publish endpoints under. A truck named like -# one could be impersonated by any of them. -DRIVER_ID_PREFIX = "driver-" - def default_trucks() -> list[str]: trucks = json.loads(TRUCKS_FILE.read_text()) @@ -89,9 +85,6 @@ def parse_args(argv: list[str] | None = None) -> argparse.Namespace: args = parser.parse_args(argv) if not args.trucks: args.trucks = default_trucks() - for truck in args.trucks: - if truck.startswith(DRIVER_ID_PREFIX): - parser.error(f"truck {truck!r} is named like a driver, whose endpoints anyone may publish") return args diff --git a/demo/carla/sim/moq_carla_sim/publish.py b/demo/carla/sim/moq_carla_sim/publish.py index a1f4d9e10ec..1e98f795493 100644 --- a/demo/carla/sim/moq_carla_sim/publish.py +++ b/demo/carla/sim/moq_carla_sim/publish.py @@ -4,8 +4,8 @@ speaks: carla/{truck}/{camera}.hang video (sd, hd) + status - carla/.socket/{truck} the truck's socket endpoint - carla/.socket/driver-{id} each driver's socket endpoint + carla/.server/{truck} the truck's server socket endpoint + carla/.client/{id} each driver's client socket endpoint """ from __future__ import annotations @@ -294,7 +294,7 @@ def _number_or_none(value: Any) -> float | None: # Every endpoint the trucks and their drivers talk through sits under this -# prefix, as `{prefix}/.socket/{id}`. +# prefix: a truck's as `{prefix}/.server/{truck}`, a driver's as `{prefix}/.client/{id}`. SOCKET_PREFIX = "carla" # How far a control may fall behind the newest before it is skipped: one player @@ -304,10 +304,10 @@ def _number_or_none(value: Any) -> float | None: class Drivers: - """A truck's socket endpoint: accepts each driver's session, fans its controls - into the command queue, and answers the driver on the same session. + """A truck's server socket endpoint: accepts each driver's session, fans its + controls into the command queue, and answers the driver on the same session. - Each driver dials from an endpoint of its own, one `track` session per lease, + Each driver dials from a client endpoint of its own, one `track` session per lease, whose messages are one control per group. Replies go back the same way, so a driver's acknowledgements never reach anyone else. """ @@ -320,8 +320,8 @@ def __init__(self, truck: str, commands: asyncio.Queue[Command]) -> None: @property def path(self) -> str: - """Where the truck's endpoint is announced.""" - return f"{SOCKET_PREFIX}/.socket/{self._truck}" + """Where the truck's server endpoint is announced.""" + return f"{SOCKET_PREFIX}/.server/{self._truck}" def reply(self, command: Command, message: dict[str, Any]) -> None: """Send `message` on the session that carried `command`, if it is still open. diff --git a/demo/carla/sim/systemd/install-user-service.sh b/demo/carla/sim/systemd/install-user-service.sh index 9ea99676e51..d5c2e7e3911 100755 --- a/demo/carla/sim/systemd/install-user-service.sh +++ b/demo/carla/sim/systemd/install-user-service.sh @@ -44,7 +44,7 @@ Before starting, write the relay settings to: CARLA_IMAGE=localhost/moq-carla: The token is a demo-project JWT scoped to publish carla/** and subscribe -carla/.socket/driver-*, the endpoints drivers dial from. For local +carla/.client/**, the endpoints drivers dial from. For local development, MOQ_URL=http://localhost:4443 needs no token. Then run: diff --git a/demo/carla/sim/systemd/install-user-service.test.sh b/demo/carla/sim/systemd/install-user-service.test.sh index b539a046740..1282474b963 100755 --- a/demo/carla/sim/systemd/install-user-service.test.sh +++ b/demo/carla/sim/systemd/install-user-service.test.sh @@ -45,7 +45,7 @@ CARLA_SYSTEMD_USER_DIR="$tmp/units" \ grep -Fxq ' MOQ_URL=https://cdn.moq.dev/demo?jwt=' "$tmp/install.out" grep -Fxq ' CARLA_IMAGE=localhost/moq-carla:' "$tmp/install.out" grep -Fq 'scoped to publish carla/** and subscribe' "$tmp/install.out" -grep -Fq 'carla/.socket/driver-*, the endpoints drivers dial from. For local' "$tmp/install.out" +grep -Fq 'carla/.client/**, the endpoints drivers dial from. For local' "$tmp/install.out" test "$(stat -c %a "$tmp/units")" = 700 test "$(stat -c %a "$tmp/config")" = 700 test "$(stat -c %a "$tmp/units/carla-sim.service")" = 600 diff --git a/demo/carla/sim/tests/test_main.py b/demo/carla/sim/tests/test_main.py index 8ec5a54bffe..09678915033 100644 --- a/demo/carla/sim/tests/test_main.py +++ b/demo/carla/sim/tests/test_main.py @@ -38,13 +38,7 @@ def test_relay_url_defaults_to_the_local_relay(monkeypatch: pytest.MonkeyPatch) def test_paths_match_the_player() -> None: assert broadcast_path("truck1", "front") == "carla/truck1/front.hang" - assert Drivers("truck1", asyncio.Queue()).path == "carla/.socket/truck1" - - -def test_a_truck_named_like_a_driver_is_refused() -> None: - """Anonymous drivers may publish `driver-*` endpoints, so such a truck could be impersonated.""" - with pytest.raises(SystemExit): - parse_args(["--url", "http://localhost:4443", "--truck", "driver-1"]) + assert Drivers("truck1", asyncio.Queue()).path == "carla/.server/truck1" def test_log_level_configures_python_and_rust(monkeypatch: pytest.MonkeyPatch) -> None: diff --git a/demo/carla/web/src/paths.test.ts b/demo/carla/web/src/paths.test.ts index 7880edaf578..a65fe94a953 100644 --- a/demo/carla/web/src/paths.test.ts +++ b/demo/carla/web/src/paths.test.ts @@ -13,7 +13,8 @@ describe("parseCamera", () => { "carla/truck1/front", "carla/truck1/rear/extra.hang", "other/truck1/front.hang", - "carla/.socket/truck1", + "carla/.server/truck1", + "carla/.client/driver", ]) { expect(parseCamera(path)).toBeUndefined(); } diff --git a/demo/carla/web/src/paths.ts b/demo/carla/web/src/paths.ts index ec63f07f39a..343788fc434 100644 --- a/demo/carla/web/src/paths.ts +++ b/demo/carla/web/src/paths.ts @@ -2,10 +2,10 @@ * The paths and connection settings shared with the simulator. * * Trucks publish one media broadcast per camera at `carla/{truck}/{camera}.hang`, - * and accept drivers on a socket endpoint named for the truck. A driver dials it - * from an endpoint of its own, `driver-{id}`, a form the demo relay lets + * and accept drivers on a server socket endpoint named for the truck. A driver + * dials it from a client endpoint of its own, the only role the demo relay lets * anonymous viewers publish. The truck's public `status` names a driver by its - * session's {@link handle} instead, so no viewer learns an id it could announce. + * session's {@link handle} instead of its id. * * @module */ @@ -29,7 +29,7 @@ export function parseCamera(path: string): Camera | undefined { return { truck, id: `${truck}/${file.slice(0, -".hang".length)}` }; } -/** The prefix every truck and driver socket endpoint sits under, as `carla/.socket/{id}`. */ +/** The prefix every truck and driver socket endpoint sits under: `carla/.server/{truck}` and `carla/.client/{driver}`. */ export const SOCKET = Moq.Path.from("carla"); /** diff --git a/demo/relay/prod.toml b/demo/relay/prod.toml index fb27ffc869d..f3292a5c961 100644 --- a/demo/relay/prod.toml +++ b/demo/relay/prod.toml @@ -46,14 +46,16 @@ key = "key.pem" # moq auth serve --listen 127.0.0.1:4440 --key root.jwk \ # --public-subscribe 'anon/**' --public-subscribe 'demo/**' \ # --public-publish 'anon/**' \ -# --public-publish 'demo/boy/.socket/viewer-*' \ -# --public-publish 'demo/carla/.socket/driver-*' \ +# --public-publish 'demo/boy/.client/*' \ +# --public-publish 'demo/carla/.client/*' \ # --mtls-publish '**' --mtls-subscribe '**' --mtls-link peer # # Anonymous MoQ Boy viewers and CARLA drivers get one shared grant each, covering only -# `viewer-*` and `driver-*` endpoint ids: a game's or truck's endpoint stays its -# publisher's, which signs in with a token. Each viewer's id is 128 random bits, so no -# viewer can guess another's. +# client socket endpoints: a game's or truck's server endpoint, `.server/`, stays +# its publisher's, which signs in with a token. `demo/**` lets viewers dial those +# servers, and also read another viewer's client endpoint, which yields nothing without +# a session's secret id. Each viewer's id is 128 random bits, so no viewer can guess +# another's. # # For multiple keys with rotation, give it `--key-dir /path/to/keys/` instead: # keys are named {kid}.jwk and resolved by the kid in the JWT header. diff --git a/doc/bin/demo.md b/doc/bin/demo.md index f03666ee29e..c67bacf8c4f 100644 --- a/doc/bin/demo.md +++ b/doc/bin/demo.md @@ -41,8 +41,8 @@ What it demonstrates: - **On-demand encoding.** Emulation and encoding pause when the last viewer leaves and resume with a keyframe when one arrives. No timers, just subscription state. - **Discovery by prefix.** Game sessions appear under `boy/game/`. No control plane. -- **Sockets.** Each emulator runs a [socket](/concept/socket) endpoint named for its game, and each viewer dials it from an endpoint with a random id. Button presses go up as messages on the viewer's own session, and the emulator answers each with that viewer's latency. A `status` track comes down to everyone with the held buttons and player count. Same relay, same protocol as the media. Sockets need `moq-lite-07-wip`, which is opt-in, on every hop, so the local relay enables it. -- **Split trust.** In production only the server publishes games and their endpoints, while anonymous viewers may publish only `viewer-*` endpoints. +- **Sockets.** Each emulator runs a [socket](/concept/socket) server endpoint named for its game, and each viewer dials it from a client endpoint with a random id. Button presses go up as messages on the viewer's own session, and the emulator answers each with that viewer's latency. A `status` track comes down to everyone with the held buttons and player count. Same relay, same protocol as the media. Sockets need `moq-lite-07-wip` or moq-transport on every hop. The emulator and viewer offer `moq-lite-07-wip`, which is opt-in, so the local relay enables it. +- **Split trust.** In production only the server publishes games and their server endpoints, while anonymous viewers may publish only client endpoints. Code: [`rs/moq-boy`](https://github.com/moq-dev/moq/tree/main/rs/moq-boy) (emulator and publisher), [`js/moq-boy`](https://github.com/moq-dev/moq/tree/main/js/moq-boy) diff --git a/doc/concept/socket.md b/doc/concept/socket.md index f9f609c8692..8bc9f893936 100644 --- a/doc/concept/socket.md +++ b/doc/concept/socket.md @@ -6,8 +6,9 @@ description: Dial and accept point-to-point sessions over MoQ, as reliable byte # Sockets A socket connects two endpoints through relays, the way a TCP connection -connects two hosts. Each endpoint announces one hidden broadcast, dials other -endpoints, and accepts their dials. Each connection is a session that only the +connects two hosts. A server accepts dials and a client dials; an endpoint may +be both. Each role an endpoint takes is one hidden broadcast, so ordinary +grants decide who may be a server. Each connection is a session that only the two ends can read while its id stays secret (see [Hidden names](#hidden-names)), in one of two protocols: `tcp`, a reliable, ordered byte pipe each way, or `track`, a track each way whose groups are messages. Use a @@ -18,7 +19,7 @@ ordinary broadcast. A socket is a convention over announcements, broadcasts, and track subscriptions, not a wire extension. It uses no instances and no track listings, and relays carry it unchanged. It needs moq-lite-07 or -moq-transport on every hop: an endpoint's broadcast is +moq-transport on every hop: an endpoint's broadcasts are [hidden](/concept/moq-lite#hidden-broadcasts), and an older moq-lite hop never carries hidden broadcasts, so a dial across one would never find its peer. Clustered relays carry hidden broadcasts to each other on every version, @@ -34,19 +35,29 @@ it in Rust. ## Endpoints -An endpoint with id `` announces one broadcast, once: +An endpoint with id `` announces one broadcast for each role it takes: ```text -/.socket/ +/.server/ a server, which peers dial +/.client/ a client, which dials servers ``` +| Role | Publishes | Subscribes | +| --- | --- | --- | +| Server | `.server/` | `.client/**` | +| Client | `.client/` | `.server/**` | + +A server announces its broadcast at its first accept, and a client at its +first dial, so a pure client never announces a server broadcast. An endpoint +that both dials and accepts announces both broadcasts under one id. + The id is one path segment: a well-known name for a server, such as a game, or a random id for a client. The prefix is shared by every endpoint that talks to -each other. The `.socket` segment starts with `.`, so endpoints are +each other. Both role segments start with `.`, so endpoints are [hidden](/concept/moq-lite#hidden-broadcasts) from anyone listing the prefix. -The announcement is used only for routing: it is how a relay finds an -endpoint. Connections are never announced. An endpoint's broadcast holds only +The announcements are used only for routing: they are how a relay finds an +endpoint. Connections are never announced. An endpoint's broadcasts hold only session tracks, served on request, whatever their protocol. ## Sessions @@ -54,55 +65,55 @@ session tracks, served on request, whatever their protocol. A session between a dialer `A` and an acceptor `B` is named by its protocol `P`, both ends, and a session id `S` that `A` picks: random and unguessable, at least 128 bits, such as 32 hex digits. Both halves of the session are tracks -with the same name, `///`, one in each -endpoint's broadcast: +with the same name, `///`, one in the +dialer's client broadcast and one in the acceptor's server broadcast: | Track | In broadcast | Written by | Read by | | --- | --- | --- | --- | -| `P/A/B/S` | `/.socket/A` | `A` | `B` | -| `P/A/B/S` | `/.socket/B` | `B` | `A` | +| `P/A/B/S` | `/.client/A` | `A` | `B` | +| `P/A/B/S` | `/.server/B` | `B` | `A` | -The protocol is `tcp` or `track`; see [Protocols](#protocols). An endpoint -resets a request whose protocol it doesn't speak, or isn't accepting, as -unsupported. +The protocol is `tcp` or `track`; see [Protocols](#protocols). A server resets +a dial whose protocol it doesn't speak, or isn't accepting, as unsupported. -The dialer's id follows the protocol in both broadcasts, so an endpoint tells a -dial from an answer by the name alone: a request with another endpoint as the -dialer and itself as the acceptor is that endpoint dialing, and a request with -itself as the dialer answers one of its own dials. An endpoint resets any other -request, such as one naming another acceptor, as not found. Since `S` is random -per dial, every session is distinct, and one endpoint can dial and accept any -number of sessions at once, with the same peer or others. +A request on a server broadcast is a dial, and one on a client broadcast +answers a dial. A server resets a dial that doesn't name another endpoint as +the dialer and itself as the acceptor, such as one naming another acceptor, as +not found, and a client resets any request but the answer to a dial it holds +the same way. Since `S` is random per dial, every session is distinct, and one +endpoint can dial and accept any number of sessions at once, with the same peer +or others. ### Dial -1. `A` picks `S` and holds its own half, `P/A/B/S` in its broadcast, - unanswered. -2. `A` subscribes to `/.socket/B` for the track `P/A/B/S`, waiting for - `B`'s endpoint to be announced if it is not yet. +1. `A` picks `S` and holds its own half, `P/A/B/S` in `/.client/A`, + unanswered, announcing that broadcast if this is its first dial. +2. `A` subscribes to `/.server/B` for the track `P/A/B/S`, waiting for + `B`'s server endpoint to be announced if it is not yet. 3. `B` receives that subscription as a request for a track it does not have: an incoming dial in protocol `P`, claiming to be from `A`, with session `S`. ### Accept -1. `B` subscribes to `/.socket/A` for the track `P/A/B/S`, and holds +1. `B` subscribes to `/.client/A` for the track `P/A/B/S`, and holds `A`'s subscription unanswered. A relay can deliver the dial before `A`'s - announcement, so `B` waits for `A`'s endpoint to be announced for as long as - `A`'s subscription stays open, and gives up once it closes. + announcement, so `B` waits for `A`'s client endpoint to be announced for as + long as `A`'s subscription stays open, and gives up once it closes. 2. `A` answers that subscription only if it dialed `S` to `B` and is still waiting, and resets any other. That makes the exchange a return-routability - check: a dial forged in `A`'s name, by anyone who can subscribe to `B`, - reaches an `A` that never dialed it, so `A` resets `B`'s subscription and `B` - resets the forger's. + check: a dial forged in `A`'s name, by anyone who can subscribe to `B`'s + server endpoint, reaches an `A` that never dialed it, so `A` resets `B`'s + subscription and `B` resets the forger's. 3. Once `A` answers, `B` answers `A`'s subscription, and the session is open for both. `B` writes nothing before `A` answers. ### Reject `B` resets `A`'s subscription, with not found, as for a session that does not -exist. An endpoint resets a dial in a protocol it is not accepting as -unsupported, and one that accepts nothing at all answers not found, as for any -track nobody serves. A dial that gives up resets `B`'s subscription in turn. +exist. A server resets a dial in a protocol it is not accepting as unsupported. +An endpoint that has never accepted has no server endpoint, so a dial to it +waits, as for one not online yet. A dial that gives up resets `B`'s +subscription in turn. ## Protocols @@ -171,8 +182,8 @@ next: commands, controls, acknowledgements, or telemetry. ## Closing -An endpoint closing, or its broadcast ending, resets every session it holds, -and stops reading them. A side that sees the peer's half reset treats the +An endpoint closing, or either of its broadcasts ending, resets every session +it holds, and stops reading them. A side that sees the peer's half reset treats the session as closed and resets its own half, so both halves end. There is no multiplexing within a session: another channel is another session. @@ -183,8 +194,9 @@ as a game's status, stays an ordinary broadcast. ## Hidden names The session id is the secret that keeps a session to its two ends: the token -grants below let any endpoint subscribe to any other, so whoever learns a -session's track name can read it, or answer it before its peer. +grants below let every client subscribe to every server, and every server to +every client, so whoever learns a session's track name can read it, or answer +it before its peer. The acceptor learns the name too, but cannot replay it to a third endpoint `C`: the name binds both ends. `C` resets `P/A/B/S` as a session for another @@ -195,31 +207,43 @@ A session track therefore never appears where a third party can read it: - It is never announced. - It is never listed: an endpoint serves its session tracks only on request, - so a moq-lite 07 track listing (`TRACKS`) of an endpoint's broadcast names - none of them, even to a reader allowed everything. + so a moq-lite 07 track listing (`TRACKS`) of either of an endpoint's + broadcasts names none of them, even to a reader allowed everything. - Logs and metrics that a third party can read must not carry it. ## Authorization Sockets need nothing beyond ordinary [token grants](/bin/relay/auth#path-matching). With the token's root at the -socket prefix, each grant is a prefix: +socket prefix, each role is two prefix grants: publish the endpoint's own +broadcast, and subscribe to the other role's. ```jsonc -// The endpoint : publishes its own endpoint, reads every endpoint. -{ "root": "", "publish": [".socket/"], "subscribe": [".socket/**"] } +// The server : publishes its endpoint, reads every client's. +{ "root": "", "publish": [".server/"], "subscribe": [".client/**"] } +// The client : publishes its endpoint, reads every server's. +{ "root": "", "publish": [".client/"], "subscribe": [".server/**"] } ``` -The publish grant pins the id, so no endpoint can announce as another. The -subscribe grant lets it reach any endpoint, which is what dialing and accepting -need; the session id keeps it out of other endpoints' sessions. A narrower -subscribe grant, such as a client allowed only `.socket/`, also works: -it can then dial only that server and accept only its dials. +An endpoint that both dials and accepts holds both. The publish grant pins the +role and the id, so a client can't announce a server endpoint, or announce as +another endpoint, and a client grant reads no other client's endpoint. The +subscribe grant lets an endpoint reach every peer of the other role, which is +what dialing and accepting need; the session id keeps it out of other +endpoints' sessions. A narrower subscribe grant, such as a client allowed only +`.server/`, also works: it can then dial only that server. + +A grant shared by many clients, such as an anonymous one publishing +`.client/*`, lets each announce any client id, so a client's id must stay a +secret too: random, and never published, such as in a status track. Two +announcements of one path coexist, so an impostor announcing a client's id can +break that client's next dial, though not read or join its sessions. -`moq auth sign` writes this as, for example: +`moq auth sign` writes these as, for example: ```bash -moq auth sign --key key.jwk --root "$PREFIX" --publish ".socket/$ID" --subscribe '.socket/**' > endpoint.jwt +moq auth sign --key key.jwk --root "$PREFIX" --publish ".server/$ID" --subscribe '.client/**' > server.jwt +moq auth sign --key key.jwk --root "$PREFIX" --publish ".client/$ID" --subscribe '.server/**' > client.jwt ``` Each client then connects to the relay at the prefix with its token, and its @@ -231,7 +255,7 @@ planned mesh layer makes ids public keys. ## Later -Later protocols are other prefixes on the same endpoint, with no new -announcement. A multiplexed `quic` mode, with many streams per session like +Later protocols are other prefixes on the same endpoint broadcasts, with no +new announcement. A multiplexed `quic` mode, with many streams per session like QUIC, would name its sessions `quic///` and bring back several groups or streams per session. diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index 9134b8d72fd..8293a785e60 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -93,8 +93,9 @@ for (let chunk = await reader?.readChunk(); chunk; chunk = await reader?.readChu ## Sockets Use `Moq.socket.Endpoint` for [point-to-point sessions](/concept/socket), with the same -origin publishing and consuming through the relay. Each endpoint announces one hidden -broadcast; accepting verifies that the named peer actually dialed this session. +origin publishing and consuming through the relay. An endpoint's first dial announces its +hidden client broadcast and its first accept its hidden server broadcast, so grants decide +which roles it may take; accepting verifies that the named peer actually dialed this session. Every hop needs moq-lite-07 or moq-transport. Lite-07 currently requires explicitly offering `moq-lite-07-wip`; older moq-lite hops do not carry these hidden endpoints. While the endpoint's own client connection is moq-lite before 07, its dials and accepts fail as diff --git a/doc/lib/rs/moq-net.md b/doc/lib/rs/moq-net.md index e17edd986ec..9a7bd7e0c07 100644 --- a/doc/lib/rs/moq-net.md +++ b/doc/lib/rs/moq-net.md @@ -21,7 +21,7 @@ What you use it for, beyond what the concept page already describes: - **Rank several CDNs.** Dial each with its own subscribe handle, `origin.clone().with_preference(origin::Preference::new(rank))` (higher wins; 0 is neutral and a negative rank demotes), all on one origin. Requests use the preferred link that has a route and fail over to the next; see [multiple CDNs](/concept/moq-lite#multiple-cdns). - **Request one instance, or follow them all.** `consumer.request(path, None)` resolves the instance serving a path now, and fails `Unroutable` only once discovery has synced with no route for it. `consumer.follow(path, None)` hands out each publisher instance serving a path from `available()`: the first once announced, then each one that takes over, `None` once the path goes offline, and whatever serves it next, like JS `follow(path)`. `consumer.announced()` lists paths only as present or absent. A broadcast already resolved stays on the old instance until dropped or its route goes. See [identity and recovery](/concept/identity) to choose between following and holding one instance. - **Discovery follows what you watch.** A client session asks the relay for announcements only under the prefixes its subscribe origin's readers watch, with `announced()`, `request`, or `follow`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. A broadcast resolved through a discovered route keeps its path watched until dropped. `request` owns discovery of its path, so no separate watch is needed. A server session, or a client fed into an origin handle marked `with_link(origin::Link::Peer)` or `Link::Upstream`, asks for everything it may, so a relay discovers everything. An HTTP gateway (the moq-hls `Server`, the moq-webrtc WHEP router) watches its whole scope while it lives, so the paths its callers name never open a request each. moq-lite-03/04 sessions, whose announcements mark no initial set, still ask for everything. -- **Dial and accept sockets.** `socket::Endpoint::new(&origin, prefix, id)` announces a hidden endpoint at `/.socket/`, used only to route dials. A session speaks one of two protocols, each with its own dial and accept. `accept_tcp()` and `accept_track()` yield an `Incoming` dial to `accept` or `reject` (dropping it rejects). `dial_tcp(peer)` and an accepted `tcp` dial yield a `socket::TcpStream`, a `group::Producer` and `group::Consumer` pair carrying one reliable, ordered byte pipe each way (finish is FIN, abort is RST, and `ready` paces the writer to the reader); `dial_track(peer, info)` and an accepted `track` dial yield a `socket::TrackStream`, this side's `track::Producer` and a `track::Subscriber` of the peer's half, subscribed reliably and in order until the application updates it, one message per group. A dial resolves once the peer accepts, and an accept checks that the claimed dialer really dialed this endpoint, waiting for its endpoint while the dial stays open. Every hop needs moq-lite-07 or moq-transport: while the origin has an older moq-lite client session whose publish half doesn't opt into hidden broadcasts (`with_hidden(true)`), dials and accepts fail with `Unsupported`. A dial to a peer behind such a hop waits, as for a peer not online yet. Session tracks are never announced or listed. See [Sockets](/concept/socket). +- **Dial and accept sockets.** `socket::Endpoint::new(&origin, prefix, id)` is a server, a client, or both: its first dial announces a hidden client endpoint at `/.client/`, and its first accept a hidden server endpoint at `/.server/`, both used only to route sessions, so grants decide which roles it may take. A session speaks one of two protocols, each with its own dial and accept. `accept_tcp()` and `accept_track()` yield an `Incoming` dial to `accept` or `reject` (dropping it rejects). `dial_tcp(server)` and an accepted `tcp` dial yield a `socket::TcpStream`, a `group::Producer` and `group::Consumer` pair carrying one reliable, ordered byte pipe each way (finish is FIN, abort is RST, and `ready` paces the writer to the reader); `dial_track(server, info)` and an accepted `track` dial yield a `socket::TrackStream`, this side's `track::Producer` and a `track::Subscriber` of the peer's half, subscribed reliably and in order until the application updates it, one message per group. A dial resolves once the peer accepts, and an accept checks that the claimed dialer really dialed this endpoint, waiting for its endpoint while the dial stays open. Every hop needs moq-lite-07 or moq-transport: while the origin has an older moq-lite client session whose publish half doesn't opt into hidden broadcasts (`with_hidden(true)`), dials and accepts fail with `Unsupported`. A dial to a peer behind such a hop waits, as for a peer not online yet. Session tracks are never announced or listed. See [Sockets](/concept/socket). - **One track per name.** Concurrent subscriptions share one request and producer. The application owns sequence numbers: the broadcast keeps nothing of an ended track, so a producer that replaces it starts at 0. A name always means the same content, so the replacement continues past its predecessor's groups with `create_group` at an explicit sequence. Readers of an aborted track resume onto the replacement when they read through an origin request, whose route always names an instance; otherwise their subscription ends with the error. - **Authored tracks default to a zero `max_age`.** `track::Info::default()` sets `max_age` to `Some(Duration::ZERO)`, the live edge only; a publisher that wants readers to reach history sets a longer bound, or `with_max_age(None)` for no publisher limit. Media tracks from `hang::container::track_info` declare `hang::container::MAX_AGE` (30 seconds). `max_age` is how long a superseded group stays fresh, never the newest group; it frees no bytes, which the cache pool's expiry reclaims. Received metadata keeps absence as no limit, and an origin's `cache_duration` can only cap it lower. - **End content by finishing tracks.** A broadcast has no finished state. When the input ends, finish each track; the broadcast stays announced and keeps serving them until you close it or drop its route. How long to keep it up for late readers is yours to decide: `moq_mux::Linger` holds a hang broadcast for a fixed window. diff --git a/go/wrapper/socket/socket.go b/go/wrapper/socket/socket.go index 4e259a77513..3770e129761 100644 --- a/go/wrapper/socket/socket.go +++ b/go/wrapper/socket/socket.go @@ -1,4 +1,4 @@ -// Package socket dials and accepts point-to-point sessions over hidden broadcasts. +// Package socket dials and accepts point-to-point sessions between server and client endpoints. package socket import ( @@ -8,10 +8,11 @@ import ( "moq.dev/moq/internal/bridge" ) -// Endpoint announces one hidden endpoint and accepts TCP and track dials separately. +// Endpoint is a server, a client, or both, and accepts TCP and track dials separately. type Endpoint struct{ inner *ffi.MoqSocketEndpoint } -// NewEndpoint announces id beneath prefix, using origin to find peers. +// NewEndpoint makes the endpoint id beneath prefix, using origin to find peers. Its first +// dial announces it as a client, and its first accept as a server. func NewEndpoint(origin *moq.OriginProducer, prefix, id string) (*Endpoint, error) { inner, err := ffi.NewMoqSocketEndpoint(bridge.OriginProducer(origin), prefix, id) if err != nil { @@ -26,7 +27,7 @@ func (e *Endpoint) ID() string { return e.inner.Id() } // Prefix returns the shared endpoint prefix. func (e *Endpoint) Prefix() string { return e.inner.Prefix() } -// Close retracts the endpoint and resets pending dials and sessions. +// Close retracts the endpoint's broadcasts and resets pending dials and sessions. func (e *Endpoint) Close() { e.inner.Close() } // DialTCP dials a new tcp session; cancelling resets only this dial. diff --git a/js/moq-boy/src/element.tsx b/js/moq-boy/src/element.tsx index 51ec2c51538..5025aa48f1a 100644 --- a/js/moq-boy/src/element.tsx +++ b/js/moq-boy/src/element.tsx @@ -21,11 +21,11 @@ const DEFAULT_PREFIX = Moq.Path.from("boy"); // Sockets need moq-lite-07 or moq-transport on every hop, and the relay offers moq-lite-07 only when asked. const VERSIONS = ["moq-lite-07-wip"]; -// A viewer's endpoint id: random, so no other viewer can claim it, under the prefix the relay lets anonymous -// viewers publish, so no viewer can claim a game's. +// A viewer's client endpoint id: random, so no other viewer can claim it. A viewer only dials, so it +// announces a client endpoint, which can never pose as a game's server endpoint. function viewerId(): string { const bytes = crypto.getRandomValues(new Uint8Array(16)); - return `viewer-${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`; + return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join(""); } const cleanup = new FinalizationRegistry((signals) => signals.close()); @@ -40,7 +40,7 @@ const cleanup = new FinalizationRegistry((signals) => signal * - `prefix-game` - Path prefix for game broadcasts and the socket endpoints of games and viewers * (default: `{prefix}/game`) * - * Each viewer runs one socket endpoint with a random id and dials each game it plays. + * Each viewer runs one client socket endpoint with a random id and dials each game it plays. */ export default class MoqBoy extends HTMLElement { /** The attributes the browser reports changes to. */ diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index f44c02f8cbe..15adcad7bdb 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -34,9 +34,6 @@ import * as Varint from "./varint.ts"; import type { Resolved, Window } from "./window.ts"; import type { Advertised, Advertisements } from "./wire.ts"; -/** The hidden broadcast segment reserved for socket endpoints. */ -export const SOCKET = ".socket"; - /** What a null {@link Delay.max} goes out as: the largest value every peer can read, as Rust sends for `None`. */ export const NO_MAX_DELAY = Milli(Varint.MAX_U53); diff --git a/js/net/src/socket.test.ts b/js/net/src/socket.test.ts index 968b839aff5..9a2c9249105 100644 --- a/js/net/src/socket.test.ts +++ b/js/net/src/socket.test.ts @@ -47,14 +47,17 @@ async function track() { const remote = await (await incoming).accept(); return { ...state, local: await dialing, remote }; } -async function broadcast(origin: Origin.Producer, id: string): Promise { - const request = origin.request(Path.from("room/.socket", id)); - const active = request.active.peek(); +type Role = ".server" | ".client"; +function announced(origin: Origin.Producer, role: Role, id: string): BroadcastConsumer | undefined { + return origin.request(Path.from("room", role, id)).active.peek(); +} +async function broadcast(origin: Origin.Producer, role: Role, id: string): Promise { + const active = announced(origin, role, id); if (!active) throw new Error("endpoint not routed locally"); return active; } -async function raw(origin: Origin.Producer, id: string, name: string): Promise { - return (await broadcast(origin, id)).track(name).subscribe({ order: "ascending", delay: { max: null } }); +async function raw(origin: Origin.Producer, role: Role, id: string, name: string): Promise { + return (await broadcast(origin, role, id)).track(name).subscribe({ order: "ascending", delay: { max: null } }); } test("socket namespace exposes endpoint and both stream roles", () => { @@ -63,6 +66,14 @@ test("socket namespace exposes endpoint and both stream roles", () => { expect(socket.TrackStream).toBeFunction(); }); +test("an endpoint closes with its origin before it dials or accepts", async () => { + const origin = new Origin.Producer(); + const endpoint = new socket.Endpoint(origin, Path.from("room"), "alice"); + origin.close(); + expect(await endpoint.closed).toBeNull(); + expect(new socket.Endpoint(origin, Path.from("room"), "bob").closed.peek()).toBeNull(); +}); + test("TCP carries ordered frames in both directions, with independent FIN", async () => { const { a, b, local, remote } = await tcp(); expect(local.peer).toBe("bob"); @@ -89,7 +100,7 @@ test("a peer route replaced between metadata and opening cannot inherit a socket const routes: { close(): void }[] = []; const tasks: Promise[] = []; const advertise = (front: BroadcastConsumer) => { - const route = wireOf(origin).receive(Path.from("room/.socket/remote")); + const route = wireOf(origin).receive(Path.from("room/.server/remote")); routes.push(route); tasks.push( (async () => { @@ -119,7 +130,7 @@ test("a peer route replaced between metadata and opening cannot inherit a socket try { const request = await requested; if (!request) throw new Error("missing dial"); - returning = await raw(origin, "alice", request.name); + returning = await raw(origin, ".client", "alice", request.name); await returning.info(); request.accept({ maxAge: null }); // Both route changes happen before the info promise's continuation opens the session. @@ -224,7 +235,7 @@ for (const protocol of ["tcp", "track"] as const) { const oldReader = local instanceof socket.TcpStream ? local.consumer : local.consumer.ordered(); remote.producer.abort(reset); await expect(oldReader.readFrame()).rejects.toBeInstanceOf(Error); - const source = await broadcast(origin, "bob"); + const source = await broadcast(origin, ".server", "bob"); let outcome: unknown; const fetched = source .track(`${protocol}/alice/bob/${local.session}`) @@ -267,12 +278,29 @@ for (const protocol of ["tcp", "track"] as const) { }); } -test("a dial-only endpoint refuses incoming requests and answers only its reserved session", async () => { - const { origin, a } = setup(); +test("an endpoint announces only the roles it takes, and its client answers only its reserved sessions", async () => { + const { origin, a, b } = setup(); await expect(a.dialTcp("alice")).rejects.toBeInstanceOf(Error); - const unsupported = await raw(origin, "alice", "tcp/bob/alice/not-a-dial"); + expect(announced(origin, ".client", "alice")).toBeUndefined(); + const cancel = new AbortController(); + const dialing = a.dialTcp("bob", { signal: cancel.signal }); + const failure = dialing.catch((error: unknown) => error); + expect(announced(origin, ".client", "alice")).toBeDefined(); + expect(announced(origin, ".server", "alice")).toBeUndefined(); + const unsupported = await raw(origin, ".client", "alice", "tcp/bob/alice/not-a-dial"); await expect(unsupported.info()).rejects.toBeInstanceOf(NotFound); unsupported.close(); + + // Bob has not accepted yet, so the dial waits for him to serve. + const clock = time(); + await clock.advance(Nano.fromSecond(Second(3600))); + expect(announced(origin, ".server", "bob")).toBeUndefined(); + const incoming = b.acceptTcp(); + expect(announced(origin, ".server", "bob")).toBeDefined(); + expect(announced(origin, ".client", "bob")).toBeUndefined(); + expect((await incoming).peer).toBe("alice"); + cancel.abort(); + expect(await failure).toBeInstanceOf(Error); }); test("unknown and unaccepted protocols reset without entering the other queue", async () => { @@ -281,7 +309,7 @@ test("unknown and unaccepted protocols reset without entering the other queue", const incoming = b.acceptTcp({ signal: hold.signal }); const rejected = incoming.catch((error: unknown) => error); for (const protocol of ["track", "quic"]) { - const subscriber = await raw(origin, "bob", `${protocol}/alice/bob/session-${protocol}`); + const subscriber = await raw(origin, ".server", "bob", `${protocol}/alice/bob/session-${protocol}`); await expect(subscriber.info()).rejects.toBeInstanceOf(Error); subscriber.close(); } @@ -340,7 +368,7 @@ test("dial and accept cancellation before announcement release their routing hol cancel.abort(); expect(await failure).toBeInstanceOf(Error); const next = b.acceptTcp(); - const subscriber = await raw(origin, "bob", "tcp/absent/bob/never-announced"); + const subscriber = await raw(origin, ".server", "bob", "tcp/absent/bob/never-announced"); const accepted = (await next).accept(); const acceptanceFailure = accepted.catch((error: unknown) => error); await clock.advance(Nano.fromSecond(Second(3600))); @@ -365,11 +393,11 @@ test("accept waits for a delayed dialer announcement only while its original dia const clock = time(); const { origin, b } = setup(); const next = b.acceptTrack(); - const subscriber = await raw(origin, "bob", "track/late/bob/delayed-announcement"); + const subscriber = await raw(origin, ".server", "bob", "track/late/bob/delayed-announcement"); const incoming = await next; const acceptance = incoming.accept(); await clock.advance(Nano.fromSecond(Second(3600))); - const route = origin.route(Path.from("room/.socket/late"), { hidden: true }); + const route = origin.route(Path.from("room/.client/late"), { hidden: true }); const answer = hooks.reserveUnlistedTrack(route.broadcast, "track/late/bob/delayed-announcement"); route.announce(); await clock.advance(Nano.zero); @@ -383,11 +411,13 @@ test("accept waits for a delayed dialer announcement only while its original dia test("forged and replayed dials cannot pass return routability", async () => { const { origin, a, b } = setup(); + // Alice dials elsewhere, so her client broadcast is there to refuse bob's check. + void a.dialTcp("carol").catch(() => {}); for (const name of ["tcp/alice/bob/forged", "tcp/alice/someone-else/replayed"]) { const cancel = new AbortController(); const wait = b.acceptTcp({ signal: cancel.signal }); void wait.catch(() => {}); - const subscriber = await raw(origin, "bob", name); + const subscriber = await raw(origin, ".server", "bob", name); const refusal = subscriber.info().catch((error: unknown) => error); if (name.includes("/bob/")) await expect((await wait).accept()).rejects.toBeInstanceOf(NotFound); else cancel.abort(); @@ -402,15 +432,19 @@ test("session names are absent from listings while reserved and established", as const next = b.acceptTcp(); const dialing = a.dialTcp("bob"); const incoming = await next; - for (const id of ["alice", "bob"]) { - const listing = (await broadcast(origin, id)).tracks(); + const endpoints = [ + [".client", "alice"], + [".server", "bob"], + ] as const; + for (const [role, id] of endpoints) { + const listing = (await broadcast(origin, role, id)).tracks(); expect(await listing.next()).toEqual({ kind: "synced" }); listing.close(); } const remote = await incoming.accept(); await dialing; - for (const id of ["alice", "bob"]) { - const listing = (await broadcast(origin, id)).tracks(); + for (const [role, id] of endpoints) { + const listing = (await broadcast(origin, role, id)).tracks(); expect(await listing.next()).toEqual({ kind: "synced" }); listing.close(); } @@ -444,11 +478,11 @@ test("track reset and endpoint close fail peers and leave no open accepts", asyn test("a second TCP group resets the session even after the first FIN", async () => { for (const initial of [0n, 2n]) { const { origin, b } = setup(); - const route = origin.route(Path.from("room/.socket/raw")); + const route = origin.route(Path.from("room/.client/raw")); const name = `tcp/raw/bob/second-${initial}`; const answer = hooks.reserveUnlistedTrack(route.broadcast, name); const next = b.acceptTcp(); - const subscriber = await raw(origin, "bob", name); + const subscriber = await raw(origin, ".server", "bob", name); const acceptance = (await next).accept(); // Drive the accept's return subscription before publishing the first half. const clock = time(); @@ -471,11 +505,11 @@ test("a second TCP group resets the session even after the first FIN", async () for (const dropped of [false, true]) { test(`TCP fails when its only group ${dropped ? "is dropped" : "never arrives"}`, async () => { const { origin, b } = setup(); - const route = origin.route(Path.from("room/.socket/raw")); + const route = origin.route(Path.from("room/.client/raw")); const name = `tcp/raw/bob/missing-${dropped}`; const answer = hooks.reserveUnlistedTrack(route.broadcast, name); const next = b.acceptTcp(); - const subscriber = await raw(origin, "bob", name); + const subscriber = await raw(origin, ".server", "bob", name); const acceptance = (await next).accept(); const clock = time(); await clock.advance(Nano.zero); @@ -532,7 +566,7 @@ for (const protocol of ["tcp", "track"] as const) { origins.add(ao); origins.add(bo); const a = new socket.Endpoint(ao, Path.from("room"), "alice"); - const route = bo.route(Path.from("room/.socket/bob"), { hidden: true }); + const route = bo.route(Path.from("room/.server/bob"), { hidden: true }); const requested = wireOf(route.broadcast).requested(); route.announce(); const pair = createMockTransportPair(alpn); @@ -543,7 +577,7 @@ for (const protocol of ["tcp", "track"] as const) { ]); let returning: Track.Subscriber | undefined; let drained: Promise | undefined; - const following = bo.follow(Path.from("room/.socket/alice")); + const following = bo.follow(Path.from("room/.client/alice")); try { const dialing = protocol === "tcp" ? a.dialTcp("bob") : a.dialTrack("bob"); void dialing.catch(() => {}); diff --git a/js/net/src/socket.ts b/js/net/src/socket.ts index db76e74bdd7..7fb2c1bb7a8 100644 --- a/js/net/src/socket.ts +++ b/js/net/src/socket.ts @@ -1,7 +1,9 @@ /** - * Point-to-point sessions over one hidden broadcast per endpoint. + * Point-to-point sessions between server and client endpoints. * - * Sessions use the existing MoQ wire and need lite-07 (currently an explicit + * An endpoint's first dial announces its hidden client broadcast, `/.client/`, + * and its first accept its hidden server broadcast, `/.server/`, so ordinary + * grants decide which roles it may take. Sessions use the existing MoQ wire and need lite-07 (currently an explicit * `moq-lite-07-wip` offer) or moq-transport on every hop. While the endpoint's origin * has a moq-lite client session before 07, dials and accepts fail as unsupported. * Their track names are secrets and are never listed. See the socket concept page. @@ -11,7 +13,7 @@ import { type Dispose, type GetPromise, type Getter, Once, Signal } from "@moq/signals"; import { NotFound, ProtocolViolation, StreamCode, StreamError } from "./error.ts"; import * as Group from "./group.ts"; -import { hooks, SOCKET } from "./internal.ts"; +import { hooks } from "./internal.ts"; import type * as Origin from "./origin.ts"; import * as Path from "./path.ts"; import type * as Track from "./track.ts"; @@ -22,6 +24,9 @@ import { wireOf } from "./wire.ts"; type Protocol = "tcp" | "track"; type Stream = TcpStream | TrackStream; +/** A server accepts dials, and a client dials. */ +type Role = "server" | "client"; +const SEGMENT: Record = { server: ".server", client: ".client" }; const reliable: Track.Subscription = { order: "ascending", delay: { max: null }, @@ -35,9 +40,9 @@ function segment(id: string): void { if (!id || id.includes("/") || id.includes("\\")) throw new TypeError("socket id must be one plain segment"); } -function endpointPath(prefix: Path.Valid, id: string): Path.Valid { +function endpointPath(prefix: Path.Valid, role: Role, id: string): Path.Valid { segment(id); - return Path.encode(Path.from(prefix, SOCKET, id)); + return Path.encode(Path.from(prefix, SEGMENT[role], id)); } function parse(name: string): { protocol: string; dialer: string; acceptor: string; session: string } | undefined { @@ -197,7 +202,13 @@ class Queue { } /** - * Announces one endpoint, dials peers under the same prefix, and accepts each protocol separately. + * A server, a client, or both: dials servers under the same prefix, and accepts each protocol + * separately. + * + * Its first dial announces its client broadcast, which holds its half of each session it dials, + * and its first accept announces its server broadcast, where peers dial it. A pure client never + * announces a server broadcast, and until the first accept a dial to it waits as for a peer not + * online yet. * * Every hop between two endpoints must carry hidden broadcasts: moq-lite-07 or moq-transport. * While the origin has a moq-lite client session before 07, whose peer never hears this @@ -216,36 +227,47 @@ export class Endpoint { #closed = new Once(); #abort = new AbortController(); #origin: Origin.Producer; - #route: Origin.Route; + #routes: Partial> = {}; #queues = { tcp: new Queue(), track: new Queue() }; - #serving = false; #sessions = new Set(); - #unclose: Dispose; + #unclose: Dispose[] = []; #withheld: Getter; - /** Publish this endpoint on origin, which must also reach its peers. */ + /** An endpoint on origin, which must also reach its peers; nothing is announced until it dials or accepts. */ constructor(origin: Origin.Producer, prefix: Path.Valid, id: string) { this.id = id; this.prefix = Path.from(prefix); + for (const role of ["server", "client"] as const) endpointPath(this.prefix, role, id); this.#origin = origin; this.#withheld = hooks.hiddenWithheld(origin); - this.#route = origin.route(endpointPath(this.prefix, id)); - this.#unclose = hooks.onClosed(this.#route.broadcast, () => this.close()); + // Before the first dial or accept no route watches the origin, so watch its close here. + this.#unclose.push(origin.closed.subscribe(() => this.close())); + if (origin.closed.peek() !== undefined) this.close(); + } + + // This endpoint's broadcast in role, announced on first use. + #route(role: Role): Origin.Route { + const existing = this.#routes[role]; + if (existing) return existing; + const route = this.#origin.route(endpointPath(this.prefix, role, this.id)); + this.#routes[role] = route; + this.#unclose.push(hooks.onClosed(route.broadcast, () => this.close())); + return route; } static { accept = (endpoint, protocol, request, info, options) => endpoint.#accept(protocol, request, info, options); } - /** Dial a TCP session; waits for the peer's announcement and acceptance until cancelled. */ + /** Dial the server peer in a TCP session; waits for its announcement and acceptance until cancelled. */ dialTcp(peer: string, options?: Options): Promise { return this.#dial("tcp", peer, {}, options) as Promise; } - /** Dial a track session; omitted info keeps every message with no publisher max age. */ + /** Dial the server peer in a track session; omitted info keeps every message with no publisher max age. */ dialTrack(peer: string, info: Track.InfoInit = { maxAge: null }, options?: Options): Promise { return this.#dial("track", peer, info, options) as Promise; } - /** Take the next TCP dial; the first call starts queueing TCP dials until close. */ + /** Take the next TCP dial; the first call starts queueing TCP dials until close, and the first accept announces the server. */ acceptTcp(options?: Options): Promise> { return this.#next("tcp", options); } @@ -262,10 +284,7 @@ export class Endpoint { signal.throwIfAborted(); const queue = this.#queues[protocol]; queue.listening = true; - if (!this.#serving) { - this.#serving = true; - void this.#serve(); - } + if (!this.#routes.server) void this.#serve(this.#route("server")); for (;;) { await waitFor(queue.dials, (dials) => dials.size > 0, signal); signal.throwIfAborted(); @@ -292,10 +311,10 @@ export class Endpoint { return unwatch; } - async #serve(): Promise { + async #serve(route: Origin.Route): Promise { try { for (;;) { - const request = await wireOf(this.#route.broadcast).requested(); + const request = await wireOf(route.broadcast).requested(); if (!request) return; const name = parse(request.name); if (!name || name.acceptor !== this.id || name.dialer === this.id) { @@ -334,14 +353,16 @@ export class Endpoint { return options?.signal ? AbortSignal.any([this.#abort.signal, options.signal]) : this.#abort.signal; } + // Subscribe to the session's half in the peer's broadcast, its server or client one by role. async #remote( protocol: Protocol, + role: Role, peer: string, name: string, signal: AbortSignal, hold: (following: Origin.Following) => void, ): Promise<{ consumer: Track.Subscriber; peer: GetPromise }> { - const following = this.#origin.follow(endpointPath(this.prefix, peer)); + const following = this.#origin.follow(endpointPath(this.prefix, role, peer)); hold(following); const abort = new AbortController(); const stop = following.closed.subscribe(() => abort.abort(following.closed.peek() ?? ended())); @@ -370,14 +391,14 @@ export class Endpoint { signal.throwIfAborted(); const session = fromBytes(crypto.getRandomValues(new Uint8Array(16))); const name = `${protocol}/${this.id}/${peer}/${session}`; - const answer = hooks.reserveUnlistedTrack(this.#route.broadcast, name); + const answer = hooks.reserveUnlistedTrack(this.#route("client").broadcast, name); let following: Origin.Following | undefined; let consumer: Track.Subscriber | undefined; let producer: Track.Producer | undefined; let stop: Dispose = () => {}; const unreached = this.#reachable(abort); try { - const remote = await this.#remote(protocol, peer, name, signal, (value) => { + const remote = await this.#remote(protocol, "server", peer, name, signal, (value) => { following = value; }); consumer = remote.consumer; @@ -424,7 +445,7 @@ export class Endpoint { try { check(); signal.throwIfAborted(); - const remote = await this.#remote(protocol, name.dialer, request.name, signal, (value) => { + const remote = await this.#remote(protocol, "client", name.dialer, request.name, signal, (value) => { following = value; }); consumer = remote.consumer; @@ -465,7 +486,7 @@ export class Endpoint { } } - /** Reset every held session, cancel pending operations, and retract the endpoint; idempotent. */ + /** Reset every held session, cancel pending operations, and retract the endpoint's broadcasts; idempotent. */ close(): void { this.#end(null); } @@ -473,11 +494,11 @@ export class Endpoint { #end(error: Error | null): void { if (this.#closed.peek() !== undefined) return; this.#closed.set(error); - this.#unclose(); + for (const unclose of this.#unclose) unclose(); this.#abort.abort(error ?? ended()); for (const queue of Object.values(this.#queues)) queue.close(); for (const session of this.#sessions) session.reset(ended()); - this.#route.broadcast.close(); + for (const route of Object.values(this.#routes)) route.broadcast.close(); } } diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/socket/Socket.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/socket/Socket.kt index d8e911da89e..449b94b71fa 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/socket/Socket.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/socket/Socket.kt @@ -1,6 +1,9 @@ package dev.moq.socket -/** Announces one hidden endpoint and dials or accepts sessions. */ +/** + * A server, a client, or both: its first dial announces it as a client, and its first accept as a + * server. + */ typealias Endpoint = uniffi.moq.MoqSocketEndpoint /** An incoming TCP dial, consumed by accepting or rejecting it. */ diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index e3bd133b9d1..c8d4771bda6 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -253,8 +253,9 @@ Every handle whose cleanup is `cancel()` is an async context manager, so exiting `from moq import socket` exposes `socket.Endpoint(origin, prefix, id)`. Use the same origin as the session's publish and consume sides. Hold the endpoint while -sessions run, or use it as an async context manager. It announces only -`/.socket/`; keep each session id private. +sessions run, or use it as an async context manager. Its first dial announces +`/.client/` and its first accept `/.server/`, so grants +decide whether it may be a client, a server, or both; keep each session id private. - `await endpoint.dial_tcp(peer)` and `await endpoint.accept_tcp()` use the TCP queue. - `await endpoint.dial_track(peer, info=None)` and `await endpoint.accept_track()` use the track queue. diff --git a/py/moq-rs/moq/socket.py b/py/moq-rs/moq/socket.py index 505f60e1660..21cc91ea79c 100644 --- a/py/moq-rs/moq/socket.py +++ b/py/moq-rs/moq/socket.py @@ -1,4 +1,4 @@ -"""Point-to-point TCP and track sessions over hidden endpoint broadcasts.""" +"""Point-to-point TCP and track sessions between server and client endpoints.""" from __future__ import annotations @@ -20,8 +20,9 @@ class Endpoint: - """Announces one hidden endpoint and dials or accepts independent sessions. + """A server, a client, or both: dials or accepts independent sessions. + Its first dial announces it as a client, and its first accept as a server. Hold it while sessions run. Closing it resets pending dials and sessions. Cancelling a dial cancels only that dial; cancelling an accept wait leaves the endpoint listening. Usable as an async context manager. @@ -47,11 +48,11 @@ async def __aexit__(self, *exc) -> None: self.close() def close(self) -> None: - """Retract the endpoint and reset its pending dials and sessions.""" + """Retract the endpoint's broadcasts and reset its pending dials and sessions.""" self._inner.close() async def dial_tcp(self, peer: str) -> TcpStream: - """Dial a new TCP session, waiting until the peer accepts it.""" + """Dial the server peer in a new TCP session, waiting until it accepts.""" return TcpStream(await self._inner.dial_tcp(peer)) async def accept_tcp(self) -> IncomingTcp: diff --git a/py/moq-rs/tests/test_socket.py b/py/moq-rs/tests/test_socket.py index 2123ad94190..ed5a6c56b34 100644 --- a/py/moq-rs/tests/test_socket.py +++ b/py/moq-rs/tests/test_socket.py @@ -184,11 +184,11 @@ async def late_peer(clock): async def test_cancelling_acceptance_drops_the_original_dial_while_proving_routability(): origin = moq.OriginProducer() endpoint = socket.Endpoint(origin, "room", "server") - forged = origin.route("room/.socket/forged", hidden=True) + forged = origin.route("room/.client/forged", hidden=True) returning = forged.broadcast.requests() forged.announce() incoming = await start(endpoint.accept_tcp()) - broadcast = await origin.consume().request("room/.socket/server") + broadcast = await origin.consume().request("room/.server/server") original = await start(broadcast.subscribe_track("tcp/forged/server/0123456789abcdef0123456789abcdef")) offered = await incoming accepting = await start(offered.accept()) diff --git a/quest/m1/README.md b/quest/m1/README.md index 8167de6e377..979f313c0fc 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -44,7 +44,6 @@ moves what remains of them once their claims merge. - [Native WebSocketStream keeps datagrams flowing](/quest/m1/websocket-stream-datagrams.md) - on Chromium's native `WebSocketStream`, QMux over WebSocket sheds a datagram only on a real send backlog, proven in headless Chromium - [Buffered playback subscribes in ascending order](/quest/m1/buffered-ascending.md) - a buffered `` asks for the oldest group first, so a voice reply's opening arrives first, and audio's head hold shrinks to the floor - [Push-to-talk's press-to-audible latency fits a budget on the defaults](/quest/m1/push-to-talk-latency.md) - press to audible on the browser defaults, excluding device output, stays under a kixtop-measured budget that `just test push-to-talk` enforces -- [Socket endpoints split into servers and clients](/quest/m1/socket-roles.md) - servers announce `.server/` and clients `.client/`, so plain grants keep a client from posing as a server or reading another client - [TS fidelity and recovery](/quest/m1/ts-reliability/README.md) - both modes have explicit profiles, automated validation, loss tests, and a dedicated guide - [Session policy lives in moq-net](/quest/m1/session-policy/README.md) - accept and connect deadlines, admission, window widening and reconnect live once in moq-net; moq-tokio and moq-relay's io_uring path call them - [Vendor and trim the WebRTC stack](/quest/m1/webrtc-vendor.md) - str0m, dimpl, `is`, and sctp-proto live in moq-webrtc with unused code removed, so moq-webrtc can take rind diff --git a/quest/m1/socket-roles.md b/quest/m1/socket-roles.md deleted file mode 100644 index 3cac616ae68..00000000000 --- a/quest/m1/socket-roles.md +++ /dev/null @@ -1,72 +0,0 @@ -# [L] Socket endpoints split into servers and clients - -## Goal - -A socket endpoint is a server, a client, or both, and the relay's ordinary -grants enforce which. A server announces `/.server/` and accepts -dials; a client announces `/.client/` and dials. A client's grant -can't announce as a server or read another client's endpoint, so roles come -from the grant rather than an id prefix such as boy's `viewer-*`. The -symmetric `.socket/` layout is gone from moq-net (Rust, JS, Python through -moq-ffi), the [socket concept page](/doc/concept/socket.md), the interop -clients, moq-boy, and CARLA. - -| Role | Publishes | Subscribes | -| --- | --- | --- | -| Server | `.server/` | `.client/**` | -| Client | `.client/` | `.server/**` | - -Non-goals: stopping a client from announcing another client's id once it learns -it. Ids stay unguessable secrets until the m3 [mesh](/quest/m3/mesh/README.md) -makes them public keys; CARLA's `status` names drivers by a session handle, -so it leaks none. - -## Plan - -Decided 2026-11-06 (maintainer, follow-up planning in `/quest-complete`, raised -while landing [moq-dev/moq#8011](https://github.com/moq-dev/moq/pull/8011) and -asking how anonymous viewers are kept from posing as cars or emulators): - -- **What the split enforces?** The dialer still publishes: its half of a - session, `P/A/B/S`, lives in its own broadcast, and the acceptor's - subscription to it is the return-routability check. - - ✅ Two hidden segments, one per role: a server publishes its own and reads - clients', a client the reverse. Plain grants enforce it, with no relay - change. - - Relay-enforced roles on session track names (dial = `P//*/*`, - listen = `P/*//*`). - - Dial ids bound to the connection, assigned by the relay or held by the - first session to claim them: hard across a cluster. - - Rely on the mesh's public-key ids alone. -- **Names?** ✅ `.server` / `.client`, read as roles. Not chosen: `.accept` / - `.dial` (the API verbs); `.listen` / `.dial`. -- **The old layout?** ✅ Replace `.socket/`: one convention, and a peer - that both dials and accepts announces both broadcasts under one id. Not - chosen: keep `.socket` for symmetric peers beside the split. -- **Milestone?** ✅ m1, before sockets first publish from the cut. Not chosen: - m3 beside the mesh's public-key ids; m4. - -Lead, for the PR to confirm: an endpoint announces `.client/` at its first -dial and `.server/` at its first accept, so a pure client never announces a -server endpoint, and today's dial-reserves-its-half and -accept-from-the-first-accept rules carry over. The session track name, the -handshake, the return-routability check, and both protocols are unchanged; only -which broadcast holds each half moves (`P/A/B/S` in `.client/A` and in -`.server/B`). - -Update with it: - -- moq-boy (`rs/moq-boy`, `js/moq-boy`): the emulator is a server, viewers are - clients; drop `VIEWER_ID_PREFIX` and the emulator's refusal of `viewer-` - names. -- CARLA: trucks are servers, drivers clients; drop the `driver-` id prefix and - the worker's refusal of `driver-*` trucks. -- `demo/relay/prod.toml` and its documented `moq auth serve` line: anonymous - publish on `demo/boy/.client/*` and `demo/carla/.client/*`, subscribe on - their `.server/**`. -- The [hosted demo deploy](/quest/m3/release/demo-sockets-deploy.md) uses - these grants. - -Public API: breaks `moq-net`'s `socket` module, `@moq/net`'s `socket` export, -and moq-ffi's socket bindings wherever they name the layout. Wire: none (a -path convention), but endpoints on the old layout can't reach new ones. diff --git a/quest/m3/mesh/README.md b/quest/m3/mesh/README.md index 46b56ce1831..797e4282a40 100644 --- a/quest/m3/mesh/README.md +++ b/quest/m3/mesh/README.md @@ -53,9 +53,10 @@ Decided 2026-10-25 with the maintainer (planning interview), still in force: - The token is the binding: enrollment proves the device key, then the coordinator issues a grant to publish `mesh//**` and subscribe `mesh/**`, plus publish on its own [socket](/doc/concept/socket.md) - endpoint, `.socket/`, so it can dial and accept under its own id - (amended 2026-11-01, 2026-11-03 when sockets became endpoints, and - 2026-11-04 when the segment became `.socket`). Relays need no new check. Membership is the coordinator's + endpoints, `.server/` and `.client/`, so it can accept and dial + under its own id (amended 2026-11-01, 2026-11-03 when sockets became + endpoints, and 2026-11-06 when endpoints split into server and client + roles). Relays need no new check. Membership is the coordinator's token only; a Tailnet-Lock analog was declined. - Protection is per broadcast, with levels that nest: identity (the token only), authentication (per-frame Ed25519 signatures, the default), and diff --git a/quest/m3/mesh/endpoint.md b/quest/m3/mesh/endpoint.md index 279bf016102..cbd03ee47cb 100644 --- a/quest/m3/mesh/endpoint.md +++ b/quest/m3/mesh/endpoint.md @@ -18,12 +18,13 @@ Decided 2026-10-25 (maintainer): iroh-shaped, not drop-in compatible; tickets, - Decided 2026-11-01 (maintainer, socket planning interview), and updated 2026-11-03 when sockets became endpoints and 2026-11-04 when the segment became `.socket` with the protocol in the session name: an `Endpoint` wraps - a [socket](/doc/concept/socket.md) endpoint. Settle the layout here: such as - one socket endpoint per service at `mesh//.socket/`, or one per - node with the service named in the session. `connect` dials with the - caller's own endpoint ID, and `accept` reads the remote ID from the dial, - which the socket's answer check proves and the grant pins (publish - `.socket/` only). Update `moq auth`'s mesh grant and + a [socket](/doc/concept/socket.md) endpoint, which since 2026-11-06 is a + server at `.server/`, a client at `.client/`, or both. Settle the + layout here: such as one socket endpoint per service under + `mesh//`, or one per node with the service named in the session. + `connect` dials with the caller's own endpoint ID, and `accept` reads the + remote ID from the dial, which the socket's answer check proves and the + grant pins (publish `.server/` and `.client/` only). Update `moq auth`'s mesh grant and `doc/bin/relay/auth.md` to match. - Streams are [byte streams](/quest/m3/stream/rust.md) at the protection level the service declares: identity reads `moq-net` directly, and diff --git a/quest/m3/release/demo-sockets-deploy.md b/quest/m3/release/demo-sockets-deploy.md index 077d859ef13..ece3bb9f396 100644 --- a/quest/m3/release/demo-sockets-deploy.md +++ b/quest/m3/release/demo-sockets-deploy.md @@ -17,9 +17,8 @@ Main's moq-boy ([moq-dev/moq#8008](https://github.com/moq-dev/moq/pull/8008)) and CARLA ([moq-dev/moq#8011](https://github.com/moq-dev/moq/pull/8011)) talk over sockets, which need lite-07 (or moq-transport) on every hop. Until moq.dev's relays accept it, the released `` can't connect at all. -The grants below follow [socket roles](/quest/m1/socket-roles.md); if it -hasn't landed by the cut, use the `.socket/viewer-*` and `.socket/driver-*` -grants documented in `demo/relay/prod.toml` instead. +The grants below are the server and client socket roles that +`demo/relay/prod.toml` documents. ## Waiting diff --git a/quest/m3/stream/README.md b/quest/m3/stream/README.md index 5dd0332469d..9ad4c08ef53 100644 --- a/quest/m3/stream/README.md +++ b/quest/m3/stream/README.md @@ -43,8 +43,9 @@ Amended 2026-11-01 with the maintainer (socket planning interview), 2026-11-03 when sockets became endpoints, and 2026-11-04 when the socket's `tcp` protocol became one group each way: connection setup is the [socket](/doc/concept/socket.md) `Endpoint`, `dial_tcp`, and -`accept_tcp`, which settle the layout (`/.socket/`, a -`tcp///` track each way). Each TCP connection is one `tcp` +`accept_tcp`, which settle the layout (`/.server/` and +`/.client/`, a `tcp///` track each +way). Each TCP connection is one `tcp` session, whose halves are a single group each way for the connection's life: frames are writes, finishing is FIN, resetting is RST, and the writer awaits `group::Producer::ready` for backpressure. Each session gets its own priority, diff --git a/quest/m5/socket-old-hop-signal.md b/quest/m5/socket-old-hop-signal.md index ac61be45479..c112e03adeb 100644 --- a/quest/m5/socket-old-hop-signal.md +++ b/quest/m5/socket-old-hop-signal.md @@ -14,7 +14,7 @@ Planned 2026-11-04 with the maintainer, from the limit [moq-dev/moq#7888](https://github.com/moq-dev/moq/pull/7888) documented. Milestone m2 (maintainer). -Where it gets lost: an endpoint's `.socket/` broadcast is hidden, and +Where it gets lost: an endpoint's `.server/` broadcast is hidden, and before lite-07 ANNOUNCE_REQUEST has no hidden opt-in. When a peer `P` reaches its relay `R` over a moq-lite-06 (or older) client session whose publish half isn't opted into hidden routes, `R` never learns `P`'s @@ -35,7 +35,7 @@ look, and the evidence has to name the endpoint. Recommended design, to settle in this quest: -- **Find the endpoint.** When a dial's interest in `/.socket/` +- **Find the endpoint.** When a dial's interest in `/.server/` reaches a relay, the relay asks each of its older sessions whose publish grant covers that path, with an ANNOUNCE_REQUEST naming the path, held open while the dial waits so a peer that comes online later is seen. Such a @@ -57,7 +57,7 @@ Recommended design, to settle in this quest: see the dial, and a dial sends no SUBSCRIBE until the endpoint is announced. Settle how the dialer's narrow interest reaches the holding relay (for example, cluster links forwarding narrow interest under - `.socket`), and how markers cross cluster links. + `.server`), and how markers cross cluster links. - **Where the marker rides.** Its own announce-stream message, or a flag on the [route layer](/quest/m2/cluster-routing/routes/README.md)'s messages if that layer has landed. Choose whichever leaves the draft simpler. diff --git a/rs/moq-boy/src/input.rs b/rs/moq-boy/src/input.rs index 5ef1afbb43b..d5960ae6877 100644 --- a/rs/moq-boy/src/input.rs +++ b/rs/moq-boy/src/input.rs @@ -1,7 +1,7 @@ //! Viewer sessions and their commands. //! -//! The emulator runs a socket endpoint named for its game, and each viewer dials it in a -//! `track` session. Each group the viewer writes is one JSON command: button states or a +//! The emulator runs a server socket endpoint named for its game, and each viewer dials it +//! from a client endpoint in a `track` session. Each group the viewer writes is one JSON command: button states or a //! reset. The emulator answers each button command with that viewer's latency breakdown, //! one group per reply, on its own half of the session. A viewer is gone once its session //! ends, and a reload is a new session. @@ -227,7 +227,7 @@ mod tests { let (tx, rx) = tokio::sync::mpsc::channel(16); tokio::spawn(async move { handle_viewers(&game, &tx).await }); - let viewer = Endpoint::new(&origin, "boy", "viewer-alice").unwrap(); + let viewer = Endpoint::new(&origin, "boy", "alice").unwrap(); let session = kio::clock::timeout(Duration::from_secs(5), viewer.dial_track("tetris", None).unwrap()) .await .expect("dial timeout") diff --git a/rs/moq-boy/src/main.rs b/rs/moq-boy/src/main.rs index 29a8c4adc2b..157553d1e91 100644 --- a/rs/moq-boy/src/main.rs +++ b/rs/moq-boy/src/main.rs @@ -61,8 +61,9 @@ pub struct Config { #[usage(long, default = "boy")] pub prefix: String, - /// Path prefix for game broadcasts ("{prefix-game}/{name}") and the game's socket endpoint - /// ("{prefix-game}/.socket/{name}"), which viewers dial. Defaults to "{prefix}/game". + /// Path prefix for game broadcasts ("{prefix-game}/{name}"), the game's server endpoint + /// ("{prefix-game}/.server/{name}"), which viewers dial, and the viewers' client endpoints + /// ("{prefix-game}/.client/{id}"). Defaults to "{prefix}/game". #[usage(long)] pub prefix_game: Option, @@ -131,21 +132,12 @@ impl Config { } } -/// Viewer endpoints take ids under this prefix, which the relay lets anonymous sessions -/// publish, so no viewer can announce a game's endpoint. -const VIEWER_ID_PREFIX: &str = "viewer-"; - -/// Refuse a name that can't be the game's endpoint id: one path segment, outside the ids -/// viewers may announce. +/// Refuse a name that can't be the game's endpoint id: one path segment. fn check_name(name: &str) -> Result<()> { anyhow::ensure!( !name.is_empty() && !name.contains(['/', '\\']), "invalid --name {name:?}: a name is one path segment" ); - anyhow::ensure!( - !name.starts_with(VIEWER_ID_PREFIX), - "invalid --name {name:?}: {VIEWER_ID_PREFIX}* ids belong to viewers" - ); Ok(()) } @@ -296,7 +288,7 @@ async fn run(config: &Config) -> Result<()> { .context("failed to announce broadcast")?; tracing::info!(broadcast = %broadcast_path, instance = %route.instance(), "announced"); - // The endpoint viewers dial, at "{prefix-game}/.socket/{name}". + // The server endpoint viewers dial, at "{prefix-game}/.server/{name}" from its first accept. let endpoint = moq_net::socket::Endpoint::new(&origin, game_prefix, &name).context("failed to open endpoint")?; tracing::info!(url = %moq_tokio::RedactedUrl::new(&url), %name, broadcast = %broadcast_path, "connecting to relay"); @@ -596,12 +588,14 @@ mod tests { assert!(parse(&["--prefix", "/boy"]).game_prefix().is_err()); } - /// A game's endpoint id is its name, so a name is one segment outside the ids viewers - /// may announce. + /// A game's endpoint id is its name, so a name is one segment. Viewers are clients, + /// so even a name like theirs can't collide with one. #[test] fn names_are_game_endpoint_ids() { - check_name("tetris").unwrap(); - for name in ["viewer-1", "", "a/b", "a\\b"] { + for name in ["tetris", "viewer-1"] { + check_name(name).unwrap(); + } + for name in ["", "a/b", "a\\b"] { check_name(name).expect_err(name); } } diff --git a/rs/moq-ffi/src/socket.rs b/rs/moq-ffi/src/socket.rs index aead16417df..6f78a6d9b1a 100644 --- a/rs/moq-ffi/src/socket.rs +++ b/rs/moq-ffi/src/socket.rs @@ -9,7 +9,8 @@ use crate::ffi::{Background, Polled}; use crate::origin::MoqOriginProducer; use crate::producer::{MoqGroupProducer, MoqTrackInfo, MoqTrackProducer}; -/// An endpoint announcing one hidden broadcast and accepting TCP and track dials separately. +/// A socket endpoint: its first dial announces it as a client, and its first accept as a +/// server, which takes TCP and track dials separately. #[derive(uniffi::Object)] pub struct MoqSocketEndpoint { inner: moq_net::socket::Endpoint, @@ -18,7 +19,8 @@ pub struct MoqSocketEndpoint { #[uniffi::export] impl MoqSocketEndpoint { - /// Announce `id` beneath `prefix`, using `origin` for publishing and finding peers. + /// The endpoint `id` beneath `prefix`, using `origin` for publishing and finding peers. + /// Nothing is announced until its first dial or accept. #[uniffi::constructor] pub fn new(origin: &MoqOriginProducer, prefix: String, id: String) -> Result, MoqError> { let _guard = crate::ffi::enter(); @@ -42,13 +44,13 @@ impl MoqSocketEndpoint { self.inner.prefix().to_string() } - /// Retract the endpoint and reset its pending dials and sessions. + /// Retract the endpoint's broadcasts and reset its pending dials and sessions. pub fn close(&self) { let _guard = crate::ffi::enter(); self.inner.close(); } - /// Dial a new `tcp` session; cancelling this call resets only this dial. + /// Dial the server `peer` in a new `tcp` session; cancelling this call resets only this dial. pub async fn dial_tcp(&self, peer: String) -> Result, MoqError> { self.driver .watch(async { @@ -73,7 +75,7 @@ impl MoqSocketEndpoint { .await } - /// Dial a new `track` session; cancelling this call resets only this dial. + /// Dial the server `peer` in a new `track` session; cancelling this call resets only this dial. pub async fn dial_track( &self, peer: String, diff --git a/rs/moq-net/CHANGELOG.md b/rs/moq-net/CHANGELOG.md index 60287cad324..2ba4c996bec 100644 --- a/rs/moq-net/CHANGELOG.md +++ b/rs/moq-net/CHANGELOG.md @@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- `socket`: `Endpoint`, which announces a hidden `/.socket/` broadcast, dials other endpoints, and accepts their dials in two protocols: `tcp` sessions (`dial_tcp`, `accept_tcp`, `TcpStream`), one group each way as a reliable, ordered byte pipe, and `track` sessions (`dial_track`, `accept_track`, `TrackStream`), a track each way with one message per group. Dials and accepts fail `Unsupported` while the origin has a moq-lite client session before 07 whose publish half doesn't opt into hidden broadcasts, since its peer never hears the endpoint; see `doc/concept/socket.md`. +- `socket`: `Endpoint`, a server, a client, or both, which announces a hidden `/.client/` broadcast at its first dial and `/.server/` at its first accept, so grants decide its roles, dials servers, and accepts clients' dials in two protocols: `tcp` sessions (`dial_tcp`, `accept_tcp`, `TcpStream`), one group each way as a reliable, ordered byte pipe, and `track` sessions (`dial_track`, `accept_track`, `TrackStream`), a track each way with one message per group. Dials and accepts fail `Unsupported` while the origin has a moq-lite client session before 07 whose publish half doesn't opt into hidden broadcasts, since its peer never hears the endpoint; see `doc/concept/socket.md`. - `transport::SETUP_RECEIVE_WINDOW`, the connection credit a server offers before it admits a session: enough for the SETUP and one in-band AUTH. ## [0.3.10](https://github.com/moq-dev/moq/compare/moq-net-v0.3.9...moq-net-v0.3.10) - 2026-10-05 diff --git a/rs/moq-net/src/model/socket.rs b/rs/moq-net/src/model/socket.rs index ba96ab1004a..06e7e53a912 100644 --- a/rs/moq-net/src/model/socket.rs +++ b/rs/moq-net/src/model/socket.rs @@ -1,8 +1,11 @@ //! Point-to-point sessions over an origin, the way TCP connects two hosts. //! -//! An [`Endpoint`] announces one hidden broadcast, `/.socket/`, used only to -//! route dials to it. From it, an endpoint dials other endpoints and accepts their dials. -//! Each connection is a session: two tracks, one in each endpoint's broadcast, both named +//! An [`Endpoint`] is a server, a client, or both. As a server it announces the hidden +//! broadcast `/.server/` at its first accept, and peers dial it there. As a +//! client it announces `/.client/` at its first dial, and dials servers. The +//! broadcasts are used only to route sessions, so ordinary grants decide each endpoint's +//! roles. Each connection is a session: two tracks, one in the dialer's client broadcast +//! and one in the acceptor's server broadcast, both named //! `///`. Sessions are never announced or listed. //! //! A session speaks one of two protocols: @@ -15,9 +18,9 @@ //! `accept_track` or [`Endpoint::poll_accept_track`], and read and write a //! [`TrackStream`]. //! -//! A dialer `A` picks a random session id `S` and subscribes to `/.socket/` for +//! A dialer `A` picks a random session id `S` and subscribes to `/.server/` for //! the track `/A/B/S`. Endpoint `B` surfaces that request as an [`Incoming`] dial -//! from `A` in its protocol's queue. To accept it, `B` subscribes to `/.socket/` +//! from `A` in its protocol's queue. To accept it, `B` subscribes to `/.client/` //! for the same track name, and `A` answers only a session it dialed, so the exchange //! checks that `A` really asked `B`: a dial forged in `A`'s name is reset. Naming both ends //! binds a session to them, so an endpoint `A` dialed cannot replay the session to a third @@ -38,9 +41,6 @@ use super::origin::{self, RouteOptions}; use super::track::{self, Delay, Order, Subscription}; use super::{frame, group}; -/// The segment every endpoint's broadcast sits under. -const SOCKET: &str = ".socket"; - /// Refuse an id that is not one plain path segment: empty, or holding a `/` or a `\`. fn check_id(id: &str) -> Result<(), Error> { if id.is_empty() || id.contains(['/', '\\']) { @@ -49,10 +49,27 @@ fn check_id(id: &str) -> Result<(), Error> { Ok(()) } -/// `/.socket/`, the broadcast of the endpoint `id`. -fn endpoint_path(prefix: &Path, id: &str) -> Result { +/// What an endpoint's broadcast is for: a server accepts dials, and a client dials. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Role { + Server, + Client, +} + +impl Role { + /// The segment the role's broadcasts sit under. + fn segment(self) -> &'static str { + match self { + Self::Server => ".server", + Self::Client => ".client", + } + } +} + +/// `//`, the endpoint `id`'s broadcast in `role`. +fn endpoint_path(prefix: &Path, role: Role, id: &str) -> Result { check_id(id)?; - Ok(prefix.join(&Path::from_static(SOCKET))?.join(&Path::new(id)?)?) + Ok(prefix.join(&Path::from_static(role.segment()))?.join(&Path::new(id)?)?) } /// A fresh session id: 128 random bits as hex, so nobody can guess a session's tracks. @@ -114,13 +131,13 @@ mod sealed { pub struct Shared { pub(super) id: Arc, pub(super) prefix: Path, + /// Where this endpoint's broadcasts are announced, at first use. + pub(super) publisher: origin::Producer, /// Where the peers' endpoints are requested. pub(super) origin: origin::Consumer, /// Where the `tcp` sessions' pumps run: the origin's driver. pub(super) tasks: crate::util::TasksWeak, - /// This endpoint's route, which owns its broadcast. - pub(super) route: origin::Route, - /// The sessions withholding the broadcast from their peer. + /// The sessions withholding the broadcasts from their peer. pub(super) withheld: origin::HiddenWithheld, pub(super) state: kio::Lock, } @@ -336,13 +353,15 @@ struct Queue { waiting: kio::WaiterList, } -/// An endpoint's handler for the requests to its broadcast: the dials peers send. +/// An endpoint's handler for the requests to its server broadcast: the dials peers send. /// /// A poller takes it out to poll it with no lock held, since taking a request wakes the /// dialer's subscription, and an inline executor can re-enter the endpoint from that wake. +/// The client broadcast has none, so it answers a request for a session it does not hold +/// with [`Error::NotFound`] at once. enum Handler { - /// Not made yet, until the first accept, so the endpoint answers a request for a - /// session it does not hold with [`Error::NotFound`] at once. + /// Not made yet, until the first accept makes the server broadcast with it, or no + /// longer, once the endpoint ended. None, /// Waiting for a poller. Idle(super::broadcast::Requests), @@ -353,6 +372,10 @@ enum Handler { /// What the endpoint's pollers share. struct State { + /// The route of the broadcast this endpoint dials from, from its first dial on. + client: Option, + /// The route of the broadcast peers dial, from its first accept on. + server: Option, /// Where the dials peers send arrive. handler: Handler, tcp: Queue, @@ -379,20 +402,72 @@ impl State { } impl Shared { + /// This endpoint's broadcast in `role`, hidden until announced. + fn create(&self, role: Role) -> Result { + self.publisher + .route(endpoint_path(&self.prefix, role, &self.id)?, RouteOptions::hidden()) + } + + /// The route of the broadcast this endpoint dials from, announced by its first dial. + /// + /// Made outside the lock, since announcing wakes local consumers, and announced only + /// once it is the endpoint's, so a racing dial's spare is never seen. + fn client(&self) -> Result { + { + let state = self.state.lock(); + if let Some(err) = &state.end { + return Err(err.clone()); + } + if let Some(route) = &state.client { + return Ok(route.clone()); + } + } + let route = self.create(Role::Client)?; + let mut state = self.state.lock(); + if let Some(err) = &state.end { + return Err(err.clone()); + } + if let Some(route) = &state.client { + return Ok(route.clone()); + } + state.client = Some(route.clone()); + drop(state); + route.announce()?; + Ok(route) + } + + /// Make the broadcast peers dial, with its handler, and announce it: the first accept. + /// + /// Called by the poller holding [`Handler::Taken`], so no other makes one. + fn serve(&self) -> Result { + let route = self.create(Role::Server)?; + // Before announcing, so the first dial finds it. + let requests = route.broadcast().requests(); + let mut state = self.state.lock(); + if let Some(err) = &state.end { + return Err(err.clone()); + } + state.server = Some(route.clone()); + drop(state); + route.announce()?; + Ok(requests) + } + /// Queue every dial on hand and take the next in `protocol`, registering `waiter` for - /// more, and fail with the endpoint's end once it stopped. + /// more, and fail with the endpoint's end once it stopped. The first call announces the + /// server broadcast, and fails as [`origin::Producer::route`] does when the origin may + /// not publish it. /// - /// A dial of this endpoint's reserves its own track, so a request reaching the handler - /// with this endpoint as the dialer names a session it never dialed, or one it gave up, - /// such as an accept of a dial forged or replayed in this endpoint's name: it is reset - /// with [`Error::NotFound`], which fails that accept. So is a request naming another - /// acceptor, such as a session replayed from the endpoint it was dialed to. A request in - /// a protocol nobody accepts is reset with [`Error::Unsupported`]. + /// A request on the server broadcast naming this endpoint as the dialer names no dial + /// to it, since its own dials live in its client broadcast: it is reset with + /// [`Error::NotFound`]. So is a request naming another acceptor, such as a session + /// replayed from the endpoint it was dialed to. A request in a protocol nobody accepts + /// is reset with [`Error::Unsupported`]. /// /// The handler is polled with no lock held (see [`Handler`]), and resets and wakes go /// out after the lock is released. fn poll_dial(&self, protocol: Protocol, waiter: &kio::Waiter) -> Poll> { - let mut requests = { + let taken = { let mut state = self.state.lock(); state.queue(protocol).listening = true; if state.end.is_some() { @@ -402,12 +477,36 @@ impl Shared { None } else { match std::mem::replace(&mut state.handler, Handler::Taken(kio::WaiterList::new())) { - Handler::Idle(requests) => Some(requests), - Handler::None => Some(self.route.broadcast().requests()), + Handler::Idle(requests) => Some(Some(requests)), + // No server broadcast yet: this poller makes it. + Handler::None => Some(None), Handler::Taken(_) => unreachable!("checked above"), } } }; + let mut requests = match taken { + Some(None) => match self.serve() { + Ok(requests) => Some(requests), + Err(err) => { + // Given back for the next accept to try, waking those that found it taken, + // unless the endpoint closed meanwhile and took it. + let mut state = self.state.lock(); + let waiting = match &mut state.handler { + Handler::Taken(waiting) => Some(waiting.take()), + _ => None, + }; + if waiting.is_some() { + state.handler = Handler::None; + } + drop(state); + if let Some(mut waiting) = waiting { + waiting.wake(); + } + return Poll::Ready(Err(err)); + } + }, + taken => taken.flatten(), + }; let mut taken = Vec::new(); let mut ended = None; if let Some(requests) = &mut requests { @@ -431,12 +530,12 @@ impl Shared { state.end.get_or_insert(err); } // Put the handler back, unless the endpoint ended meanwhile: then it is dropped - // after the lock is released. + // after the lock is released, with the server broadcast if `close` hasn't taken it. if let Some(handler) = requests.take() { let next = match state.end { None => Handler::Idle(handler), Some(_) => { - retired = Some(handler); + retired = Some((handler, state.server.take())); Handler::None } }; @@ -492,11 +591,13 @@ impl Shared { } }; drop(state); - if let Some(retired) = retired { + if let Some((handler, server)) = retired { // Closed first, as `close` may not have yet: dropping the last handler rejects // the dials still queued with `Dropped`, rather than the close's `Unroutable`. - self.route.broadcast().close(); - drop(retired); + if let Some(server) = &server { + server.broadcast().close(); + } + drop(handler); } for mut wake in wakes { wake.wake(); @@ -521,13 +622,19 @@ impl Shared { /// Poll for the endpoint's end, registering `waiter` for it. fn poll_end(&self, waiter: &kio::Waiter) -> Result<(), Error> { - if let Some(err) = &self.state.lock().end { - return Err(err.clone()); - } - match self.route.broadcast().poll_closed(waiter) { - Poll::Ready(()) => Err(Error::Closed), - Poll::Pending => Ok(()), + let routes = { + let state = self.state.lock(); + if let Some(err) = &state.end { + return Err(err.clone()); + } + [state.client.clone(), state.server.clone()] + }; + for route in routes.iter().flatten() { + if route.broadcast().poll_closed(waiter).is_ready() { + return Err(Error::Closed); + } } + Ok(()) } fn close(&self) { @@ -550,9 +657,12 @@ impl Shared { wakes.push(queue.waiting.take()); } let streams = std::mem::take(&mut state.streams); + let routes = [state.client.take(), state.server.take()]; drop(guard); - self.route.broadcast().close(); + for route in routes.iter().flatten() { + route.broadcast().close(); + } // Reset outside the lock. for stream in streams { stream.abort(Error::Cancel); @@ -564,18 +674,23 @@ impl Shared { wake.wake(); } drop(requests); + drop(routes); } } -/// A socket endpoint: announces `/.socket/`, dials other endpoints, and -/// accepts their dials. +/// A socket endpoint: a server, a client, or both. +/// +/// Its first dial announces `/.client/`, which holds its half of each session +/// it dials, and its first accept announces `/.server/`, where peers dial it and +/// which holds its half of each session it accepts. So a pure client never announces a +/// server broadcast, and the origin's grants decide which roles it may take. /// /// It accepts dials in a protocol from that protocol's first accept on, like a TCP /// listener: before that, a dial in it is reset with [`Error::Unsupported`], and after it, -/// dials queue until accepted. Until the endpoint's first accept in any protocol, a dial -/// to it is reset with [`Error::NotFound`], as for any track nobody serves. +/// dials queue until accepted. Until the endpoint's first accept in any protocol, it has no +/// server broadcast, so a dial to it waits as for a peer not online yet. /// -/// Dropping it, or [`Self::close`], retracts the broadcast, resets the dials waiting to be +/// Dropping it, or [`Self::close`], retracts its broadcasts, resets the dials waiting to be /// accepted, and resets every session it handed out: a [`TcpStream`] entirely, and this /// side's half of a [`TrackStream`]. The peer's half of a [`TrackStream`] is read through /// its [`TrackStream::consumer`], which the application owns: drop the streams too, which @@ -595,29 +710,32 @@ pub struct Endpoint { } impl Endpoint { - /// Announce the endpoint `id` under `prefix` on `origin`, which also reaches the peers. + /// The endpoint `id` under `prefix` on `origin`, which also reaches the peers. Nothing + /// is announced until its first dial or accept. /// /// `id` names the endpoint: a well-known name for a server, or a random one for a - /// client. It must be one path segment. Fails like - /// [`origin::Producer::route`] when `origin` may not publish - /// `/.socket/`. + /// client. It must be one path segment. pub fn new( origin: &origin::Producer, prefix: impl TryInto>, id: &str, ) -> Result { let prefix = crate::path::convert(prefix)?; - let route = origin.route(endpoint_path(&prefix, id)?, RouteOptions::default())?; + for role in [Role::Server, Role::Client] { + endpoint_path(&prefix, role, id)?; + } let consumer = origin.consume(); Ok(Self { shared: Arc::new(Shared { id: id.into(), prefix, + publisher: origin.clone(), withheld: consumer.hidden_withheld(), origin: consumer, tasks: origin.tasks(), - route, state: kio::Lock::new(State { + client: None, + server: None, handler: Handler::None, tcp: Queue::default(), track: Queue::default(), @@ -633,23 +751,25 @@ impl Endpoint { &self.shared.id } - /// The prefix the endpoint's broadcast sits under, and where it finds its peers. + /// The prefix the endpoint's broadcasts sit under, and where it finds its peers. pub fn prefix(&self) -> &Path { &self.shared.prefix } - /// Dial the endpoint `peer` in a new `tcp` session, resolving once the peer accepts it. + /// Dial the server `peer` in a new `tcp` session, resolving once the peer accepts it. /// /// Waits for as long as the peer takes to accept: drop the returned future to give up, - /// which resets the session. That includes waiting for the peer's endpoint to be - /// announced. Fails with the peer's reset when it rejects the dial, or does not accept - /// `tcp` sessions, and with [`Error::Unsupported`] for a dial to this endpoint itself - /// or across a hop that can't carry it (see [`Endpoint`]). + /// which resets the session. That includes waiting for the peer's server broadcast to + /// be announced. Fails with the peer's reset when it rejects the dial, or does not + /// accept `tcp` sessions, and with [`Error::Unsupported`] for a dial to this endpoint + /// itself or across a hop that can't carry it (see [`Endpoint`]). The first dial + /// announces the client broadcast, and fails as [`origin::Producer::route`] does when + /// the origin may not publish it. pub fn dial_tcp(&self, peer: &str) -> Result>, Error> { self.dial(peer, None) } - /// Dial the endpoint `peer` in a new `track` session; see [`Self::dial_tcp`]. + /// Dial the server `peer` in a new `track` session; see [`Self::dial_tcp`]. /// /// `info` describes this side's half; `None` keeps every message until read, with no /// max age. @@ -663,18 +783,16 @@ impl Endpoint { fn dial(&self, peer: &str, info: Option) -> Result>, Error> { let shared = &self.shared; - let path = endpoint_path(&shared.prefix, peer)?; + let path = endpoint_path(&shared.prefix, Role::Server, peer)?; if peer == &*shared.id { return Err(Error::Unsupported); } - if let Some(err) = &shared.state.lock().end { - return Err(err.clone()); - } + let client = shared.client()?; let session = session_id(); let name = track_name(S::PROTOCOL.as_str(), &shared.id, peer, &session); // This side's half, waiting for the peer to ask for it, which only the peer can: // nobody else knows the session. - let answer = shared.route.broadcast().reserve_unlisted_track(name.clone())?; + let answer = client.broadcast().reserve_unlisted_track(name.clone())?; // Followed rather than requested, so a peer not announced yet is waited for. let resolving = Box::new(shared.origin.follow(path, None)?); Ok(kio::Pending::new(Dialing { @@ -709,7 +827,9 @@ impl Endpoint { /// [`Endpoint`]). /// /// The first call starts accepting `tcp` dials. They queue until taken, or until their - /// dialer gives up, so keep accepting, and accept or reject each one. + /// dialer gives up, so keep accepting, and accept or reject each one. The endpoint's + /// first accept in either protocol announces its server broadcast, and fails as + /// [`origin::Producer::route`] does when the origin may not publish it. #[cfg_attr(feature = "async", kio::wrapper)] pub fn poll_accept_tcp(&self, waiter: &kio::Waiter) -> Poll, Error>> { self.poll_accept(waiter) @@ -771,10 +891,12 @@ impl Incoming { let shared = self.shared.clone(); let (peer, session) = (self.peer.clone(), self.session.clone()); let request = self.request.take().expect("taken only by accept, reject or drop"); - // Followed rather than requested: the dialer announced its endpoint before it - // dialed, but a relay can deliver the dial first. A dial claiming an endpoint + // Followed rather than requested: the dialer announced its client broadcast before + // it dialed, but a relay can deliver the dial first. A dial claiming an endpoint // nobody announces waits for as long as its dialer holds it open. - let step = match endpoint_path(&shared.prefix, &peer).and_then(|path| shared.origin.follow(path, None)) { + let step = match endpoint_path(&shared.prefix, Role::Client, &peer) + .and_then(|path| shared.origin.follow(path, None)) + { Ok(following) => Step::Resolving(Box::new(following)), Err(err) => Step::Failed(err), }; @@ -1271,10 +1393,19 @@ mod tests { #[test] fn an_endpoint_path_holds_one_segment() { let prefix = Path::from_static("room"); - assert_eq!(endpoint_path(&prefix, "alice").unwrap().as_str(), "room/.socket/alice"); - assert!(endpoint_path(&prefix, "a/b").is_err()); - assert!(endpoint_path(&prefix, "").is_err()); - assert!(endpoint_path(&prefix, "a\\b").is_err()); + assert_eq!( + endpoint_path(&prefix, Role::Server, "alice").unwrap().as_str(), + "room/.server/alice" + ); + assert_eq!( + endpoint_path(&prefix, Role::Client, "alice").unwrap().as_str(), + "room/.client/alice" + ); + for role in [Role::Server, Role::Client] { + assert!(endpoint_path(&prefix, role, "a/b").is_err()); + assert!(endpoint_path(&prefix, role, "").is_err()); + assert!(endpoint_path(&prefix, role, "a\\b").is_err()); + } } /// Taking a dial wakes the dialer's subscription, and an inline executor can re-enter @@ -1307,7 +1438,8 @@ mod tests { // Listening, so the dial queues for the handler. assert!(endpoint.poll_accept_tcp(&noop).is_pending()); - let broadcast = endpoint.shared.route.broadcast().consume(); + let server = endpoint.shared.state.lock().server.clone().unwrap(); + let broadcast = server.broadcast().consume(); let dial = broadcast .track("tcp/alice/bob/0123456789abcdef0123456789abcdef") .unwrap() @@ -1347,7 +1479,8 @@ mod tests { assert!(endpoint.poll_accept_track(&noop).is_pending()); assert!(endpoint.poll_accept_tcp(&noop).is_pending()); - let broadcast = endpoint.shared.route.broadcast().consume(); + let server = endpoint.shared.state.lock().server.clone().unwrap(); + let broadcast = server.broadcast().consume(); let queued = || endpoint.shared.state.lock().track.dials.len(); let dial = |session: u32| { let dial = broadcast diff --git a/rs/moq-net/tests/integration/socket.rs b/rs/moq-net/tests/integration/socket.rs index 82a8d4320a0..2bd90f5f6d1 100644 --- a/rs/moq-net/tests/integration/socket.rs +++ b/rs/moq-net/tests/integration/socket.rs @@ -78,6 +78,12 @@ impl Fixture { } } +/// Start `endpoint` accepting `tcp` dials, which announces its server broadcast, for a +/// test that dials it by hand. +fn listen(endpoint: &Endpoint) { + assert!(endpoint.poll_accept_tcp(&kio::Waiter::noop()).is_pending()); +} + const MB: usize = 1 << 20; /// Dial `acceptor` from `dialer` in a `tcp` session while `acceptor` accepts, returning @@ -292,12 +298,13 @@ struct ByHand { async fn dial_by_hand(fixture: &mut Fixture, bob: &Endpoint) -> ByHand { let carol = fixture.client(LITE).await; let endpoint = carol - .route("room/.socket/carol", moq_net::origin::RouteOptions::hidden()) + .route("room/.client/carol", moq_net::origin::RouteOptions::hidden()) .unwrap(); endpoint.announce().unwrap(); let mut requests = endpoint.broadcast().requests(); let name = "tcp/carol/bob/0123456789abcdef0123456789abcdef"; - let broadcast = kio::clock::timeout(TIMEOUT, carol.consume().request("room/.socket/bob", None)) + listen(bob); + let broadcast = kio::clock::timeout(TIMEOUT, carol.consume().request("room/.server/bob", None)) .await .expect("request timeout") .expect("bob's endpoint"); @@ -544,7 +551,7 @@ async fn a_protocol_nobody_accepts_is_reset() { // An unknown protocol is reset too. let mallory = fixture.client(LITE).await; - let broadcast = kio::clock::timeout(TIMEOUT, mallory.consume().request("room/.socket/bob", None)) + let broadcast = kio::clock::timeout(TIMEOUT, mallory.consume().request("room/.server/bob", None)) .await .expect("request timeout") .expect("bob's endpoint"); @@ -588,9 +595,10 @@ async fn a_dial_waits_for_its_peer() { async fn an_accept_waits_for_its_dialer() { let mut fixture = Fixture::new(); let bob = fixture.endpoint(LITE, "bob").await; + listen(&bob); let carol = fixture.client(LITE).await; let name = "tcp/carol/bob/0123456789abcdef0123456789abcdef"; - let broadcast = kio::clock::timeout(TIMEOUT, carol.consume().request("room/.socket/bob", None)) + let broadcast = kio::clock::timeout(TIMEOUT, carol.consume().request("room/.server/bob", None)) .await .expect("request timeout") .expect("bob's endpoint"); @@ -608,7 +616,7 @@ async fn an_accept_waits_for_its_dialer() { ); let endpoint = carol - .route("room/.socket/carol", moq_net::origin::RouteOptions::hidden()) + .route("room/.client/carol", moq_net::origin::RouteOptions::hidden()) .unwrap(); let mut requests = endpoint.broadcast().requests(); endpoint.announce().unwrap(); @@ -630,8 +638,9 @@ async fn an_accept_waits_for_its_dialer() { async fn an_accept_ends_with_its_dial() { let mut fixture = Fixture::new(); let bob = fixture.endpoint(LITE, "bob").await; + listen(&bob); let mallory = fixture.client(LITE).await; - let broadcast = kio::clock::timeout(TIMEOUT, mallory.consume().request("room/.socket/bob", None)) + let broadcast = kio::clock::timeout(TIMEOUT, mallory.consume().request("room/.server/bob", None)) .await .expect("request timeout") .expect("bob's endpoint"); @@ -667,8 +676,9 @@ async fn a_replayed_session_never_connects() { let session = accepted.session().to_string(); // Replayed from bob's side, which knows the session. + listen(&carol); let mallory = fixture.client(LITE).await; - let broadcast = kio::clock::timeout(TIMEOUT, mallory.consume().request("room/.socket/carol", None)) + let broadcast = kio::clock::timeout(TIMEOUT, mallory.consume().request("room/.server/carol", None)) .await .expect("request timeout") .expect("carol's endpoint"); @@ -719,8 +729,11 @@ async fn a_forged_dial_never_connects() { let alice = fixture.endpoint(LITE, "alice").await; let bob = fixture.endpoint(LITE, "bob").await; let mallory = fixture.client(LITE).await; + // Alice is a client, dialing elsewhere, so her client broadcast answers bob. + let _elsewhere = alice.dial_tcp("carol").unwrap(); + listen(&bob); - let broadcast = kio::clock::timeout(TIMEOUT, mallory.consume().request("room/.socket/bob", None)) + let broadcast = kio::clock::timeout(TIMEOUT, mallory.consume().request("room/.server/bob", None)) .await .expect("request timeout") .expect("bob's endpoint"); @@ -754,7 +767,7 @@ async fn a_forged_dial_never_connects() { let forged = kio::clock::timeout(TIMEOUT, forged).await.expect("forged timeout"); assert!(forged.is_err(), "the forger read bob's {protocol} half"); - // Alice never heard of it as a dial either. + // Alice never heard of it as a dial either, even accepting. assert!(kio::clock::timeout(SETTLE, alice.accept_tcp()).await.is_err()); assert!(kio::clock::timeout(SETTLE, alice.accept_track()).await.is_err()); } @@ -832,8 +845,8 @@ async fn session_tracks_are_never_listed() { ); let eve = fixture.client(LITE).await; - for id in ["alice", "bob"] { - let broadcast = kio::clock::timeout(TIMEOUT, eve.consume().request(format!("room/.socket/{id}"), None)) + for id in [".client/alice", ".server/bob"] { + let broadcast = kio::clock::timeout(TIMEOUT, eve.consume().request(format!("room/{id}"), None)) .await .expect("request timeout") .expect("the endpoint"); @@ -851,17 +864,41 @@ async fn session_tracks_are_never_listed() { dialed.producer.finish().unwrap(); } -/// An endpoint takes dials only from its first accept on, like a TCP listener: before it, -/// a dial is reset rather than left waiting. +/// An endpoint announces only the roles it takes: its first dial its client broadcast, +/// and its first accept its server broadcast. So a dial to an endpoint that has only +/// dialed finds no server and waits, until that endpoint accepts. #[kio::test] -async fn an_endpoint_not_accepting_resets_dials() { +async fn an_endpoint_announces_only_its_roles() { let mut fixture = Fixture::new(); let alice = fixture.endpoint(LITE, "alice").await; - let _bob = fixture.endpoint(LITE, "bob").await; - let dialed = kio::clock::timeout(TIMEOUT, alice.dial_tcp("bob").unwrap()) + let bob = fixture.endpoint(LITE, "bob").await; + let _elsewhere = bob.dial_tcp("carol").unwrap(); + let mut dial = alice.dial_tcp("bob").unwrap(); + assert!( + kio::clock::timeout(SETTLE, &mut dial).await.is_err(), + "a dial reached an endpoint that only dials" + ); + + let eve = fixture.client(LITE).await; + for (path, announced) in [ + ("room/.client/alice", true), + ("room/.client/bob", true), + ("room/.server/alice", false), + ("room/.server/bob", false), + ] { + let found = kio::clock::timeout(SETTLE, eve.consume().request(path, None)).await; + assert_eq!(matches!(found, Ok(Ok(_))), announced, "{path}"); + } + + let accept = async { bob.accept_tcp().await?.accept().await }; + let (dialed, accepted) = kio::clock::timeout(TIMEOUT, async { futures::join!(dial, accept) }) .await - .expect("dial timeout"); - assert!(dialed.is_err(), "a dial to an endpoint not accepting connected"); + .expect("connect timeout"); + let (mut dialed, accepted) = (dialed.unwrap(), accepted.unwrap()); + assert_eq!(dialed.session(), accepted.session()); + dialed.producer.finish().unwrap(); + let found = kio::clock::timeout(TIMEOUT, eve.consume().request("room/.server/bob", None)).await; + assert!(matches!(found, Ok(Ok(_))), "bob's server broadcast"); } /// An acceptor can finish its initial burst before the dialer gets the answer. diff --git a/rs/moq-relay/tests/integration/socket_auth.rs b/rs/moq-relay/tests/integration/socket_auth.rs index 1803c651b86..e57e2296359 100644 --- a/rs/moq-relay/tests/integration/socket_auth.rs +++ b/rs/moq-relay/tests/integration/socket_auth.rs @@ -1,10 +1,12 @@ //! Sockets through a relay that admits with `moq-auth` tokens, verified by the reference //! auth server, granting only the prefixes `doc/concept/socket.md` lists. //! -//! Every token is rooted at the socket prefix `room`. An endpoint's token publishes its own -//! endpoint, `.socket/`, and subscribes to every endpoint, `.socket/**`, so the -//! session track names are what keep third parties out: a forged dial never connects, and no -//! listing gives a session's name away. +//! Every token is rooted at the socket prefix `room`. A server's token publishes its own +//! endpoint, `.server/`, and subscribes to every client, `.client/**`; a client's token +//! publishes `.client/` and subscribes to every server, `.server/**`. So a client can't +//! pose as a server or read another client, and the session track names are what keep +//! third parties out of a server's sessions: a forged dial never connects, and no listing +//! gives a session's name away. use std::time::Duration; @@ -114,11 +116,20 @@ impl Fixture { Ok(session) } - /// The endpoint `id`'s client, holding the grants `doc/concept/socket.md` lists: publish - /// its own endpoint, subscribe to every endpoint. - async fn endpoint(&self, id: &str, version: &str) -> (Endpoint, moq_net::origin::Producer, moq_net::Session) { + /// The endpoint `id` in `role`, holding the grants `doc/concept/socket.md` lists for it: + /// publish its own endpoint, subscribe to every endpoint of the other role. + async fn endpoint( + &self, + role: Role, + id: &str, + version: &str, + ) -> (Endpoint, moq_net::origin::Producer, moq_net::Session) { + let (own, peers) = match role { + Role::Server => (".server", ".client"), + Role::Client => (".client", ".server"), + }; let (origin, session) = self - .client(&self.token(&format!(".socket/{id}"), ".socket/**"), version) + .client(&self.token(&format!("{own}/{id}"), &format!("{peers}/**")), version) .await; // The session is rooted at the prefix, so the endpoint's prefix is the root. let endpoint = Endpoint::new(&origin, "", id).expect("endpoint"); @@ -126,6 +137,13 @@ impl Fixture { } } +/// Which grants an endpoint's token holds. +#[derive(Clone, Copy)] +enum Role { + Server, + Client, +} + /// Dial `acceptor` from `dialer` in a `tcp` session while `acceptor` accepts, returning /// both ends. async fn connect_tcp(dialer: &Endpoint, acceptor: &Endpoint) -> (TcpStream, TcpStream) { @@ -190,8 +208,8 @@ async fn recv(reader: &mut moq_net::track::Ordered) -> Vec { async fn prefix_grants_admit_a_session() { for (dialer, acceptor) in [(LITE, LITE), (LITE, IETF), (IETF, LITE)] { let fixture = Fixture::new().await; - let (alice, _alice_origin, _alice_session) = fixture.endpoint("alice", dialer).await; - let (bob, _bob_origin, _bob_session) = fixture.endpoint("bob", acceptor).await; + let (alice, _alice_origin, _alice_session) = fixture.endpoint(Role::Client, "alice", dialer).await; + let (bob, _bob_origin, _bob_session) = fixture.endpoint(Role::Server, "bob", acceptor).await; let (mut dialed, mut accepted) = connect_tcp(&alice, &bob).await; dialed.producer.write_frame(None, &b"ping"[..]).expect("write"); assert_eq!(read(&mut accepted.consumer).await, b"ping", "{dialer} to {acceptor}"); @@ -210,25 +228,25 @@ async fn prefix_grants_admit_a_session() { } } -/// Mallory may read every endpoint, so she can ask bob for a session in alice's name. Bob -/// sees a dial from alice, but alice never dialed it and resets his accept, so it never -/// connects and mallory reads nothing. +/// Mallory, a client, may dial every server, so she can ask bob for a session in alice's +/// name. Bob sees a dial from alice, but alice never dialed it and resets his accept, so it +/// never connects and mallory reads nothing. #[tokio::test] async fn a_forged_dial_never_connects() { let fixture = Fixture::new().await; - let (alice, _alice_origin, _alice_session) = fixture.endpoint("alice", LITE).await; - let (bob, _bob_origin, _bob_session) = fixture.endpoint("bob", LITE).await; - let (_mallory, mallory_origin, _mallory_session) = fixture.endpoint("mallory", LITE).await; - // Alice keeps accepting, as a server would, which is how she resets the forged accept. - let alice_accepts = async { - let _ = alice.accept_tcp().await; - panic!("alice heard of a dial"); - }; + let (alice, _alice_origin, _alice_session) = fixture.endpoint(Role::Client, "alice", LITE).await; + let (bob, _bob_origin, _bob_session) = fixture.endpoint(Role::Server, "bob", LITE).await; + let (_mallory, mallory_origin, _mallory_session) = fixture.endpoint(Role::Client, "mallory", LITE).await; + // Alice dials elsewhere, so her client endpoint is there to reset the forged accept. + let _elsewhere = alice.dial_tcp("carol").expect("dial"); + + // Bob's first accept announces his server endpoint. + assert!(bob.poll_accept_tcp(&kio::Waiter::noop()).is_pending()); let forge = async { let broadcast = mallory_origin .consume() - .request(".socket/bob", None) + .request(".server/bob", None) .await .expect("bob's endpoint"); let forged = broadcast @@ -241,14 +259,61 @@ async fn a_forged_dial_never_connects() { assert!(accepted.is_err(), "bob connected to a forged dial"); assert!(forged.is_err(), "mallory read bob's half"); }; - kio::clock::timeout(TIMEOUT, async { - futures::select_biased! { - () = futures::FutureExt::fuse(Box::pin(forge)) => {} - () = futures::FutureExt::fuse(Box::pin(alice_accepts)) => {} + kio::clock::timeout(TIMEOUT, forge).await.expect("forge timeout"); +} + +/// A client's grant keeps it a client: an accept announces a server endpoint the relay +/// never carries, so no dial reaches it, and another client's endpoint is out of reach. +/// +/// Each absence is read by a session that connects once the relay holds everything it +/// could have carried, so its first sync with the relay would have listed it. +#[tokio::test] +async fn a_client_grant_neither_serves_nor_reads_clients() { + let fixture = Fixture::new().await; + let (alice, _alice_origin, _alice_session) = fixture.endpoint(Role::Client, "alice", LITE).await; + let (_bob, bob_origin, _bob_session) = fixture.endpoint(Role::Server, "bob", LITE).await; + // Bob, a server, reads a client endpoint once the relay carries it. + let carried = |id: &'static str| { + let origin = bob_origin.consume(); + async move { + kio::clock::timeout(TIMEOUT, origin.request(id, None)) + .await + .expect("request timeout") + .unwrap_or_else(|err| panic!("{id}: {err}")); } - }) - .await - .expect("forge timeout"); + }; + + // Alice dials, which announces her client endpoint. + let _alice_dial = alice.dial_tcp("carol").expect("dial"); + carried(".client/alice").await; + + // Mallory, a client, can't read it. + let (mallory, mallory_origin, _mallory_session) = fixture.endpoint(Role::Client, "mallory", LITE).await; + let read = kio::clock::timeout(TIMEOUT, mallory_origin.consume().request(".client/alice", None)) + .await + .expect("request timeout"); + assert!( + matches!(read, Err(moq_net::Error::Unroutable)), + "mallory read alice's endpoint: {:?}", + read.err() + ); + + // Mallory accepts as a server would, then dials, announcing her client endpoint after + // her server one on the same session: once it is carried, the relay decided both. + assert!(mallory.poll_accept_tcp(&kio::Waiter::noop()).is_pending()); + let _mallory_dial = mallory.dial_tcp("bob").expect("dial"); + carried(".client/mallory").await; + + // So no dial can reach her. + let (_dave, dave_origin, _dave_session) = fixture.endpoint(Role::Client, "dave", LITE).await; + let served = kio::clock::timeout(TIMEOUT, dave_origin.consume().request(".server/mallory", None)) + .await + .expect("request timeout"); + assert!( + matches!(served, Err(moq_net::Error::Unroutable)), + "the relay carried mallory's server endpoint: {:?}", + served.err() + ); } /// A reader allowed every endpoint lists both ends of a running session and finds no @@ -256,8 +321,8 @@ async fn a_forged_dial_never_connects() { #[tokio::test] async fn a_reader_of_everything_lists_no_session() { let fixture = Fixture::new().await; - let (alice, _alice_origin, _alice_session) = fixture.endpoint("alice", LITE).await; - let (bob, _bob_origin, _bob_session) = fixture.endpoint("bob", LITE).await; + let (alice, _alice_origin, _alice_session) = fixture.endpoint(Role::Client, "alice", LITE).await; + let (bob, _bob_origin, _bob_session) = fixture.endpoint(Role::Server, "bob", LITE).await; let (mut dialed, mut accepted) = connect_tcp(&alice, &bob).await; dialed.producer.write_frame(None, &b"secret"[..]).expect("write"); assert_eq!(read(&mut accepted.consumer).await, b"secret"); @@ -265,9 +330,9 @@ async fn a_reader_of_everything_lists_no_session() { send(&track_dialed.producer, b"secret"); assert_eq!(recv(&mut track_accepted.consumer.ordered()).await, b"secret"); - let (eve_origin, _eve_session) = fixture.client(&fixture.token(".socket/eve", "**"), LITE).await; - for id in ["alice", "bob"] { - let broadcast = kio::clock::timeout(TIMEOUT, eve_origin.consume().request(format!(".socket/{id}"), None)) + let (eve_origin, _eve_session) = fixture.client(&fixture.token(".client/eve", "**"), LITE).await; + for id in [".client/alice", ".server/bob"] { + let broadcast = kio::clock::timeout(TIMEOUT, eve_origin.consume().request(id, None)) .await .expect("request timeout") .expect("the endpoint"); diff --git a/swift/Sources/Moq/Socket.swift b/swift/Sources/Moq/Socket.swift index ce39e3456be..7dec5e5cd21 100644 --- a/swift/Sources/Moq/Socket.swift +++ b/swift/Sources/Moq/Socket.swift @@ -1,14 +1,15 @@ import MoqFFI -/// Point-to-point sessions over hidden endpoint broadcasts. +/// Point-to-point sessions between server and client endpoints. public enum Socket {} extension Socket { - /// Announces one endpoint and dials or accepts independent TCP and track sessions. + /// A server, a client, or both: dials or accepts independent TCP and track sessions. public final class Endpoint: Sendable { let ffi: MoqSocketEndpoint - /// Announce `id` beneath `prefix`, using `origin` to find peers. + /// The endpoint `id` beneath `prefix`, using `origin` to find peers. Its first dial + /// announces it as a client, and its first accept as a server. public init(origin: OriginProducer, prefix: String, id: String) throws { ffi = try MoqSocketEndpoint(origin: origin.ffi, prefix: prefix, id: id) } @@ -17,7 +18,7 @@ extension Socket { public var id: String { ffi.id() } /// The shared endpoint prefix. public var prefix: String { ffi.prefix() } - /// Retract the endpoint and reset its pending dials and sessions. + /// Retract the endpoint's broadcasts and reset its pending dials and sessions. public func close() { ffi.close() } /// Dial a new tcp session; cancelling resets this dial. diff --git a/test/interop/socket.sh b/test/interop/socket.sh index 42fd013e36c..98edff2f4ad 100644 --- a/test/interop/socket.sh +++ b/test/interop/socket.sh @@ -33,13 +33,13 @@ run_socket_pair() { mkfifo "$events" "$ack" exec 8<>"$events" 9<>"$ack" from=$(relay_next_line) - # Grant each peer only its own route and the shared socket subtree. + # Grant each peer only its own endpoint and the other role's endpoints. harness_spawn "$name-accept" "$LOGS/$name-accept.log" run_socket_acceptor "$events" "$ack" "$acceptor" accept \ - "$(token_url --root "$prefix" --publish '.socket/acceptor' --subscribe '.socket/**')" "$prefix" "$protocol" "$version" + "$(token_url --root "$prefix" --publish '.server/acceptor' --subscribe '.client/**')" "$prefix" "$protocol" "$version" pid="$HARNESS_PID" if IFS= read -r -t "$TIMEOUT" ready <&8 && [[ "$ready" == 'socket ready' ]]; then harness_spawn "$name-dial" "$LOGS/$name-dial.log" run_socket_client "$dialer" dial \ - "$(token_url --root "$prefix" --publish '.socket/dialer' --subscribe '.socket/**')" "$prefix" "$protocol" "$version" + "$(token_url --root "$prefix" --publish '.client/dialer' --subscribe '.server/**')" "$prefix" "$protocol" "$version" dial_pid="$HARNESS_PID" harness_wait "$dial_pid" || true if grep -qx "socket verified $protocol dial" "$LOGS/$name-dial.log"; then