@takosjp/yurucommu-core 3.3.0 → 3.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takosjp/yurucommu-core",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "license": "AGPL-3.0-only",
   "type": "module",
   "workspaces": [

package/packages/api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takosjp/yurucommu-api",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Typed client SDK and public API contract for yurucommu-server clients.",
   "license": "AGPL-3.0-only",
   "type": "module",

package/packages/api/src/index.ts

@@ -1,5 +1,6 @@
 export * from "./lib/api.ts";
 export * from "./lib/transport.ts";
 export * from "./lib/rtc-client.ts";
+export * from "./lib/realtime-client.ts";
 export * from "./social-server.ts";
 export * from "./types/index.ts";

package/packages/api/src/lib/rtc-client.ts

@@ -313,9 +313,7 @@ export class CallClient {
     }
   }
 
-  private onRinging(
-    frame: Extract<HubToClientFrame, { t: "ringing" }>,
-  ): void {
+  private onRinging(frame: Extract<HubToClientFrame, { t: "ringing" }>): void {
     if (this.call) {
       // Already busy — auto-decline the second ring.
       this.send({ t: "reject", callId: frame.callId, reason: "busy" });

package/packages/api/src/types/call.ts

@@ -27,13 +27,7 @@ export interface CallMediaKind {
 
 /** Cross-instance signaling message kinds (Matrix-VoIP inspired). */
 export type RtcSignalType =
-  | "offer"
-  | "answer"
-  | "candidate"
-  | "accept"
-  | "reject"
-  | "hangup"
-  | "cancel";
+  "offer" | "answer" | "candidate" | "accept" | "reject" | "hangup" | "cancel";
 
 /**
  * Selected SFU focus for a group call. `null`/absent means pure P2P (1:1).
@@ -286,9 +280,7 @@ export function parseRtcSignalEnvelope(
     candidates: parseCandidates(input.candidates),
     sfuFocus: parseSfuFocus(input.sfuFocus),
     reason:
-      typeof input.reason === "string"
-        ? input.reason.slice(0, 200)
-        : undefined,
+      typeof input.reason === "string" ? input.reason.slice(0, 200) : undefined,
     ts,
     ttlMs,
   };

package/packages/api/src/types/index.ts

@@ -1,6 +1,9 @@
 // Call signaling wire contract + browser<->hub frames (voice + video).
 export * from "./call.ts";
 
+// Realtime stream wire contract (per-user event feed + control frames).
+export * from "./realtime.ts";
+
 // ===== Yurucommu AP-Native Types =====
 
 // Actor represents a user (Person) in ActivityPub

package/packages/api/src/types/realtime.ts

@@ -0,0 +1,139 @@
+/**
+ * Realtime stream wire contract (browser <-> per-user RealtimeStreamDO).
+ *
+ * One authenticated WebSocket per user carries every live update the client
+ * used to poll for: talk messages, typing, read receipts, contact-list
+ * changes, new notifications, and the authoritative unread counters. The
+ * server pushes `RealtimeEvent` envelopes; the client sends only the small
+ * control frames below (writes stay on the REST API).
+ *
+ * Event ids are a per-user monotonic sequence assigned by the Durable Object.
+ * A reconnecting client offers its last seen id in `hello`; the DO replays the
+ * gap from its ring buffer, or answers `resync` when the gap is older than the
+ * buffer so the client re-fetches via the normal REST reads.
+ */
+
+export type RealtimeEventType =
+  | "talk.message"
+  | "talk.typing"
+  | "talk.read"
+  | "talk.contacts_changed"
+  | "notification.new"
+  | "unread";
+
+export interface RealtimeEvent {
+  /** Per-user monotonic sequence number (assigned by the stream DO). */
+  id: number;
+  type: RealtimeEventType;
+  data: Record<string, unknown>;
+}
+
+/** `talk.message` payload. `other_ap_id` is from the RECEIVING user's view. */
+export interface TalkMessageEventData {
+  kind: "dm" | "community";
+  /** DM: the counterpart actor (per-recipient). */
+  other_ap_id?: string;
+  /** Community chat: the community actor. */
+  community_ap_id?: string;
+  conversation_id?: string;
+  message: {
+    id: string;
+    sender: {
+      ap_id: string;
+      username: string;
+      preferred_username: string | null;
+      name: string | null;
+      icon_url: string | null;
+    };
+    content: string | null;
+    attachments?: unknown[];
+    created_at: string | null;
+  };
+}
+
+export interface TalkTypingEventData {
+  other_ap_id: string;
+  is_typing: boolean;
+  typed_at: string;
+}
+
+export interface TalkReadEventData {
+  other_ap_id: string;
+  conversation_id: string;
+  last_read_at: string;
+}
+
+/** Authoritative unread counters (server-computed; never client-derived). */
+export interface UnreadEventData {
+  dm: number;
+  community: number;
+  talk_total: number;
+  notifications: number;
+}
+
+// --- Client -> server frames -------------------------------------------------
+
+export type RealtimeClientFrame =
+  { t: "hello"; lastEventId?: number } | { t: "ping" } | { t: "pong" };
+
+// --- Server -> client frames -------------------------------------------------
+
+export type RealtimeServerFrame =
+  | { t: "hello_ok"; lastEventId: number }
+  | { t: "event"; event: RealtimeEvent }
+  /** The requested replay gap is older than the buffer: re-fetch via REST. */
+  | { t: "resync" }
+  | { t: "ping" }
+  | { t: "pong" };
+
+export function parseRealtimeClientFrame(
+  raw: unknown,
+): RealtimeClientFrame | null {
+  if (!raw || typeof raw !== "object") return null;
+  const frame = raw as { t?: unknown; lastEventId?: unknown };
+  if (frame.t === "ping" || frame.t === "pong") return { t: frame.t };
+  if (frame.t === "hello") {
+    const lastEventId =
+      typeof frame.lastEventId === "number" &&
+      Number.isFinite(frame.lastEventId) &&
+      frame.lastEventId >= 0
+        ? Math.floor(frame.lastEventId)
+        : undefined;
+    return { t: "hello", lastEventId };
+  }
+  return null;
+}
+
+export function parseRealtimeServerFrame(
+  raw: unknown,
+): RealtimeServerFrame | null {
+  if (!raw || typeof raw !== "object") return null;
+  const frame = raw as { t?: unknown; event?: unknown; lastEventId?: unknown };
+  if (frame.t === "ping" || frame.t === "pong" || frame.t === "resync") {
+    return { t: frame.t };
+  }
+  if (frame.t === "hello_ok" && typeof frame.lastEventId === "number") {
+    return { t: "hello_ok", lastEventId: frame.lastEventId };
+  }
+  if (frame.t === "event" && frame.event && typeof frame.event === "object") {
+    const event = frame.event as {
+      id?: unknown;
+      type?: unknown;
+      data?: unknown;
+    };
+    if (typeof event.id === "number" && typeof event.type === "string") {
+      return {
+        t: "event",
+        event: {
+          id: event.id,
+          type: event.type as RealtimeEventType,
+          data:
+            event.data && typeof event.data === "object"
+              ? (event.data as Record<string, unknown>)
+              : {},
+        },
+      };
+    }
+  }
+  return null;
+}

package/src/backend/index.ts

@@ -30,6 +30,8 @@ import { appsApiRoutes, appsServeRoutes } from "./routes/apps.ts";
 import mobileRoutes from "./routes/mobile.ts";
 import notificationPusherRoutes from "./routes/notification-pushers.ts";
 import rtcRoutes from "./routes/rtc/index.ts";
+import realtimeRoutes from "./routes/realtime/index.ts";
+import { sweepRealtimeNotifications } from "./runtime/realtime-hub.ts";
 
 import { rateLimit, RateLimitConfigs } from "./middleware/rate-limit.ts";
 import { csrfProtection } from "./middleware/csrf.ts";
@@ -600,6 +602,9 @@ function applyGlobalMiddleware(app: YurucommuApp): void {
             error,
           });
         }
+        // Same choke point feeds the realtime stream: the push-jobs the inbox
+        // trigger wrote tell us exactly which users gained a notification.
+        await sweepRealtimeNotifications(c.env);
       })();
       // Prefer to run the sweep AFTER the response is sent (waitUntil) so its
       // 2-4 D1 round-trips never add latency to the request. `executionCtx`
