Skip to content

A worker and a gateway serve the daemon protocol on /v1/session with the token's identity #1639

Open

Description

@V3RON

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
Loading

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): adding session to CORE_ROUTE_SEGMENTS bumps max by one; min stays. 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: only uplink-websocket.ts, upgrade-router.ts and websocket-client.ts name ws; 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: requireAuth on every route but healthz; the cross-site check covers the upgrade; core-routes.test.ts checks the new route is declared.
  • src/daemon/AGENTS.md (Connections): "admin comes only from a credential at hello" 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.get names via and the token's name
  • B2: hello over a session: a principal claim (ignored); a credential (refused, closed); a range below the daemon's; a request before hello
  • B3: calls and pushes over a session: lease.request progress 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); agent lease.list; events.subscribe with 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's expiresAt
  • B12: token.revoke on 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:changed passes, with every Tests line above as a test.
  • pnpm check passes, the protocol-bump check included: max is one above the value main holds when this lands.
  • The website build passes: pnpm --dir website install && pnpm --dir website build && node website/scripts/check-openapi.mjs.
  • src/http/server.ts no longer says a worker upgrades nothing.

Out of scope

Depends on

Written by an agent.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    task:readySpec checked. An agent may implement it once its Depends on allow.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions