@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.21

package/dist/local-devices/keys.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Redis keys and bus topics of the connected-machine relay (environments spec §6, §13). Every key
+ * is per device (or per request); writers set a TTL on each.
+ */
+/** The lease of the replica holding the machine's connection: `capk:device-lease:<deviceId>`. */
+export declare const deviceLeaseKey: (deviceId: string) => string;
+/** The list of requests waiting for the machine: `capk:device-req:<deviceId>`. */
+export declare const deviceReqKey: (deviceId: string) => string;
+/** The result of one request: `capk:device-res:<requestId>`. */
+export declare const deviceResKey: (requestId: string) => string;
+/** The prefix of {@link deviceTakenKey} (the holder's Lua script builds the key from it). */
+export declare const DEVICE_TAKEN_PREFIX = "capk:device-taken:";
+/**
+ * A request the holder forwarded to a machine: `capk:device-taken:<requestId>` → the device
+ * id. Only a result for a taken request of the socket's own device is accepted.
+ */
+export declare const deviceTakenKey: (requestId: string) => string;
+/** A new request for the machine of the device. */
+export declare const deviceReqTopic: (deviceId: string) => string;
+/** The result of one request is ready. */
+export declare const deviceResTopic: (requestId: string) => string;
+/** Another replica took the machine's connection over. */
+export declare const deviceTakeoverTopic: (deviceId: string) => string;
+/** The machine's credential was revoked: its connection is closed. */
+export declare const deviceRevokedTopic: (deviceId: string) => string;

package/dist/local-devices/keys.js

@@ -0,0 +1,25 @@
+/**
+ * Redis keys and bus topics of the connected-machine relay (environments spec §6, §13). Every key
+ * is per device (or per request); writers set a TTL on each.
+ */
+/** The lease of the replica holding the machine's connection: `capk:device-lease:<deviceId>`. */
+export const deviceLeaseKey = (deviceId) => `capk:device-lease:${deviceId}`;
+/** The list of requests waiting for the machine: `capk:device-req:<deviceId>`. */
+export const deviceReqKey = (deviceId) => `capk:device-req:${deviceId}`;
+/** The result of one request: `capk:device-res:<requestId>`. */
+export const deviceResKey = (requestId) => `capk:device-res:${requestId}`;
+/** The prefix of {@link deviceTakenKey} (the holder's Lua script builds the key from it). */
+export const DEVICE_TAKEN_PREFIX = "capk:device-taken:";
+/**
+ * A request the holder forwarded to a machine: `capk:device-taken:<requestId>` → the device
+ * id. Only a result for a taken request of the socket's own device is accepted.
+ */
+export const deviceTakenKey = (requestId) => `${DEVICE_TAKEN_PREFIX}${requestId}`;
+/** A new request for the machine of the device. */
+export const deviceReqTopic = (deviceId) => `device.req.${deviceId}`;
+/** The result of one request is ready. */
+export const deviceResTopic = (requestId) => `device.res.${requestId}`;
+/** Another replica took the machine's connection over. */
+export const deviceTakeoverTopic = (deviceId) => `device.takeover.${deviceId}`;
+/** The machine's credential was revoked: its connection is closed. */
+export const deviceRevokedTopic = (deviceId) => `device.revoked.${deviceId}`;

package/dist/local-devices/local-device-gateway.d.ts

