Repository navigation
Description
Part of #1635.
Scope
A Node.js program on another machine calls connectSimlock({ url, token }) or connectSimlockAdmin({ url, token }) and gets the same typed client it gets on the daemon's machine, talking to a standalone worker or a gateway over the session path: leases, renewals, pushes and version checks all work. A farm that cannot be reached is REMOTE_UNREACHABLE, a refused token UNAUTHENTICATED, a revoked one ends the session with UNAUTHENTICATED, and 45 s with no ping from the farm is a lost connection. The URL rule moves out of simlock tunnel into one shared function, with tunnel accepting and refusing exactly the URLs and tokens it does today; only its messages say "farm" for "worker".
A user would notice: a client that hangs on a dead network, a reply cut short, an error code a program cannot match, or simlock tunnel accepting or refusing a URL differently than before.
Technical spec
Commit 1cd9315.
Rows
Behaviours: B5
Interfaces: I3, I4, I5
Existing code: X7, X8, X9 (the rule half), X21, X22, X19 (using-devices/programmatic-client.mdx, reference/errors.mdx)
Facts
| # | Fact | Source |
|---|---|---|
| F1 | The client takes either a connection or a connector with an endpoint, and throws otherwise |
src/simlock-client/client.ts:186-194 |
| F2 | A version mismatch at hello gives a degraded client, not a throw |
src/simlock-client/client.ts:165-168 |
| F3 | connectSimlock sends no credential, so its session is agent on the socket |
src/client/index.ts:55-57 |
| F4 | ws is loaded with import() on the first connect, so the CLI and MCP load it only when they use it |
src/ports/websocket-client.ts:88-91 |
| F5 | The local connect waits at most 10 s | src/ports/ipc.ts:52 |
| F6 | tunnel's URL rule, its messages and its bounds: MAX_URL_CHARS 2048, MAX_TOKEN_CHARS 4096 |
src/cli/commands/tunnel.ts:34-35, :111-149 |
| F7 | tunnel ends a socket after 45 s without a ping from the farm, and hears pings through onPing |
src/cli/commands/tunnel.ts:317, :610 |
| F8 | A closed connection rejects every in-flight call with DAEMON_CONNECTION_LOST |
src/simlock-client/wire.ts:127-132 |
Modules touched
src/simlock-client/ (client.ts, the remote connector, the shared farm URL rule, AGENTS.md), src/client/index.ts, src/admin/index.ts, src/ports/websocket-client.ts (text frames, maxPayload), src/contract/ (errors.ts: REMOTE_UNREACHABLE, UNAUTHENTICATED in ErrorDetailsMap and ERROR_TABLE; protocol.ts bump), src/cli/commands/tunnel.ts (calls the shared rule), src/http/errors.ts (its own UNAUTHENTICATED now has a table row), src/http/AGENTS.md (its Known gaps line drops UNAUTHENTICATED), src/client/AGENTS.md (the session is the token's role, not always agent), and the website pages using-devices/programmatic-client.mdx and reference/errors.mdx. Searches: connectSimlock(, connectSimlockAdmin(, NodeIpcTransport, NodeWebSocketClientConnector, parsedUrl, checkedUrl, checkedToken, UNAUTHENTICATED, SILENCE_TIMEOUT_MS.
Rules in play
- ADR 0081 §3: the typed clients choose remote by URL; ADR 0003 §10: the client never reconnects.
src/contract/AGENTS.md: two new error codes joinErrorDetailsMapandERROR_TABLEand bumpmaxby one;errors.mdxgains their rows.src/simlock-client/AGENTS.md: never reconnects, retries or renews; never imports core, daemon or drivers (no-core-leak.test.ts).src/ports/AGENTS.md:wsstays a lazy import inwebsocket-client.ts; every wait bounded (connect 10 s, silence 45 s).src/http/AGENTS.mdKnown gaps:UNAUTHENTICATEDgains itsERROR_TABLErow, so that line shrinks.- Documentation rule 9: the two website pages.
Tests
Seam: connectSimlock and connectSimlockAdmin against a test server on the session path, with the fake clock (models: src/admin/index.test.ts, src/simlock-client/client-pushes.test.ts, src/ports/websocket-client.test.ts), and simlock tunnel's URL cases (model: src/cli/tunnel.test.ts); one case runs the real client against a worker with fake drivers over its real session path from #1639 (model: src/daemon/identity-uplink.e2e.test.ts).
- B5: a remote typed client: worker URL; gateway URL; a refused URL shape;
urlwithconnection,endpoint,ipcorcredential; an over-long token; nothing listening; no answer in 10 s; 401; 403; 404 at the path; 502 from a proxy; another protocol version; alease-lostpush; a 60 MiB reply; the real client over a worker's real session path; a dropped connection; 45 s without a ping; close 4003
Done when
pnpm test:changedpasses, with the Tests line above as a test, andsrc/cli/tunnel.test.tspasses with only its expected messages changed from "worker URL" and "the worker's origin" to "farm URL" and "the farm's origin" (src/cli/tunnel.test.ts:127,:132,:137).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.
Out of scope
- The CLI and MCP using the remote client (Every simlock command runs against a remote farm with --url or SIMLOCK_URL and a token #1641, A held remote simlock lease and simlock mcp reconnect and keep their lease through a network drop #1642).
Depends on
Written by an agent.
Activity