@takosjp/yurucommu-core 3.2.1 → 3.4.0

package/src/backend/runtime/realtime-stream-do.ts

@@ -0,0 +1,323 @@
+/**
+ * RealtimeStreamDO — per-local-user realtime fanout stream.
+ *
+ * One DO instance per local actor (`idFromName(actorApId)`). It is the single
+ * standing WebSocket the browser keeps open; every live update the client used
+ * to poll for (talk messages, typing, read receipts, notifications, unread
+ * counters) is pushed through it as a `RealtimeEvent`.
+ *
+ * Producers (the worker's REST handlers and queue consumers) POST events to
+ * `/_emit`; the DO assigns a monotonic id, persists the event into a small
+ * ring buffer (so a reconnect can replay the gap across hibernation), and
+ * broadcasts to every connected socket. Deliberately separate from
+ * `CallSignalingDurableObject`: call signaling is ephemeral SDP/ICE with its
+ * own state machine, while this stream is a durable-ordered event feed.
+ *
+ * Auth model: the DO binding is the trust boundary. `/ _ws` upgrades arrive
+ * only via the worker route, which either resolved the session actor or
+ * verified a one-time ticket this DO minted earlier (`/_ticket`); the DO
+ * re-checks ticket upgrades against its own storage so a ticket is
+ * single-use and expires even if the worker is confused.
+ *
+ * Uses Hibernatable WebSockets: idle sockets are evicted from memory and the
+ * ring buffer lives in DO storage, so an idle connected user costs nothing.
+ */
+
+import type {
+  RealtimeEvent,
+  RealtimeServerFrame,
+} from "../../../packages/api/src/types/realtime.ts";
+import { parseRealtimeClientFrame } from "../../../packages/api/src/types/realtime.ts";
+
+// --- Minimal Cloudflare DO + Hibernatable WebSocket surface ----------------
+// (typed file-locally, matching call-signaling-do.ts, so this file does not
+// depend on a specific @cloudflare/workers-types version)
+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;
+    limit?: number;
+    reverse?: boolean;
+  }): Promise<Map<string, T>>;
+}
+interface DoState {
+  acceptWebSocket(ws: DoWebSocket, tags?: string[]): void;
+  getWebSockets(tag?: string): DoWebSocket[];
+  readonly storage: DoStorage;
+}
+declare const WebSocketPair: {
+  new (): { 0: DoWebSocket; 1: DoWebSocket };
+};
+
+const SEQ_KEY = "seq";
+const EVENT_PREFIX = "evt:";
+/** Ring buffer size: how many events a reconnect can replay before `resync`. */
+const EVENT_BUFFER_SIZE = 200;
+const TICKET_PREFIX = "ticket:";
+/** Outstanding one-time tickets per user (multiple tabs may mint at once). */
+const MAX_OUTSTANDING_TICKETS = 8;
+const TICKET_TTL_MS = 60_000;
+
+interface StoredTicket {
+  hash: string;
+  expiresAt: number;
+}
+
+function eventKey(seq: number): string {
+  // Fixed-width key so storage.list({prefix}) returns events in seq order.
+  return `${EVENT_PREFIX}${String(seq).padStart(12, "0")}`;
+}
+
+async function sha256Hex(value: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(value),
+  );
+  return [...new Uint8Array(digest)]
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/** Constant-time hex-string comparison (both inputs are fixed-width hashes). */
+function timingSafeEqualHex(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
+export class RealtimeStreamDO {
+  private seqCache: number | null = null;
+
+  constructor(private readonly state: DoState) {}
+
+  async fetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    switch (url.pathname) {
+      case "/_ws":
+        return this.handleUpgrade(request);
+      case "/_emit":
+        return this.handleEmit(request);
+      case "/_ticket":
+        return this.handleMintTicket(request);
+      case "/_state":
+        return this.handleState();
+      default:
+        return new Response("not found", { status: 404 });
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Ticket mint + verify (one-time, short-lived; stored only as a hash)
+  // -------------------------------------------------------------------------
+  private async handleMintTicket(request: Request): Promise<Response> {
+    if (request.method !== "POST") {
+      return new Response("method not allowed", { status: 405 });
+    }
+    const ticket =
+      crypto.randomUUID().replaceAll("-", "") +
+      crypto.randomUUID().replaceAll("-", "");
+    const hash = await sha256Hex(ticket);
+    const now = Date.now();
+
+    const stored = await this.state.storage.list<StoredTicket>({
+      prefix: TICKET_PREFIX,
+    });
+    // Drop expired tickets; keep the newest few so parallel tabs still work.
+    const live = [...stored.entries()]
+      .filter(([, t]) => t.expiresAt > now)
+      .sort((a, b) => a[1].expiresAt - b[1].expiresAt);
+    for (const [key] of stored) {
+      if (!live.some(([liveKey]) => liveKey === key)) {
+        await this.state.storage.delete(key);
+      }
+    }
+    while (live.length >= MAX_OUTSTANDING_TICKETS) {
+      const [oldestKey] = live.shift()!;
+      await this.state.storage.delete(oldestKey);
+    }
+    await this.state.storage.put(`${TICKET_PREFIX}${hash}`, {
+      hash,
+      expiresAt: now + TICKET_TTL_MS,
+    } satisfies StoredTicket);
+
+    return Response.json({ ticket });
+  }
+
+  private async consumeTicket(ticket: string): Promise<boolean> {
+    const hash = await sha256Hex(ticket);
+    const key = `${TICKET_PREFIX}${hash}`;
+    const stored = await this.state.storage.get<StoredTicket>(key);
+    if (!stored) return false;
+    // Single-use: consume before validating expiry so a replay always misses.
+    await this.state.storage.delete(key);
+    if (stored.expiresAt <= Date.now()) return false;
+    return timingSafeEqualHex(stored.hash, hash);
+  }
+
+  // -------------------------------------------------------------------------
+  // WebSocket upgrade
+  // -------------------------------------------------------------------------
+  private async handleUpgrade(request: Request): Promise<Response> {
+    if (request.headers.get("Upgrade")?.toLowerCase() !== "websocket") {
+      return new Response("expected websocket", { status: 426 });
+    }
+    // The worker route either authenticated the session itself (auth=session)
+    // or forwards a ticket this DO minted; re-verify tickets against storage.
+    const authMode = request.headers.get("X-Realtime-Auth");
+    if (authMode === "ticket") {
+      const ticket = request.headers.get("X-Realtime-Ticket") ?? "";
+      if (!ticket || !(await this.consumeTicket(ticket))) {
+        return new Response("invalid ticket", { status: 401 });
+      }
+    } else if (authMode !== "session") {
+      return new Response("unauthorized", { status: 401 });
+    }
+
+    const pair = new WebSocketPair();
+    const client = pair[0];
+    const server = pair[1];
+    this.state.acceptWebSocket(server);
+    return new Response(null, {
+      status: 101,
+      // `webSocket` is a Cloudflare-specific ResponseInit field.
+      webSocket: client,
+    } as unknown as ResponseInit);
+  }
+
+  // -------------------------------------------------------------------------
+  // Event ingest + fanout
+  // -------------------------------------------------------------------------
+  private async handleEmit(request: Request): Promise<Response> {
+    if (request.method !== "POST") {
+      return new Response("method not allowed", { status: 405 });
+    }
+    let body: { type?: unknown; data?: unknown };
+    try {
+      body = (await request.json()) as { type?: unknown; data?: unknown };
+    } catch {
+      return new Response("bad json", { status: 400 });
+    }
+    if (typeof body.type !== "string" || !body.type) {
+      return new Response("bad event", { status: 400 });
+    }
+    const data =
+      body.data && typeof body.data === "object"
+        ? (body.data as Record<string, unknown>)
+        : {};
+
+    const seq = (await this.currentSeq()) + 1;
+    const event: RealtimeEvent = {
+      id: seq,
+      type: body.type as RealtimeEvent["type"],
+      data,
+    };
+    await this.state.storage.put(eventKey(seq), event);
+    await this.state.storage.put(SEQ_KEY, seq);
+    this.seqCache = seq;
+    const pruneSeq = seq - EVENT_BUFFER_SIZE;
+    if (pruneSeq > 0) {
+      await this.state.storage.delete(eventKey(pruneSeq));
+    }
+
+    this.broadcast({ t: "event", event });
+    return Response.json({
+      id: seq,
+      sockets: this.state.getWebSockets().length,
+    });
+  }
+
+  private async handleState(): Promise<Response> {
+    return Response.json({
+      seq: await this.currentSeq(),
+      sockets: this.state.getWebSockets().length,
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Hibernatable WebSocket events
+  // -------------------------------------------------------------------------
+  async webSocketMessage(
+    ws: DoWebSocket,
+    message: string | ArrayBuffer,
+  ): Promise<void> {
+    if (typeof message !== "string") return;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(message);
+    } catch {
+      return;
+    }
+    const frame = parseRealtimeClientFrame(parsed);
+    if (!frame) return;
+
+    switch (frame.t) {
+      case "ping":
+        this.send(ws, { t: "pong" });
+        return;
+      case "pong":
+        return;
+      case "hello": {
+        const seq = await this.currentSeq();
+        if (frame.lastEventId !== undefined && frame.lastEventId < seq) {
+          const oldestBuffered = Math.max(1, seq - EVENT_BUFFER_SIZE + 1);
+          if (frame.lastEventId >= oldestBuffered - 1) {
+            for (let i = frame.lastEventId + 1; i <= seq; i++) {
+              const event = await this.state.storage.get<RealtimeEvent>(
+                eventKey(i),
+              );
+              if (event) this.send(ws, { t: "event", event });
+            }
+          } else {
+            // Gap predates the ring buffer: the client must re-fetch via REST.
+            this.send(ws, { t: "resync" });
+          }
+        }
+        this.send(ws, { t: "hello_ok", lastEventId: seq });
+        return;
+      }
+    }
+  }
+
+  async webSocketClose(ws: DoWebSocket): Promise<void> {
+    try {
+      ws.close();
+    } catch {
+      // already closing
+    }
+  }
+
+  async webSocketError(): Promise<void> {
+    // getWebSockets() excludes the errored socket automatically.
+  }
+
+  // -------------------------------------------------------------------------
+  // Internals
+  // -------------------------------------------------------------------------
+  private async currentSeq(): Promise<number> {
+    if (this.seqCache !== null) return this.seqCache;
+    const stored = await this.state.storage.get<number>(SEQ_KEY);
+    this.seqCache = typeof stored === "number" ? stored : 0;
+    return this.seqCache;
+  }
+
+  private broadcast(frame: RealtimeServerFrame): void {
+    for (const ws of this.state.getWebSockets()) this.send(ws, frame);
+  }
+
+  private send(ws: DoWebSocket, frame: RealtimeServerFrame): void {
+    try {
+      ws.send(JSON.stringify(frame));
+    } catch {
+      // socket gone; getWebSockets() will drop it
+    }
+  }
+}

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,14 @@ 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;
+  // Per-user realtime event stream (talk/typing/read/notification/unread push).
+  // Same pass-through; optional: when unbound the realtime routes answer 503
+  // and clients fall back to their low-frequency polling loops.
+  REALTIME_STREAM?: 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";