@linkshell/gateway 0.1.0

package/src/pairings.ts

@@ -0,0 +1,75 @@
+import { randomInt, randomUUID } from "node:crypto";
+
+export interface PairingRecord {
+  sessionId: string;
+  pairingCode: string;
+  expiresAt: number; // unix ms
+  claimed: boolean;
+}
+
+const PAIRING_TTL = 10 * 60_000; // 10 minutes
+const CLEANUP_INTERVAL = 60_000;
+
+export class PairingManager {
+  private pairings = new Map<string, PairingRecord>();
+  private cleanupTimer: ReturnType<typeof setInterval>;
+
+  constructor() {
+    this.cleanupTimer = setInterval(() => this.cleanup(), CLEANUP_INTERVAL);
+  }
+
+  create(sessionId?: string): PairingRecord {
+    const id = sessionId ?? randomUUID();
+    const code = String(randomInt(100000, 999999));
+    const record: PairingRecord = {
+      sessionId: id,
+      pairingCode: code,
+      expiresAt: Date.now() + PAIRING_TTL,
+      claimed: false,
+    };
+    this.pairings.set(code, record);
+    return record;
+  }
+
+  claim(pairingCode: string): PairingRecord | { error: string; status: number } {
+    const record = this.pairings.get(pairingCode);
+    if (!record) {
+      return { error: "pairing_not_found", status: 404 };
+    }
+    if (record.expiresAt < Date.now()) {
+      this.pairings.delete(pairingCode);
+      return { error: "pairing_expired", status: 410 };
+    }
+    record.claimed = true;
+    return record;
+  }
+
+  getStatus(pairingCode: string): { status: string; expiresAt: number; sessionId: string } | { error: string; httpStatus: number } {
+    const record = this.pairings.get(pairingCode);
+    if (!record) {
+      return { error: "pairing_not_found", httpStatus: 404 };
+    }
+    if (record.expiresAt < Date.now()) {
+      this.pairings.delete(pairingCode);
+      return { error: "pairing_expired", httpStatus: 410 };
+    }
+    return {
+      status: record.claimed ? "claimed" : "waiting",
+      expiresAt: record.expiresAt,
+      sessionId: record.sessionId,
+    };
+  }
+
+  private cleanup(): void {
+    const now = Date.now();
+    for (const [code, record] of this.pairings) {
+      if (record.expiresAt < now) {
+        this.pairings.delete(code);
+      }
+    }
+  }
+
+  destroy(): void {
+    clearInterval(this.cleanupTimer);
+  }
+}

package/src/relay.ts

