Repository navigation
Description
Part of #1635.
Scope
A standalone worker and a gateway accept a WebSocket upgrade on /v1/session that carries the daemon protocol, so a remote program with an agent or operator token can say hello and make every call it makes on the local socket, pushes included. The token, not hello, sets the session's role, principal, name and via. A message over 32 MiB or a binary one closes the socket, a silent peer is closed, a proxy identity's session ends at its expiry, and simlock token revoke closes the token's open sessions at once. No client uses the path yet; the next task adds one.
A user would notice: a session that gets a role or principal other than its token's, a revoked token still working on an open session, a lease socket or the uplink that stops working, or a worker or gateway that fails to start.
Technical spec
Commit 1cd9315.
Rows
Behaviours: B1, B2, B3, B4, B12
Interfaces: I1, I2
Existing code: X1, X2, X3, X4, X5, X6, X18, X20, X23, X24, X19 (gateway/access-control.mdx, using-devices/remote-agents.mdx's list of routes)
Facts
| # | Fact | Source |
|---|---|---|
| F1 | A lease socket's upgrade runs the whole HTTP app (requireAuth included) through app.leaseSocket, which a capture turns into an accept or a refusal Response before handleUpgrade |
src/ports/upgrade-router.ts:59-94 |
| F2 | buildHttpSession builds the HTTP dispatch session (principal, name, role, via) from an Identity |
src/http/dispatcher-session.ts:39, :72-75 |
| F3 | The daemon accepts a connection in #accept(socket, forcedRole?, link?); the role is resolved at hello unless forced |
src/daemon/server.ts:476-510, src/daemon/server-hello.ts:79-84 |
| F4 | The uplink's WebSocket connection adapter buffers text until the first data listener and keeps binary apart; it is the model for the session's adapter | src/ports/uplink-websocket.ts:57, :74-94 |
| F5 | The server reads a connection by appending each chunk to a buffer and splitting on \n, with no line cap of its own |
src/daemon/server.ts:512-526 |
| F6 | A worker's token.revoke only revokes; a gateway's also calls closeUplinksForToken |
src/daemon/dispatcher-admin.ts:66-68, src/gateway/dispatcher.ts:430-434 |
| F7 | The router's lease-socket ping interval is 15 s | src/ports/upgrade-router.ts:35 |
Modules touched
src/ports/ (upgrade-router.ts, which holds the session's WebSocket adapter or keeps it in a file out of the barrel as uplink-websocket.ts is, testing.ts, AGENTS.md), src/http/ (app.ts, the session route and its declaration in route-declarations.ts, server.ts comment, AGENTS.md), src/daemon/ (server.ts, server-connection.ts (the session's identity, token id and expiry on Connection), server-hello.ts, server-requests.ts, dispatcher-admin.ts, dispatcher-options.ts (the worker's close-sessions hook for token.revoke), worker-composition.ts, main.ts, AGENTS.md), src/gateway/dispatcher.ts (revoke), src/contract/protocol.ts (CORE_ROUTE_SEGMENTS, PROTOCOL_VERSION_RANGE), and the website pages gateway/access-control.mdx and using-devices/remote-agents.mdx. Searches: createUpgradeRouter, onServerCreated, forcedRole, acceptUplink, closeUplinksForToken, tokenRevoke, CORE_ROUTE_SEGMENTS, isGatewayUplink.
flowchart LR
router[ports: upgrade router] --> app[http: session route + auth]
app --> server[daemon: accept with identity]
server --> hello[daemon: hello keeps identity]
revoke[daemon + gateway: token.revoke] --> server
Rules in play
- ADR 0081 §1–2: one path, identity from the token, revoke closes sessions.
- ADR 0003 §2: the same dispatcher; §4–5 as narrowed by ADR 0081.
src/contract/AGENTS.md(Protocol version): addingsessiontoCORE_ROUTE_SEGMENTSbumpsmaxby one;minstays. A worker serves only enrolled devices on a platform whose virtualDevices is false #1598 bumps it too (toolchain: two contract-shape tasks overlap), so this task waits for it.src/ports/AGENTS.md: onlyuplink-websocket.ts,upgrade-router.tsandwebsocket-client.tsnamews; the session adapter sits in one of the first two or keeps out of the barrel like them. Every wait bounded (pings, expiry).src/http/AGENTS.md:requireAuthon every route but healthz; the cross-site check covers the upgrade;core-routes.test.tschecks the new route is declared.src/daemon/AGENTS.md(Connections): "admin comes only from a credential athello" changes to name the session path; edit the manual in this PR.- Documentation rule 9: the two website pages.
Tests
Seam: the HTTP listener with createUpgradeRouter and a ws test client against a worker and a gateway with fake drivers (models: src/ports/upgrade-router.test.ts, src/ports/uplink-websocket.test.ts, src/daemon/server-roles.test.ts, src/daemon/server-pushes.test.ts).
- B1: a session opened on a worker and a gateway: agent token; operator token; no
Authorization; unknown or revoked token; worker join token; proxy identity same-origin; proxy identity cross-site;/v1/session/x;identity.getnamesviaand the token's name - B2:
helloover a session: aprincipalclaim (ignored); acredential(refused, closed); a range below the daemon's; a request beforehello - B3: calls and pushes over a session:
lease.requestprogress and grant with the token's owner;requesterId; the same idempotency key from a second session while waiting (attaches); release from a second session (lease-lost); TTL expiry (lease-lost); agentlease.list;events.subscribewith an operator token; close mid-request (request and lease go on) - B4: a session's limits: a 33 MiB message; a 9 MiB
device.exec; a binary message; no pong for two intervals; a proxy identity'sexpiresAt - B12:
token.revokeon a worker and a gateway: one session (closed 4003); two sessions; another token's session (open); the revoked token's lease (runs to its TTL); a reconnect (401)
Done when
pnpm test:changedpasses, with every Tests line above as a test.pnpm checkpasses, the protocol-bump check included:maxis one above the valuemainholds when this lands.- The website build passes:
pnpm --dir website install && pnpm --dir website build && node website/scripts/check-openapi.mjs. src/http/server.tsno longer says a worker upgrades nothing.
Out of scope
- Any client of the path (connectSimlock and connectSimlockAdmin reach a remote farm with a URL and a token #1640), the CLI (Every simlock command runs against a remote farm with --url or SIMLOCK_URL and a token #1641).
Depends on
Written by an agent.
Activity