@@ -0,0 +1,134 @@
+import { type ExtensionContext } from "@capybara-hq/plugin-sdk";
+import type { WebSocket } from "@fastify/websocket";
+import type { Redis } from "ioredis";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { type MachineIdentity, MachinesService } from "./machines.js";
+/** WebSocket close codes the gateway uses (the program reads 4002 and 4003). */
+export declare const DEVICE_CLOSE: {
+    /** The kernel is shutting down: reconnect (another gateway replica takes over). */
+    readonly shutdown: 1001;
+    /** A frame larger than `devices.local.maxFrameBytes` (sent by `ws` itself). */
+    readonly tooBig: 1009;
+    /** The kernel failed (e.g. the database): reconnect. */
+    readonly internal: 1011;
+    /** The lease was lost (renewal kept failing or the key was taken): reconnect. */
+    readonly leaseLost: 4001;
+    /** A newer connection of the device took over: the program exits. */
+    readonly replaced: 4002;
+    /** The machine's credential was revoked: the program exits. */
+    readonly revoked: 4003;
+    /** No valid `hello` first, or a frame that is not protocol v1 from a device. */
+    readonly protocol: 4400;
+    /** The lease could not be claimed in time: reconnect. */
+    readonly claimTimeout: 4409;
+};
+/** How long the program has to send `hello` after the upgrade. */
+export declare const HELLO_TIMEOUT_MS = 10000;
+/** How often a connection is pinged; two pings without a pong close it. */
+export declare const PING_INTERVAL_MS = 20000;
+/** How long a new connection retries the lease after asking the holder to let go. */
+export declare const CLAIM_TIMEOUT_MS = 5000;
+/** The pause between two tries at the lease while claiming. */
+export declare const CLAIM_RETRY_MS = 250;
+type State = "hello" | "claiming" | "holding" | "closed";
+/**
+ * One machine connection on this replica. Its state (the socket, the lease handle, the requests
+ * it forwarded) is the socket's own and lives exactly as long as the socket.
+ */
+declare class DeviceConnection {
+    private readonly gw;
+    private readonly socket;
+    readonly identity: MachineIdentity;
+    private readonly credential;
+    readonly token: `${string}-${string}-${string}-${string}-${string}`;
+    state: State;
+    private lease;
+    private readonly unsubscribes;
+    private helloTimer;
+    private pingTimer;
+    private missedPongs;
+    private lastTouch;
+    private lastAuth;
+    /** The drains (and the close after a revocation) run one after another. */
+    private chain;
+    /** Resolves once the lease is handed back (or was never held). */
+    private released;
+    constructor(gw: LocalDeviceGateway, socket: WebSocket, identity: MachineIdentity, credential: string);
+    get deviceId(): string;
+    start(): void;
+    private onFrame;
+    /**
+     * Stores one result and announces it (the relay's wire, relay.ts), only for a request taken for
+     * this device (ruling R20); anything else is dropped.
+     */
+    private store;
+    /**
+     * Claims the device's lease; true when this connection holds it. The newest connection
+     * wins (ruling R21): when another connection holds the lease, a takeover is published (the
+     * holder yields to any takeover) and the lease retried every {@link CLAIM_RETRY_MS} for
+     * {@link CLAIM_TIMEOUT_MS}, then 4409 (the program reconnects). A claimer never yields.
+     */
+    private claim;
+    /** Subscribes for this connection; a subscription that completes after the close is ended. */
+    private subscribe;
+    /** Queues one drain of the request list after the ones already queued. */
+    private drain;
+    private drainOnce;
+    /** The next ping (a chain of timeouts; the lease renewal is LockService's, not this timer's). */
+    private schedulePing;
+    private ping;
+    /** The credential still stands (membership, org and device are read live). */
+    private reauthenticate;
+    private traffic;
+    /** Closes the socket with `code` and hands the lease back; idempotent. */
+    close(code: number, reason: string): Promise<void>;
+    /** Stops timers and subscriptions and releases the lease (a lost one is abandoned). */
+    shutdown(): Promise<void>;
+}
+/**
+ * The gateway role's half of the device relay (environments spec §13.4): holds the WebSocket
+ * connections of connected machines (`GET /device/connect`, device-routes.ts). One connection per
+ * device across replicas, under the lease `capk:device-lease:<deviceId>` (the newest
+ * connection wins: it publishes `device.takeover.<deviceId>` and the holder lets go). The
+ * holder drains `capk:device-req:<deviceId>` on every `device.req.<deviceId>` nudge,
+ * once after claiming and on every ping, marking each forwarded request taken for its device
+ * (`capk:device-taken:<id>`, TTL the reconnect grace plus the request's deadline plus a margin).
+ * A `res` is accepted only for a request taken for the socket's device: it is stored under
+ * `capk:device-res:<id>` for the rest of that TTL and published on `device.res.<id>`.
+ * `device.revoked.<deviceId>` closes the connection of that machine only (ruling R16). The
+ * sockets are this process's own; everything other replicas need is in Redis.
+ */
+export declare class LocalDeviceGateway {
+    readonly machines: Pick<MachinesService, "authenticate" | "recordHello" | "touch">;
+    readonly locks: Pick<LockService, "hold">;
+    readonly bus: ExtensionContext["bus"];
+    readonly redis: Redis;
+    private readonly config;
+    readonly log: Pick<KernelLogger, "info" | "warn">;
+    /** This replica's open connections (the sockets cannot live anywhere else). */
+    private readonly connections;
+    private stopping;
+    /** How often connections are pinged ({@link PING_INTERVAL_MS}; a test seam). */
+    pingIntervalMs: number;
+    constructor(machines: Pick<MachinesService, "authenticate" | "recordHello" | "touch">, locks: Pick<LockService, "hold">, bus: ExtensionContext["bus"], redis: Redis, config: KernelConfigService, log: Pick<KernelLogger, "info" | "warn">);
+    graceMs(): number;
+    leaseTtlMs(): number;
+    maxFrameBytes(): number;
+    /** Who a `Bearer` machine credential stands for, or null (checked before the upgrade). */
+    authenticate(credential: string): Promise<MachineIdentity | null>;
+    /** Serves one upgraded socket of an authenticated machine until it closes. */
+    accept(socket: WebSocket, identity: MachineIdentity, credential: string): void;
+    /**
+     * How many devices this process holds the connection of (replica presence reports it): only
+     * sockets past the hello that hold their device's lease, so a socket still claiming or being
+     * replaced by a newer one does not count a device twice.
+     */
+    connectionCount(): number;
+    /** @internal a connection that ended. */
+    forget(conn: DeviceConnection): void;
+    /** Closes every connection (1001) and hands their leases back. */
+    stop(): Promise<void>;
+}
+export {};