@av-pi-studio/server 0.0.119 → 0.0.121

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -231,24 +231,26 @@ To use a **different `pi` binary** than the bundled one, set
231
231
  extend the `pi` provider via `"extends": "pi"` (a custom provider must also set a `label`).
232
232
 
233
233
  **Relay (opt-in, off by default):** with `daemon.relay.enabled: true`, the daemon dials outbound
234
- to the `endpoint` (a self-hosted `@av-pi-studio/relay` server or Cloudflare Workers deployment)
235
- after the WS server is up, so remote clients can reach it without an inbound port. It registers
236
- under a **deterministic** rendezvous session id derived from its own persistent public key
237
- (`deriveRelaySessionId`, `@av-pi-studio/relay`) — the same id on every (re)connect, so a pairing
238
- link printed once (`pi-studio daemon pair`) keeps working across relay drops/restarts. See
234
+ to the `endpoint` (a self-hosted `@av-pi-studio/relay` server) after the WS server is up, so remote
235
+ clients can reach it without an inbound port. It keeps one **control socket** registered under a
236
+ **deterministic** rendezvous session id derived from its own persistent public key
237
+ (`deriveRelaySessionId`, `@av-pi-studio/relay`), so a pairing link printed once
238
+ (`pi-studio daemon pair`) keeps working across relay drops and restarts. A dropped control socket
239
+ is redialed with backoff (1 s doubling to 30 s, ±20 %); a relay that never answers the registration
240
+ within 10 s speaks an older protocol, and the daemon logs that the relay must be updated. See
239
241
  `@av-pi-studio/relay`'s README for running a relay (`pi-studio-relay` bin / `pi-studio relay