@@ -780,6 +785,8 @@ function mountCoreRoutes(app: YurucommuApp): void {
   app.route("/api/moderation", moderationRoutes);
   app.route("/api/apps", appsApiRoutes);
   app.route("/hosted", appsServeRoutes);
+  // Realtime stream: capability probe + WS ticket + per-user socket upgrade.
+  app.route("/api/realtime", realtimeRoutes);
   // Call feature: /api/rtc/* (session) + /ap/rtc/signal (server-to-server).
   app.route("/", rtcRoutes);
   app.route("/", activitypubRoutes);
@@ -953,6 +960,10 @@ type WorkerBindings = EnvVars & {
   // spreads it through untouched (it is not DB/MEDIA/KV/ASSETS) so app code and
   // the rtc routes read it as c.env.CALL_SIGNALING.
   CALL_SIGNALING?: DurableObjectNamespace;
+  // Per-user realtime event stream Durable Object namespace. Same pass-through
+  // as CALL_SIGNALING; optional — when unbound the realtime routes answer 503
+  // and clients fall back to polling.
+  REALTIME_STREAM?: DurableObjectNamespace;
 };
 
 export default {

package/src/backend/lib/delivery/queue.ts

@@ -531,6 +531,10 @@ export async function handleDeliveryQueueBatch(
       error,
     });
   }
