@av-pi-studio/server 0.0.120 → 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 +17 -15
- package/dist/daemon/bootstrap.js +55 -141
- package/dist/daemon/relay-connection.d.ts +46 -0
- package/dist/daemon/relay-connection.js +226 -0
- package/dist/daemon/relay-sessions.d.ts +23 -0
- package/dist/daemon/relay-sessions.js +114 -0
- package/dist/daemon/relay-transport.d.ts +32 -42
- package/dist/daemon/relay-transport.js +157 -91
- package/dist/ws/session.d.ts +4 -4
- package/dist/ws/session.js +4 -4
- package/package.json +3 -3
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
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
(`deriveRelaySessionId`, `@av-pi-studio/relay`)
|
|
238
|
-
|
|
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
|
-
|
|
244
|
-
|
|
245
|
-
`
|
|
246
|
-
one
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
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
|
|
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
|
package/dist/daemon/bootstrap.js
CHANGED
|
@@ -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
|
|
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:
|
|
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:
|
|
659
|
-
routeBinaryFrame(session, frame.binary,
|
|
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-
|
|
668
|
-
// § Behavior — `connectRelay`). Fully opt-in:
|
|
669
|
-
// so a daemon with no relay config behaves
|
|
670
|
-
//
|
|
671
|
-
//
|
|
672
|
-
//
|
|
673
|
-
//
|
|
674
|
-
//
|
|
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
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
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
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
/**
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
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
|
-
/**
|
|
44
|
+
/** Stop redialing, close the control socket and every open data socket. */
|
|
49
45
|
close(): void;
|
|
50
46
|
}
|
|
51
47
|
/**
|
|
52
|
-
*
|
|
53
|
-
*
|
|
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,
|
|
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-
|
|
3
|
-
* §
|
|
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
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
* `
|
|
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
|
|
12
|
-
*
|
|
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
|
-
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
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 {
|
|
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
|
-
*
|
|
69
|
-
*
|
|
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,
|
|
78
|
-
|
|
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(
|
|
86
|
-
|
|
87
|
-
|
|
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
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
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("
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
if (closed)
|
|
148
|
+
socket.on("ping", armSilence);
|
|
149
|
+
socket.on("message", (data, isBinary) => {
|
|
150
|
+
if (ended)
|
|
109
151
|
return;
|
|
110
|
-
|
|
111
|
-
|
|
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
|
-
|
|
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
|
-
|
|
120
|
-
return sessionId;
|
|
121
|
-
},
|
|
181
|
+
sessionId,
|
|
122
182
|
close() {
|
|
183
|
+
if (closed)
|
|
184
|
+
return;
|
|
123
185
|
closed = true;
|
|
124
|
-
|
|
125
|
-
|
|
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
|
}
|
package/dist/ws/session.d.ts
CHANGED
|
@@ -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 (
|
|
52
|
-
*
|
|
53
|
-
*
|
|
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`
|
|
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
|
}
|
package/dist/ws/session.js
CHANGED
|
@@ -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 (
|
|
65
|
-
*
|
|
66
|
-
*
|
|
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`
|
|
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.
|
|
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.
|
|
28
|
-
"@av-pi-studio/relay": "^0.0.
|
|
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",
|