240
242
  start`). Direct WebSocket connections are completely unaffected either way — the relay only adds
241
243
  an additional connection path.
242
244
 
243
- The same pairing link can be opened by any number of clients over the daemon's lifetime — each
244
- one gets its own fresh E2EE handshake and its own daemon-side `Session` (see `relay-transport.ts`'s
245
- `onHandshake` → `bootstrap.ts`'s `resetRelaySession()`); connecting a second client after a first
246
- one disconnected is a normal, supported reconnection, not a re-pairing.
247
-
248
- Terminal I/O and file-transfer chunks work over a relay connection too — the daemon and client
249
- encrypt binary application data as the relay channel's `e2ee_bin` frame (a base64-wrapped JSON
250
- text frame, not a raw binary WebSocket frame; see `@av-pi-studio/relay`'s README § Wire protocol),
251
- so no daemon or web-client feature is direct-connection-only.
245
+ Each client that opens the pairing link gets its **own** daemon connection: the relay asks the
246
+ daemon over the control socket to open a data socket for it, and the two run their own E2EE
247
+ handshake, `hello` and daemon-side `Session`. Several clients (up to 32) can be connected at once
248
+ and none replaces another; closing one disposes only its session. Terminal I/O and file-transfer
249
+ chunks work over a relay connection like over a direct one (the channel carries text and binary
250
+ application messages as encrypted binary frames; see `@av-pi-studio/relay`'s README § Wire
251
+ protocol), and file downloads are paced on the connection's queue, so no daemon or web-client
252
+ feature is direct-connection-only. A daemon on this version needs a protocol-2 relay (and clients
253
+ on protocol 2): older relays and clients cannot connect.
252
254
 
253
255
  ---
254
256
 
@@ -435,7 +437,7 @@ The daemon logs its full operational lifecycle through one `pino` logger created
435
437
  (`src/logging/logger.ts`): startup (home, config, serverId), agent recovery, WS client
436
438
  connect/disconnect (with close code + duration), upgrade/auth rejections, every RPC (at `debug`,
437
439
  with duration; failures at `warn`), agent create/turn lifecycle (prompt *sizes*, never contents),
438
- terminal open/kill/exit, `pi` provider process spawn/exit, and relay dial events.
440
+ terminal open/kill/exit, `pi` provider process spawn/exit, and relay events (control socket connected/registered/closed with the next redial delay, replaced, outdated relay, ignored dials, data-socket close).
439
441
 
440
442
  Output goes to **stdout always** — pretty on a TTY, NDJSON otherwise (so `docker logs` /
441
443
  journald / PM2 work out of the box) — **plus** a rotating NDJSON file under
@@ -17,7 +17,7 @@ import nacl from "tweetnacl";
17
17
  import { SERVER_VERSION } from "../version.js";
18
18
  import { createHttpServer } from "../http/http-server.js";
19
19
  import { createWebSocketServer } from "../ws/ws-server.js";
20
- import { HandlerRegistry, routeTextFrame, routeBinaryFrame } from "../ws/router.js";
20
+ import { HandlerRegistry, routeTextFrame, routeBinaryFrame, } from "../ws/router.js";
21
21
  import { Session } from "../ws/session.js";
22
22
  import { createInMemoryCapabilityStore } from "../ws/capability-store.js";
23
23
  import { SessionSubscriptions } from "../ws/session-subscriptions.js";
@@ -72,9 +72,10 @@ import { DaemonStatusService } from "../observability/daemon-status-service.js";
72
72
  import { registerViewerSettingsHandlers } from "../viewers/viewer-settings-rpc.js";
73
73
  import { ResourceService } from "../resources/resource-service.js";
74
74
  import { registerSkillsHandlers } from "../resources/skills-rpc.js";
75
- import { SERVER_FEATURES, helloSchema, serverInfoPayloadSchema, statusSchema, } from "@av-pi-studio/protocol";
75
+ import { SERVER_FEATURES } from "@av-pi-studio/protocol";
76
76
  import { parseDaemonListen } from "./index.js";
77
77
  import { isLoopbackHost, UNPROTECTED_BIND_WARNING } from "./loopback.js";
78
+ import { attachRelaySession } from "./relay-sessions.js";
78
79
  import { connectRelay } from "./relay-transport.js";
79
80
  function resolveHome(opts) {
80
81
  return opts.home ?? process.env.PI_STUDIO_HOME ?? join(homedir(), ".pi-studio");
@@ -627,6 +628,19 @@ export function startDaemon(opts) {
627
628
  envPassword: process.env.PI_STUDIO_PASSWORD,
628
629
  });
629
630
  const auth = createPasswordAuth(passwordHash);
631
+ // Per-session cleanup shared by direct and relay sessions: without it a closed client's
632
+ // subscriptions and transfers would leak until a failed send.
633
+ const disposeSession = (session) => {
634
+ subscriptions.disposeSession(session);
635
+ daemonStatusService.disposeSession(session);
636
+ daemonLogsService.disposeSession(session);
637
+ fileTransfer.disposeSession(session);
638
+ };
639
+ // Post-handshake binary frames: terminal (Input/Resize) first, then file-transfer (upload).
640
+ const binaryHandler = (session, bytes) => {
641
+ terminalBinaryHandler(session, bytes);
642
+ fileTransferBinary(session, bytes);
643
+ };
630
644
  // ── HTTP + WS wiring ─────────────────────────────────────────────────────────
631
645
  const httpServer = createHttpServer({
632
646
  hostnames,
@@ -644,160 +658,60 @@ export function startDaemon(opts) {
644
658
  onSession: (session) => {
645
659
  logger.info({ clientId: session.clientId, clientType: session.clientType }, "ws client connected");
646
660
  },
647
- onSessionClose: (session) => {
648
- subscriptions.disposeSession(session);
649
- daemonStatusService.disposeSession(session);
650
- daemonLogsService.disposeSession(session);
651
- fileTransfer.disposeSession(session);
652
- },
661
+ onSessionClose: disposeSession,
653
662
  onMessage: (session, frame) => {
654
663
  if ("text" in frame) {
655
664
  void routeTextFrame(session, frame.text, registry);
656
665
  }
657
666
  else {
658
- // Binary frames: try terminal (Input/Resize) then file-transfer (upload) decoders.
659
- routeBinaryFrame(session, frame.binary, (s, bytes) => {
660
- terminalBinaryHandler(s, bytes);
661
- fileTransferBinary(s, bytes);
662
- });
667
+ // Binary frames: terminal (Input/Resize) first, then file-transfer (upload).
668
+ routeBinaryFrame(session, frame.binary, binaryHandler);
663
669
  }
664
670
  },
665
671
  });
666
672
  sessionsHolder.sessions = wsHandle.sessions;
667
- // ── Optional outbound relay (architecture/relay-e2ee.md, architecture/daemon-bootstrap.md
668
- // § Behavior — `connectRelay`). Fully opt-in: `config.daemon.relay.enabled` defaults to false,
669
- // so a daemon with no relay config behaves identically to before — only the direct WS listener
670
- // above ever starts. When enabled, each decrypted relay app message is dispatched through the
671
- // exact same `registry`/`routeTextFrame` RPC surface direct clients use, via a persistent
672
- // synthetic `Session` whose `send()` re-encrypts the response back onto the same E2EE channel.
673
- //
674
- // A relay session id pairs at most one client with this daemon at a time (`RelaySessionBridge`),
675
- // so exactly one `Session` is live per relay connection — created lazily on the client's `hello`
676
- // (mirroring `ws-server.ts`'s direct-WS handshake exactly: validate `hello`, rehydrate/persist
677
- // capabilities by `clientId`, reply with `status`/`server_info`), then reused for every
678
- // subsequent frame until the relay reconnects with a new session id.
673
+ // ── Optional outbound relay (architecture/relay-protocol.md § Behavior — Daemon;
674
+ // architecture/daemon-bootstrap.md § Behavior — `connectRelay`). Fully opt-in:
675
+ // `config.daemon.relay.enabled` defaults to false, so a daemon with no relay config behaves
676
+ // identically to before — only the direct WS listener above ever starts. When enabled,
677
+ // `connectRelay` keeps one control socket registered and opens a data connection per client
678
+ // (`relay_dial`); each connection gets its own `Session` through `attachRelaySession` — the relay
679
+ // twin of the direct `hello` path, routed through the same `registry`/`routeTextFrame` surface and
680
+ // disposed by the same per-session cleanup (`disposeSession`) when its socket closes.
679
681
  let relayHandle;
680
682
  if (config.daemon.relay.enabled) {
681
- let relaySession = null;
682
- let relayReply = null;
683
- let relayReplyBinary = null;
684
- const resetRelaySession = () => {
685
- if (relaySession) {
686
- relaySessions.delete(relaySession);
687
- // Same per-session disposal a direct socket close runs (`onSessionClose` above): without
688
- // it a replaced relay peer's subscriptions would leak until a failed send.
689
- subscriptions.disposeSession(relaySession);
690
- daemonStatusService.disposeSession(relaySession);
691
- daemonLogsService.disposeSession(relaySession);
692
- fileTransfer.disposeSession(relaySession);
693
- }
694
- relaySession = null;
695
- };
696
683
  relayHandle = connectRelay({
697
684
  publicKey: Buffer.from(daemonKeypairB64.publicKeyB64, "base64"),
698
685
  secretKey: Buffer.from(daemonKeypairB64.secretKeyB64, "base64"),
699
686
  }, config.daemon.relay, {
700
- onMessage: (plaintext, reply) => {
701
- relayReply = reply; // kept in sync per message too; the real fix is capturing this in onHandshake below
702
- if (relaySession === null) {
703
- // First frame on this relay connection must be `hello`, exactly like direct WS.
704
- let parsed;
705
- try {
706
- parsed = JSON.parse(plaintext);
707
- }
708
- catch {
709
- return; // not JSON — ignore, matching routeTextFrame's tolerance
710
- }
711
- const hello = helloSchema.safeParse(parsed);
712
- if (!hello.success)
713
- return; // non-hello first frame: ignore (no socket to close)
714
- const stored = relayCapabilityStore.get(hello.data.clientId);
715
- const capabilities = hello.data.capabilities ?? stored ?? {};
716
- relayCapabilityStore.set(hello.data.clientId, capabilities);
717
- relaySession = new Session({
718
- id: randomUUID(),
719
- clientId: hello.data.clientId,
720
- clientType: hello.data.clientType,
721
- platform: hello.data.platform,
722
- agentStreams: hello.data.agentStreams,
723
- capabilities,
724
- appVersion: hello.data.appVersion,
725
- transport: "relay",
726
- // `Session.send()` calls `socket.send(jsonString)`; `Session.sendBinary()` calls
727
- // `socket.send(bytes)` — same method, discriminated by argument type here so both
728
- // funnel to the matching relay reply callback (text `e2ee_app` vs binary `e2ee_bin`).
729
- socket: {
730
- send: (data) => {
731
- if (typeof data === "string")
732
- relayReply?.(data);
733
- else
734
- relayReplyBinary?.(data);
735
- },
736
- close: () => { },
737
- },
738
- });
739
- relaySessions.add(relaySession);
740
- logger.info({
741
- clientId: relaySession.clientId,
742
- clientType: relaySession.clientType,
743
- via: "relay",
744
- }, "ws client connected");
745
- const payload = serverInfoPayloadSchema.parse({
746
- status: "server_info",
747
- serverId,
748
- hostname: opts.host,
749
- version: SERVER_VERSION,
750
- // Same value the direct-WS handshake reports (`ws/ws-server.ts`): the DAEMON's home
751
- // dir, which a relay-remote client (different machine, possibly different OS) has no
752
- // other way to learn.
753
- homeDir: homedir(),
754
- capabilities: {},
755
- features: Object.fromEntries(Object.values(SERVER_FEATURES).map((k) => [k, true])),
756
- });
757
- relaySession.send(statusSchema.parse({ type: "status", payload }));
758
- return;
759
- }
760
- void routeTextFrame(relaySession, plaintext, registry);
761
- },
762
- onBinaryMessage: (bytes, replyBinary) => {
763
- relayReplyBinary = replyBinary; // kept in sync per message too; the real fix is capturing this in onHandshake below
764
- if (relaySession === null)
765
- return; // binary frames before `hello` have no session to target
766
- routeBinaryFrame(relaySession, bytes, (s, b) => {
767
- terminalBinaryHandler(s, b);
768
- fileTransferBinary(s, b);
769
- });
770
- },
771
- onError: (err) => {
772
- logger.error({ err: err?.message ?? String(err) }, "relay channel error");
773
- },
774
- onSessionStart: (sessionId) => {
775
- logger.info({ sessionId }, "relay connected");
776
- },
777
- onHandshake: (reply, replyBinary) => {
778
- // A NEW peer just completed the E2EE handshake on this (possibly already-`ready`)
779
- // channel — browser reload, second tab, or a genuine reconnect all look identical here.
780
- // Drop any app-level Session tied to whichever peer held the channel before; the next
781
- // app frame is that new peer's own `hello`, not a continuation of the old one's.
782
- //
783
- // Capture `reply`/`replyBinary` right here rather than waiting for the first
784
- // `onMessage`/`onBinaryMessage` call: a file download's `Begin`/`Chunk`/`End` frames are
785
- // sent daemon → client entirely unprompted (the client never sends binary first, unlike
786
- // terminal input), so `relayReplyBinary` used to stay `null` until a binary frame
787
- // happened to arrive from the client — which never happened for downloads, silently
788
- // dropping every relay-routed file download with no error on either side.
789
- relayReply = reply;
790
- relayReplyBinary = replyBinary;
791
- if (relaySession)
792
- logger.info({ sessionId: relaySession.id }, "relay peer replaced");
793
- resetRelaySession();
794
- },
795
- onReconnect: (sessionId) => {
796
- logger.info({ sessionId }, "relay reconnecting with new session");
797
- resetRelaySession();
798
- relayReply = null;
799
- relayReplyBinary = null;
800
- },
687
+ logger,
688
+ onConnection: (conn) => attachRelaySession(conn, {
689
+ registry,
690
+ routeTextFrame,
691
+ routeBinaryFrame,
692
+ binaryHandler,
693
+ capabilityStore: relayCapabilityStore,
694
+ buildServerInfo: () => ({
695
+ status: "server_info",
696
+ serverId,
697
+ hostname: opts.host,
698
+ version: SERVER_VERSION,
699
+ // Same value the direct-WS handshake reports (`ws/ws-server.ts`): the DAEMON's home
700
+ // dir, which a relay-remote client (different machine, possibly different OS) has no
701
+ // other way to learn.
702
+ homeDir: homedir(),
703
+ capabilities: {},
704
+ features: Object.fromEntries(Object.values(SERVER_FEATURES).map((k) => [k, true])),
705
+ }),
706
+ onSessionOpen: (session) => {
707
+ relaySessions.add(session);
708
+ },
709
+ onSessionClose: (session) => {
710
+ relaySessions.delete(session);
711
+ disposeSession(session);
712
+ },
713
+ logger,
714
+ }),
801
715
  });
802
716
  }
803
717
  // Recover persisted agents on boot (best-effort; provider sessions are re-attached lazily).
@@ -0,0 +1,46 @@
1
+ import type { Logger } from "../logging/logger.js";
2
+ import type { DaemonKeypair } from "./relay-transport.js";
3
+ /** Timers and sizes tests may shorten; `RELAY_DEFAULTS` supplies every value not given. */
4
+ export interface RelayConnectionLimits {
5
+ /** Largest accepted WebSocket frame. */
6
+ maxFrameBytes?: number;
7
+ /** Dial plus pairing: the socket is closed when `relay_paired` has not arrived in time. */
8
+ attachTimeoutMs?: number;
9
+ /** A paired socket that has not received a valid channel `hello` is closed. */
10
+ keyExchangeTimeoutMs?: number;
11
+ /** No frame and no ping from the relay for this long: the socket is dead. */
12
+ silenceTimeoutMs?: number;
13
+ }
14
+ export interface OpenRelayConnectionOptions {
15
+ /** Relay WebSocket URL (`ws://host:port` or `wss://…`). */
16
+ url: string;
17
+ sessionId: string;
18
+ connectionId: string;
19
+ keypair: DaemonKeypair;
20
+ limits?: RelayConnectionLimits;
21
+ logger: Logger;
22
+ }
23
+ /** A client connection routed through the relay; mirrors a direct socket. */
24
+ export interface RelayConnection {
25
+ readonly connectionId: string;
26
+ /** The data socket's queued bytes. */
27
+ readonly bufferedAmount: number;
28
+ /** Channel ready and socket open. */
29
+ readonly isOpen: boolean;
30
+ /** Send one text message; dropped silently when the connection is not open. */
31
+ sendText(text: string): void;
32
+ /** Send one binary message; dropped silently when the connection is not open. */
33
+ sendBinary(bytes: Uint8Array): void;
34
+ /** Close the data socket with `code`; the relay forwards it to the client. */
35
+ close(code?: number, reason?: string): void;
36
+ onText(handler: (text: string) => void): void;
37
+ onBinary(handler: (bytes: Uint8Array) => void): void;
38
+ /** Fires once, with the code the socket closed with. */
39
+ onClose(handler: (code: number, reason: string) => void): void;
40
+ }
41
+ /**
42
+ * Dial the relay for `connectionId` and bring the data socket up. Synchronous: progress and
43
+ * failures arrive through the connection's events (`onClose` fires once, whatever the cause).
44
+ */
45
+ export declare function openRelayConnection(options: OpenRelayConnectionOptions): RelayConnection;
46
+ //# sourceMappingURL=relay-connection.d.ts.map
@@ -0,0 +1,226 @@
1
+ /**
2
+ * One relay data socket per client connection (architecture/relay-protocol.md § Behavior — Daemon
3
+ * (data socket), § 2, § Error handling; features/relay-multi-client.md § Public contract 2).
4
+ *
5
+ * Given a `connectionId` from the relay's `relay_dial`, the daemon dials a data socket, sends
6
+ * `relay_daemon_attach`, waits for `relay_paired`, then runs the channel's daemon side
7
+ * (`createDaemonChannel`) over the socket and exposes it as a `RelayConnection` that behaves like a
8
+ * direct socket: text, binary, queued bytes, open state and close with a code. The socket is a real
9
+ * `ws` socket, so `bufferedAmount` is real and download pacing works on the relay.
10
+ *
11
+ * Sessions and `hello` handling live above this module; it imports no `Session` or registry code.
12
+ */
13
+ import { WebSocket } from "ws";
14
+ import { createDaemonChannel, encodeControlFrame, parseRelayFrame, RELAY_CLOSE, RELAY_DEFAULTS, } from "@av-pi-studio/relay";
15
+ const decoder = new TextDecoder();
16
+ function toBytes(data) {
17
+ const buf = Array.isArray(data)
18
+ ? Buffer.concat(data)
19
+ : Buffer.isBuffer(data)
20
+ ? data
21
+ : Buffer.from(data);
22
+ return new Uint8Array(buf.buffer, buf.byteOffset, buf.length);
23
+ }
24
+ /** Adapt a `ws` socket's post-pairing frames to the channel's byte `Transport`. */
25
+ function createSocketTransport(socket) {
26
+ let onFrame;
27
+ let onClose;
28
+ return {
29
+ transport: {
30
+ send: (bytes) => {
31
+ if (socket.readyState === WebSocket.OPEN)
32
+ socket.send(bytes);
33
+ },
34
+ onFrame: (h) => {
35
+ onFrame = h;
36
+ },
37
+ onClose: (h) => {
38
+ onClose = h;
39
+ },
40
+ close: (code, reason) => closeSocket(socket, code, reason),
41
+ },
42
+ deliverFrame: (frame) => onFrame?.(frame),
43
+ deliverClose: (code, reason) => onClose?.(code, reason),
44
+ };
45
+ }
46
+ /** Close with `code`; a code a close frame cannot carry falls back to 1000. */
47
+ function closeSocket(socket, code = 1000, reason = "") {
48
+ if (socket.readyState === WebSocket.CLOSING || socket.readyState === WebSocket.CLOSED)
49
+ return;
50
+ try {
51
+ socket.close(code, reason);
52
+ }
53
+ catch {
54
+ socket.close(1000, "");
55
+ }
56
+ }
57
+ /**
58
+ * Dial the relay for `connectionId` and bring the data socket up. Synchronous: progress and
59
+ * failures arrive through the connection's events (`onClose` fires once, whatever the cause).
60
+ */
61
+ export function openRelayConnection(options) {
62
+ const { url, sessionId, connectionId, keypair } = options;
63
+ const logger = options.logger.child({ component: "relay-connection", connectionId });
64
+ const limits = {
65
+ maxFrameBytes: options.limits?.maxFrameBytes ?? RELAY_DEFAULTS.maxFrameBytes,
66
+ attachTimeoutMs: options.limits?.attachTimeoutMs ?? RELAY_DEFAULTS.attachTimeoutMs,
67
+ keyExchangeTimeoutMs: options.limits?.keyExchangeTimeoutMs ?? RELAY_DEFAULTS.keyExchangeTimeoutMs,
68
+ silenceTimeoutMs: options.limits?.silenceTimeoutMs ?? RELAY_DEFAULTS.silenceTimeoutMs,
69
+ };
70
+ const socket = new WebSocket(url, {
71
+ maxPayload: limits.maxFrameBytes,
72
+ handshakeTimeout: RELAY_DEFAULTS.connectTimeoutMs,
73
+ });
74
+ const socketTransport = createSocketTransport(socket);
75
+ const textHandlers = [];
76
+ const binaryHandlers = [];
77
+ const closeHandlers = [];
78
+ let channel = null;
79
+ let ready = false;
80
+ let closedWith = null;
81
+ let setupTimer;
82
+ let silenceTimer;
83
+ let lastActivity = Date.now();
84
+ /** The one place a connection ends: idempotent, clears timers, fires `onClose` once. */
85
+ const finish = (code, reason) => {
86
+ if (closedWith)
87
+ return;
88
+ closedWith = { code, reason };
89
+ ready = false;
90
+ clearTimeout(setupTimer);
91
+ clearTimeout(silenceTimer);
92
+ logger.info({ code, reason }, "relay data socket closed");
93
+ for (const h of closeHandlers)
94
+ h(code, reason);
95
+ };
96
+ /** Close the socket with a relay code and end the connection. */
97
+ const abort = (spec) => {
98
+ closeSocket(socket, spec.code, spec.reason);
99
+ finish(spec.code, spec.reason);
100
+ };
101
+ const armSilence = () => {
102
+ const remaining = limits.silenceTimeoutMs - (Date.now() - lastActivity);
103
+ silenceTimer = setTimeout(() => {
104
+ if (Date.now() - lastActivity >= limits.silenceTimeoutMs) {
105
+ logger.warn("relay data socket silent; closing");
106
+ abort(RELAY_CLOSE.PING_TIMEOUT);
107
+ }
108
+ else {
109
+ armSilence();
110
+ }
111
+ }, Math.max(remaining, 1));
112
+ };
113
+ const touch = () => {
114
+ lastActivity = Date.now();
115
+ };
116
+ const startChannel = () => {
117
+ clearTimeout(setupTimer);
118
+ setupTimer = setTimeout(() => {
119
+ logger.warn("no channel hello before the key-exchange timeout; closing");
120
+ abort(RELAY_CLOSE.PROTOCOL_ERROR);
121
+ }, limits.keyExchangeTimeoutMs);
122
+ channel = createDaemonChannel({
123
+ transport: socketTransport.transport,
124
+ daemonKeypair: keypair,
125
+ events: {
126
+ onText: (text) => {
127
+ for (const h of textHandlers)
128
+ h(text);
129
+ },
130
+ onBinary: (bytes) => {
131
+ for (const h of binaryHandlers)
132
+ h(bytes);
133
+ },
134
+ onReady: () => {
135
+ clearTimeout(setupTimer);
136
+ ready = true;
137
+ },
138
+ onClose: (code, reason) => finish(code ?? 1006, reason ?? ""),
139
+ // Channel errors carry a fixed phrase, never payload.
140
+ onError: (cause) => logger.warn({ err: cause.message }, "relay channel error"),
141
+ },
142
+ });
143
+ };
144
+ socket.on("open", () => {
145
+ logger.info("relay data socket opened");
146
+ setupTimer = setTimeout(() => {
147
+ logger.warn("relay did not pair the data socket in time; closing");
148
+ abort(RELAY_CLOSE.PROTOCOL_ERROR);
149
+ }, limits.attachTimeoutMs);
150
+ touch();
151
+ armSilence();
152
+ socket.send(encodeControlFrame({ type: "relay_daemon_attach", v: 2, sessionId, connectionId }));
153
+ });
154
+ socket.on("ping", touch);
155
+ socket.on("message", (data, isBinary) => {
156
+ if (closedWith)
157
+ return;
158
+ touch();
159
+ if (channel) {
160
+ socketTransport.deliverFrame(isBinary ? toBytes(data) : decoder.decode(toBytes(data)));
161
+ return;
162
+ }
163
+ // Before pairing only the relay's own control frame is valid.
164
+ if (isBinary)
165
+ return abort(RELAY_CLOSE.PROTOCOL_ERROR);
166
+ const frame = parseRelayFrame(decoder.decode(toBytes(data)));
167
+ if (frame?.type === "relay_paired" && frame.connectionId === connectionId)
168
+ startChannel();
169
+ });
170
+ socket.on("error", (err) => {
171
+ logger.warn({ err: err.message }, "relay data socket error");
172
+ });
173
+ socket.on("close", (code, reasonBuf) => {
174
+ const reason = reasonBuf?.length ? reasonBuf.toString("utf8") : "";
175
+ if (channel)
176
+ socketTransport.deliverClose(code, reason);
177
+ finish(code, reason);
178
+ });
179
+ const connection = {
180
+ connectionId,
181
+ get bufferedAmount() {
182
+ return socket.bufferedAmount;
183
+ },
184
+ get isOpen() {
185
+ return ready && !closedWith && socket.readyState === WebSocket.OPEN;
186
+ },
187
+ sendText: (text) => {
188
+ if (!connection.isOpen)
189
+ return;
190
+ try {
191
+ channel?.send(text);
192
+ }
193
+ catch {
194
+ // The channel already closed itself (counter limit) and reported through `onError`.
195
+ }
196
+ },
197
+ sendBinary: (bytes) => {
198
+ if (!connection.isOpen)
199
+ return;
200
+ try {
201
+ channel?.sendBinary(bytes);
202
+ }
203
+ catch {
204
+ // See `sendText`.
205
+ }
206
+ },
207
+ close: (code = 1000, reason = "") => {
208
+ closeSocket(socket, code, reason);
209
+ finish(code, reason);
210
+ },
211
+ onText: (handler) => {
212
+ textHandlers.push(handler);
213
+ },
214
+ onBinary: (handler) => {
215
+ binaryHandlers.push(handler);
216
+ },
217
+ onClose: (handler) => {
218
+ if (closedWith)
219
+ handler(closedWith.code, closedWith.reason);
220
+ else
221
+ closeHandlers.push(handler);
222
+ },
223
+ };
224
+ return connection;
225
+ }
226
+ //# sourceMappingURL=relay-connection.js.map
@@ -0,0 +1,23 @@
1
+ import type { Logger } from "../logging/logger.js";
2
+ import type { CapabilityStore } from "../ws/capability-store.js";
3
+ import type { BinaryHandler, HandlerRegistry } from "../ws/router.js";
4
+ import { Session } from "../ws/session.js";
5
+ import type { RelayConnection } from "./relay-connection.js";
6
+ export interface RelaySessionDeps {
7
+ registry: HandlerRegistry;
8
+ routeTextFrame: (session: Session, text: string, registry: HandlerRegistry) => Promise<void>;
9
+ routeBinaryFrame: (session: Session, bytes: Uint8Array, binaryHandler?: BinaryHandler) => void;
10
+ /** Handler for post-handshake binary records (terminal input, file uploads). */
11
+ binaryHandler: BinaryHandler;
12
+ capabilityStore: CapabilityStore;
13
+ /** The `server_info` payload fields; parsed with `serverInfoPayloadSchema` before sending. */
14
+ buildServerInfo: () => Record<string, unknown>;
15
+ /** Called once the handshake completes and the `server_info` reply is sent. */
16
+ onSessionOpen: (session: Session) => void;
17
+ /** Called once when the connection closes, if a session was created. */
18
+ onSessionClose: (session: Session) => void;
19
+ logger: Logger;
20
+ }
21
+ /** Wire `conn` to its own daemon session; see the module comment. */
22
+ export declare function attachRelaySession(conn: RelayConnection, deps: RelaySessionDeps): void;
23
+ //# sourceMappingURL=relay-sessions.d.ts.map
@@ -0,0 +1,114 @@
1
+ /**
2
+ * One daemon `Session` per relay connection (architecture/relay-protocol.md § 5, § Behavior —
3
+ * Daemon; features/relay-multi-client.md § Public contract 2).
4
+ *
5
+ * A {@link RelayConnection} behaves like a direct socket, so this module is the relay twin of the
6
+ * direct `hello` path in `ws/ws-server.ts`: the first text record must be a valid `hello` (else the
7
+ * connection closes with 1008), which creates the session, rehydrates/persists capabilities by
8
+ * `clientId`, and answers `status`/`server_info`. Later records go to the same router and binary
9
+ * handlers direct sessions use. When the connection closes, `deps.onSessionClose` runs — the same
10
+ * disposal function a direct close runs; there is no second disposal list here.
11
+ */
12
+ import { randomUUID } from "node:crypto";
13
+ import { helloSchema, serverInfoPayloadSchema, statusSchema } from "@av-pi-studio/protocol";
14
+ import { Session } from "../ws/session.js";
15
+ /** `WebSocket.OPEN` / `WebSocket.CLOSED` readyState values. */
16
+ const WS_OPEN = 1;
17
+ const WS_CLOSED = 3;
18
+ /** The slice of `ws.WebSocket` a `Session` uses, backed by a relay connection. */
19
+ function socketFacade(conn) {
20
+ const facade = {
21
+ send: (data) => {
22
+ if (typeof data === "string")
23
+ conn.sendText(data);
24
+ else
25
+ conn.sendBinary(data);
26
+ },
27
+ close: (code, reason) => conn.close(code, reason),
28
+ get bufferedAmount() {
29
+ return conn.bufferedAmount;
30
+ },
31
+ get readyState() {
32
+ return conn.isOpen ? WS_OPEN : WS_CLOSED;
33
+ },
34
+ };
35
+ return facade;
36
+ }
37
+ /** Wire `conn` to its own daemon session; see the module comment. */
38
+ export function attachRelaySession(conn, deps) {
39
+ const { logger } = deps;
40
+ const connectedAt = Date.now();
41
+ let session = null;
42
+ conn.onText((text) => {
43
+ if (session !== null) {
44
+ void deps.routeTextFrame(session, text, deps.registry);
45
+ return;
46
+ }
47
+ // First text record must be a valid JSON `hello` (same reasons as the direct path).
48
+ let parsed;
49
+ try {
50
+ parsed = JSON.parse(text);
51
+ }
52
+ catch {
53
+ logger.warn({ connectionId: conn.connectionId }, "relay handshake failed: invalid hello JSON");
54
+ conn.close(1008, "invalid hello");
55
+ return;
56
+ }
57
+ const hello = helloSchema.safeParse(parsed);
58
+ if (!hello.success) {
59
+ logger.warn({ connectionId: conn.connectionId }, "relay handshake failed: first frame not a valid hello");
60
+ conn.close(1008, "first frame must be hello");
61
+ return;
62
+ }
63
+ // Persist on hello; rehydrate stored caps when the hello omits them.
64
+ const stored = deps.capabilityStore.get(hello.data.clientId);
65
+ const capabilities = hello.data.capabilities ?? stored ?? {};
66
+ deps.capabilityStore.set(hello.data.clientId, capabilities);
67
+ const created = new Session({
68
+ id: randomUUID(),
69
+ clientId: hello.data.clientId,
70
+ clientType: hello.data.clientType,
71
+ platform: hello.data.platform,
72
+ agentStreams: hello.data.agentStreams,
73
+ capabilities,
74
+ socket: socketFacade(conn),
75
+ appVersion: hello.data.appVersion,
76
+ transport: "relay",
77
+ });
78
+ session = created;
79
+ const payload = serverInfoPayloadSchema.parse(deps.buildServerInfo());
80
+ created.send(statusSchema.parse({ type: "status", payload }));
81
+ deps.onSessionOpen(created);
82
+ logger.info({
83
+ clientId: created.clientId,
84
+ clientType: created.clientType,
85
+ via: "relay",
86
+ connectionId: conn.connectionId,
87
+ }, "ws client connected");
88
+ });
89
+ conn.onBinary((bytes) => {
90
+ if (session === null)
91
+ return; // binary records before `hello` have no session to target
92
+ deps.routeBinaryFrame(session, bytes, deps.binaryHandler);
93
+ });
94
+ conn.onClose((code) => {
95
+ if (session === null)
96
+ return;
97
+ const closed = session;
98
+ try {
99
+ deps.onSessionClose(closed);
100
+ }
101
+ catch (err) {
102
+ logger.warn({ err, clientId: closed.clientId }, "onSessionClose callback threw; session teardown continues");
103
+ }
104
+ logger.info({
105
+ clientId: closed.clientId,
106
+ clientType: closed.clientType,
107
+ via: "relay",
108
+ connectionId: conn.connectionId,
109
+ code,
110
+ durationMs: Date.now() - connectedAt,
111
+ }, "ws client disconnected");
112
+ });
113
+ }
114
+ //# sourceMappingURL=relay-sessions.js.map
@@ -1,3 +1,5 @@
1
+ import type { Logger } from "../logging/logger.js";
2
+ import { type RelayConnection, type RelayConnectionLimits } from "./relay-connection.js";
1
3
  /** Mirrors `daemon.relay` in `daemon-config.ts` / architecture/config.md. */
