@takosjp/yurucommu-core 3.2.1 → 3.3.0

package/src/backend/runtime/call-signaling-do.ts

@@ -0,0 +1,242 @@
+/**
+ * CallSignalingDurableObject — per-local-user signaling hub (call feature).
+ *
+ * One DO instance per local actor (`idFromName(actorApId)`). It is the standing
+ * presence socket the browser connects to (so an incoming ring can arrive before
+ * any call object exists), the fan-in point for cross-instance signals delivered
+ * to `/ap/rtc/signal`, and the owner of the per-call state machine (via the
+ * runtime-neutral `CallHub`).
+ *
+ * Uses Hibernatable WebSockets: idle presence sockets can be evicted and the DO
+ * reconstructs its `CallHub` from durable storage (`call:*` records) on wake.
+ * The CF/DO + Hibernatable-WebSocket surface is typed file-locally so this file
+ * does not depend on a specific `@cloudflare/workers-types` version.
+ */
+
+import { getDb } from "../../db/index.ts";
+import type { EnvVars } from "../types.ts";
+import { CallHub, type CallRecord } from "./call-hub-core.ts";
+import { createCallHubPort } from "./call-hub-port.ts";
+import type {
+  ClientToHubFrame,
+  HubToClientFrame,
+  RtcSignalEnvelopeV1,
+} from "../../../packages/api/src/types/call.ts";
+import {
+  isTerminalCallState,
+  parseRtcSignalEnvelope,
+} from "../../../packages/api/src/types/call.ts";
+
+// --- Minimal Cloudflare DO + Hibernatable WebSocket surface ----------------
+interface DoWebSocket {
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+}
+interface DoStorage {
+  get<T = unknown>(key: string): Promise<T | undefined>;
+  put(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  list<T = unknown>(options?: { prefix?: string }): Promise<Map<string, T>>;
+  setAlarm(scheduledTime: number): Promise<void>;
+  getAlarm(): Promise<number | null>;
+}
+interface DoState {
+  acceptWebSocket(ws: DoWebSocket, tags?: string[]): void;
+  getWebSockets(tag?: string): DoWebSocket[];
+  readonly storage: DoStorage;
+}
+declare const WebSocketPair: {
+  new (): { 0: DoWebSocket; 1: DoWebSocket };
+};
+
+type CallDoEnv = EnvVars & {
+  DB: D1Database;
+  CALL_SIGNALING?: DurableObjectNamespace;
+};
+
+const ALARM_INTERVAL_MS = 15_000;
+const ACTOR_KEY = "actor";
+const CALL_PREFIX = "call:";
+
+export class CallSignalingDurableObject {
+  private hub: CallHub | null = null;
+  private actorApId: string | null = null;
+
+  constructor(
+    private readonly state: DoState,
+    private readonly env: CallDoEnv,
+  ) {}
+
+  // -------------------------------------------------------------------------
+  // HTTP entry (from the CloudflareSignalingHub adapter)
+  // -------------------------------------------------------------------------
+  async fetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    if (url.pathname === "/_ws") {
+      return this.handleUpgrade(request, url);
+    }
+    if (url.pathname === "/_ingest") {
+      return this.handleIngest(request);
+    }
+    return new Response("not found", { status: 404 });
+  }
+
+  private async handleUpgrade(request: Request, url: URL): Promise<Response> {
+    if (request.headers.get("Upgrade")?.toLowerCase() !== "websocket") {
+      return new Response("expected websocket", { status: 426 });
+    }
+    const actor =
+      request.headers.get("X-Call-Actor") ?? url.searchParams.get("actor");
+    if (!actor) return new Response("missing actor", { status: 400 });
+    await this.setActor(actor);
+
+    const pair = new WebSocketPair();
+    const client = pair[0];
+    const server = pair[1];
+    this.state.acceptWebSocket(server);
+    await this.scheduleAlarm();
+    return new Response(null, {
+      status: 101,
+      // `webSocket` is a Cloudflare-specific ResponseInit field.
+      webSocket: client,
+    } as unknown as ResponseInit);
+  }
+
+  private async handleIngest(request: Request): Promise<Response> {
+    let body: unknown;
+    try {
+      body = await request.json();
+    } catch {
+      return new Response("bad json", { status: 400 });
+    }
+    const envelope = parseRtcSignalEnvelope(body);
+    if (!envelope) return new Response("bad envelope", { status: 400 });
+    await this.setActor(envelope.to);
+    const hub = await this.ensureHub();
+    if (!hub) return new Response("no actor", { status: 409 });
+    await hub.handleInboundSignal(envelope);
+    await this.scheduleAlarm();
+    return new Response(null, { status: 204 });
+  }
+
+  // -------------------------------------------------------------------------
+  // Hibernatable WebSocket events
+  // -------------------------------------------------------------------------
+  async webSocketMessage(
+    ws: DoWebSocket,
+    message: string | ArrayBuffer,
+  ): Promise<void> {
+    if (typeof message !== "string") return;
+    let frame: ClientToHubFrame;
+    try {
+      const parsed = JSON.parse(message);
+      if (!parsed || typeof parsed.t !== "string") return;
+      frame = parsed as ClientToHubFrame;
+    } catch {
+      return;
+    }
+    const hub = await this.ensureHub();
+    if (!hub) {
+      this.send(ws, { t: "error", code: "no_session" });
+      return;
+    }
+    await hub.handleClientFrame(this.wrap(ws), frame);
+    await this.scheduleAlarm();
+  }
+
+  async webSocketClose(ws: DoWebSocket): Promise<void> {
+    try {
+      ws.close();
+    } catch {
+      // already closing
+    }
+  }
+
+  async webSocketError(): Promise<void> {
+    // getWebSockets() excludes the errored socket automatically.
+  }
+
+  async alarm(): Promise<void> {
+    const hub = await this.ensureHub();
+    hub?.tick();
+    const active = (hub?.activeCalls().length ?? 0) > 0;
+    const connected = this.state.getWebSockets().length > 0;
+    if (active || connected) await this.scheduleAlarm(true);
+  }
+
+  // -------------------------------------------------------------------------
+  // Internals
+  // -------------------------------------------------------------------------
+  private async setActor(actor: string): Promise<void> {
+    if (this.actorApId === actor) return;
+    this.actorApId = actor;
+    await this.state.storage.put(ACTOR_KEY, actor);
+  }
+
+  private async ensureHub(): Promise<CallHub | null> {
+    if (this.hub) return this.hub;
+    const actor =
+      this.actorApId ?? (await this.state.storage.get<string>(ACTOR_KEY));
+    if (!actor) return null;
+    this.actorApId = actor;
+
+    const db = getDb(this.env.DB);
+    const storage = this.state.storage;
+    const base = createCallHubPort({
+      localActorApId: actor,
+      db,
+      env: this.env,
+      broadcast: (frame: HubToClientFrame) => {
+        for (const ws of this.state.getWebSockets()) this.send(ws, frame);
+      },
+      hasClients: () => this.state.getWebSockets().length > 0,
+    });
+    // Layer durable DO storage on top of the D1 persist so the in-memory call
+    // map survives hibernation.
+    const hub = new CallHub({
+      ...base,
+      persist: async (call: CallRecord) => {
+        if (isTerminalCallState(call.state)) {
+          await storage.delete(`${CALL_PREFIX}${call.callId}`);
+        } else {
+          await storage.put(`${CALL_PREFIX}${call.callId}`, call);
+        }
+        await base.persist?.(call);
+      },
+    });
+    const stored = await storage.list<CallRecord>({ prefix: CALL_PREFIX });
+    hub.hydrate([...stored.values()]);
+    this.hub = hub;
+    return hub;
+  }
+
+  private wrap(ws: DoWebSocket) {
+    return {
+      send: (frame: HubToClientFrame) => this.send(ws, frame),
+      close: (code?: number, reason?: string) => {
+        try {
+          ws.close(code, reason);
+        } catch {
+          // ignore
+        }
+      },
+    };
+  }
+
+  private send(ws: DoWebSocket, frame: HubToClientFrame): void {
+    try {
+      ws.send(JSON.stringify(frame));
+    } catch {
+      // socket gone; getWebSockets() will drop it
+    }
+  }
+
+  private async scheduleAlarm(force = false): Promise<void> {
+    const existing = await this.state.storage.getAlarm();
+    if (existing !== null && !force) return;
+    await this.state.storage.setAlarm(Date.now() + ALARM_INTERVAL_MS);
+  }
+}
+
+// Re-exported here so the type is available to callers that only import the DO.
+export type { RtcSignalEnvelopeV1 };