+  // Same choke point feeds the realtime stream (federated + fanout inserts).
+  const { sweepRealtimeNotifications } =
+    await import("../../runtime/realtime-hub.ts");
+  await sweepRealtimeNotifications(env);
 }
 
 export async function handleDeliveryDlqBatch(

package/src/backend/lib/unread-counts.ts

@@ -17,8 +17,14 @@
  *   own, after the later of the per-community read time and the join time.
  */
 
-import { sql } from "drizzle-orm";
-import type { Database } from "../../db/index.ts";
+import { and, count, eq, sql } from "drizzle-orm";
+import {
+  activities,
+  inbox as inboxTable,
+  objects,
+  type Database,
+} from "../../db/index.ts";
+import { notificationEligibilityWhere } from "./notification-eligibility.ts";
 
 export interface YurumeUnreadCounts {
   readonly dm: number;
@@ -77,3 +83,58 @@ export async function yurumeUnreadCounts(
   const community = Number(communityRow?.c ?? 0);
   return { dm, community, total: dm + community };
 }
+
+/**
+ * Unread social-notification count. SAME shared eligibility builder as the
+ * notifications list, the badge endpoint, and push delivery (not-self,
+ * user-facing types, archive exclusion, direct-DM exclusion, block/mute
+ * suppression) so a realtime-pushed badge can never drift from the badge the
+ * client fetches.
+ */
+export async function notificationUnreadCount(
+  db: Database,
+  actorApId: string,
+): Promise<number> {
+  const result = await db
+    .select({ count: count() })
+    .from(inboxTable)
+    .innerJoin(activities, eq(inboxTable.activityApId, activities.apId))
+    .leftJoin(objects, eq(activities.objectApId, objects.apId))
+    .where(
+      and(
+        eq(inboxTable.actorApId, actorApId),
+        eq(inboxTable.read, 0),
+        ...notificationEligibilityWhere(db, actorApId, { direct: "exclude" }),
+      ),
+    )
+    .get();
+  return Number(result?.count ?? 0);
+}
+
+export interface UnreadSnapshot {
+  readonly dm: number;
+  readonly community: number;
+  readonly talkTotal: number;
+  readonly notifications: number;
+}
+
+/**
+ * One authoritative unread snapshot (talk + notifications) for the realtime
+ * `unread` event. Server-computed on every emit so clients never derive or
+ * increment counters themselves.
+ */
+export async function computeUnreadSnapshot(
+  db: Database,
+  actorApId: string,
+): Promise<UnreadSnapshot> {
+  const [talk, notifications] = await Promise.all([
+    yurumeUnreadCounts(db, actorApId),
+    notificationUnreadCount(db, actorApId),
+  ]);
+  return {
+    dm: talk.dm,
+    community: talk.community,
+    talkTotal: talk.total,
+    notifications,
+  };
+}

package/src/backend/public.ts

@@ -16,6 +16,9 @@ export { wrapCloudflareBindings } from "./runtime/cloudflare.ts";
 // Call feature: the signaling Durable Object class each product's generated
 // worker entry must re-export so Wrangler can bind CALL_SIGNALING to it.
 export { CallSignalingDurableObject } from "./runtime/call-signaling-do.ts";
+// Realtime stream: the per-user fanout Durable Object class each product's
+// generated worker entry must re-export so Wrangler can bind REALTIME_STREAM.
+export { RealtimeStreamDO } from "./runtime/realtime-stream-do.ts";
 export type { Env, EnvVars } from "./types.ts";
 export type {
   DeliveryDlqMessageV1,

package/src/backend/routes/communities/messages.ts

@@ -23,6 +23,12 @@ import {
 } from "../../lib/attachments.ts";
 import { communityRequiresMembership } from "../../lib/community-visibility.ts";
 import { rateLimit, RateLimitConfigs } from "../../middleware/rate-limit.ts";
+import {
+  emitRealtimeBestEffort,
+  emitUnreadSnapshot,
+  isRealtimeAvailable,
+  runRealtimeAfterResponse,
+} from "../../runtime/realtime-hub.ts";
 import {
   deleteObjectCascade,
   purgeMediaBlobs,
@@ -408,24 +414,54 @@ messagesRouter.post(
       ...pushJobStatements,
     ]);
 
-    return c.json(
-      {
-        message: {
-          id: objectApId,
-          sender: {
-            ap_id: actor.ap_id,
-            username: formatUsername(actor.ap_id),
-            preferred_username: actor.preferred_username,
-            name: actor.name,
-            icon_url: actor.icon_url,
-          },
-          content,
-          attachments,
-          created_at: now,
-        },
+    const messagePayload = {
+      id: objectApId,
+      sender: {
+        ap_id: actor.ap_id,
+        username: formatUsername(actor.ap_id),
+        preferred_username: actor.preferred_username,
+        name: actor.name,
+        icon_url: actor.icon_url,
       },
-      201,
-    );
+      content,
+      attachments,
+      created_at: now,
+    };
+
+    // Realtime fanout to LOCAL members (best-effort, after the response).
+    // Community talk has no inbox row, so the shared notification sweep never
+    // sees it — this direct emit is the only realtime path. Membership rows
+    // exist only for local members (remote membership is a follows edge), and
+    // the fanout is capped so a huge community cannot stall the writer.
+    if (isRealtimeAvailable(c.env)) {
+      const communityApIdForEmit = community.apId;
+      await runRealtimeAfterResponse(c, async () => {
+        const members = await db
+          .select({ actorApId: communityMembers.actorApId })
+          .from(communityMembers)
+          .where(eq(communityMembers.communityApId, communityApIdForEmit))
+          .limit(200);
+        await emitRealtimeBestEffort(
+          c.env,
+          members.map(({ actorApId }) => ({
+            actorApId,
+            type: "talk.message",
+            data: {
+              kind: "community",
+              community_ap_id: communityApIdForEmit,
+              message: messagePayload,
+            },
+          })),
+        );
+        await Promise.all(
+          members
+            .filter(({ actorApId }) => actorApId !== actor.ap_id)
+            .map(({ actorApId }) => emitUnreadSnapshot(c.env, actorApId)),
+        );
+      });
+    }
+
+    return c.json({ message: messagePayload }, 201);
   },
 );
 

package/src/backend/routes/dm/messages.ts

@@ -35,6 +35,10 @@ import {
   resolveConversationId,
 } from "./query-helpers.ts";
 import { enqueueDeliveryToActor } from "../../lib/delivery/queue.ts";
+import {
+  emitRealtimeBestEffort,
+  runRealtimeAfterResponse,
+} from "../../runtime/realtime-hub.ts";
 import { feedCursorWhere } from "../../lib/feed-cursor.ts";
 import { toApAttachments } from "../../lib/activitypub-helpers.ts";
 import { validateChatAttachments } from "../../lib/attachments.ts";
@@ -600,15 +604,51 @@ dm.post("/user/:encodedApId/messages", async (c) => {
     await enqueueDeliveryToActor(c.env, deliveryActivityId, otherApId);
   }
 
+  const messagePayload = {
+    id: apId,
+    sender: buildSenderFromActor(actor),
+    content,
+    attachments,
+    created_at: now,
+  };
+
+  // Realtime fanout (best-effort, after the response): the recipient's open
+  // thread gets the message body without polling; the sender's OTHER tabs and
+  // devices stay in sync too. `other_ap_id` is per-recipient (each side sees
+  // the counterpart). Unread counters flow via the shared post-response sweep
+  // (the inbox trigger wrote a push job for the local recipient).
+  await runRealtimeAfterResponse(c, () =>
+    emitRealtimeBestEffort(c.env, [
+      ...(isRecipientLocal
+        ? [
+            {
+              actorApId: otherApId,
+              type: "talk.message",
+              data: {
+                kind: "dm",
+                other_ap_id: actor.ap_id,
+                conversation_id: conversationId,
+                message: messagePayload,
+              },
+            },
+          ]
+        : []),
+      {
+        actorApId: actor.ap_id,
+        type: "talk.message",
+        data: {
+          kind: "dm",
+          other_ap_id: otherApId,
+          conversation_id: conversationId,
+          message: messagePayload,
+        },
+      },
+    ]),
+  );
+
   return c.json(
     {
-      message: {
-        id: apId,
-        sender: buildSenderFromActor(actor),
-        content,
-        attachments,
-        created_at: now,
-      },
+      message: messagePayload,
       conversation_id: conversationId,
     },
     201,

package/src/backend/routes/dm/read-archive.ts

@@ -11,6 +11,11 @@ import {
   objects,
 } from "../../../db/index.ts";
 import { resolveConversationId } from "./query-helpers.ts";
+import {
+  emitRealtimeBestEffort,
+  emitUnreadSnapshot,
+  runRealtimeAfterResponse,
+} from "../../runtime/realtime-hub.ts";
 import {
   buildActorInfoMap,
   byTimeDesc,
@@ -54,6 +59,23 @@ readArchive.post("/user/:encodedApId/read", async (c) => {
       set: { lastReadAt: now },
     });
 
+  // Live read receipt for the partner's open thread + refreshed unread badge
+  // for the reader's OTHER tabs/devices.
+  await runRealtimeAfterResponse(c, async () => {
+    await emitRealtimeBestEffort(c.env, [
+      {
+        actorApId: otherApId,
+        type: "talk.read",
+        data: {
+          other_ap_id: actor.ap_id,
+          conversation_id: conversationId,
+          last_read_at: now,
+        },
+      },
+    ]);
+    await emitUnreadSnapshot(c.env, actor.ap_id);
+  });
+
   return c.json({ success: true, last_read_at: now });
 });
 
@@ -108,6 +130,11 @@ readArchive.post("/community/:encodedApId/read", async (c) => {
       set: { lastReadAt: now },
     });
 
+  // Refresh the reader's unread badge on their other tabs/devices.
+  await runRealtimeAfterResponse(c, () =>
+    emitUnreadSnapshot(c.env, actor.ap_id),
+  );
+
   return c.json({ success: true, last_read_at: now });
 });
 

package/src/backend/routes/dm/typing.ts

@@ -3,6 +3,10 @@
 import { Hono } from "hono";
 import { and, eq } from "drizzle-orm";
 import { dmTyping } from "../../../db/index.ts";
+import {
+  emitRealtimeBestEffort,
+  runRealtimeAfterResponse,
+} from "../../runtime/realtime-hub.ts";
 import { type HonoEnv, parseOtherApId } from "./conversations-helpers.ts";
 
 const typing = new Hono<HonoEnv>();
@@ -28,6 +32,18 @@ typing.post("/user/:encodedApId/typing", async (c) => {
       set: { lastTypedAt: now },
     });
 
+  // Push the indicator to the partner's live sockets; the GET endpoint stays
+  // as the fallback-polling read.
+  await runRealtimeAfterResponse(c, () =>
+    emitRealtimeBestEffort(c.env, [
+      {
+        actorApId: otherApId,
+        type: "talk.typing",
+        data: { other_ap_id: actor.ap_id, is_typing: true, typed_at: now },
+      },
+    ]),
+  );
+
   return c.json({ success: true, typed_at: now });
 });
 