2
4
  export interface RelayConfig {
3
5
  enabled: boolean;
@@ -10,53 +12,41 @@ export interface DaemonKeypair {
10
12
  publicKey: Uint8Array;
11
13
  secretKey: Uint8Array;
12
14
  }
13
- export interface RelayTransportEvents {
14
- /** Fired with a decrypted TEXT app message once a client's E2EE handshake completes; `reply` sends an encrypted text response back on the same channel. */
15
- onMessage?: (plaintext: string, reply: (message: string) => void) => void;
16
- /**
17
- * Fired with a decrypted BINARY app message (terminal I/O, file-transfer chunks) once a
18
- * client's E2EE handshake completes; `replyBinary` sends an encrypted binary response back on
19
- * the same channel. Mirrors `onMessage`/`reply` exactly, just for the binary sibling wire frame
20
- * (`e2ee_bin` vs `e2ee_app` — see `@av-pi-studio/relay`'s `channel.ts`).
21
- */
22
- onBinaryMessage?: (bytes: Uint8Array, replyBinary: (bytes: Uint8Array) => void) => void;
23
- /** Fired once per successful (re)connection, with the session id just registered. */
24
- onSessionStart?: (sessionId: string) => void;
25
- /** Fired when a relay drop triggers a reconnect, with the NEW session id about to be registered. */
26
- onReconnect?: (sessionId: string) => void;
27
- /**
28
- * Fired every time the E2EE handshake (re)completes on the current relay socket — not just
29
- * once per socket connection. The relay multiplexes one deterministic session id across
30
- * however many client sockets attach over the daemon's lifetime (browser reload, second tab,
31
- * plain reconnect); `createDaemonChannel` now re-arms on each fresh `e2ee_hello` instead of
32
- * ignoring it, so a NEW peer taking over an already-`ready` channel fires this again. Consumers
33
- * should treat it as "forget any app-level session state tied to the previous peer" — the next
34
- * app frame is a new peer's `hello`, not a continuation of the old peer's session.
35
- *
36
- * Hands over `reply`/`replyBinary` directly (the same stable `channel.send`/`channel.sendBinary`
37
- * `onMessage`/`onBinaryMessage` pass on every call) so a consumer can send unprompted — a file
38
- * download's `Begin`/`Chunk`/`End` binary frames flow daemon → client with no inbound binary
39
- * frame ever arriving first, unlike terminal I/O. Capturing the reply functions only inside
40
- * `onMessage`/`onBinaryMessage` (as this used to do) left `replyBinary` `null` until the client
41
- * happened to send binary first, silently dropping every relay-routed file download.
42
- */
43
- onHandshake?: (reply: (message: string) => void, replyBinary: (bytes: Uint8Array) => void) => void;
44
- onError?: (error: unknown) => void;
15
+ /** Timers and sizes tests may shorten; `RELAY_DEFAULTS` supplies every value not given. */
16
+ export interface RelayTransportLimits extends RelayConnectionLimits {
17
+ /** Data sockets open at once; further `relay_dial`s are ignored. */
18
+ maxConnections?: number;
19
+ /** Wait for `relay_registered` before deciding the relay is outdated. */
20
+ registrationAnswerTimeoutMs?: number;
21
+ backoffInitialMs?: number;
22
+ backoffMaxMs?: number;
23
+ /** Fraction of the delay added or removed at random (0.2 = ±20 %). */
24
+ backoffJitter?: number;
25
+ /** Wait after the relay closed the control socket with `replaced`. */
26
+ replacedWaitMs?: number;
27
+ }
28
+ /** The slice of the timer API the control loop uses; tests inject a recording fake. */
29
+ export interface RelayTimers {
30
+ setTimeout(callback: () => void, ms: number): unknown;
31
+ clearTimeout(handle: unknown): void;
32
+ }
33
+ export interface RelayTransportOptions {
34
+ /** Called once per `relay_dial`, with the connection that is being opened. */
35
+ onConnection: (conn: RelayConnection) => void;
36
+ logger: Logger;
37
+ limits?: RelayTransportLimits;
38
+ /** Jitter source in `[0, 1)`; defaults to `Math.random`. */
39
+ random?: () => number;
40
+ timers?: RelayTimers;
45
41
  }
46
42
  export interface RelayTransportHandle {
47
43
  readonly sessionId: string;
48
- /** Tear down the relay transport: stops reconnecting and closes the current socket/channel. */
44
+ /** Stop redialing, close the control socket and every open data socket. */
49
45
  close(): void;
50
46
  }
51
47
  /**
52
- * Dial outbound to the relay, registering the deterministic session id derived from the daemon's
53
- * own public key (`deriveRelaySessionId`) — the SAME id on every (re)connect, so a pairing URL
54
- * printed once keeps working across relay drops/restarts. This does not weaken
55
- * architecture/relay-e2ee.md § Error Handling's "new session → new keys" guarantee: the rendezvous
56
- * session id is just a routing label the relay uses to pair sockets, never a key input — the
57
- * client's `createClientChannel` still generates a FRESH ephemeral Curve25519 keypair on every
58
- * connection, so every reconnect still derives an independent ECDH shared key even though the
59
- * session id it registers under is unchanged.
48
+ * Open the control socket and keep it registered; see the module comment. Returns at once: dial
49
+ * progress and failures are logged, never thrown (an unreachable relay is retried with backoff).
60
50
  */
61
- export declare function connectRelay(keypair: DaemonKeypair, config: RelayConfig, events?: RelayTransportEvents): RelayTransportHandle;
51
+ export declare function connectRelay(keypair: DaemonKeypair, config: RelayConfig, options: RelayTransportOptions): RelayTransportHandle;
62
52
  //# sourceMappingURL=relay-transport.d.ts.map
@@ -1,29 +1,28 @@
1
1
  /**
2
- * Daemon-side outbound relay transport (architecture/relay-e2ee.md § Behavior — Connection setup,
3
- * § TLS, § Pairing; architecture/daemon-bootstrap.md § Behavior — `connectRelay`).
2
+ * Daemon-side outbound relay transport (architecture/relay-protocol.md § Behavior — Daemon (control
3
+ * loop), § 2, § 3, § Error handling; features/relay-multi-client.md § Public contract 2).
4
4
  *
5
- * The daemon dials OUTBOUND to a relay server (so no inbound port needs to be opened) and registers
6
- * a session id so the relay can pair an incoming client connection with this daemon. Once
7
- * connected, all application traffic on the socket is E2EE via `createDaemonChannel`
8
- * (`@av-pi-studio/relay`) — the daemon refuses to process ANY app message until the client's
9
- * `e2ee_hello`/`e2ee_ready` handshake completes.
5
+ * The daemon dials OUTBOUND to a relay (no inbound port to open) and keeps ONE control socket
6
+ * registered under its session id with protocol 2. Each `relay_dial { connectionId }` the relay
7
+ * sends on it makes the daemon open a data socket (`openRelayConnection`, at most 32 at a time) and
8
+ * hand the resulting {@link RelayConnection} to `onConnection`. Sessions, `hello` handling and
9
+ * disposal live above this module (`relay-sessions.ts`, wired in `bootstrap.ts`).
10
10
  *
11
- * The session id is `deriveRelaySessionId(keypair.publicKey)` — deterministic, not random — so a
12
- * pairing URL printed once keeps working across relay reconnects. Earlier this used a fresh
13
- * `randomUUID()` per connect AND per reconnect, which meant any pairing link went stale the moment
14
- * the relay connection dropped and reconnected (the daemon would register under a session id no
15
- * printed link referenced). Deriving from the public key — which the pairing link already carries
16
- * and which the spec already treats as the trust anchor (relay-e2ee.md § Pairing) — costs nothing
17
- * in secrecy and keeps the same session id for the life of the daemon's keypair.
11
+ * The session id is `deriveRelaySessionId(keypair.publicKey)` — deterministic — so a pairing link
12
+ * printed once keeps working across control-socket drops and relay restarts.
18
13
  *
19
- * TODO(verify): the exact registration frame format is unresolved upstream
20
- * (architecture/relay-e2ee.md § TODO(verify) — "Relay server routing/session-id assignment
21
- * protocol details"). This implementation registers with `{ type: "relay_register", sessionId }`
22
- * immediately after the socket opens; the client transport (task-003) and Cloudflare adapter
23
- * (task-004) built in this sprint agree on this same frame.
14
+ * The control socket is redialed with backoff (1, 2, 4 … 30 s, ±20 % jitter) when it closes, when
15
+ * the relay does not answer the registration within 10 s (an outdated relay) and when it stays
16
+ * silent for 90 s (no frame and no ping). A control drop never touches the data connections: they
17
+ * are independent sockets and end only when their own socket closes.
24
18
  */
25
19
  import { WebSocket } from "ws";
26
- import { createDaemonChannel, deriveRelaySessionId, } from "@av-pi-studio/relay";
20
+ import { deriveRelaySessionId, encodeControlFrame, parseRelayFrame, RELAY_CLOSE, RELAY_DEFAULTS, } from "@av-pi-studio/relay";
21
+ import { openRelayConnection, } from "./relay-connection.js";
22
+ const systemTimers = {
23
+ setTimeout: (callback, ms) => setTimeout(callback, ms),
24
+ clearTimeout: (handle) => clearTimeout(handle),
25
+ };
27
26
  function relayUrl(config) {
28
27
  if (!config.endpoint) {
29
28
  throw new Error("relay-transport: config.daemon.relay.endpoint is required when relay.enabled");
@@ -34,95 +33,162 @@ function relayUrl(config) {
34
33
  const host = config.endpoint.replace(/^(?:https?|wss?):\/\//, "").replace(/\/+$/, "");
35
34
  return `${scheme}://${host}`;
36
35
  }
37
- /** Wrap a `ws` `WebSocket` as the relay package's transport-agnostic `Transport`. */
38
- function wrapSocket(socket) {
39
- const messageHandlers = [];
40
- const closeHandlers = [];
41
- socket.on("message", (data, isBinary) => {
42
- if (isBinary)
43
- return; // the relay channel protocol is text-frame only
44
- const text = Array.isArray(data)
45
- ? Buffer.concat(data).toString("utf8")
46
- : Buffer.isBuffer(data)
47
- ? data.toString("utf8")
48
- : Buffer.from(data).toString("utf8");
49
- for (const h of messageHandlers)
50
- h(text);
51
- });
52
- socket.on("close", (code, reasonBuf) => {
53
- const reason = reasonBuf?.length ? reasonBuf.toString("utf8") : `code ${code}`;
54
- for (const h of closeHandlers)
55
- h(reason);
56
- });
57
- return {
58
- send: (data) => {
59
- if (socket.readyState === WebSocket.OPEN)
60
- socket.send(data);
61
- },
62
- onMessage: (h) => messageHandlers.push(h),
63
- onClose: (h) => closeHandlers.push(h),
64
- close: () => socket.close(),
65
- };
66
- }
67
36
  /**
68
- * Dial outbound to the relay, registering the deterministic session id derived from the daemon's
69
- * own public key (`deriveRelaySessionId`) — the SAME id on every (re)connect, so a pairing URL
70
- * printed once keeps working across relay drops/restarts. This does not weaken
71
- * architecture/relay-e2ee.md § Error Handling's "new session → new keys" guarantee: the rendezvous
72
- * session id is just a routing label the relay uses to pair sockets, never a key input — the
73
- * client's `createClientChannel` still generates a FRESH ephemeral Curve25519 keypair on every
74
- * connection, so every reconnect still derives an independent ECDH shared key even though the
75
- * session id it registers under is unchanged.
37
+ * Open the control socket and keep it registered; see the module comment. Returns at once: dial
38
+ * progress and failures are logged, never thrown (an unreachable relay is retried with backoff).
76
39
  */
77
- export function connectRelay(keypair, config, events = {}) {
78
- let closed = false;
79
- let currentSocket = null;
80
- let currentChannel = null;
40
+ export function connectRelay(keypair, config, options) {
41
+ const url = relayUrl(config);
81
42
  const sessionId = deriveRelaySessionId(keypair.publicKey);
43
+ const logger = options.logger.child({ component: "relay", sessionId });
44
+ const random = options.random ?? Math.random;
45
+ const timers = options.timers ?? systemTimers;
46
+ const limits = {
47
+ maxConnections: options.limits?.maxConnections ?? RELAY_DEFAULTS.maxClientsPerDaemon,
48
+ maxFrameBytes: options.limits?.maxFrameBytes ?? RELAY_DEFAULTS.maxFrameBytes,
49
+ silenceTimeoutMs: options.limits?.silenceTimeoutMs ?? RELAY_DEFAULTS.silenceTimeoutMs,
50
+ registrationAnswerTimeoutMs: options.limits?.registrationAnswerTimeoutMs ?? RELAY_DEFAULTS.registrationAnswerTimeoutMs,
51
+ backoffInitialMs: options.limits?.backoffInitialMs ?? RELAY_DEFAULTS.backoffInitialMs,
52
+ backoffMaxMs: options.limits?.backoffMaxMs ?? RELAY_DEFAULTS.backoffMaxMs,
53
+ backoffJitter: options.limits?.backoffJitter ?? RELAY_DEFAULTS.backoffJitter,
54
+ replacedWaitMs: options.limits?.replacedWaitMs ?? RELAY_DEFAULTS.replacedWaitMs,
55
+ };
56
+ const connections = new Set();
57
+ let closed = false;
58
+ let controlSocket = null;
59
+ let redialTimer;
60
+ /** Consecutive control-socket failures since the last `relay_registered`. */
61
+ let failures = 0;
62
+ /** The next backoff delay: initial · 2^failures, capped, with ± jitter. Advances `failures`. */
63
+ const nextBackoffMs = () => {
64
+ const base = Math.min(limits.backoffInitialMs * 2 ** failures, limits.backoffMaxMs);
65
+ failures += 1;
66
+ const spread = (random() * 2 - 1) * limits.backoffJitter;
67
+ return Math.round(base * (1 + spread));
68
+ };
69
+ const handleDial = (connectionId) => {
70
+ if (connections.size >= limits.maxConnections) {
71
+ logger.warn({ connectionId, open: connections.size, max: limits.maxConnections }, "relay_dial ignored: too many open connections");
72
+ return;
73
+ }
74
+ const conn = openRelayConnection({
75
+ url,
76
+ sessionId,
77
+ connectionId,
78
+ keypair,
79
+ limits: options.limits,
80
+ logger: options.logger,
81
+ });
82
+ connections.add(conn);
83
+ conn.onClose(() => connections.delete(conn));
84
+ try {
85
+ options.onConnection(conn);
86
+ }
87
+ catch (err) {
88
+ logger.error({ connectionId, err: err?.message ?? String(err) }, "relay onConnection threw; closing the connection");
89
+ conn.close(1011, "internal error");
90
+ }
91
+ };
82
92
  const dial = () => {
83
93
  if (closed)
84
94
  return;
85
- const socket = new WebSocket(relayUrl(config));
86
- currentSocket = socket;
87
- socket.on("open", () => {
95
+ const socket = new WebSocket(url, {
96
+ maxPayload: limits.maxFrameBytes,
97
+ handshakeTimeout: RELAY_DEFAULTS.connectTimeoutMs,
98
+ });
99
+ controlSocket = socket;
100
+ let ended = false;
101
+ let registered = false;
102
+ let registrationTimer;
103
+ let silenceTimer;
104
+ /** The one place a control socket ends: idempotent; clears timers; schedules the redial. */
105
+ const end = (code, reason) => {
106
+ if (ended)
107
+ return;
108
+ ended = true;
109
+ timers.clearTimeout(registrationTimer);
110
+ timers.clearTimeout(silenceTimer);
111
+ if (controlSocket === socket)
112
+ controlSocket = null;
88
113
  if (closed)
89
114
  return;
90
- socket.send(JSON.stringify({ type: "relay_register", sessionId }));
91
- const channel = createDaemonChannel({
92
- transport: wrapSocket(socket),
93
- attachment: { sessionId },
94
- daemonKeypair: keypair,
95
- events: {
96
- onMessage: (plaintext) => events.onMessage?.(plaintext, (message) => channel.send(message)),
97
- onBinaryMessage: (bytes) => events.onBinaryMessage?.(bytes, (reply) => channel.sendBinary(reply)),
98
- onReady: () => events.onHandshake?.(channel.send, channel.sendBinary),
99
- onAuthError: (err) => events.onError?.(err),
100
- },
101
- });
102
- currentChannel = channel;
103
- events.onSessionStart?.(sessionId);
115
+ let delayMs;
116
+ if (code === RELAY_CLOSE.REPLACED.code) {
117
+ delayMs = limits.replacedWaitMs;
118
+ logger.warn("relay control socket replaced: another daemon is registered with this key; " +
119
+ "waiting before registering again");
120
+ }
121
+ else {
122
+ delayMs = nextBackoffMs();
123
+ }
124
+ logger.info({ code, reason, nextRedialMs: delayMs }, "relay control socket closed");
125
+ redialTimer = timers.setTimeout(dial, delayMs);
126
+ };
127
+ /** Abandon a socket the relay will not close for us (no answer, silence). */
128
+ const drop = (code, reason) => {
129
+ socket.terminate();
130
+ end(code, reason);
131
+ };
132
+ const armSilence = () => {
133
+ timers.clearTimeout(silenceTimer);
134
+ silenceTimer = timers.setTimeout(() => {
135
+ logger.warn({ silenceTimeoutMs: limits.silenceTimeoutMs }, "relay control socket silent; redialing");
136
+ drop(RELAY_CLOSE.PING_TIMEOUT.code, "silence");
137
+ }, limits.silenceTimeoutMs);
138
+ };
139
+ socket.on("open", () => {
140
+ logger.info("relay connected");
141
+ socket.send(encodeControlFrame({ type: "relay_daemon_register", v: 2, sessionId }));
142
+ registrationTimer = timers.setTimeout(() => {
143
+ logger.warn({ registrationAnswerTimeoutMs: limits.registrationAnswerTimeoutMs }, "relay did not answer the registration: it speaks an older protocol and must be updated");
144
+ drop(1000, "registration timeout");
145
+ }, limits.registrationAnswerTimeoutMs);
146
+ armSilence();
104
147
  });
105
- socket.on("close", () => {
106
- currentSocket = null;
107
- currentChannel = null;
108
- if (closed)
148
+ socket.on("ping", armSilence);
149
+ socket.on("message", (data, isBinary) => {
150
+ if (ended)
109
151
  return;
110
- events.onReconnect?.(sessionId);
111
- dial();
152
+ armSilence();
153
+ if (isBinary)
154
+ return; // the control socket carries text frames only
155
+ const text = Array.isArray(data)
156
+ ? Buffer.concat(data).toString("utf8")
157
+ : Buffer.isBuffer(data)
158
+ ? data.toString("utf8")
159
+ : Buffer.from(data).toString("utf8");
160
+ const frame = parseRelayFrame(text);
161
+ if (frame?.type === "relay_registered") {
162
+ timers.clearTimeout(registrationTimer);
163
+ registered = true;
164
+ failures = 0;
165
+ logger.info("relay registered");
166
+ }
167
+ else if (frame?.type === "relay_dial" && registered) {
168
+ handleDial(frame.connectionId);
169
+ }
170
+ // Anything else (unknown or malformed control frame) is ignored.
112
171
  });
113
172
  socket.on("error", (err) => {
114
- events.onError?.(err);
173
+ logger.warn({ err: err.message }, "relay control socket error");
174
+ });
175
+ socket.on("close", (code, reasonBuf) => {
176
+ end(code, reasonBuf?.length ? reasonBuf.toString("utf8") : "");
115
177
  });
116
178
  };
117
179
  dial();
118
180
  return {
119
- get sessionId() {
120
- return sessionId;
121
- },
181
+ sessionId,
122
182
  close() {
183
+ if (closed)
184
+ return;
123
185
  closed = true;
124
- currentChannel?.close();
125
- currentSocket?.close();
186
+ timers.clearTimeout(redialTimer);
187
+ controlSocket?.terminate();
188
+ controlSocket = null;
189
+ for (const conn of connections)
190
+ conn.close(1001, "daemon shutting down");
191
+ connections.clear();
126
192
  },
127
193
  };
128
194
  }
@@ -48,12 +48,12 @@ export declare class Session {
48
48
  /** Send raw bytes as a binary frame (terminal/file streams). */
49
49
  sendBinary(bytes: Uint8Array): void;
50
50
  /**
51
- * Bytes queued on the socket and not yet flushed, or `undefined` when the socket cannot say (the
52
- * relay's stand-in socket forwards each frame into an encrypted channel and has no queue to
53
- * read). Bulk senders pace themselves on it; `undefined` means "do not pace".
51
+ * Bytes queued on the socket and not yet flushed, or `undefined` when the socket cannot say (a
52
+ * stand-in socket with no queue). Direct sockets and relay connections both report it, so bulk
53
+ * senders pace themselves on it; `undefined` means "do not pace".
54
54
  */
55
55
  get bufferedAmount(): number | undefined;
56
- /** False once the socket is closing or closed. A socket with no `readyState` (relay) is open. */
56
+ /** False once the socket is closing or closed. A socket with no `readyState` is open. */
57
57
  get isOpen(): boolean;
58
58
  close(code?: number, reason?: string): void;
59
59
  }
@@ -61,15 +61,15 @@ export class Session {
61
61
  this.socket.send(bytes);
62
62
  }
63
63
  /**
64
- * Bytes queued on the socket and not yet flushed, or `undefined` when the socket cannot say (the
65
- * relay's stand-in socket forwards each frame into an encrypted channel and has no queue to
66
- * read). Bulk senders pace themselves on it; `undefined` means "do not pace".
64
+ * Bytes queued on the socket and not yet flushed, or `undefined` when the socket cannot say (a
65
+ * stand-in socket with no queue). Direct sockets and relay connections both report it, so bulk
66
+ * senders pace themselves on it; `undefined` means "do not pace".
67
67
  */
68
68
  get bufferedAmount() {
69
69
  const queued = this.socket.bufferedAmount;
70
70
  return typeof queued === "number" ? queued : undefined;
71
71
  }
72
- /** False once the socket is closing or closed. A socket with no `readyState` (relay) is open. */
72
+ /** False once the socket is closing or closed. A socket with no `readyState` is open. */
73
73
  get isOpen() {
74
74
  const state = this.socket.readyState;
75
75
  return typeof state !== "number" || state === WS_OPEN;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@av-pi-studio/server",
3
- "version": "0.0.119",
3
+ "version": "0.0.121",
4
4
  "bin": {
5
5
  "pi-studio-daemon": "dist/daemon/main.js"
6
6
  },
@@ -24,8 +24,8 @@
24
24
  "clean": "rm -rf dist *.tsbuildinfo"
25
25
  },
26
26
  "dependencies": {
27
- "@av-pi-studio/protocol": "^0.0.119",
28
- "@av-pi-studio/relay": "^0.0.119",
27
+ "@av-pi-studio/protocol": "^0.0.121",
28
+ "@av-pi-studio/relay": "^0.0.121",
29
29
  "@earendil-works/pi-coding-agent": "^1.4.0",
30
30
  "@xterm/addon-serialize": "^0.14.0",
31
31
  "@xterm/headless": "^6.0.0",