package/src/backend/runtime/signaling-hub.ts

@@ -0,0 +1,187 @@
+/**
+ * ISignalingHub — the seam that decouples call signaling from the Durable Object
+ * runtime. The `/api/rtc/socket` and `/ap/rtc/signal` routes talk to this
+ * interface; on Cloudflare it forwards to the per-user `CallSignalingDurable
+ * Object`, and on a Bun/Node self-host it uses an in-process hub.
+ *
+ * The DO instance itself is addressed by `idFromName(actorApId)`, so signaling
+ * for a given local user always lands on the same object regardless of which
+ * edge handled the request.
+ */
+
+import type { Env } from "../types.ts";
+import type { RtcSignalEnvelopeV1 } from "../../../packages/api/src/types/call.ts";
+import type {
+  ClientToHubFrame,
+  HubToClientFrame,
+} from "../../../packages/api/src/types/call.ts";
+import { CallHub, type HubConnection } from "./call-hub-core.ts";
+import { createCallHubPort } from "./call-hub-port.ts";
+import { logger } from "../lib/logger.ts";
+
+const log = logger.child({ component: "rtc.hub" });
+
+export interface ISignalingHub {
+  /** Handle a browser WebSocket upgrade for `actorApId` (returns 101). */
+  upgrade(request: Request, actorApId: string): Promise<Response>;
+  /** Push an inbound cross-instance signal to `actorApId`'s live sockets. */
+  deliver(actorApId: string, envelope: RtcSignalEnvelopeV1): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Cloudflare: forward to the per-user Durable Object
+// ---------------------------------------------------------------------------
+class CloudflareSignalingHub implements ISignalingHub {
+  constructor(private readonly ns: DurableObjectNamespace) {}
+
+  private stub(actorApId: string): DurableObjectStub {
+    return this.ns.get(this.ns.idFromName(actorApId));
+  }
+
+  async upgrade(request: Request, actorApId: string): Promise<Response> {
+    const headers = new Headers(request.headers);
+    headers.set("X-Call-Actor", actorApId);
+    const forwarded = new Request("https://call-do/_ws", {
+      method: "GET",
+      headers,
+    });
+    return this.stub(actorApId).fetch(
+      forwarded as unknown as Parameters<DurableObjectStub["fetch"]>[0],
+    ) as unknown as Promise<Response>;
+  }
+
+  async deliver(
+    actorApId: string,
+    envelope: RtcSignalEnvelopeV1,
+  ): Promise<void> {
+    await this.stub(actorApId).fetch("https://call-do/_ingest", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(envelope),
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// In-process (Bun/Node self-host): a per-actor CallHub + live socket set.
+// The Bun server WebSocket wiring drives attach()/message()/detach(); the DO-
+// less runtime therefore keeps calls working without Cloudflare.
+// ---------------------------------------------------------------------------
+export interface LocalSocket {
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+}
+
+interface LocalUserHub {
+  hub: CallHub;
+  sockets: Set<LocalSocket>;
+}
+
+class LocalSignalingHub implements ISignalingHub {
+  private readonly users = new Map<string, LocalUserHub>();
+
+  constructor(private readonly env: Env) {}
+
+  private getOrCreate(actorApId: string): LocalUserHub {
+    let entry = this.users.get(actorApId);
+    if (entry) return entry;
+    const sockets = new Set<LocalSocket>();
+    const port = createCallHubPort({
+      localActorApId: actorApId,
+      db: this.env.DB_INSTANCE,
+      env: this.env,
+      broadcast: (frame: HubToClientFrame) => {
+        const data = JSON.stringify(frame);
+        for (const s of sockets) {
+          try {
+            s.send(data);
+          } catch {
+            // drop dead socket on next detach
+          }
+        }
+      },
+      hasClients: () => sockets.size > 0,
+    });
+    entry = { hub: new CallHub(port), sockets };
+    this.users.set(actorApId, entry);
+    return entry;
+  }
+
+  private wrap(socket: LocalSocket): HubConnection {
+    return {
+      send: (frame) => socket.send(JSON.stringify(frame)),
+      close: (code, reason) => socket.close(code, reason),
+    };
+  }
+
+  /** Register a live browser socket (called by the Bun server WS handler). */
+  attach(actorApId: string, socket: LocalSocket): void {
+    this.getOrCreate(actorApId).sockets.add(socket);
+  }
+
+  detach(actorApId: string, socket: LocalSocket): void {
+    this.users.get(actorApId)?.sockets.delete(socket);
+  }
+
+  /** Route a browser frame (called by the Bun server WS message handler). */
+  async message(
+    actorApId: string,
+    socket: LocalSocket,
+    raw: string,
+  ): Promise<void> {
+    let frame: ClientToHubFrame;
+    try {
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed.t !== "string") return;
+      frame = parsed as ClientToHubFrame;
+    } catch {
+      return;
+    }
+    await this.getOrCreate(actorApId).hub.handleClientFrame(
+      this.wrap(socket),
+      frame,
+    );
+  }
+
+  async upgrade(_request: Request, _actorApId: string): Promise<Response> {
+    // The Bun runtime upgrades WebSockets at the server boundary (server.upgrade)
+    // and drives attach()/message()/detach() directly, so this Hono-level path is
+    // never used there. Reaching it means a runtime without Durable Objects and
+    // without the Bun WS wiring.
+    return new Response(
+      JSON.stringify({
+        error: "signaling_unavailable",
+        message: "Call signaling requires the Durable Objects runtime.",
+      }),
+      { status: 503, headers: { "Content-Type": "application/json" } },
+    );
+  }
+
+  async deliver(
+    actorApId: string,
+    envelope: RtcSignalEnvelopeV1,
+  ): Promise<void> {
+    await this.getOrCreate(actorApId).hub.handleInboundSignal(envelope);
+  }
+}
+
+// One in-process hub per worker process (Bun/Node path only).
+let localHubSingleton: LocalSignalingHub | null = null;
+
+/** Resolve the signaling hub for this runtime. */
+export function getSignalingHub(env: Env): ISignalingHub {
+  if (env.CALL_SIGNALING) {
+    return new CloudflareSignalingHub(env.CALL_SIGNALING);
+  }
+  if (!localHubSingleton) localHubSingleton = new LocalSignalingHub(env);
+  return localHubSingleton;
+}
+
+/** Whether calls can be served on this runtime (a signaling transport exists). */
+export function isSignalingAvailable(env: Env): boolean {
+  // Cloudflare DO binding is the supported production transport. (The in-process
+  // Bun hub exists but its browser WS wiring is host-server-driven.)
+  return Boolean(env.CALL_SIGNALING);
+}
+
+export { log as signalingLog };

package/src/backend/types.ts

@@ -85,6 +85,30 @@ export interface EnvVars {
   // 既存動作と同じ (= APP_URL 単一 origin のみ accept、 production 影響ゼロ)。
   CSRF_ALLOWED_ORIGINS?: string;
 
+  // --- Call feature (WebRTC voice + video) -------------------------------
+  // ICE (STUN/TURN) servers advertised to authenticated call clients as a JSON
+  // array of { urls, username?, credential? }. When TURN uses coturn's REST
+  // ephemeral-credential scheme instead, set YURUCOMMU_RTC_TURN_URIS +
+  // YURUCOMMU_RTC_TURN_SECRET and the app mints short-lived creds per request.
+  // Unset => STUN-only (P2P still works on permissive networks; TURN is the
+  // single biggest determinant of cross-network 1:1 success, so operators
+  // should configure it). None of this is required for the worker to boot.
+  YURUCOMMU_RTC_ICE_SERVERS?: string;
+  // coturn REST-API ephemeral credentials (RFC 8489 long-term-cred via HMAC).
+  // Comma-separated turn:/turns: URIs + a shared secret; TTL in seconds.
+  YURUCOMMU_RTC_TURN_URIS?: string;
+  YURUCOMMU_RTC_TURN_SECRET?: string; // secret
+  YURUCOMMU_RTC_TURN_TTL?: string;
+  // SFU adapter selector for GROUP calls. "p2p" (default) = no SFU, 1:1 P2P
+  // only. Other values ("whip" / "livekit" / "cloudflare-realtime") select a
+  // WHIP/WHEP-speaking focus so the SFU backend stays vendor-neutral. 1:1 calls
+  // never require any SFU config.
+  YURUCOMMU_RTC_SFU_ADAPTER?: string;
+  YURUCOMMU_RTC_SFU_URL?: string;
+  YURUCOMMU_RTC_SFU_TOKEN?: string; // secret
+  YURUCOMMU_RTC_SFU_APP_ID?: string;
+  YURUCOMMU_RTC_SFU_APP_SECRET?: string; // secret
+
   // Declare the reverse-proxy type so the client-IP resolver trusts the right
   // forwarding header (opt-in; a worker fronted directly by a client cannot
   // spoof its own IP otherwise). Accepted values:
@@ -119,6 +143,10 @@ export type Env = {
   ASSETS?: IStaticAssets;
   DELIVERY_QUEUE?: Queue<DeliveryQueueMessageV1>;
   DELIVERY_DLQ?: Queue<DeliveryDlqMessageV1>;
+  // Signaling hub for the call feature. Passes through wrapCloudflareBindings
+  // untouched (it is not one of DB/MEDIA/KV/ASSETS). Optional: when unbound the
+  // call routes 503 and the rest of the app serves normally.
+  CALL_SIGNALING?: DurableObjectNamespace;
 } & EnvVars;
 
 export type Variables = {

package/src/db/schema/calls.ts

@@ -0,0 +1,46 @@
+/**
+ * Call sessions (WebRTC voice + video).
+ *
+ * One row per call, owned by the LOCAL actor. Ephemeral signaling (SDP/ICE)
+ * never lands here — it flows over the dedicated `/ap/rtc/signal` transport and
+ * the Signaling Durable Object. This table is the durable record: call history,
+ * missed-call surfacing, and current-state lookups.
+ */
+
+import { index, integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { nowIso } from "./date-utils.ts";
+import { actors } from "./actors.ts";
+
+export const callSessions = sqliteTable(
+  "call_sessions",
+  {
+    // callId (client-minted uuid; also the signaling anti-replay nonce).
+    id: text("id").primaryKey(),
+    localActorApId: text("local_actor_ap_id")
+      .notNull()
+      .references(() => actors.apId, { onDelete: "cascade" }),
+    peerActorApId: text("peer_actor_ap_id").notNull(),
+    direction: text("direction").notNull(), // "incoming" | "outgoing"
+    // CallState: ringing | connecting | connected | ended | missed | rejected |
+    // failed | cancelled.
+    state: text("state").notNull().default("ringing"),
+    mediaAudio: integer("media_audio").notNull().default(1),
+    mediaVideo: integer("media_video").notNull().default(0),
+    // Selected SFU focus JSON, or NULL for pure P2P (1:1).
+    sfuFocus: text("sfu_focus"),
+    // Cached peer signaling endpoint so mid-call frames skip re-resolution.
+    peerSignalEndpoint: text("peer_signal_endpoint"),
+    endReason: text("end_reason"),
+    createdAt: text("created_at").notNull().$defaultFn(nowIso),
+    updatedAt: text("updated_at")
+      .notNull()
+      .$defaultFn(nowIso)
+      .$onUpdateFn(nowIso),
+    connectedAt: text("connected_at"),
+    endedAt: text("ended_at"),
+  },
+  (t) => [
+    index("call_sessions_local_created_idx").on(t.localActorApId, t.createdAt),
+    index("call_sessions_state_idx").on(t.state),
+  ],
+);

package/src/db/schema/index.ts

@@ -15,4 +15,5 @@ export * from "./stories.ts";
 export * from "./notes.ts";
 export * from "./messaging.ts";
 export * from "./mobile.ts";
+export * from "./calls.ts";
 export * from "./relations.ts";