@@ -0,0 +1,209 @@
+import type WebSocket from "ws";
+import {
+  parseEnvelope,
+  parseTypedPayload,
+  serializeEnvelope,
+  createEnvelope,
+} from "@linkshell/protocol";
+import type { Envelope } from "@linkshell/protocol";
+import type { SessionManager, ConnectedDevice } from "./sessions.js";
+
+export function handleSocketMessage(
+  socket: WebSocket,
+  raw: string,
+  role: "host" | "client",
+  sessionId: string,
+  deviceId: string,
+  sessions: SessionManager,
+): void {
+  let envelope: Envelope;
+  try {
+    envelope = parseEnvelope(raw);
+  } catch {
+    socket.send(
+      serializeEnvelope(
+        createEnvelope({
+          type: "session.error",
+          sessionId,
+          payload: { code: "invalid_message", message: "Failed to parse envelope" },
+        }),
+      ),
+    );
+    return;
+  }
+
+  const session = sessions.get(sessionId);
+  if (!session) {
+    socket.send(
+      serializeEnvelope(
+        createEnvelope({
+          type: "session.error",
+          sessionId,
+          payload: { code: "session_not_found", message: "Session not found" },
+        }),
+      ),
+    );
+    return;
+  }
+
+  if (role === "host") {
+    handleHostMessage(envelope, session, sessions);
+  } else {
+    handleClientMessage(envelope, socket, session, deviceId, sessions);
+  }
+}
+
+function handleHostMessage(
+  envelope: Envelope,
+  session: ReturnType<SessionManager["get"]> & {},
+  sessions: SessionManager,
+): void {
+  switch (envelope.type) {
+    case "session.connect": {
+      // Extract metadata from host's connect message
+      const p = parseTypedPayload("session.connect", envelope.payload);
+      if (p.provider || p.hostname) {
+        sessions.setMetadata(session.id, p.provider ?? undefined, p.hostname ?? undefined);
+      }
+      break;
+    }
+    case "terminal.output": {
+      sessions.bufferOutput(session.id, envelope);
+      broadcastToClients(session, envelope);
+      break;
+    }
+    case "terminal.exit": {
+      sessions.terminate(session.id);
+      broadcastToClients(session, envelope);
+      break;
+    }
+    case "session.heartbeat":
+      break;
+    case "control.grant":
+    case "control.reject":
+      broadcastToClients(session, envelope);
+      break;
+    default:
+      broadcastToClients(session, envelope);
+      break;
+  }
+}
+
+function handleClientMessage(
+  envelope: Envelope,
+  socket: WebSocket,
+  session: ReturnType<SessionManager["get"]> & {},
+  deviceId: string,
+  sessions: SessionManager,
+): void {
+  switch (envelope.type) {
+    case "terminal.input": {
+      // Only controller can send input
+      if (session.controllerId !== deviceId) {
+        socket.send(
+          serializeEnvelope(
+            createEnvelope({
+              type: "session.error",
+              sessionId: session.id,
+              payload: { code: "control_conflict", message: "Not the controller" },
+            }),
+          ),
+        );
+        return;
+      }
+      sendToHost(session, envelope);
+      break;
+    }
+    case "terminal.resize": {
+      if (session.controllerId !== deviceId) return;
+      sendToHost(session, envelope);
+      break;
+    }
+    case "session.ack": {
+      // Forward ACK to host
+      sendToHost(session, envelope);
+      break;
+    }
+    case "session.resume": {
+      const p = parseTypedPayload("session.resume", envelope.payload);
+      // Replay from gateway buffer first
+      const replay = sessions.getReplayFrom(session.id, p.lastAckedSeq);
+      for (const msg of replay) {
+        const payload = msg.payload as Record<string, unknown>;
+        socket.send(
+          serializeEnvelope(
+            createEnvelope({
+              type: "terminal.output",
+              sessionId: session.id,
+              seq: msg.seq,
+              payload: { ...payload, isReplay: true },
+            }),
+          ),
+        );
+      }
+      // Also forward resume to host so it can fill gaps beyond gateway buffer
+      sendToHost(session, envelope);
+      break;
+    }
+    case "control.claim": {
+      const granted = sessions.claimControl(session.id, deviceId);
+      if (granted) {
+        const grantMsg = createEnvelope({
+          type: "control.grant",
+          sessionId: session.id,
+          payload: { deviceId },
+        });
+        socket.send(serializeEnvelope(grantMsg));
+        sendToHost(session, grantMsg);
+      } else {
+        socket.send(
+          serializeEnvelope(
+            createEnvelope({
+              type: "control.reject",
+              sessionId: session.id,
+              payload: { deviceId, reason: "Another device holds control" },
+            }),
+          ),
+        );
+      }
+      break;
+    }
+    case "control.release": {
+      sessions.releaseControl(session.id, deviceId);
+      const releaseMsg = createEnvelope({
+        type: "control.release",
+        sessionId: session.id,
+        payload: { deviceId },
+      });
+      broadcastToClients(session, releaseMsg);
+      sendToHost(session, releaseMsg);
+      break;
+    }
+    case "session.heartbeat":
+      break;
+    default:
+      sendToHost(session, envelope);
+      break;
+  }
+}
+
+function broadcastToClients(
+  session: ReturnType<SessionManager["get"]> & {},
+  envelope: Envelope,
+): void {
+  const data = serializeEnvelope(envelope);
+  for (const [, client] of session.clients) {
+    if (client.socket.readyState === client.socket.OPEN) {
+      client.socket.send(data);
+    }
+  }
+}
+
+function sendToHost(
+  session: ReturnType<SessionManager["get"]> & {},
+  envelope: Envelope,
+): void {
+  if (session.host && session.host.socket.readyState === session.host.socket.OPEN) {
+    session.host.socket.send(serializeEnvelope(envelope));
+  }
+}

package/src/sessions.ts

