Skip to content

connectSimlock and connectSimlockAdmin reach a remote farm with a URL and a token #1640

Open

Description

@V3RON

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 join ErrorDetailsMap and ERROR_TABLE and bump max by one; errors.mdx gains 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: ws stays a lazy import in websocket-client.ts; every wait bounded (connect 10 s, silence 45 s).
  • src/http/AGENTS.md Known gaps: UNAUTHENTICATED gains its ERROR_TABLE row, 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; url with connection, endpoint, ipc or credential; an over-long token; nothing listening; no answer in 10 s; 401; 403; 404 at the path; 502 from a proxy; another protocol version; a lease-lost push; 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:changed passes, with the Tests line above as a test, and src/cli/tunnel.test.ts passes 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 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.

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