package/src/backend/routes/notifications.ts

@@ -35,6 +35,10 @@ import {
   NOTIFICATION_ACTIVITY_TYPES,
   notificationEligibilityWhere,
 } from "../lib/notification-eligibility.ts";
+import {
+  emitUnreadSnapshot,
+  runRealtimeAfterResponse,
+} from "../runtime/realtime-hub.ts";
 
 const notifications = new Hono<{ Bindings: Env; Variables: Variables }>();
 
@@ -622,6 +626,11 @@ notifications.post("/read", async (c) => {
     );
   }
 
+  // Sync the reader's OTHER tabs/devices: push the fresh authoritative badge.
+  await runRealtimeAfterResponse(c, () =>
+    emitUnreadSnapshot(c.env, actor.ap_id),
+  );
+
   return c.json({ success: true });
 });
 
@@ -681,6 +690,11 @@ notifications.post("/archive", async (c) => {
     ARCHIVE_CREATE_BATCH_SIZE,
   );
 
+  // Archiving an unread notification removes it from the badge count.
+  await runRealtimeAfterResponse(c, () =>
+    emitUnreadSnapshot(c.env, actor.ap_id),
+  );
+
   return c.json({ success: true, archived_count });
 });
 
@@ -716,6 +730,11 @@ notifications.delete("/archive", async (c) => {
       ),
     );
 
+  // Unarchiving can resurface unread rows into the badge count.
+  await runRealtimeAfterResponse(c, () =>
+    emitUnreadSnapshot(c.env, actor.ap_id),
+  );
+
   return c.json({ success: true });
 });
 
@@ -758,6 +777,12 @@ notifications.post("/archive/all", async (c) => {
     rows,
     ARCHIVE_CREATE_BATCH_SIZE,
   );
+
+  // Archive-all clears the whole badge; sync the reader's other tabs/devices.
+  await runRealtimeAfterResponse(c, () =>
+    emitUnreadSnapshot(c.env, actor.ap_id),
+  );
+
   return c.json({ success: true, archived_count });
 });