@@ -0,0 +1,205 @@
+import type WebSocket from "ws";
+import type { Envelope } from "@linkshell/protocol";
+
+export type SessionState = "active" | "host_disconnected" | "terminated";
+
+export interface ConnectedDevice {
+  socket: WebSocket;
+  role: "host" | "client";
+  deviceId: string;
+  connectedAt: number;
+}
+
+export interface Session {
+  id: string;
+  state: SessionState;
+  host: ConnectedDevice | undefined;
+  clients: Map<string, ConnectedDevice>;
+  controllerId: string | undefined;
+  lastActivity: number;
+  createdAt: number;
+  outputBuffer: Envelope[];
+  hostDisconnectedAt: number | undefined;
+  // Metadata from host's session.connect
+  provider: string | undefined;
+  hostname: string | undefined;
+}
+
+const OUTPUT_BUFFER_CAPACITY = 200;
+const HOST_RECONNECT_WINDOW = 60_000; // 60s
+const CLEANUP_INTERVAL = 30_000;
+
+export class SessionManager {
+  private sessions = new Map<string, Session>();
+  private cleanupTimer: ReturnType<typeof setInterval>;
+
+  constructor() {
+    this.cleanupTimer = setInterval(() => this.cleanup(), CLEANUP_INTERVAL);
+  }
+
+  getOrCreate(sessionId: string): Session {
+    let session = this.sessions.get(sessionId);
+    if (!session) {
+      session = {
+        id: sessionId,
+        state: "active",
+        host: undefined,
+        clients: new Map(),
+        controllerId: undefined,
+        lastActivity: Date.now(),
+        createdAt: Date.now(),
+        outputBuffer: [],
+        hostDisconnectedAt: undefined,
+        provider: undefined,
+        hostname: undefined,
+      };
+      this.sessions.set(sessionId, session);
+    }
+    return session;
+  }
+
+  get(sessionId: string): Session | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  setHost(sessionId: string, device: ConnectedDevice): void {
+    const session = this.getOrCreate(sessionId);
+    session.host = device;
+    session.state = "active";
+    session.hostDisconnectedAt = undefined;
+    session.lastActivity = Date.now();
+  }
+
+  addClient(sessionId: string, device: ConnectedDevice): void {
+    const session = this.getOrCreate(sessionId);
+    session.clients.set(device.deviceId, device);
+    session.lastActivity = Date.now();
+  }
+
+  removeHost(
+    sessionId: string,
+  ): { clients: Map<string, ConnectedDevice> } | undefined {
+    const session = this.sessions.get(sessionId);
+    if (!session) return undefined;
+    session.host = undefined;
+    session.state = "host_disconnected";
+    session.hostDisconnectedAt = Date.now();
+    return { clients: session.clients };
+  }
+
+  removeClient(sessionId: string, deviceId: string): void {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+    session.clients.delete(deviceId);
+    if (session.controllerId === deviceId) {
+      // Transfer control to next client or clear
+      const next = session.clients.keys().next();
+      session.controllerId = next.done ? undefined : next.value;
+    }
+    this.maybeDelete(sessionId);
+  }
+
+  bufferOutput(sessionId: string, envelope: Envelope): void {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+    session.outputBuffer.push(envelope);
+    if (session.outputBuffer.length > OUTPUT_BUFFER_CAPACITY) {
+      session.outputBuffer.shift();
+    }
+    session.lastActivity = Date.now();
+  }
+
+  getReplayFrom(sessionId: string, afterSeq: number): Envelope[] {
+    const session = this.sessions.get(sessionId);
+    if (!session) return [];
+    return session.outputBuffer.filter(
+      (e) => e.seq !== undefined && e.seq > afterSeq,
+    );
+  }
+
+  claimControl(sessionId: string, deviceId: string): boolean {
+    const session = this.sessions.get(sessionId);
+    if (!session) return false;
+    if (session.controllerId && session.controllerId !== deviceId) {
+      return false;
+    }
+    session.controllerId = deviceId;
+    return true;
+  }
+
+  releaseControl(sessionId: string, deviceId: string): boolean {
+    const session = this.sessions.get(sessionId);
+    if (!session) return false;
+    if (session.controllerId !== deviceId) return false;
+    session.controllerId = undefined;
+    return true;
+  }
+
+  terminate(sessionId: string): void {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+    session.state = "terminated";
+  }
+
+  listActive(): Session[] {
+    return [...this.sessions.values()].filter((s) => s.state !== "terminated");
+  }
+
+  getSummary(sessionId: string) {
+    const session = this.sessions.get(sessionId);
+    if (!session) return undefined;
+    return {
+      id: session.id,
+      state: session.state,
+      hasHost: !!session.host,
+      clientCount: session.clients.size,
+      controllerId: session.controllerId ?? null,
+      lastActivity: session.lastActivity,
+      createdAt: session.createdAt,
+      bufferSize: session.outputBuffer.length,
+      provider: session.provider ?? null,
+      hostname: session.hostname ?? null,
+    };
+  }
+
+  setMetadata(sessionId: string, provider?: string, hostname?: string): void {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+    if (provider) session.provider = provider;
+    if (hostname) session.hostname = hostname;
+  }
+
+  private maybeDelete(sessionId: string): void {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+    if (!session.host && session.clients.size === 0) {
+      this.sessions.delete(sessionId);
+    }
+  }
+
+  private cleanup(): void {
+    const now = Date.now();
+    for (const [id, session] of this.sessions) {
+      // Remove sessions where host disconnected and window expired
+      if (
+        session.state === "host_disconnected" &&
+        session.hostDisconnectedAt &&
+        now - session.hostDisconnectedAt > HOST_RECONNECT_WINDOW
+      ) {
+        session.state = "terminated";
+      }
+      // Clean up terminated sessions with no connections
+      if (
+        session.state === "terminated" &&
+        !session.host &&
+        session.clients.size === 0
+      ) {
+        this.sessions.delete(id);
+      }
+    }
+  }
+
+  destroy(): void {
+    clearInterval(this.cleanupTimer);
+  }
+}