Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

refactor(web): bundle committed community websocket delivery (#519)

Gener88484ac0473f
diff --git a/scripts/ci/workflow-contract.test.ts b/scripts/ci/workflow-contract.test.ts
index a6ded8f06..2ce7e0b37 100644
--- a/scripts/ci/workflow-contract.test.ts
+++ b/scripts/ci/workflow-contract.test.ts
@@ -9,6 +9,13 @@ function normalizeWorkflow(text: string): string {
const workflow = normalizeWorkflow(readFileSync(resolve(workflowRoot, "e2e-ui.yml"), "utf8"))
const ciWorkflow = normalizeWorkflow(readFileSync(resolve(workflowRoot, "ci.yml"), "utf8"))
+const wsDoPackage = JSON.parse(
+ readFileSync(resolve(import.meta.dirname, "../../src/ws-do/package.json"), "utf8"),
+) as { scripts: Record<string, string> }
+const rootVitestConfig = readFileSync(
+ resolve(import.meta.dirname, "../../vitest.config.ts"),
+ "utf8",
+)
const autoTagReleaseWorkflow = normalizeWorkflow(
readFileSync(resolve(workflowRoot, "auto-tag-release.yml"), "utf8"),
)
@@ -171,6 +178,17 @@ describe("Turbo CI execution", () => {
"run: pnpm build --filter=@alook/shared --filter=@alook/web --filter=@alook/cli --filter=@alook/email-worker --filter=@alook/ws-do --filter=@alook/wake-worker",
)
})
+
+ it("runs the ordinary ws-do Vitest suite through the standard test task", () => {
+ expect(wsDoPackage.scripts.test).toBe("vitest run --passWithNoTests")
+ expect(wsDoPackage.scripts).not.toHaveProperty("test:workers")
+ expect(ciJob("test-linux")).toContain("pnpm turbo run test --filter='!@alook/daemon'")
+ })
+
+ it("does not exclude ws-do product source from Node coverage", () => {
+ expect(rootVitestConfig).not.toContain('"src/ws-do/src/**"')
+ expect(rootVitestConfig).not.toContain('"src/ws-do/src/**/*.ts"')
+ })
})
describe("Desktop updater release", () => {
diff --git a/src/shared/src/community-ws-bundle.ts b/src/shared/src/community-ws-bundle.ts
new file mode 100644
index 000000000..2a8a8d97e
--- /dev/null
+++ b/src/shared/src/community-ws-bundle.ts
@@ -0,0 +1,344 @@
+import {
+ COMMUNITY_BROWSER_EVENT_CONTRACT_VERSION,
+ COMMUNITY_BROWSER_EVENT_MAX_BYTES,
+ decodeCommunityBrowserEvent,
+ encodeCommunityBrowserEvent,
+ utf8ByteLength,
+ type CommunityBrowserEventEnvelopeV1,
+ type CommunityWsEvent,
+} from "./community-ws-events"
+import { MESSAGE_DELIVERY_MAX_EVENTS_PER_USER } from "./community-message-delivery"
+
+export const COMMUNITY_BROWSER_EVENT_BATCH_TYPE = "community:events.batch" as const
+export const COMMUNITY_DELIVERY_OPERATION_ID_PREFIX = "message:" as const
+export const COMMUNITY_DELIVERY_OPERATION_ID_HEADER = "x-alook-community-operation-id" as const
+export const COMMUNITY_DELIVERY_OPERATION_ID_BYTES = 51
+export const COMMUNITY_DELIVERY_DIGEST_HEX_LENGTH = 64
+export const COMMUNITY_BROWSER_EVENT_BATCH_ENVELOPE_BYTES = 1_024
+export const COMMUNITY_BROWSER_EVENT_BATCH_MAX_BYTES =
+ MESSAGE_DELIVERY_MAX_EVENTS_PER_USER * COMMUNITY_BROWSER_EVENT_MAX_BYTES
+ + COMMUNITY_BROWSER_EVENT_BATCH_ENVELOPE_BYTES
+
+const OPERATION_ID_RE = /^message:[A-Za-z0-9_-]{43}$/
+const DIGEST_RE = /^[0-9a-f]{64}$/
+
+export type CommunityDeliveryOperationId = `${typeof COMMUNITY_DELIVERY_OPERATION_ID_PREFIX}${string}`
+export type CommunityDeliveryDigest = string
+
+export type CommunityBrowserEventBatch = {
+ type: typeof COMMUNITY_BROWSER_EVENT_BATCH_TYPE
+ operationId: CommunityDeliveryOperationId
+ operationDigest: CommunityDeliveryDigest
+ events: CommunityBrowserEventEnvelopeV1[]
+}
+
+export type PreparedCommunityDeliveryEvents = {
+ events: CommunityWsEvent[]
+ envelopes: CommunityBrowserEventEnvelopeV1[]
+ bodies: string[]
+ digest: CommunityDeliveryDigest
+}
+
+export type CommunityDeliveryPrepareFailureReason =
+ | "invalid-event-count"
+ | "invalid-child"
+ | "oversized-child"
+
+export type CommunityDeliveryPrepareResult =
+ | { ok: true; prepared: PreparedCommunityDeliveryEvents }
+ | {
+ ok: false
+ reason: CommunityDeliveryPrepareFailureReason
+ eventIndex?: number
+ byteLength?: number
+ }
+
+export type CommunityBrowserEventBatchEncodeResult =
+ | {
+ ok: true
+ batch: CommunityBrowserEventBatch
+ body: string
+ byteLength: number
+ childBodies: string[]
+ }
+ | {
+ ok: false
+ reason:
+ | CommunityDeliveryPrepareFailureReason
+ | "invalid-operation-id"
+ | "invalid-operation-digest"
+ | "digest-mismatch"
+ | "batch-invariant-oversized"
+ eventIndex?: number
+ byteLength?: number
+ actualDigest?: CommunityDeliveryDigest
+ }
+
+export type CommunityBrowserEventBatchDecodeResult =
+ | { ok: true; batch: CommunityBrowserEventBatch; events: CommunityWsEvent[] }
+ | {
+ ok: false
+ reason:
+ | "oversized"
+ | "non-object"
+ | "missing-type"
+ | "wrong-type"
+ | "invalid-operation-id"
+ | "invalid-operation-digest"
+ | "invalid-payload"
+ | "invalid-event-count"
+ | "invalid-child"
+ eventIndex?: number
+ byteLength?: number
+ }
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function isWellFormedUnicode(value: string): boolean {
+ for (let index = 0; index < value.length; index += 1) {
+ const codeUnit = value.charCodeAt(index)
+ if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
+ const next = value.charCodeAt(index + 1)
+ if (!Number.isInteger(next) || next < 0xdc00 || next > 0xdfff) return false
+ index += 1
+ } else if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
+ return false
+ }
+ }
+ return true
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+ let value = ""
+ for (const byte of bytes) value += byte.toString(16).padStart(2, "0")
+ return value
+}
+
+function bytesToBase64Url(bytes: Uint8Array): string {
+ const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
+ let value = ""
+ for (let index = 0; index < bytes.length; index += 3) {
+ const first = bytes[index] ?? 0
+ const second = bytes[index + 1] ?? 0
+ const third = bytes[index + 2] ?? 0
+ const combined = (first << 16) | (second << 8) | third
+ value += alphabet[(combined >>> 18) & 63]
+ value += alphabet[(combined >>> 12) & 63]
+ if (index + 1 < bytes.length) value += alphabet[(combined >>> 6) & 63]
+ if (index + 2 < bytes.length) value += alphabet[combined & 63]
+ }
+ return value
+}
+
+async function sha256(value: Uint8Array): Promise<Uint8Array> {
+ const input = new Uint8Array(value.byteLength)
+ input.set(value)
+ return new Uint8Array(await crypto.subtle.digest("SHA-256", input.buffer))
+}
+
+export function isCommunityDeliveryOperationId(value: unknown): value is CommunityDeliveryOperationId {
+ return typeof value === "string"
+ && utf8ByteLength(value) === COMMUNITY_DELIVERY_OPERATION_ID_BYTES
+ && OPERATION_ID_RE.test(value)
+}
+
+export function isCommunityDeliveryDigest(value: unknown): value is CommunityDeliveryDigest {
+ return typeof value === "string"
+ && value.length === COMMUNITY_DELIVERY_DIGEST_HEX_LENGTH
+ && DIGEST_RE.test(value)
+}
+
+export async function deriveCommunityDeliveryOperationId(
+ messageId: string,
+): Promise<CommunityDeliveryOperationId> {
+ if (messageId.length === 0 || !isWellFormedUnicode(messageId)) {
+ throw new Error("invalid community delivery message id")
+ }
+ const digest = await sha256(new TextEncoder().encode(messageId))
+ const operationId = `${COMMUNITY_DELIVERY_OPERATION_ID_PREFIX}${bytesToBase64Url(digest)}`
+ if (!isCommunityDeliveryOperationId(operationId)) {
+ throw new Error("invalid derived community delivery operation id")
+ }
+ return operationId
+}
+
+export async function computeCommunityDeliveryDigestFromBodies(
+ bodies: readonly string[],
+): Promise<CommunityDeliveryDigest> {
+ let byteLength = 0
+ const encoded = bodies.map((body) => {
+ const bytes = new TextEncoder().encode(body)
+ byteLength += 4 + bytes.byteLength
+ return bytes
+ })
+ const canonical = new Uint8Array(byteLength)
+ const view = new DataView(canonical.buffer)
+ let offset = 0
+ for (const bytes of encoded) {
+ view.setUint32(offset, bytes.byteLength, false)
+ offset += 4
+ canonical.set(bytes, offset)
+ offset += bytes.byteLength
+ }
+ return bytesToHex(await sha256(canonical))
+}
+
+export async function prepareCommunityDeliveryEvents(
+ values: readonly unknown[],
+): Promise<CommunityDeliveryPrepareResult> {
+ if (values.length < 1 || values.length > MESSAGE_DELIVERY_MAX_EVENTS_PER_USER) {
+ return { ok: false, reason: "invalid-event-count" }
+ }
+ const events: CommunityWsEvent[] = []
+ const envelopes: CommunityBrowserEventEnvelopeV1[] = []
+ const bodies: string[] = []
+ for (let eventIndex = 0; eventIndex < values.length; eventIndex += 1) {
+ const decoded = decodeCommunityBrowserEvent(values[eventIndex])
+ if (!decoded.ok) return { ok: false, reason: "invalid-child", eventIndex }
+ const encoded = encodeCommunityBrowserEvent(decoded.event)
+ if (!encoded.ok) {
+ return {
+ ok: false,
+ reason: encoded.reason === "oversized" ? "oversized-child" : "invalid-child",
+ eventIndex,
+ ...(encoded.byteLength === undefined ? {} : { byteLength: encoded.byteLength }),
+ }
+ }
+ events.push(decoded.event)
+ envelopes.push(encoded.event)
+ bodies.push(encoded.body)
+ }
+ return {
+ ok: true,
+ prepared: {
+ events,
+ envelopes,
+ bodies,
+ digest: await computeCommunityDeliveryDigestFromBodies(bodies),
+ },
+ }
+}
+
+export async function encodeCommunityBrowserEventBatch(input: {
+ operationId: unknown
+ operationDigest: unknown
+ events: readonly unknown[]
+}): Promise<CommunityBrowserEventBatchEncodeResult> {
+ if (!isCommunityDeliveryOperationId(input.operationId)) {
+ return { ok: false, reason: "invalid-operation-id" }
+ }
+ if (!isCommunityDeliveryDigest(input.operationDigest)) {
+ return { ok: false, reason: "invalid-operation-digest" }
+ }
+ const prepared = await prepareCommunityDeliveryEvents(input.events)
+ if (!prepared.ok) return prepared
+ return encodePreparedCommunityBrowserEventBatch({
+ operationId: input.operationId,
+ operationDigest: input.operationDigest,
+ prepared: prepared.prepared,
+ })
+}
+
+export function encodePreparedCommunityBrowserEventBatch(input: {
+ operationId: unknown
+ operationDigest: unknown
+ prepared: PreparedCommunityDeliveryEvents
+}): CommunityBrowserEventBatchEncodeResult {
+ if (!isCommunityDeliveryOperationId(input.operationId)) {
+ return { ok: false, reason: "invalid-operation-id" }
+ }
+ if (!isCommunityDeliveryDigest(input.operationDigest)) {
+ return { ok: false, reason: "invalid-operation-digest" }
+ }
+ if (input.prepared.digest !== input.operationDigest) {
+ return {
+ ok: false,
+ reason: "digest-mismatch",
+ actualDigest: input.prepared.digest,
+ }
+ }
+ const prefix = JSON.stringify({
+ type: COMMUNITY_BROWSER_EVENT_BATCH_TYPE,
+ operationId: input.operationId,
+ operationDigest: input.operationDigest,
+ }).slice(0, -1)
+ const body = `${prefix},"events":[${input.prepared.bodies.join(",")}]}`
+ const byteLength = utf8ByteLength(body)
+ if (byteLength > COMMUNITY_BROWSER_EVENT_BATCH_MAX_BYTES) {
+ return { ok: false, reason: "batch-invariant-oversized", byteLength }
+ }
+ const batch: CommunityBrowserEventBatch = {
+ type: COMMUNITY_BROWSER_EVENT_BATCH_TYPE,
+ operationId: input.operationId,
+ operationDigest: input.operationDigest,
+ events: input.prepared.envelopes,
+ }
+ return { ok: true, batch, body, byteLength, childBodies: input.prepared.bodies }
+}
+
+export function isCommunityBrowserEventBatchCandidate(
+ value: unknown,
+): value is Record<string, unknown> & { type: typeof COMMUNITY_BROWSER_EVENT_BATCH_TYPE } {
+ return isRecord(value) && value.type === COMMUNITY_BROWSER_EVENT_BATCH_TYPE
+}
+
+export function decodeCommunityBrowserEventBatch(
+ value: unknown,
+ encodedByteLength?: number,
+): CommunityBrowserEventBatchDecodeResult {
+ const byteLength = encodedByteLength ?? utf8ByteLength(JSON.stringify(value))
+ if (byteLength > COMMUNITY_BROWSER_EVENT_BATCH_MAX_BYTES) {
+ return { ok: false, reason: "oversized", byteLength }
+ }
+ if (!isRecord(value)) return { ok: false, reason: "non-object" }
+ if (typeof value.type !== "string" || value.type.length === 0) {
+ return { ok: false, reason: "missing-type" }
+ }
+ if (value.type !== COMMUNITY_BROWSER_EVENT_BATCH_TYPE) {
+ return { ok: false, reason: "wrong-type" }
+ }
+ if (!isCommunityDeliveryOperationId(value.operationId)) {
+ return { ok: false, reason: "invalid-operation-id" }
+ }
+ if (!isCommunityDeliveryDigest(value.operationDigest)) {
+ return { ok: false, reason: "invalid-operation-digest" }
+ }
+ if (
+ Object.keys(value).length !== 4
+ || !Object.hasOwn(value, "type")
+ || !Object.hasOwn(value, "operationId")
+ || !Object.hasOwn(value, "operationDigest")
+ || !Object.hasOwn(value, "events")
+ ) {
+ return { ok: false, reason: "invalid-payload" }
+ }
+ if (
+ !Array.isArray(value.events)
+ || value.events.length < 1
+ || value.events.length > MESSAGE_DELIVERY_MAX_EVENTS_PER_USER
+ ) {
+ return { ok: false, reason: "invalid-event-count" }
+ }
+ const events: CommunityWsEvent[] = []
+ const envelopes: CommunityBrowserEventEnvelopeV1[] = []
+ for (let eventIndex = 0; eventIndex < value.events.length; eventIndex += 1) {
+ const child = decodeCommunityBrowserEvent(value.events[eventIndex])
+ if (!child.ok || child.sourceVersion !== COMMUNITY_BROWSER_EVENT_CONTRACT_VERSION) {
+ return { ok: false, reason: "invalid-child", eventIndex }
+ }
+ events.push(child.event)
+ envelopes.push(value.events[eventIndex] as CommunityBrowserEventEnvelopeV1)
+ }
+ return {
+ ok: true,
+ batch: {
+ type: COMMUNITY_BROWSER_EVENT_BATCH_TYPE,
+ operationId: value.operationId,
+ operationDigest: value.operationDigest,
+ events: envelopes,
+ },
+ events,
+ }
+}
diff --git a/src/shared/src/index.ts b/src/shared/src/index.ts
index a8aa26aa7..512b811e9 100644
--- a/src/shared/src/index.ts
+++ b/src/shared/src/index.ts
@@ -606,6 +606,34 @@ export {
encodeCommunityBrowserEvent,
WS_EVENTS,
} from "./community-ws-events";
+export type {
+ CommunityDeliveryOperationId,
+ CommunityDeliveryDigest,
+ CommunityBrowserEventBatch,
+ PreparedCommunityDeliveryEvents,
+ CommunityDeliveryPrepareFailureReason,
+ CommunityDeliveryPrepareResult,
+ CommunityBrowserEventBatchEncodeResult,
+ CommunityBrowserEventBatchDecodeResult,
+} from "./community-ws-bundle";
+export {
+ COMMUNITY_BROWSER_EVENT_BATCH_TYPE,
+ COMMUNITY_DELIVERY_OPERATION_ID_PREFIX,
+ COMMUNITY_DELIVERY_OPERATION_ID_HEADER,
+ COMMUNITY_DELIVERY_OPERATION_ID_BYTES,
+ COMMUNITY_DELIVERY_DIGEST_HEX_LENGTH,
+ COMMUNITY_BROWSER_EVENT_BATCH_ENVELOPE_BYTES,
+ COMMUNITY_BROWSER_EVENT_BATCH_MAX_BYTES,
+ isCommunityDeliveryOperationId,
+ isCommunityDeliveryDigest,
+ deriveCommunityDeliveryOperationId,
+ computeCommunityDeliveryDigestFromBodies,
+ prepareCommunityDeliveryEvents,
+ encodeCommunityBrowserEventBatch,
+ encodePreparedCommunityBrowserEventBatch,
+ isCommunityBrowserEventBatchCandidate,
+ decodeCommunityBrowserEventBatch,
+} from "./community-ws-bundle";
// Database
export { createDb } from "./db/index";
diff --git a/src/shared/test/community-ws-bundle.contract.test.ts b/src/shared/test/community-ws-bundle.contract.test.ts
new file mode 100644
index 000000000..7a4d6a569
--- /dev/null
+++ b/src/shared/test/community-ws-bundle.contract.test.ts
@@ -0,0 +1,241 @@
+import { describe, expect, it, vi } from "vitest"
+import {
+ COMMUNITY_BROWSER_EVENT_BATCH_MAX_BYTES,
+ COMMUNITY_BROWSER_EVENT_BATCH_TYPE,
+ COMMUNITY_BROWSER_EVENT_MAX_BYTES,
+ COMMUNITY_DELIVERY_OPERATION_ID_BYTES,
+ computeCommunityDeliveryDigestFromBodies,
+ decodeCommunityBrowserEventBatch,
+ deriveCommunityDeliveryOperationId,
+ encodeCommunityBrowserEvent,
+ encodeCommunityBrowserEventBatch,
+ encodePreparedCommunityBrowserEventBatch,
+ isCommunityBrowserEventBatchCandidate,
+ isCommunityDeliveryDigest,
+ isCommunityDeliveryOperationId,
+ prepareCommunityDeliveryEvents,
+ utf8ByteLength,
+ WS_EVENTS,
+ type CommunityBotAuditEvent,
+ type CommunityWsEvent,
+} from "../src"
+import { communityWsEventFixtures } from "./community-ws-events.fixtures"
+
+function maximizeAuditPadding(): CommunityBotAuditEvent {
+ let low = 0
+ let high = COMMUNITY_BROWSER_EVENT_MAX_BYTES
+ let best: CommunityBotAuditEvent | null = null
+ while (low <= high) {
+ const mid = Math.floor((low + high) / 2)
+ const event: CommunityBotAuditEvent = {
+ ...communityWsEventFixtures["community:bot.audit_event"],
+ payload: { padding: "x".repeat(mid) },
+ }
+ const encoded = encodeCommunityBrowserEvent(event)
+ if (encoded.ok) {
+ best = event
+ low = mid + 1
+ } else {
+ high = mid - 1
+ }
+ }
+ if (!best) throw new Error("audit fixture cannot fit")
+ return best
+}
+
+describe("community WS batch transport contract", () => {
+ const children: CommunityWsEvent[] = [
+ communityWsEventFixtures["community:message.create"],
+ communityWsEventFixtures["community:unread.bump"],
+ communityWsEventFixtures["community:mention.create"],
+ ]
+
+ it("locks operation ID grammar and SHA-256 vectors", async () => {
+ await expect(deriveCommunityDeliveryOperationId("message-1")).resolves.toBe(
+ "message:neuIC0O99vRloK-xMK7XGzHPIZYm82N_V31BZ82A5fI",
+ )
+ await expect(deriveCommunityDeliveryOperationId("é-message")).resolves.toBe(
+ "message:tg9ymYSdoZdumzg9P_Hu-TJVaZJSHEtJ6Iib_JRy71w",
+ )
+ await expect(deriveCommunityDeliveryOperationId("emoji-😀")).resolves.toMatch(/^message:/)
+ await expect(deriveCommunityDeliveryOperationId("")).rejects.toThrow("invalid community delivery message id")
+ await expect(deriveCommunityDeliveryOperationId("\ud800")).rejects.toThrow("invalid community delivery message id")
+ await expect(deriveCommunityDeliveryOperationId("\udc00")).rejects.toThrow("invalid community delivery message id")
+ const operationId = await deriveCommunityDeliveryOperationId("message-1")
+ expect(utf8ByteLength(operationId)).toBe(COMMUNITY_DELIVERY_OPERATION_ID_BYTES)
+ expect(isCommunityDeliveryOperationId(operationId)).toBe(true)
+ expect(isCommunityDeliveryOperationId(`${operationId}x`)).toBe(false)
+ expect(isCommunityDeliveryOperationId(`Message:${operationId.slice(8)}`)).toBe(false)
+ })
+
+ it("fails closed if the SHA-256 runtime violates the fixed operation-ID invariant", async () => {
+ const digest = vi.spyOn(crypto.subtle, "digest").mockResolvedValueOnce(new ArrayBuffer(1))
+ try {
+ await expect(deriveCommunityDeliveryOperationId("message-runtime-fault"))
+ .rejects.toThrow("invalid derived community delivery operation id")
+ } finally {
+ digest.mockRestore()
+ }
+ })
+
+ it("locks the length-prefixed canonical digest vector", async () => {
+ await expect(computeCommunityDeliveryDigestFromBodies([
+ '{"a":1}',
+ '{"b":"é"}',
+ ])).resolves.toBe("65171f224e0fa5a07f436b80d1f4b0bd1bcaf790d6c20998d1f8aad95ad54d2c")
+ expect(isCommunityDeliveryDigest("a".repeat(64))).toBe(true)
+ expect(isCommunityDeliveryDigest("A".repeat(64))).toBe(false)
+ expect(isCommunityDeliveryDigest("a".repeat(63))).toBe(false)
+ })
+
+ it("round-trips one strict outer frame without entering the 41-event union", async () => {
+ const operationId = await deriveCommunityDeliveryOperationId("message-1")
+ const prepared = await prepareCommunityDeliveryEvents(children)
+ expect(prepared.ok).toBe(true)
+ if (!prepared.ok) return
+ const encoded = await encodeCommunityBrowserEventBatch({
+ operationId,
+ operationDigest: prepared.prepared.digest,
+ events: children,
+ })
+ expect(encoded.ok).toBe(true)
+ if (!encoded.ok) return
+ expect(encoded.batch).toEqual(JSON.parse(encoded.body))
+ expect(encoded.batch.type).toBe(COMMUNITY_BROWSER_EVENT_BATCH_TYPE)
+ expect(Object.keys(encoded.batch).sort()).toEqual([
+ "events",
+ "operationDigest",
+ "operationId",
+ "type",
+ ])
+ expect(encoded.batch.events.map((event) => event.type)).toEqual(children.map((event) => event.type))
+ expect(decodeCommunityBrowserEventBatch(encoded.batch, encoded.byteLength)).toEqual({
+ ok: true,
+ batch: encoded.batch,
+ events: children,
+ })
+ expect(isCommunityBrowserEventBatchCandidate(encoded.batch)).toBe(true)
+ expect(Object.values(WS_EVENTS)).not.toContain(COMMUNITY_BROWSER_EVENT_BATCH_TYPE)
+ expect(Object.values(WS_EVENTS)).toHaveLength(41)
+ })
+
+ it("rejects invalid count, child, operation metadata, digest mismatch, and strict outer keys", async () => {
+ const operationId = await deriveCommunityDeliveryOperationId("message-1")
+ const prepared = await prepareCommunityDeliveryEvents(children)
+ if (!prepared.ok) throw new Error("fixture must prepare")
+
+ await expect(encodeCommunityBrowserEventBatch({
+ operationId,
+ operationDigest: prepared.prepared.digest,
+ events: [],
+ })).resolves.toMatchObject({ ok: false, reason: "invalid-event-count" })
+ await expect(encodeCommunityBrowserEventBatch({
+ operationId,
+ operationDigest: prepared.prepared.digest,
+ events: Array.from({ length: 6 }, () => children[0]),
+ })).resolves.toMatchObject({ ok: false, reason: "invalid-event-count" })
+ await expect(encodeCommunityBrowserEventBatch({
+ operationId,
+ operationDigest: prepared.prepared.digest,
+ events: [...children, { type: "community:future" }],
+ })).resolves.toMatchObject({ ok: false, reason: "invalid-child", eventIndex: 3 })
+ await expect(prepareCommunityDeliveryEvents([{
+ ...communityWsEventFixtures["community:bot.audit_event"],
+ payload: { padding: "x".repeat(COMMUNITY_BROWSER_EVENT_MAX_BYTES) },
+ }])).resolves.toMatchObject({ ok: false, reason: "oversized-child", eventIndex: 0 })
+ await expect(encodeCommunityBrowserEventBatch({
+ operationId: "message:short",
+ operationDigest: prepared.prepared.digest,
+ events: children,
+ })).resolves.toMatchObject({ ok: false, reason: "invalid-operation-id" })
+ await expect(encodeCommunityBrowserEventBatch({
+ operationId,
+ operationDigest: "A".repeat(64),
+ events: children,
+ })).resolves.toMatchObject({ ok: false, reason: "invalid-operation-digest" })
+ await expect(encodeCommunityBrowserEventBatch({
+ operationId,
+ operationDigest: "0".repeat(64),
+ events: children,
+ })).resolves.toMatchObject({ ok: false, reason: "digest-mismatch" })
+ expect(encodePreparedCommunityBrowserEventBatch({
+ operationId: "message:short",
+ operationDigest: prepared.prepared.digest,
+ prepared: prepared.prepared,
+ })).toMatchObject({ ok: false, reason: "invalid-operation-id" })
+ expect(encodePreparedCommunityBrowserEventBatch({
+ operationId,
+ operationDigest: "A".repeat(64),
+ prepared: prepared.prepared,
+ })).toMatchObject({ ok: false, reason: "invalid-operation-digest" })
+ expect(encodePreparedCommunityBrowserEventBatch({
+ operationId,
+ operationDigest: prepared.prepared.digest,
+ prepared: {
+ ...prepared.prepared,
+ bodies: [`"${"x".repeat(COMMUNITY_BROWSER_EVENT_BATCH_MAX_BYTES)}"`],
+ },
+ })).toMatchObject({ ok: false, reason: "batch-invariant-oversized" })
+
+ const encoded = await encodeCommunityBrowserEventBatch({
+ operationId,
+ operationDigest: prepared.prepared.digest,
+ events: children,
+ })
+ if (!encoded.ok) throw new Error("fixture must encode")
+ expect(decodeCommunityBrowserEventBatch({ ...encoded.batch, extra: true })).toMatchObject({
+ ok: false,
+ reason: "invalid-payload",
+ })
+ expect(decodeCommunityBrowserEventBatch(null)).toMatchObject({ ok: false, reason: "non-object" })
+ expect(decodeCommunityBrowserEventBatch({})).toMatchObject({ ok: false, reason: "missing-type" })
+ expect(decodeCommunityBrowserEventBatch({ type: "community:message.create" })).toMatchObject({
+ ok: false,
+ reason: "wrong-type",
+ })
+ expect(decodeCommunityBrowserEventBatch({ ...encoded.batch, events: [] })).toMatchObject({
+ ok: false,
+ reason: "invalid-event-count",
+ })
+ expect(decodeCommunityBrowserEventBatch({
+ ...encoded.batch,
+ operationId: "message:short",
+ })).toMatchObject({ ok: false, reason: "invalid-operation-id" })
+ expect(decodeCommunityBrowserEventBatch({
+ ...encoded.batch,
+ operationDigest: "A".repeat(64),
+ })).toMatchObject({ ok: false, reason: "invalid-operation-digest" })
+ expect(decodeCommunityBrowserEventBatch({
+ ...encoded.batch,
+ events: [{ ...encoded.batch.events[0], contractVersion: undefined }],
+ })).toMatchObject({ ok: false, reason: "invalid-child", eventIndex: 0 })
+ expect(decodeCommunityBrowserEventBatch(encoded.batch, COMMUNITY_BROWSER_EVENT_BATCH_MAX_BYTES + 1)).toEqual({
+ ok: false,
+ reason: "oversized",
+ byteLength: COMMUNITY_BROWSER_EVENT_BATCH_MAX_BYTES + 1,
+ })
+ })
+
+ it("proves five maximum legal children fit the exact outer ceiling", async () => {
+ const maxChild = maximizeAuditPadding()
+ const maxChildEncoded = encodeCommunityBrowserEvent(maxChild)
+ expect(maxChildEncoded.ok).toBe(true)
+ if (!maxChildEncoded.ok) return
+ expect(maxChildEncoded.byteLength).toBe(COMMUNITY_BROWSER_EVENT_MAX_BYTES)
+ const events = Array.from({ length: 5 }, () => maxChild)
+ const prepared = await prepareCommunityDeliveryEvents(events)
+ expect(prepared.ok).toBe(true)
+ if (!prepared.ok) return
+ const encoded = await encodeCommunityBrowserEventBatch({
+ operationId: await deriveCommunityDeliveryOperationId("maximum-operation"),
+ operationDigest: prepared.prepared.digest,
+ events,
+ })
+ expect(encoded.ok).toBe(true)
+ if (!encoded.ok) return
+ expect(encoded.childBodies.every((body) => utf8ByteLength(body) === COMMUNITY_BROWSER_EVENT_MAX_BYTES)).toBe(true)
+ expect(encoded.byteLength).toBeLessThanOrEqual(COMMUNITY_BROWSER_EVENT_BATCH_MAX_BYTES)
+ expect(COMMUNITY_BROWSER_EVENT_BATCH_MAX_BYTES - encoded.byteLength).toBeGreaterThanOrEqual(0)
+ expect(decodeCommunityBrowserEventBatch(encoded.batch, encoded.byteLength)).toMatchObject({ ok: true })
+ })
+})
diff --git a/src/web/src/hooks/community/community-ws/bundle-events.test.ts b/src/web/src/hooks/community/community-ws/bundle-events.test.ts
new file mode 100644
index 000000000..837896918
--- /dev/null
+++ b/src/web/src/hooks/community/community-ws/bundle-events.test.ts
@@ -0,0 +1,431 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import {
+ COMMUNITY_BROWSER_EVENT_BATCH_MAX_BYTES,
+ COMMUNITY_BROWSER_EVENT_BATCH_TYPE,
+ deriveCommunityDeliveryOperationId,
+ encodeCommunityBrowserEventBatch,
+ prepareCommunityDeliveryEvents,
+ type CommunityWsEvent,
+} from "@alook/shared"
+import { communityKeys } from "@/lib/query-keys"
+
+const reconcileCommunityWsReconnect = vi.hoisted(() => vi.fn(async () => ({
+ policyCount: 13,
+ successCount: 13,
+ failureCount: 0,
+})))
+
+vi.mock("./reconnect", () => ({ reconcileCommunityWsReconnect }))
+
+import {
+ capturedOnMessage,
+ capturedQueryClient,
+ cleanupCommunityWsHarness,
+ forumSidebarFixture,
+ mountHook,
+ resetCommunityWsHarness,
+} from "./test-harness"
+import { useCommunityStore } from "@/stores/community"
+import { getMessageOverlay, useMessageStreamStore } from "@/stores/community/message-stream"
+
+beforeEach(async () => {
+ reconcileCommunityWsReconnect.mockClear()
+ await resetCommunityWsHarness()
+})
+afterEach(cleanupCommunityWsHarness)
+
+const message = {
+ type: "community:message.create" as const,
+ channelId: "ch-1",
+ serverId: "server-1",
+ message: {
+ id: "message-1",
+ seq: 1,
+ authorId: "author-1",
+ authorName: "Alice",
+ content: "hello",
+ type: "chat" as const,
+ createdAt: "2026-08-21T00:00:00.000Z",
+ },
+}
+const mentionEvents: CommunityWsEvent[] = [
+ message,
+ {
+ type: "community:unread.bump",
+ userId: "viewer-1",
+ channelId: "ch-1",
+ serverId: "server-1",
+ railChannelId: "ch-1",
+ isMention: true,
+ },
+ {
+ type: "community:mention.create",
+ userId: "viewer-1",
+ messageId: "message-1",
+ channelId: "ch-1",
+ authorName: "Alice",
+ },
+]
+
+async function batchFor(messageId: string, events: readonly CommunityWsEvent[]) {
+ const operationId = await deriveCommunityDeliveryOperationId(messageId)
+ const prepared = await prepareCommunityDeliveryEvents(events)
+ if (!prepared.ok) throw new Error("bundle fixture must prepare")
+ const encoded = await encodeCommunityBrowserEventBatch({
+ operationId,
+ operationDigest: prepared.prepared.digest,
+ events,
+ })
+ if (!encoded.ok) throw new Error("bundle fixture must encode")
+ return encoded.batch
+}
+
+function invalidationCount(queryKey: readonly unknown[]): number {
+ return vi.mocked(capturedQueryClient.invalidateQueries).mock.calls.filter(([filters]) =>
+ JSON.stringify(filters.queryKey) === JSON.stringify(queryKey)).length
+}
+
+describe("useCommunityWs — operation bundles", () => {
+ it("decodes all children before one dispatch, deduplicates invalidations, and suppresses same-digest replay", async () => {
+ await mountHook({ viewerUserId: "viewer-1" })
+ capturedQueryClient.setQueryData(communityKeys.servers(), {
+ servers: [{ id: "server-1", mentions: 5 }],
+ })
+ vi.spyOn(capturedQueryClient, "invalidateQueries")
+ const frame = await batchFor("message-1", mentionEvents)
+
+ capturedOnMessage!(frame)
+ expect(capturedQueryClient.getQueryData<{ servers: Array<{ id: string; mentions: number }> }>(
+ communityKeys.servers(),
+ )?.servers[0]?.mentions).toBe(5)
+ expect(invalidationCount(communityKeys.inbox())).toBe(1)
+ expect(invalidationCount(communityKeys.dms())).toBe(1)
+ expect(invalidationCount(communityKeys.servers())).toBe(1)
+
+ const callsAfterFirst = vi.mocked(capturedQueryClient.invalidateQueries).mock.calls.length
+ capturedOnMessage!(frame)
+ expect(vi.mocked(capturedQueryClient.invalidateQueries)).toHaveBeenCalledTimes(callsAfterFirst)
+ const { useCommunityWsStore } = await import("@/stores/community/ws")
+ expect(useCommunityWsStore.getState().seenDeliveryOperations.get(frame.operationId))
+ .toEqual({ digest: frame.operationDigest, completed: true })
+ })
+
+ it("treats repair-then-late-bundle mention state as authoritative invalidation, never arithmetic", async () => {
+ await mountHook({ viewerUserId: "viewer-1" })
+ const { useCommunityWsStore } = await import("@/stores/community/ws")
+ useCommunityWsStore.getState().markSeenMessage(message.message.id)
+ capturedQueryClient.setQueryData(communityKeys.servers(), {
+ servers: [{ id: "server-1", mentions: 9 }],
+ })
+ vi.spyOn(capturedQueryClient, "invalidateQueries")
+
+ capturedOnMessage!(await batchFor("message-late", mentionEvents))
+ expect(capturedQueryClient.getQueryData<{ servers: Array<{ mentions: number }> }>(
+ communityKeys.servers(),
+ )?.servers[0]?.mentions).toBe(9)
+ expect(invalidationCount(communityKeys.inbox())).toBe(1)
+ expect(invalidationCount(communityKeys.dms())).toBe(1)
+ expect(invalidationCount(communityKeys.servers())).toBe(1)
+ })
+
+ it("rejects malformed children without poisoning the operation map", async () => {
+ await mountHook({ viewerUserId: "viewer-1" })
+ const frame = await batchFor("message-malformed", mentionEvents)
+ capturedOnMessage!({
+ ...frame,
+ events: [...frame.events, { type: "community:future", contractVersion: 1 }],
+ })
+
+ const { useCommunityWsStore } = await import("@/stores/community/ws")
+ expect(useCommunityWsStore.getState().seenDeliveryOperations.size).toBe(0)
+ expect(reconcileCommunityWsReconnect).not.toHaveBeenCalled()
+ })
+
+ it("reports bounded metadata for oversized and invalid batch or single frames", async () => {
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {})
+ await mountHook({ viewerUserId: "viewer-1" })
+
+ capturedOnMessage!({
+ type: COMMUNITY_BROWSER_EVENT_BATCH_TYPE,
+ padding: "x".repeat(COMMUNITY_BROWSER_EVENT_BATCH_MAX_BYTES),
+ })
+ capturedOnMessage!({
+ type: COMMUNITY_BROWSER_EVENT_BATCH_TYPE,
+ extra: true,
+ })
+ capturedOnMessage!({
+ type: "community:message.create",
+ contractVersion: 2,
+ })
+
+ expect(warn).toHaveBeenCalledWith(
+ "[ws] frame dropped",
+ expect.objectContaining({ reason: "oversized" }),
+ )
+ expect(warn).toHaveBeenCalledWith(
+ "[ws] frame dropped",
+ expect.objectContaining({ reason: "invalid-payload", type: COMMUNITY_BROWSER_EVENT_BATCH_TYPE }),
+ )
+ expect(warn).toHaveBeenCalledWith(
+ "[ws] frame dropped",
+ expect.objectContaining({ type: "community:message.create", contractVersion: 2 }),
+ )
+ })
+
+ it("rejects same-ID/different-digest before projection and reconciles once", async () => {
+ await mountHook({ viewerUserId: "viewer-1" })
+ useCommunityStore.getState().subscribe({ channelId: "ch-1" })
+ vi.spyOn(capturedQueryClient, "invalidateQueries")
+ const first = await batchFor("message-conflict", mentionEvents)
+ const conflicting = await batchFor("message-conflict", [
+ { ...message, message: { ...message.message, content: "different" } },
+ ])
+ capturedOnMessage!(first)
+ const { useCommunityWsStore } = await import("@/stores/community/ws")
+ const seenMessages = useCommunityWsStore.getState().seenMessageIds.size
+ const overlayBeforeConflict = getMessageOverlay({
+ kind: "channel",
+ id: "ch-1",
+ serverId: "s1",
+ })
+ const invalidationsBeforeConflict = vi.mocked(capturedQueryClient.invalidateQueries).mock.calls.length
+
+ capturedOnMessage!(conflicting)
+ expect(useCommunityWsStore.getState().seenMessageIds.size).toBe(seenMessages)
+ expect(getMessageOverlay({ kind: "channel", id: "ch-1", serverId: "s1" }))
+ .toBe(overlayBeforeConflict)
+ expect(vi.mocked(capturedQueryClient.invalidateQueries))
+ .toHaveBeenCalledTimes(invalidationsBeforeConflict)
+ expect(useCommunityWsStore.getState().seenDeliveryOperations.get(first.operationId))
+ .toEqual({ digest: first.operationDigest, completed: true })
+ expect(reconcileCommunityWsReconnect).toHaveBeenCalledTimes(1)
+ })
+
+ it("locks the digest across a second-child fault, rejects conflict, then completes replay", async () => {
+ await mountHook({ viewerUserId: "viewer-1" })
+ useCommunityStore.getState().subscribe({ channelId: "ch-1" })
+ capturedQueryClient.setQueryData(communityKeys.server("s1"), {
+ id: "s1",
+ categories: [{
+ id: "category-1",
+ channels: [{ id: "text-parent", type: "text", unread: false }],
+ }],
+ })
+ const setQueryData = vi.spyOn(capturedQueryClient, "setQueryData")
+ .mockImplementationOnce(() => { throw new Error("second-child fault") })
+ vi.spyOn(capturedQueryClient, "invalidateQueries")
+ const events: CommunityWsEvent[] = [
+ {
+ ...message,
+ serverId: "s1",
+ parentChannelId: "text-parent",
+ message: { ...message.message, id: "message-before-second-child-fault" },
+ },
+ {
+ type: "community:unread.bump",
+ userId: "viewer-1",
+ channelId: "ch-1",
+ serverId: "s1",
+ railChannelId: "text-parent",
+ isMention: false,
+ },
+ ]
+ const frame = await batchFor("message-second-child-fault", events)
+ const conflicting = await batchFor("message-second-child-fault", [
+ {
+ ...events[0]!,
+ message: { ...message.message, id: "message-before-second-child-fault", content: "tampered" },
+ } as CommunityWsEvent,
+ events[1]!,
+ ])
+
+ capturedOnMessage!(frame)
+ const { useCommunityWsStore } = await import("@/stores/community/ws")
+ expect(reconcileCommunityWsReconnect).toHaveBeenCalledTimes(1)
+ expect(useCommunityWsStore.getState().seenDeliveryOperations.get(frame.operationId))
+ .toEqual({ digest: frame.operationDigest, completed: false })
+ expect(getMessageOverlay({ kind: "channel", id: "ch-1", serverId: "s1" })
+ .liveById.has("message-before-second-child-fault")).toBe(true)
+
+ setQueryData.mockRestore()
+ const invalidationsAfterFailure = vi.mocked(capturedQueryClient.invalidateQueries).mock.calls.length
+ capturedOnMessage!(conflicting)
+ expect(reconcileCommunityWsReconnect).toHaveBeenCalledTimes(2)
+ expect(useCommunityWsStore.getState().seenDeliveryOperations.get(frame.operationId))
+ .toEqual({ digest: frame.operationDigest, completed: false })
+ expect(getMessageOverlay({ kind: "channel", id: "ch-1", serverId: "s1" })
+ .liveById.get("message-before-second-child-fault")?.content).toBe("hello")
+ expect(vi.mocked(capturedQueryClient.invalidateQueries))
+ .toHaveBeenCalledTimes(invalidationsAfterFailure)
+
+ capturedOnMessage!(frame)
+ expect(reconcileCommunityWsReconnect).toHaveBeenCalledTimes(2)
+ expect(useCommunityWsStore.getState().seenDeliveryOperations.get(frame.operationId))
+ .toEqual({ digest: frame.operationDigest, completed: true })
+ expect(useCommunityWsStore.getState().seenMessageIds.size).toBe(1)
+ expect(getMessageOverlay({ kind: "channel", id: "ch-1", serverId: "s1" }).liveById.size)
+ .toBe(1)
+ expect(capturedQueryClient.getQueryData<{
+ categories: Array<{ channels: Array<{ id: string; unread: boolean }> }>
+ }>(communityKeys.server("s1"))?.categories[0]?.channels[0]?.unread).toBe(true)
+
+ const invalidationsAfterCompletion = vi.mocked(capturedQueryClient.invalidateQueries).mock.calls.length
+ capturedOnMessage!(frame)
+ expect(vi.mocked(capturedQueryClient.invalidateQueries))
+ .toHaveBeenCalledTimes(invalidationsAfterCompletion)
+ })
+
+ it("replays every legal committed-message child idempotently after a partial parent projection", async () => {
+ await mountHook({ viewerUserId: "viewer-1" })
+ useCommunityStore.getState().subscribe({ channelId: "other-channel" })
+ capturedQueryClient.setQueryData(communityKeys.server("s1"), {
+ id: "s1",
+ categories: [{
+ id: "category-1",
+ channels: [{ id: "forum_1", type: "forum", unread: false }],
+ }],
+ })
+ capturedQueryClient.setQueryData(
+ communityKeys.forumSidebarThreads("s1"),
+ forumSidebarFixture(["ch-1"]),
+ )
+ capturedQueryClient.setQueryData(communityKeys.servers(), {
+ servers: [{ id: "s1", mentions: 5 }],
+ })
+ capturedQueryClient.setQueryData(communityKeys.channelMessages("forum_1"), {
+ pages: [{
+ messages: [{
+ id: "opener-1",
+ thread: { id: "ch-1", name: "thread", messageCount: 1 },
+ }],
+ hasMore: false,
+ }],
+ pageParams: [null],
+ })
+ const parentScope = { kind: "channel" as const, id: "forum_1", serverId: "s1" }
+ useMessageStreamStore.getState().dispatch(parentScope, {
+ type: "wsMessage",
+ message: {
+ id: "opener-1",
+ seq: 1,
+ type: "chat",
+ authorId: "author-1",
+ authorName: "Alice",
+ content: "opener",
+ createdAt: "2026-08-20T00:00:00.000Z",
+ thread: { id: "ch-1", name: "thread", messageCount: 1 },
+ },
+ })
+ vi.spyOn(capturedQueryClient, "invalidateQueries")
+ const { useCommunityWsStore } = await import("@/stores/community/ws")
+ const originalDispatch = useMessageStreamStore.getState().dispatch
+ useMessageStreamStore.setState({
+ dispatch: (scope, event) => {
+ originalDispatch(scope, event)
+ throw new Error("partial parent projection fault")
+ },
+ })
+ const frame = await batchFor("message-projection-fault", [
+ {
+ ...message,
+ serverId: "s1",
+ parentChannelId: "forum_1",
+ message: { ...message.message, id: "message-before-fault" },
+ },
+ {
+ type: "community:unread.bump",
+ userId: "viewer-1",
+ channelId: "ch-1",
+ serverId: "s1",
+ railChannelId: "forum_1",
+ isMention: true,
+ },
+ {
+ type: "community:mention.create",
+ userId: "viewer-1",
+ messageId: "message-before-fault",
+ channelId: "ch-1",
+ authorName: "Alice",
+ },
+ {
+ type: "community:channel.member_add",
+ userId: "viewer-1",
+ serverId: "s1",
+ channelId: "ch-1",
+ },
+ {
+ type: "community:channel.child_update",
+ parentChannelId: "forum_1",
+ channelId: "ch-1",
+ changes: { messageCount: 2, lastMessageAt: "2026-08-21T00:00:00.000Z" },
+ },
+ ])
+
+ try {
+ capturedOnMessage!(frame)
+ expect(reconcileCommunityWsReconnect).toHaveBeenCalledTimes(1)
+ expect(useCommunityWsStore.getState().seenDeliveryOperations.get(frame.operationId))
+ .toEqual({ digest: frame.operationDigest, completed: false })
+ // All preceding children are legal committed-message projections. Their
+ // writes remain visible when the final parent projection throws.
+ expect(useCommunityWsStore.getState().seenMessageIds.has("message-before-fault")).toBe(true)
+ expect(capturedQueryClient.getQueryData<ReturnType<typeof forumSidebarFixture>>(
+ communityKeys.forumSidebarThreads("s1"),
+ )?.threads).toMatchObject([{ id: "ch-1", unread: true }])
+ expect(capturedQueryClient.getQueryData<{
+ servers: Array<{ id: string; mentions: number }>
+ }>(communityKeys.servers())?.servers[0]?.mentions).toBe(5)
+ expect(capturedQueryClient.getQueryData<{
+ pages: Array<{ messages: Array<{ thread: { messageCount: number } }> }>
+ }>(communityKeys.channelMessages("forum_1"))?.pages[0]?.messages[0]?.thread.messageCount)
+ .toBe(2)
+ expect(getMessageOverlay(parentScope).liveById.get("opener-1")?.thread?.messageCount)
+ .toBe(2)
+ } finally {
+ useMessageStreamStore.setState({ dispatch: originalDispatch })
+ }
+
+ capturedOnMessage!(frame)
+ expect(reconcileCommunityWsReconnect).toHaveBeenCalledTimes(1)
+ expect(useCommunityWsStore.getState().seenDeliveryOperations.get(frame.operationId))
+ .toEqual({ digest: frame.operationDigest, completed: true })
+ expect(useCommunityWsStore.getState().seenMessageIds.size).toBe(1)
+ expect(capturedQueryClient.getQueryData<{
+ servers: Array<{ id: string; mentions: number }>
+ }>(communityKeys.servers())?.servers[0]?.mentions).toBe(5)
+ expect(capturedQueryClient.getQueryData<ReturnType<typeof forumSidebarFixture>>(
+ communityKeys.forumSidebarThreads("s1"),
+ )?.threads).toMatchObject([{ id: "ch-1", unread: true }])
+ expect(capturedQueryClient.getQueryData<{
+ pages: Array<{ messages: Array<{ thread: { messageCount: number } }> }>
+ }>(communityKeys.channelMessages("forum_1"))?.pages[0]?.messages[0]?.thread.messageCount)
+ .toBe(2)
+ expect(getMessageOverlay(parentScope).liveById.get("opener-1")?.thread?.messageCount)
+ .toBe(2)
+
+ const invalidationsAfterSuccess = vi.mocked(capturedQueryClient.invalidateQueries).mock.calls.length
+ capturedOnMessage!(frame)
+ expect(vi.mocked(capturedQueryClient.invalidateQueries))
+ .toHaveBeenCalledTimes(invalidationsAfterSuccess)
+ })
+
+ it("reports a rejected authoritative reconciliation after a digest conflict", async () => {
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {})
+ reconcileCommunityWsReconnect.mockRejectedValueOnce(new Error("reconcile unavailable"))
+ await mountHook({ viewerUserId: "viewer-1" })
+ const first = await batchFor("message-reconcile-reject", mentionEvents)
+ const conflicting = await batchFor("message-reconcile-reject", [
+ { ...message, message: { ...message.message, content: "different" } },
+ ])
+
+ capturedOnMessage!(first)
+ capturedOnMessage!(conflicting)
+
+ await vi.waitFor(() => {
+ expect(warn).toHaveBeenCalledWith(
+ "[ws] batch reconciliation failed",
+ expect.objectContaining({ reason: "digest-conflict" }),
+ )
+ })
+ })
+})
diff --git a/src/web/src/hooks/community/community-ws/handler-context.ts b/src/web/src/hooks/community/community-ws/handler-context.ts
index 57bc818a4..3a3c80481 100644
--- a/src/web/src/hooks/community/community-ws/handler-context.ts
+++ b/src/web/src/hooks/community/community-ws/handler-context.ts
@@ -22,6 +22,7 @@ export type UseCommunityWsOptions = {
}
export type CommunityWsDispatchContext = {
+ deliveryMode: "single" | "batch"
queryClient: QueryClient
communityStore: ReturnType<typeof useCommunityStore.getState>
wsStore: ReturnType<typeof useCommunityWsStore.getState>
@@ -50,7 +51,7 @@ export type MembershipEventContext = Pick<
>
export type SocialEventContext = Pick<
CommunityWsHandlerContext,
- "queryClient" | "sub" | "viewerUserIdRef" | "projection"
+ "deliveryMode" | "queryClient" | "sub" | "viewerUserIdRef" | "projection"
>
export type PresenceMachineEventContext = Pick<
CommunityWsHandlerContext,
diff --git a/src/web/src/hooks/community/community-ws/message-events.ts b/src/web/src/hooks/community/community-ws/message-events.ts
index e791e84df..3f99870c2 100644
--- a/src/web/src/hooks/community/community-ws/message-events.ts
+++ b/src/web/src/hooks/community/community-ws/message-events.ts
@@ -28,7 +28,9 @@ import {
} from "@/hooks/community/community-ws/message-projections"
import {
invalidateChannelMembers,
+ invalidateDms,
invalidateFriends,
+ invalidateInbox,
invalidatePins,
} from "@/hooks/community/community-ws/invalidation-projections"
@@ -45,6 +47,7 @@ export function handleMessageCreate(
wsStore,
sub,
viewerUserIdRef,
+ deliveryMode,
scheduleInboxInvalidate,
projection,
}: MessageEventContext,
@@ -75,6 +78,11 @@ export function handleMessageCreate(
{ type: "wsMessage", message: projected },
)
}
+ const viewerId = viewerUserIdRef.current
+ if (deliveryMode === "batch" && event.message.authorId !== viewerId) {
+ invalidateInbox(projection)
+ invalidateDms(projection)
+ }
if (wsStore.hasSeenMessage(event.message.id)) return
wsStore.markSeenMessage(event.message.id)
// Sending a message is an implicit typing.stop for its author —
@@ -123,8 +131,7 @@ export function handleMessageCreate(
// 2) Every message.create — regardless of focus — schedules a
// debounced inbox invalidation. Skip messages authored by the
// viewer since they never affect their own unreads.
- const viewerId = viewerUserIdRef.current
- if (event.message.authorId !== viewerId) {
+ if (deliveryMode === "single" && event.message.authorId !== viewerId) {
scheduleInboxInvalidate()
}
diff --git a/src/web/src/hooks/community/community-ws/registry.test.ts b/src/web/src/hooks/community/community-ws/registry.test.ts
index 9ab6ee829..ca2c932b2 100644
--- a/src/web/src/hooks/community/community-ws/registry.test.ts
+++ b/src/web/src/hooks/community/community-ws/registry.test.ts
@@ -63,6 +63,7 @@ vi.mock("./presence-machine-events", () => ({
function dispatchContext(queryClient = new QueryClient()): CommunityWsDispatchContext {
return {
+ deliveryMode: "single",
queryClient,
communityStore: {} as CommunityWsDispatchContext["communityStore"],
wsStore: {} as CommunityWsDispatchContext["wsStore"],
@@ -152,6 +153,19 @@ describe("community WebSocket registry", () => {
}
})
+ it("wraps a multi-event delivery in exactly one projection batch", () => {
+ const batch = vi.spyOn(notifyManager, "batch")
+ try {
+ dispatchCommunityWsEvents([
+ communityWsEventFixtures["community:typing.start"],
+ communityWsEventFixtures["community:typing.stop"],
+ ], dispatchContext())
+ expect(batch).toHaveBeenCalledTimes(1)
+ } finally {
+ batch.mockRestore()
+ }
+ })
+
it("lets later events observe synchronous projections from earlier events", () => {
const queryClient = new QueryClient()
const observed: number[] = []
diff --git a/src/web/src/hooks/community/community-ws/social-events.test.ts b/src/web/src/hooks/community/community-ws/social-events.test.ts
index 23467f9f0..9a33d4f8d 100644
--- a/src/web/src/hooks/community/community-ws/social-events.test.ts
+++ b/src/web/src/hooks/community/community-ws/social-events.test.ts
@@ -343,6 +343,20 @@ describe("useCommunityWs — message.create patches channel unread in the open s
expect(servers?.servers[0].mentions).toBe(3)
})
+ it("leaves an absent or unrelated server rail cache unchanged on a legacy mention bump", async () => {
+ await mountHook({ viewerUserId: "u_me" })
+
+ capturedOnMessage!(unreadBump("ch_a", "u_me", { serverId: "srv_x", isMention: true }))
+ expect(capturedQueryClient.getQueryData(communityKeys.servers())).toBeUndefined()
+
+ const unrelated = {
+ servers: [{ id: "srv_other", name: "Other", initial: "O", active: false, mentions: 4, icon: null }],
+ }
+ capturedQueryClient.setQueryData(communityKeys.servers(), unrelated)
+ capturedOnMessage!(unreadBump("ch_a", "u_me", { serverId: "srv_x", isMention: true }))
+ expect(capturedQueryClient.getQueryData(communityKeys.servers())).toEqual(unrelated)
+ })
+
it("existing focused-channel message patch and debounced inbox invalidation still fire on message.create", async () => {
vi.useFakeTimers()
try {
diff --git a/src/web/src/hooks/community/community-ws/social-events.ts b/src/web/src/hooks/community/community-ws/social-events.ts
index 88afbe0b0..4d0189867 100644
--- a/src/web/src/hooks/community/community-ws/social-events.ts
+++ b/src/web/src/hooks/community/community-ws/social-events.ts
@@ -37,7 +37,7 @@ type CommunityUnreadBump = Extract<
// defensively).
export function handleUnreadBump(
event: CommunityUnreadBump,
- { queryClient, viewerUserIdRef, sub }: SocialEventContext,
+ { deliveryMode, projection, queryClient, viewerUserIdRef, sub }: SocialEventContext,
) {
const viewerId = viewerUserIdRef.current
// `railChannelId` is the always-locatable fallback. A participating
@@ -46,6 +46,9 @@ export function handleUnreadBump(
const railChannelId = event.railChannelId ?? event.channelId
const targetServerId =
event.serverId ?? useCommunityStore.getState().currentServerId
+ if (deliveryMode === "batch" && event.isMention && event.serverId) {
+ invalidateServersList(projection)
+ }
const hasChildSidebarRow = !!targetServerId && event.channelId !== railChannelId &&
hasProjectedForumSidebarThread(
queryClient,
@@ -102,20 +105,22 @@ export function handleUnreadBump(
// locate a rail row, so skip (the tree dot / inbox still reflect it).
if (event.isMention && event.serverId) {
const bumpServerId = event.serverId
- queryClient.setQueryData<ServersResponse | undefined>(
- communityKeys.servers(),
- (prev) =>
- prev
- ? {
- ...prev,
- servers: prev.servers.map((s) =>
- s.id === bumpServerId
- ? { ...s, mentions: s.mentions + 1 }
- : s,
- ),
- }
- : prev,
- )
+ if (deliveryMode === "single") {
+ queryClient.setQueryData<ServersResponse | undefined>(
+ communityKeys.servers(),
+ (prev) =>
+ prev
+ ? {
+ ...prev,
+ servers: prev.servers.map((s) =>
+ s.id === bumpServerId
+ ? { ...s, mentions: s.mentions + 1 }
+ : s,
+ ),
+ }
+ : prev,
+ )
+ }
}
}
}
diff --git a/src/web/src/hooks/community/use-community-ws.test.ts b/src/web/src/hooks/community/use-community-ws.test.ts
index 4f4271496..3830c8431 100644
--- a/src/web/src/hooks/community/use-community-ws.test.ts
+++ b/src/web/src/hooks/community/use-community-ws.test.ts
@@ -86,6 +86,7 @@ describe("useCommunityWs — double-mount detection", () => {
expect(capturedOnMessage).not.toBeNull()
expect(capturedOnReconnect).not.toBeNull()
expect(capturedUseUserWsOptions?.requestDaemonStatusOnAuth).toBe(false)
+ expect(capturedUseUserWsOptions).not.toHaveProperty("capabilities")
})
it("emits console.warn when a second instance mounts with a different send", async () => {
diff --git a/src/web/src/hooks/community/use-community-ws.ts b/src/web/src/hooks/community/use-community-ws.ts
index 366fa5f93..cd6f1703d 100644
--- a/src/web/src/hooks/community/use-community-ws.ts
+++ b/src/web/src/hooks/community/use-community-ws.ts
@@ -6,7 +6,10 @@ import { useUserWs } from "@/lib/use-user-ws"
import { useCommunityStore } from "@/stores/community"
import { useCommunityWsStore } from "@/stores/community/ws"
import { reconcileCommunityWsReconnect } from "@/hooks/community/community-ws/reconnect"
-import { dispatchCommunityWsEvent } from "@/hooks/community/community-ws/registry"
+import {
+ dispatchCommunityWsEvent,
+ dispatchCommunityWsEvents,
+} from "@/hooks/community/community-ws/registry"
import { runCommunityWsProjectionTransaction } from "@/hooks/community/community-ws/projection-transaction"
import {
invalidateDms,
@@ -19,6 +22,8 @@ import type {
} from "@/hooks/community/community-ws/handler-context"
import {
decodeCommunityBrowserEvent,
+ decodeCommunityBrowserEventBatch,
+ isCommunityBrowserEventBatchCandidate,
isCommunityEventType,
TYPING_INDICATOR_THROTTLE_MS,
} from "@alook/shared"
@@ -151,24 +156,6 @@ export function useCommunityWs(options?: UseCommunityWsOptions): void {
const handleMessage = useCallback(
(msg: { type: string;[key: string]: unknown }) => {
if (!msg.type.startsWith("community:")) return
- const decoded = decodeCommunityBrowserEvent(msg)
- if (!decoded.ok) {
- const metadata = {
- reason: decoded.reason,
- type: isCommunityEventType(msg.type) ? msg.type : "unknown",
- ...(typeof msg.contractVersion === "number"
- && Number.isSafeInteger(msg.contractVersion)
- ? { contractVersion: msg.contractVersion }
- : {}),
- } as const
- console.warn("[ws] frame dropped", {
- event: "community_ws_frame_dropped",
- ...metadata,
- })
- trackCommunityWsFrameDropped(metadata)
- return
- }
- const event = decoded.event
const communityStore = useCommunityStore.getState()
const sub = communityStore.subscription
const wsStore = useCommunityWsStore.getState()
@@ -182,7 +169,8 @@ export function useCommunityWs(options?: UseCommunityWsOptions): void {
if (!e.channelId) return false
return e.channelId === sub.channelId || e.channelId === sub.dmConversationId
}
- const context: CommunityWsDispatchContext = {
+ const context = (deliveryMode: "single" | "batch"): CommunityWsDispatchContext => ({
+ deliveryMode,
queryClient,
communityStore,
wsStore,
@@ -190,9 +178,93 @@ export function useCommunityWs(options?: UseCommunityWsOptions): void {
viewerUserIdRef,
matchesFocus,
scheduleInboxInvalidate,
+ })
+ const reconcileAfterBatchFailure = (reason: "digest-conflict" | "projection-failed") => {
+ void reconcileCommunityWsReconnect(queryClient, 0).catch(() => {
+ console.warn("[ws] batch reconciliation failed", {
+ event: "community_ws_batch_reconciliation_failed",
+ reason,
+ })
+ })
}
- dispatchCommunityWsEvent(event, context)
+ if (isCommunityBrowserEventBatchCandidate(msg)) {
+ const decoded = decodeCommunityBrowserEventBatch(msg)
+ if (!decoded.ok) {
+ const reason = decoded.reason === "oversized" ? "oversized" : "invalid-payload"
+ const metadata = {
+ reason,
+ type: msg.type,
+ ...(decoded.byteLength === undefined ? {} : { byteCount: decoded.byteLength }),
+ } as const
+ console.warn("[ws] frame dropped", {
+ event: "community_ws_frame_dropped",
+ ...metadata,
+ })
+ trackCommunityWsFrameDropped(metadata)
+ return
+ }
+ const operationStatus = wsStore.observeDeliveryOperation(
+ decoded.batch.operationId,
+ decoded.batch.operationDigest,
+ )
+ if (operationStatus === "duplicate") return
+ if (operationStatus === "conflict") {
+ console.warn("[ws] delivery operation digest conflict", {
+ event: "community_ws_delivery_operation_conflict",
+ operationId: decoded.batch.operationId,
+ operationDigest: decoded.batch.operationDigest,
+ eventCount: decoded.events.length,
+ })
+ reconcileAfterBatchFailure("digest-conflict")
+ return
+ }
+ try {
+ dispatchCommunityWsEvents(decoded.events, context("batch"))
+ } catch {
+ console.warn("[ws] delivery operation projection failed", {
+ event: "community_ws_delivery_operation_projection_failed",
+ operationId: decoded.batch.operationId,
+ operationDigest: decoded.batch.operationDigest,
+ eventCount: decoded.events.length,
+ })
+ reconcileAfterBatchFailure("projection-failed")
+ return
+ }
+ // Complete dedup only after every child projected successfully. The
+ // first valid frame already locked operationId -> digest above, so a
+ // conflicting digest fails closed even while this operation remains
+ // observed but incomplete/retryable after a projection failure.
+ // Browser projections are not rollback-capable: a later child can
+ // throw after an earlier child updated a Zustand/query-cache overlay.
+ // Keeping the failed operation locked but incomplete lets the
+ // identical bundle retry, so idempotent child projections can finish
+ // converging even when authoritative reconnect reconciliation fails.
+ wsStore.completeDeliveryOperation(
+ decoded.batch.operationId,
+ decoded.batch.operationDigest,
+ )
+ return
+ }
+
+ const decoded = decodeCommunityBrowserEvent(msg)
+ if (!decoded.ok) {
+ const metadata = {
+ reason: decoded.reason,
+ type: isCommunityEventType(msg.type) ? msg.type : "unknown",
+ ...(typeof msg.contractVersion === "number"
+ && Number.isSafeInteger(msg.contractVersion)
+ ? { contractVersion: msg.contractVersion }
+ : {}),
+ } as const
+ console.warn("[ws] frame dropped", {
+ event: "community_ws_frame_dropped",
+ ...metadata,
+ })
+ trackCommunityWsFrameDropped(metadata)
+ return
+ }
+ dispatchCommunityWsEvent(decoded.event, context("single"))
},
[queryClient, scheduleInboxInvalidate],
)
diff --git a/src/web/src/lib/community/message-delivery-transport.test.ts b/src/web/src/lib/community/message-delivery-transport.test.ts
index 02c1ebc4b..38d526535 100644
--- a/src/web/src/lib/community/message-delivery-transport.test.ts
+++ b/src/web/src/lib/community/message-delivery-transport.test.ts
@@ -1,20 +1,18 @@
import { afterAll, beforeEach, describe, expect, it, vi } from "vitest"
import {
+ COMMUNITY_DELIVERY_OPERATION_ID_HEADER,
MESSAGE_DELIVERY_BODY_MAX_BYTES,
+ deriveCommunityDeliveryOperationId,
type MessageDeliveryBatch,
} from "@alook/shared"
const {
bindingFetch,
- broadcastToUsers,
logInfo,
- logWarn,
logError,
} = vi.hoisted(() => ({
bindingFetch: vi.fn<(...args: unknown[]) => Promise<Response>>(),
- broadcastToUsers: vi.fn<(...args: unknown[]) => Promise<void>>(async () => {}),
logInfo: vi.fn(),
- logWarn: vi.fn(),
logError: vi.fn(),
}))
@@ -28,15 +26,13 @@ vi.mock("@opennextjs/cloudflare", () => ({
}),
}))
-vi.mock("../broadcast", () => ({ broadcastToUsers }))
-
vi.mock("@alook/shared", async () => {
const actual = await vi.importActual<typeof import("@alook/shared")>("@alook/shared")
return {
...actual,
createLogger: () => ({
info: (...args: unknown[]) => logInfo(...args),
- warn: (...args: unknown[]) => logWarn(...args),
+ warn: vi.fn(),
error: (...args: unknown[]) => logError(...args),
debug: vi.fn(),
}),
@@ -87,6 +83,11 @@ function requestBatch(callIndex: number): MessageDeliveryBatch {
return JSON.parse(init.body as string) as MessageDeliveryBatch
}
+function requestOperationId(callIndex: number): string | null {
+ const init = bindingFetch.mock.calls[callIndex]?.[1] as RequestInit
+ return new Headers(init.headers).get(COMMUNITY_DELIVERY_OPERATION_ID_HEADER)
+}
+
beforeEach(() => {
vi.clearAllMocks()
globalThis.fetch = globalFetch as unknown as typeof fetch
@@ -106,6 +107,15 @@ describe("sendMessageDeliveryBatch", () => {
"http://internal/broadcast/community/message-delivery",
)
expect(requestBatch(0)).toEqual(batch())
+ expect(requestOperationId(0)).toBe(await deriveCommunityDeliveryOperationId("message-1"))
+ })
+
+ it("rejects a caller-supplied operation ID that does not match the committed message", async () => {
+ await expect(sendMessageDeliveryBatch(
+ batch(),
+ await deriveCommunityDeliveryOperationId("different-message"),
+ )).rejects.toThrow("operation ID does not match message")
+ expect(bindingFetch).not.toHaveBeenCalled()
})
it("chunks 1,000 targets without dropping or duplicating a target", async () => {
@@ -148,6 +158,8 @@ describe("sendMessageDeliveryBatch", () => {
expect(new TextEncoder().encode(init.body as string).byteLength)
.toBeLessThanOrEqual(MESSAGE_DELIVERY_BODY_MAX_BYTES)
}
+ expect(new Set(bindingFetch.mock.calls.map((_, index) => requestOperationId(index))))
+ .toEqual(new Set([await deriveCommunityDeliveryOperationId("message-1")]))
})
it("fails closed when even a single-target batch is oversized", async () => {
@@ -188,8 +200,8 @@ describe("sendMessageDeliveryBatch", () => {
})
expect(requestBatch(1).memberAdded).toBeUndefined()
expect(requestBatch(1).parentProjection).toBeUndefined()
+ expect(requestOperationId(1)).toBe(requestOperationId(0))
expect(globalFetch).not.toHaveBeenCalled()
- expect(broadcastToUsers).not.toHaveBeenCalled()
})
it("stops after the initial attempt plus two failed-only retries", async () => {
@@ -201,6 +213,8 @@ describe("sendMessageDeliveryBatch", () => {
expect(bindingFetch).toHaveBeenCalledTimes(3)
expect(requestBatch(1).contentUserIds).toEqual(["u2"])
expect(requestBatch(2).contentUserIds).toEqual(["u2"])
+ expect(requestOperationId(1)).toBe(requestOperationId(0))
+ expect(requestOperationId(2)).toBe(requestOperationId(0))
})
it.each([
@@ -215,35 +229,16 @@ describe("sendMessageDeliveryBatch", () => {
await expect(sendMessageDeliveryBatch(batch())).rejects.toThrow(/failed for 1 chunk/)
expect(bindingFetch).toHaveBeenCalledTimes(1)
expect(globalFetch).not.toHaveBeenCalled()
- expect(broadcastToUsers).not.toHaveBeenCalled()
})
- it.each([404, 405])("uses ordered plan-projected legacy delivery only for %i", async (status) => {
- bindingFetch.mockResolvedValue(new Response("old worker", { status }))
-
- await sendMessageDeliveryBatch(batch())
-
- expect(broadcastToUsers.mock.calls.map((call) =>
- (call[1] as { type: string }).type,
- )).toEqual([
- "community:message.create",
- "community:unread.bump",
- "community:unread.bump",
- "community:mention.create",
- "community:channel.member_add",
- "community:channel.child_update",
- ])
- expect((broadcastToUsers.mock.calls[1]?.[1] as { userId: string }).userId).toBe("u2")
- expect((broadcastToUsers.mock.calls[2]?.[1] as { userId: string }).userId).toBe("u3")
- expect((broadcastToUsers.mock.calls[3]?.[1] as { userId: string }).userId).toBe("u3")
- expect(logWarn).toHaveBeenCalledWith(
- "message_delivery_legacy_compat",
- expect.objectContaining({ messageId: "message-1", status, targetCount: 4 }),
- )
+ it.each([404, 405])("fails closed when ws-do lacks the batch route (%i)", async (status) => {
+ bindingFetch.mockResolvedValue(new Response("route unavailable", { status }))
+ await expect(sendMessageDeliveryBatch(batch())).rejects.toThrow(/failed for 1 chunk/)
+ expect(bindingFetch).toHaveBeenCalledTimes(1)
expect(globalFetch).not.toHaveBeenCalled()
})
- it("does not enter legacy mode after a binding 5xx or throw", async () => {
+ it("uses only the binding/dev fallback transport after a binding 5xx or throw", async () => {
bindingFetch.mockResolvedValueOnce(new Response("unavailable", { status: 503 }))
globalFetch.mockResolvedValueOnce(Response.json({ failedUserIds: [] }))
await sendMessageDeliveryBatch(batch())
@@ -252,17 +247,11 @@ describe("sendMessageDeliveryBatch", () => {
globalFetch.mockResolvedValueOnce(Response.json({ failedUserIds: [] }))
await sendMessageDeliveryBatch(batch())
- expect(broadcastToUsers).not.toHaveBeenCalled()
- expect(logWarn).not.toHaveBeenCalledWith(
- "message_delivery_legacy_compat",
- expect.anything(),
- )
})
it("does not enter legacy mode for an invalid successful response", async () => {
bindingFetch.mockResolvedValue(new Response("not json", { status: 200 }))
await expect(sendMessageDeliveryBatch(batch())).rejects.toThrow(/failed for 1 chunk/)
- expect(broadcastToUsers).not.toHaveBeenCalled()
})
})
diff --git a/src/web/src/lib/community/message-delivery-transport.ts b/src/web/src/lib/community/message-delivery-transport.ts
index fcef06df1..fe3e003ed 100644
--- a/src/web/src/lib/community/message-delivery-transport.ts
+++ b/src/web/src/lib/community/message-delivery-transport.ts
@@ -1,15 +1,17 @@
import { getCloudflareContext } from "@opennextjs/cloudflare"
import {
+ COMMUNITY_DELIVERY_OPERATION_ID_HEADER,
DEV_WS_DO_URL,
MESSAGE_DELIVERY_MAX_USERS,
createLogger,
+ deriveCommunityDeliveryOperationId,
isValidCommunityUserTarget,
parseStrictFailedSubset,
serializeMessageDeliveryBatch,
type MessageDeliveryBatch,
+ type CommunityDeliveryOperationId,
} from "@alook/shared"
import { fetchViaBindingOrDevFallback } from "../dev-binding-fetch"
-import { broadcastToUsers } from "../broadcast"
const log = createLogger({ service: "message-delivery-transport" })
const maxAttempts = 3
@@ -63,7 +65,11 @@ function parseFailedUserIds(value: unknown, requested: readonly string[]): strin
)
}
-async function sendAttempt(env: Env, batch: MessageDeliveryBatch): Promise<string[]> {
+async function sendAttempt(
+ env: Env,
+ batch: MessageDeliveryBatch,
+ operationId: CommunityDeliveryOperationId,
+): Promise<string[]> {
const requested = allTargetUserIds(batch)
const response = await fetchViaBindingOrDevFallback(
env.WS_DO_WORKER,
@@ -71,25 +77,14 @@ async function sendAttempt(env: Env, batch: MessageDeliveryBatch): Promise<strin
"/broadcast/community/message-delivery",
{
method: "POST",
- headers: { "content-type": "application/json" },
+ headers: {
+ "content-type": "application/json",
+ [COMMUNITY_DELIVERY_OPERATION_ID_HEADER]: operationId,
+ },
body: serializeMessageDeliveryBatch(batch),
},
{ logPrefix: "message_delivery", log, label: batch.messageId },
)
- if (response.status === 404 || response.status === 405) {
- log.warn("message_delivery_legacy_compat", {
- messageId: batch.messageId,
- status: response.status,
- targetCount: requested.length,
- contentCount: batch.contentUserIds.length,
- unreadCount: batch.unreadPlainUserIds.length + batch.unreadMentionUserIds.length,
- mentionCount: batch.mentionUserIds.length,
- memberCount: batch.memberAdded ? 1 : 0,
- parentCount: batch.parentProjectionUserIds?.length ?? 0,
- })
- await deliverWithLegacyCommunityBroadcast(batch)
- return []
- }
let body: unknown
try {
body = await response.json()
@@ -115,71 +110,15 @@ async function sendAttempt(env: Env, batch: MessageDeliveryBatch): Promise<strin
return failed
}
-async function deliverWithLegacyCommunityBroadcast(batch: MessageDeliveryBatch): Promise<void> {
- const message = batch.messageEvent
- if (batch.contentUserIds.length > 0) {
- await broadcastToUsers(batch.contentUserIds, message)
- }
- await settleLegacyTargets(batch.unreadPlainUserIds, (userId) =>
- broadcastToUsers([userId], {
- type: "community:unread.bump",
- userId,
- channelId: message.channelId,
- ...(message.serverId ? { serverId: message.serverId } : {}),
- ...(message.serverId
- ? { railChannelId: message.parentChannelId ?? message.channelId }
- : {}),
- isMention: false,
- }),
- )
- await settleLegacyTargets(batch.unreadMentionUserIds, (userId) =>
- broadcastToUsers([userId], {
- type: "community:unread.bump",
- userId,
- channelId: message.channelId,
- ...(message.serverId ? { serverId: message.serverId } : {}),
- ...(message.serverId
- ? { railChannelId: message.parentChannelId ?? message.channelId }
- : {}),
- isMention: true,
- }),
- )
- await settleLegacyTargets(batch.mentionUserIds, (userId) =>
- broadcastToUsers([userId], {
- type: "community:mention.create",
- userId,
- messageId: batch.messageId,
- channelId: message.channelId,
- authorName: message.message.authorName,
- }),
- )
- if (batch.memberAdded) {
- await broadcastToUsers([batch.memberAdded.userId], {
- type: "community:channel.member_add",
- ...batch.memberAdded,
- })
- }
- if (batch.parentProjection && batch.parentProjectionUserIds?.length) {
- await broadcastToUsers(batch.parentProjectionUserIds, batch.parentProjection)
- }
-}
-
-async function settleLegacyTargets(
- userIds: readonly string[],
- send: (userId: string) => Promise<void>,
+async function sendChunk(
+ env: Env,
+ initial: MessageDeliveryBatch,
+ operationId: CommunityDeliveryOperationId,
): Promise<void> {
- let next = 0
- const workers = Array.from({ length: Math.min(maxActiveChunks, userIds.length) }, async () => {
- while (next < userIds.length) await send(userIds[next++]!)
- })
- await Promise.all(workers)
-}
-
-async function sendChunk(env: Env, initial: MessageDeliveryBatch): Promise<void> {
let pending = initial
for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
const startedAt = Date.now()
- const failed = await sendAttempt(env, pending)
+ const failed = await sendAttempt(env, pending, operationId)
log.info("message_delivery_attempt_complete", {
messageId: initial.messageId,
attempt,
@@ -195,14 +134,18 @@ async function sendChunk(env: Env, initial: MessageDeliveryBatch): Promise<void>
}
}
-async function settleChunks(env: Env, chunks: MessageDeliveryBatch[]): Promise<void> {
+async function settleChunks(
+ env: Env,
+ chunks: MessageDeliveryBatch[],
+ operationId: CommunityDeliveryOperationId,
+): Promise<void> {
let next = 0
const results: PromiseSettledResult<void>[] = new Array(chunks.length)
const workers = Array.from({ length: Math.min(maxActiveChunks, chunks.length) }, async () => {
while (next < chunks.length) {
const index = next++
try {
- await sendChunk(env, chunks[index]!)
+ await sendChunk(env, chunks[index]!, operationId)
results[index] = { status: "fulfilled", value: undefined }
} catch (reason) {
results[index] = { status: "rejected", reason }
@@ -216,7 +159,15 @@ async function settleChunks(env: Env, chunks: MessageDeliveryBatch[]): Promise<v
}
}
-export async function sendMessageDeliveryBatch(batch: MessageDeliveryBatch): Promise<void> {
+export async function sendMessageDeliveryBatch(
+ batch: MessageDeliveryBatch,
+ plannedOperationId?: CommunityDeliveryOperationId,
+): Promise<void> {
+ const derivedOperationId = await deriveCommunityDeliveryOperationId(batch.messageId)
+ if (plannedOperationId !== undefined && plannedOperationId !== derivedOperationId) {
+ throw new Error("message delivery: operation ID does not match message")
+ }
+ const operationId = plannedOperationId ?? derivedOperationId
const { env } = getCloudflareContext()
const targets = allTargetUserIds(batch)
const chunks: MessageDeliveryBatch[] = []
@@ -247,5 +198,5 @@ export async function sendMessageDeliveryBatch(batch: MessageDeliveryBatch): Pro
chunks.push(accepted)
index = acceptedEnd
}
- await settleChunks(env as Env, chunks)
+ await settleChunks(env as Env, chunks, operationId)
}
diff --git a/src/web/src/lib/community/message-dispatcher.test.ts b/src/web/src/lib/community/message-dispatcher.test.ts
index 76ae7711d..2e385b5fb 100644
--- a/src/web/src/lib/community/message-dispatcher.test.ts
+++ b/src/web/src/lib/community/message-dispatcher.test.ts
@@ -62,6 +62,7 @@ vi.mock("./wake-producer", () => ({
}))
import { dispatchCommittedMessage, planCommittedMessage } from "./message-dispatcher"
+import { deriveCommunityDeliveryOperationId } from "@alook/shared"
const message = {
id: "msg_1",
@@ -347,6 +348,7 @@ describe("planCommittedMessage", () => {
const first = await planCommittedMessage({} as never, "msg_1")
const second = await planCommittedMessage({} as never, "msg_1")
expect(second).toEqual(first)
+ expect(first.operationId).toBe(await deriveCommunityDeliveryOperationId("msg_1"))
})
})
@@ -370,6 +372,10 @@ describe("dispatchCommittedMessage", () => {
expect(mockWaitUntil).toHaveBeenCalledWith(work)
await expect(work).resolves.toBeUndefined()
expect(mockSendMessageDeliveryBatch).toHaveBeenCalledTimes(1)
+ expect(mockSendMessageDeliveryBatch).toHaveBeenCalledWith(
+ expect.objectContaining({ messageId: "msg_1" }),
+ await deriveCommunityDeliveryOperationId("msg_1"),
+ )
expect(mockEnqueueBotWakePayloads).toHaveBeenCalledWith([])
})
diff --git a/src/web/src/lib/community/message-dispatcher.ts b/src/web/src/lib/community/message-dispatcher.ts
index b444cadaf..00dd75a17 100644
--- a/src/web/src/lib/community/message-dispatcher.ts
+++ b/src/web/src/lib/community/message-dispatcher.ts
@@ -1,10 +1,12 @@
import { getCloudflareContext } from "@opennextjs/cloudflare"
import {
+ deriveCommunityDeliveryOperationId,
WS_EVENTS,
createLogger,
queries,
withD1Retry,
type CommunityMessageCreate,
+ type CommunityDeliveryOperationId,
type Database,
type MessageDeliveryBatch,
type WakePayload,
@@ -24,6 +26,7 @@ export type CommittedMessageStructuralOutcome = {
}
export type MessageDeliveryPlan = MessageDeliveryBatch & {
+ operationId: CommunityDeliveryOperationId
wakeBotUserIds: string[]
}
@@ -201,6 +204,7 @@ export async function planCommittedMessage(
}
return {
+ operationId: await deriveCommunityDeliveryOperationId(message.id),
messageId: message.id,
messageEvent,
contentUserIds,
@@ -250,7 +254,7 @@ async function runCommittedMessageDispatch(
botUserId,
}))
const [browser, wake] = await Promise.allSettled([
- sendMessageDeliveryBatch(browserBatch),
+ sendMessageDeliveryBatch(browserBatch, plan.operationId),
enqueueBotWakePayloads(wakePayloads),
])
if (browser.status === "rejected") {
diff --git a/src/web/src/lib/use-user-ws.test.ts b/src/web/src/lib/use-user-ws.test.ts
index 0e21f4e9a..0bc0b7f0b 100644
--- a/src/web/src/lib/use-user-ws.test.ts
+++ b/src/web/src/lib/use-user-ws.test.ts
@@ -1,5 +1,8 @@
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest"
-import type { WsMessage } from "@alook/shared"
+import {
+ COMMUNITY_BROWSER_EVENT_BATCH_MAX_BYTES,
+ type WsMessage,
+} from "@alook/shared"
import type { UseUserWsOptions } from "./use-user-ws"
// --- Mock WebSocket ---
@@ -853,6 +856,20 @@ describe("useUserWs", () => {
ws.simulateRawMessage(oversizedCommunity)
expect(onMessage).not.toHaveBeenCalled()
+ const legalLargeBatch = {
+ type: "community:events.batch",
+ payload: "x".repeat(70_000),
+ }
+ ws.simulateMessage(legalLargeBatch)
+ expect(onMessage).toHaveBeenCalledWith(legalLargeBatch)
+
+ onMessage.mockClear()
+ ws.simulateRawMessage(JSON.stringify({
+ type: "community:events.batch",
+ payload: "x".repeat(COMMUNITY_BROWSER_EVENT_BATCH_MAX_BYTES),
+ }))
+ expect(onMessage).not.toHaveBeenCalled()
+
const generic = { type: "task.updated", payload: "x".repeat(65_536) }
ws.simulateMessage(generic)
expect(onMessage).toHaveBeenCalledWith(generic)
diff --git a/src/web/src/lib/use-user-ws.ts b/src/web/src/lib/use-user-ws.ts
index b6604d0b5..f38020baa 100644
--- a/src/web/src/lib/use-user-ws.ts
+++ b/src/web/src/lib/use-user-ws.ts
@@ -1,7 +1,9 @@
"use client"
import { useEffect, useRef, useCallback } from "react"
import {
+ COMMUNITY_BROWSER_EVENT_BATCH_MAX_BYTES,
COMMUNITY_BROWSER_EVENT_MAX_BYTES,
+ isCommunityBrowserEventBatchCandidate,
isCommunityEventCandidate,
isCommunityEventType,
type WsMessage,
@@ -295,9 +297,13 @@ export function useUserWs(
reportDroppedFrame("pre-auth-frame", msg)
return
}
- if (isCommunityEventCandidate(msg)) {
+ const isCommunityBatch = isCommunityBrowserEventBatchCandidate(msg)
+ if (isCommunityEventCandidate(msg) || isCommunityBatch) {
const byteCount = new TextEncoder().encode(e.data).byteLength
- if (byteCount > COMMUNITY_BROWSER_EVENT_MAX_BYTES) {
+ const maxBytes = isCommunityBatch
+ ? COMMUNITY_BROWSER_EVENT_BATCH_MAX_BYTES
+ : COMMUNITY_BROWSER_EVENT_MAX_BYTES
+ if (byteCount > maxBytes) {
reportDroppedFrame("oversized", msg, byteCount)
return
}
diff --git a/src/web/src/stores/community/ws.test.ts b/src/web/src/stores/community/ws.test.ts
index 261686b91..efdba7aee 100644
--- a/src/web/src/stores/community/ws.test.ts
+++ b/src/web/src/stores/community/ws.test.ts
@@ -1,6 +1,8 @@
import { beforeEach, describe, expect, it } from "vitest"
import {
BOT_AUDIT_RING_MAX,
+ SEEN_DELIVERY_OPERATION_MAX,
+ SEEN_DELIVERY_OPERATION_TRIM_TO,
SEEN_MESSAGE_MAX,
SEEN_MESSAGE_TRIM_TO,
useCommunityWsStore,
@@ -29,6 +31,7 @@ describe("useCommunityWsStore", () => {
const s = useCommunityWsStore.getState()
expect(s.onlineUserIds.size).toBe(0)
expect(s.seenMessageIds.size).toBe(0)
+ expect(s.seenDeliveryOperations.size).toBe(0)
})
it("setPresence adds and removes user ids", () => {
@@ -144,14 +147,82 @@ describe("useCommunityWsStore", () => {
expect(after.has("m0")).toBe(false)
})
+ it("locks a delivery digest before completion and keeps same-digest failures retryable", () => {
+ const store = useCommunityWsStore.getState()
+ expect(store.observeDeliveryOperation("operation-1", "a".repeat(64))).toBe("new")
+ const observed = useCommunityWsStore.getState().seenDeliveryOperations
+ expect(observed.get("operation-1")).toEqual({
+ digest: "a".repeat(64),
+ completed: false,
+ })
+ expect(useCommunityWsStore.getState().observeDeliveryOperation("operation-1", "a".repeat(64)))
+ .toBe("retryable")
+ expect(useCommunityWsStore.getState().observeDeliveryOperation("operation-1", "b".repeat(64)))
+ .toBe("conflict")
+ expect(useCommunityWsStore.getState().seenDeliveryOperations).toBe(observed)
+ expect(useCommunityWsStore.getState().completeDeliveryOperation("operation-1", "b".repeat(64)))
+ .toBe(false)
+ expect(useCommunityWsStore.getState().completeDeliveryOperation("operation-1", "a".repeat(64)))
+ .toBe(true)
+ expect(useCommunityWsStore.getState().seenDeliveryOperations.get("operation-1"))
+ .toEqual({ digest: "a".repeat(64), completed: true })
+ expect(useCommunityWsStore.getState().observeDeliveryOperation("operation-1", "a".repeat(64)))
+ .toBe("duplicate")
+ expect(useCommunityWsStore.getState().observeDeliveryOperation("operation-1", "b".repeat(64)))
+ .toBe("conflict")
+ })
+
+ it("trims retryable/completed delivery operations together and retains them across reconnect", () => {
+ for (let index = 0; index <= SEEN_DELIVERY_OPERATION_MAX; index += 1) {
+ useCommunityWsStore.getState().observeDeliveryOperation(
+ `operation-${index}`,
+ index.toString(16).padStart(64, "0"),
+ )
+ if (index % 2 === 0) {
+ useCommunityWsStore.getState().completeDeliveryOperation(
+ `operation-${index}`,
+ index.toString(16).padStart(64, "0"),
+ )
+ }
+ }
+ const operations = useCommunityWsStore.getState().seenDeliveryOperations
+ expect(operations.size).toBe(SEEN_DELIVERY_OPERATION_TRIM_TO)
+ expect(operations.has("operation-0")).toBe(false)
+ expect(operations.has(`operation-${SEEN_DELIVERY_OPERATION_MAX}`)).toBe(true)
+ expect(operations.get(`operation-${SEEN_DELIVERY_OPERATION_MAX}`)?.completed).toBe(true)
+ expect(operations.get(`operation-${SEEN_DELIVERY_OPERATION_MAX - 1}`)?.completed).toBe(false)
+
+ useCommunityWsStore.getState().markAccessDisconnected()
+ useCommunityWsStore.getState().markAccessConnected()
+ expect(useCommunityWsStore.getState().seenDeliveryOperations).toBe(operations)
+ })
+
it("reset clears both online and seen sets", () => {
useCommunityWsStore.getState().setPresence("u1", true)
useCommunityWsStore.getState().markSeenMessage("m1")
+ useCommunityWsStore.getState().observeDeliveryOperation(
+ "retryable-operation",
+ "a".repeat(64),
+ )
+ useCommunityWsStore.getState().observeDeliveryOperation(
+ "completed-operation",
+ "b".repeat(64),
+ )
+ useCommunityWsStore.getState().completeDeliveryOperation(
+ "completed-operation",
+ "b".repeat(64),
+ )
+
+ expect(useCommunityWsStore.getState().seenDeliveryOperations.get("retryable-operation"))
+ .toEqual({ digest: "a".repeat(64), completed: false })
+ expect(useCommunityWsStore.getState().seenDeliveryOperations.get("completed-operation"))
+ .toEqual({ digest: "b".repeat(64), completed: true })
useCommunityWsStore.getState().reset()
expect(useCommunityWsStore.getState().onlineUserIds.size).toBe(0)
expect(useCommunityWsStore.getState().seenMessageIds.size).toBe(0)
+ expect(useCommunityWsStore.getState().seenDeliveryOperations.size).toBe(0)
})
it("starts with an empty userStatuses map", () => {
diff --git a/src/web/src/stores/community/ws.ts b/src/web/src/stores/community/ws.ts
index 3ee4c9080..9cdc70da5 100644
--- a/src/web/src/stores/community/ws.ts
+++ b/src/web/src/stores/community/ws.ts
@@ -26,6 +26,14 @@ import { create } from "zustand"
// 400). Extracted as constants so the tests can assert the boundary directly.
export const SEEN_MESSAGE_MAX = 500
export const SEEN_MESSAGE_TRIM_TO = 400
+export const SEEN_DELIVERY_OPERATION_MAX = 500
+export const SEEN_DELIVERY_OPERATION_TRIM_TO = 400
+
+type DeliveryOperationObservationResult = "new" | "retryable" | "duplicate" | "conflict"
+type DeliveryOperationState = {
+ digest: string
+ completed: boolean
+}
/**
* Bounded ring for live bot-audit events, PER bot. The modal reads from here
@@ -60,6 +68,7 @@ export type CommunityWsStoreState = {
*/
onlineUserIds: Set<string>
seenMessageIds: Set<string>
+ seenDeliveryOperations: Map<string, DeliveryOperationState>
/**
* Live status deltas learned via `community:status.update` after the
* initial member/friend fetch — see plans/profile-card.md's "overlay
@@ -98,6 +107,11 @@ export type CommunityWsStoreState = {
resetPresence: () => void
hasSeenMessage: (id: string) => boolean
markSeenMessage: (id: string) => void
+ observeDeliveryOperation: (
+ operationId: string,
+ operationDigest: string,
+ ) => DeliveryOperationObservationResult
+ completeDeliveryOperation: (operationId: string, operationDigest: string) => boolean
setUserStatus: (userId: string, emoji: string | null, text: string | null) => void
resetUserStatuses: () => void
markAccessDisconnected: () => void
@@ -108,13 +122,14 @@ export type CommunityWsStoreState = {
const initialState = (): Pick<
CommunityWsStoreState,
- "onlineUserIds" | "seenMessageIds" | "userStatuses" | "botAuditEvents"
+ "onlineUserIds" | "seenMessageIds" | "seenDeliveryOperations" | "userStatuses" | "botAuditEvents"
| "accessEpoch" | "accessConnected"
> => ({
accessEpoch: 0,
accessConnected: false,
onlineUserIds: new Set(),
seenMessageIds: new Set(),
+ seenDeliveryOperations: new Map(),
userStatuses: new Map(),
botAuditEvents: new Map(),
})
@@ -170,6 +185,38 @@ export const useCommunityWsStore = create<CommunityWsStoreState>((set, get) => (
set({ seenMessageIds: next })
},
+ observeDeliveryOperation: (operationId, operationDigest) => {
+ const current = get().seenDeliveryOperations
+ const observed = current.get(operationId)
+ if (observed !== undefined) {
+ if (observed.digest !== operationDigest) return "conflict"
+ return observed.completed ? "duplicate" : "retryable"
+ }
+ const next = new Map(current)
+ next.set(operationId, { digest: operationDigest, completed: false })
+ if (next.size > SEEN_DELIVERY_OPERATION_MAX) {
+ set({
+ seenDeliveryOperations: new Map(
+ [...next].slice(-SEEN_DELIVERY_OPERATION_TRIM_TO),
+ ),
+ })
+ return "new"
+ }
+ set({ seenDeliveryOperations: next })
+ return "new"
+ },
+
+ completeDeliveryOperation: (operationId, operationDigest) => {
+ const current = get().seenDeliveryOperations
+ const observed = current.get(operationId)
+ if (!observed || observed.digest !== operationDigest) return false
+ if (observed.completed) return true
+ const next = new Map(current)
+ next.set(operationId, { ...observed, completed: true })
+ set({ seenDeliveryOperations: next })
+ return true
+ },
+
setUserStatus: (userId, emoji, text) => {
const next = new Map(get().userStatuses)
next.set(userId, { emoji, text })
diff --git a/src/web/src/test/e2e-ui/22-committed-message-delivery.spec.ts b/src/web/src/test/e2e-ui/22-committed-message-delivery.spec.ts
index 53f320298..3e0f66525 100644
--- a/src/web/src/test/e2e-ui/22-committed-message-delivery.spec.ts
+++ b/src/web/src/test/e2e-ui/22-committed-message-delivery.spec.ts
@@ -11,15 +11,16 @@ import {
seedServer,
} from "./_fixtures/seed"
import {
- frozenF1090ebeDecoderAccepts,
+ communityFrameEvents,
proxyCommunityWebSockets,
type CapturedCommunityFrame,
} from "./_fixtures/community-ws-proxy"
function messageFrame(frame: CapturedCommunityFrame, channelId: string, content: string): boolean {
- return frame.type === "community:message.create"
- && frame.channelId === channelId
- && frame.message?.content === content
+ return communityFrameEvents(frame).some((event) =>
+ event.type === "community:message.create"
+ && event.channelId === channelId
+ && event.message?.content?.includes(content))
}
test.describe.serial("committed message delivery QA", () => {
@@ -32,7 +33,7 @@ test.describe.serial("committed message delivery QA", () => {
const carol = await asUser("carol")
let armed = false
- const carolFrames = await proxyCommunityWebSockets(carol.context)
+ const carolProxy = await proxyCommunityWebSockets(carol.context)
await gotoAfterUserWsAuth(carol.page, `/c/channels/${serverId}/${forumId}`)
await expect(carol.page.getByTestId(`community-forum-post-${threadId}`)).toBeVisible({ timeout: 20_000 })
armed = true
@@ -43,30 +44,38 @@ test.describe.serial("committed message delivery QA", () => {
const body = `participant reply ${Date.now()}`
await sendMessage(bob.page, body)
- await expect.poll(() => carolFrames.some((frame) => armed
- && frame.type === "community:channel.child_update"
- && frame.parentChannelId === forumId
- && frame.channelId === threadId), { timeout: 20_000 }).toBe(true)
- expect(carolFrames.some((frame) => messageFrame(frame, threadId, body))).toBe(false)
+ await expect.poll(() => carolProxy.frames.some((frame) => armed
+ && communityFrameEvents(frame).some((event) =>
+ event.type === "community:channel.child_update"
+ && event.parentChannelId === forumId
+ && event.channelId === threadId)), { timeout: 20_000 }).toBe(true)
+ expect(carolProxy.frames.some((frame) => messageFrame(frame, threadId, body))).toBe(false)
await expect(carol.page.getByText(body, { exact: false })).toHaveCount(0)
})
- test("Q7 channel: a dropped message frame is repaired when a later seq arrives", async ({ asUser }) => {
+ test("Q7 channel: a held mention bundle is repaired before late release", async ({ asUser }) => {
const serverId = await seedServer("alice", `Gap channel ${Date.now()}`)
const channelId = await seedChannel("alice", serverId, "gap-channel")
await seedJoinServer("alice", "bob", serverId)
await seedMessage("alice", channelId, "gap baseline")
+ const bobInfo = await memberInfo("alice", serverId, userId("bob"))
const bob = await asUser("bob")
let armed = false
let dropped = false
- const frames = await proxyCommunityWebSockets(bob.context, (frame) => {
+ const missing = `missing channel ${Date.now()}`
+ const later = `later channel ${Date.now()}`
+ const proxy = await proxyCommunityWebSockets(bob.context, { decide: (frame) => {
if (armed && !dropped && frame.type === "community:message.create" && frame.channelId === channelId) {
dropped = true
- return "drop"
+ return "hold"
+ }
+ if (armed && !dropped && messageFrame(frame, channelId, missing)) {
+ dropped = true
+ return "hold"
}
return "forward"
- })
+ } })
const gapRequests: string[] = []
bob.page.on("request", (request) => {
const url = new URL(request.url())
@@ -79,17 +88,40 @@ test.describe.serial("committed message delivery QA", () => {
const alice = await asUser("alice")
await gotoAfterUserWsAuth(alice.page, `/c/channels/${serverId}/${channelId}`)
- const missing = `missing channel ${Date.now()}`
- const later = `later channel ${Date.now()}`
armed = true
- await sendMessage(alice.page, missing)
+ const editable = composerEditable(alice.page)
+ await editable.click()
+ await editable.pressSequentially(`@${bobInfo.name.slice(0, 3)}`)
+ await alice.page.getByTestId(`community-mention-option-${bobInfo.id}`).click()
+ await editable.pressSequentially(` ${missing}`)
+ await alice.page.keyboard.press("Enter")
await expect.poll(() => dropped, { timeout: 20_000 }).toBe(true)
await sendMessage(alice.page, later)
await expectMessageVisible(bob.page, missing)
await expectMessageVisible(bob.page, later)
expect(gapRequests.length).toBeGreaterThan(0)
- expect(frames.filter((frame) => messageFrame(frame, channelId, missing))).toHaveLength(1)
+ expect(proxy.heldCount()).toBe(1)
+ const heldBatch = proxy.frames.find((frame) => messageFrame(frame, channelId, missing))
+ expect(heldBatch?.type).toBe("community:events.batch")
+ expect(communityFrameEvents(heldBatch!).some((event) =>
+ event.type === "community:mention.create")).toBe(true)
+ expect(proxy.releaseHeld((frame) => messageFrame(frame, channelId, missing))).toBe(1)
+ await bob.page.evaluate(() => new Promise<void>((resolve) => {
+ requestAnimationFrame(() => requestAnimationFrame(() => resolve()))
+ }))
+ await expect(bob.page.getByText(missing, { exact: false })).toHaveCount(1)
+ expect(proxy.frames.filter((frame) => messageFrame(frame, channelId, missing))).toHaveLength(1)
+ await expect.poll(async () => {
+ const response = await bob.page.request.get("/api/community/servers")
+ const data = await response.json() as { servers: Array<{ id: string; mentions: number }> }
+ const authoritative = data.servers.find((server) => server.id === serverId)?.mentions ?? 0
+ const badge = bob.page.getByTestId(`community-rail-unread-badge-${serverId}`)
+ const displayed = await badge.count() === 0
+ ? 0
+ : Number((await badge.textContent())?.trim())
+ return displayed === authoritative
+ }, { timeout: 20_000 }).toBe(true)
})
test("Q7 DM: a dropped message frame is repaired when a later seq arrives", async ({ asUser }) => {
@@ -98,13 +130,19 @@ test.describe.serial("committed message delivery QA", () => {
const bob = await asUser("bob")
let armed = false
let dropped = false
- await proxyCommunityWebSockets(bob.context, (frame) => {
+ const missing = `missing dm ${Date.now()}`
+ const later = `later dm ${Date.now()}`
+ await proxyCommunityWebSockets(bob.context, { decide: (frame) => {
if (armed && !dropped && frame.type === "community:message.create" && frame.channelId === dmId) {
dropped = true
return "drop"
}
+ if (armed && !dropped && messageFrame(frame, dmId, missing)) {
+ dropped = true
+ return "drop"
+ }
return "forward"
- })
+ } })
const gapRequests: string[] = []
bob.page.on("request", (request) => {
const url = new URL(request.url())
@@ -117,8 +155,6 @@ test.describe.serial("committed message delivery QA", () => {
const alice = await asUser("alice")
await gotoAfterUserWsAuth(alice.page, `/c/me/${dmId}`)
- const missing = `missing dm ${Date.now()}`
- const later = `later dm ${Date.now()}`
armed = true
await sendMessage(alice.page, missing)
await expect.poll(() => dropped, { timeout: 20_000 }).toBe(true)
@@ -129,51 +165,127 @@ test.describe.serial("committed message delivery QA", () => {
expect(gapRequests.length).toBeGreaterThan(0)
})
- test("Q8: the frozen f1090ebe browser decoder accepts live channel, mention, and DM frames", async ({ asUser }) => {
- const serverId = await seedServer("alice", `Old decoder ${Date.now()}`)
- const channelId = await seedChannel("alice", serverId, "old-decoder")
+ test("Q8: capable duplicate suppression ends safely at full reload", async ({ asUser }) => {
+ const serverId = await seedServer("alice", `Atomic batch ${Date.now()}`)
+ const channelId = await seedChannel("alice", serverId, "atomic-batch")
await seedJoinServer("alice", "bob", serverId)
- const dmId = await seedDm("alice", userId("bob"))
const bobInfo = await memberInfo("alice", serverId, userId("bob"))
const bob = await asUser("bob")
- const droppedDiagnostics: string[] = []
- bob.page.on("console", (message) => {
- if (message.text().includes("community_ws_frame_dropped")) droppedDiagnostics.push(message.text())
+ let armed = false
+ let duplicated = false
+ const body = `atomic duplicate ${Date.now()}`
+ const serverRequests: string[] = []
+ bob.page.on("request", (request) => {
+ if (new URL(request.url()).pathname === "/api/community/servers") {
+ serverRequests.push(request.url())
+ }
})
- const frames = await proxyCommunityWebSockets(bob.context)
+ const proxy = await proxyCommunityWebSockets(bob.context, { decide: (frame) => {
+ if (
+ armed
+ && !duplicated
+ && frame.type === "community:events.batch"
+ && messageFrame(frame, channelId, body)
+ ) {
+ duplicated = true
+ return "duplicate"
+ }
+ return "forward"
+ } })
await gotoAfterUserWsAuth(bob.page, `/c/channels/${serverId}/${channelId}`)
await expect(composerEditable(bob.page)).toBeVisible()
const alice = await asUser("alice")
await gotoAfterUserWsAuth(alice.page, `/c/channels/${serverId}/${channelId}`)
+ armed = true
+ const editable = composerEditable(alice.page)
+ await editable.click()
+ await editable.pressSequentially(`@${bobInfo.name.slice(0, 3)}`)
+ await alice.page.getByTestId(`community-mention-option-${bobInfo.id}`).click()
+ await editable.pressSequentially(` ${body}`)
+ await alice.page.keyboard.press("Enter")
+ await expect.poll(() => duplicated, { timeout: 20_000 }).toBe(true)
+
+ const batches = proxy.frames.filter((frame) =>
+ frame.type === "community:events.batch" && messageFrame(frame, channelId, body))
+ expect(batches).toHaveLength(1)
+ const batch = batches[0]!
+ expect(batch.operationId).toMatch(/^message:[A-Za-z0-9_-]{43}$/)
+ expect(batch.operationDigest).toMatch(/^[0-9a-f]{64}$/)
+ expect(communityFrameEvents(batch).map((event) => event.type)).toEqual([
+ "community:message.create",
+ "community:unread.bump",
+ "community:mention.create",
+ ])
+ const messageId = communityFrameEvents(batch)[0]?.message?.id
+ expect(messageId).toBeTruthy()
+ await expect(bob.page.getByTestId(`community-message-${messageId}`)).toHaveCount(1)
+
+ const requestsBeforeReload = serverRequests.length
+ await gotoAfterUserWsAuth(bob.page, `/c/channels/${serverId}/${channelId}`)
+ await expect(bob.page.getByTestId(`community-message-${messageId}`)).toHaveCount(1)
+ await expect.poll(() => serverRequests.length, { timeout: 20_000 })
+ .toBeGreaterThan(requestsBeforeReload)
+ const requestsBeforeReplay = serverRequests.length
+ proxy.replay(batch)
+ await expect.poll(() => serverRequests.length, { timeout: 20_000 })
+ .toBeGreaterThan(requestsBeforeReplay)
+ await expect(bob.page.getByTestId(`community-message-${messageId}`)).toHaveCount(1)
+ })
+
+ test("Q9: every receiver gets the same batch-only channel and DM delivery", async ({ asUser }) => {
+ const serverId = await seedServer("alice", `Batch receivers ${Date.now()}`)
+ const channelId = await seedChannel("alice", serverId, "batch-receivers")
+ await seedJoinServer("alice", "bob", serverId)
+ const dmId = await seedDm("alice", userId("bob"))
+ const bobInfo = await memberInfo("alice", serverId, userId("bob"))
+
+ const firstBob = await asUser("bob")
+ const secondBob = await asUser("bob")
+ const firstProxy = await proxyCommunityWebSockets(firstBob.context)
+ const secondProxy = await proxyCommunityWebSockets(secondBob.context)
+ await gotoAfterUserWsAuth(firstBob.page, `/c/channels/${serverId}/${channelId}`)
+ await gotoAfterUserWsAuth(secondBob.page, `/c/channels/${serverId}/${channelId}`)
+ await expect(composerEditable(firstBob.page)).toBeVisible()
+ await expect(composerEditable(secondBob.page)).toBeVisible()
+
+ const alice = await asUser("alice")
+ await gotoAfterUserWsAuth(alice.page, `/c/channels/${serverId}/${channelId}`)
+ const firstChannelStart = firstProxy.frames.length
+ const secondChannelStart = secondProxy.frames.length
const editable = composerEditable(alice.page)
await editable.click()
await editable.pressSequentially(`@${bobInfo.name.slice(0, 3)}`)
await alice.page.getByTestId(`community-mention-option-${bobInfo.id}`).click()
- await editable.pressSequentially(" compatibility channel")
+ await editable.pressSequentially(" batch channel")
await alice.page.keyboard.press("Enter")
- await expect.poll(() => frames.some((frame) => frame.type === "community:mention.create"), {
+ await expect.poll(() => firstProxy.frames.slice(firstChannelStart).some((frame) =>
+ frame.type === "community:events.batch"
+ && communityFrameEvents(frame).some((event) => event.type === "community:mention.create")), {
+ timeout: 20_000,
+ }).toBe(true)
+ await expect.poll(() => secondProxy.frames.slice(secondChannelStart).some((frame) =>
+ frame.type === "community:events.batch"
+ && communityFrameEvents(frame).some((event) => event.type === "community:mention.create")), {
timeout: 20_000,
}).toBe(true)
+ await expectMessageVisible(firstBob.page, "batch channel")
+ await expectMessageVisible(secondBob.page, "batch channel")
- await gotoAfterUserWsAuth(bob.page, `/c/me/${dmId}`)
+ await gotoAfterUserWsAuth(firstBob.page, `/c/me/${dmId}`)
+ await gotoAfterUserWsAuth(secondBob.page, `/c/me/${dmId}`)
await gotoAfterUserWsAuth(alice.page, `/c/me/${dmId}`)
- const dmBody = `compatibility dm ${Date.now()}`
+ const firstDmStart = firstProxy.frames.length
+ const secondDmStart = secondProxy.frames.length
+ const dmBody = `batch dm ${Date.now()}`
await sendMessage(alice.page, dmBody)
- await expectMessageVisible(bob.page, dmBody)
+ await expectMessageVisible(firstBob.page, dmBody)
+ await expectMessageVisible(secondBob.page, dmBody)
- const relevant = frames.filter((frame) => [
- "community:message.create",
- "community:unread.bump",
- "community:mention.create",
- "community:channel.member_add",
- "community:channel.child_update",
- ].includes(frame.type))
- expect(relevant.some((frame) => frame.type === "community:message.create" && frame.channelId === channelId)).toBe(true)
- expect(relevant.some((frame) => frame.type === "community:mention.create" && frame.channelId === channelId)).toBe(true)
- expect(relevant.some((frame) => frame.type === "community:message.create" && frame.channelId === dmId)).toBe(true)
- expect(relevant.every(frozenF1090ebeDecoderAccepts)).toBe(true)
- expect(droppedDiagnostics).toEqual([])
+ expect(firstProxy.frames.slice(firstDmStart).filter((frame) =>
+ frame.type === "community:events.batch" && messageFrame(frame, dmId, dmBody))).toHaveLength(1)
+ expect(secondProxy.frames.slice(secondDmStart).filter((frame) =>
+ frame.type === "community:events.batch" && messageFrame(frame, dmId, dmBody))).toHaveLength(1)
})
})
diff --git a/src/web/src/test/e2e-ui/_fixtures/community-ws-proxy.ts b/src/web/src/test/e2e-ui/_fixtures/community-ws-proxy.ts
index 3abddee53..4eea5903a 100644
--- a/src/web/src/test/e2e-ui/_fixtures/community-ws-proxy.ts
+++ b/src/web/src/test/e2e-ui/_fixtures/community-ws-proxy.ts
@@ -3,6 +3,9 @@ import type { BrowserContext, WebSocketRoute } from "@playwright/test"
export type CapturedCommunityFrame = {
type: string
contractVersion?: number
+ operationId?: string
+ operationDigest?: string
+ events?: CapturedCommunityFrame[]
channelId?: string
parentChannelId?: string
messageId?: string
@@ -10,7 +13,26 @@ export type CapturedCommunityFrame = {
[key: string]: unknown
}
-type FrameDecision = (frame: CapturedCommunityFrame) => "drop" | "forward"
+type FrameDecision = (
+ frame: CapturedCommunityFrame,
+) => "drop" | "duplicate" | "forward" | "hold"
+
+type HeldCommunityFrame = {
+ client: WebSocketRoute
+ frame: CapturedCommunityFrame
+ message: string | Buffer
+}
+
+export type CommunityWsProxy = {
+ frames: CapturedCommunityFrame[]
+ heldCount: () => number
+ releaseHeld: (predicate?: (frame: CapturedCommunityFrame) => boolean) => number
+ replay: (frame: CapturedCommunityFrame) => void
+}
+
+export type CommunityWsProxyOptions = {
+ decide?: FrameDecision
+}
function parseCommunityFrame(message: string | Buffer): CapturedCommunityFrame | null {
try {
@@ -28,65 +50,62 @@ function parseCommunityFrame(message: string | Buffer): CapturedCommunityFrame |
}
}
-/**
- * Test-only transparent WS proxy. It records community browser-v1 frames and
- * can drop selected server frames without adding a production fault hook.
- */
export async function proxyCommunityWebSockets(
context: BrowserContext,
- decide: FrameDecision = () => "forward",
-): Promise<CapturedCommunityFrame[]> {
+ options: CommunityWsProxyOptions = {},
+): Promise<CommunityWsProxy> {
const frames: CapturedCommunityFrame[] = []
+ const held: HeldCommunityFrame[] = []
+ const payloads = new WeakMap<CapturedCommunityFrame, string | Buffer>()
+ let activeClient: WebSocketRoute | undefined
await context.routeWebSocket(/.*/, (client: WebSocketRoute) => {
+ activeClient = client
const server = client.connectToServer()
server.onMessage((message) => {
const frame = parseCommunityFrame(message)
if (frame) {
frames.push(frame)
- if (decide(frame) === "drop") return
+ payloads.set(frame, message)
+ const decision = options.decide?.(frame) ?? "forward"
+ if (decision === "drop") return
+ if (decision === "hold") {
+ held.push({ client, frame, message })
+ return
+ }
+ client.send(message)
+ if (decision === "duplicate") client.send(message)
+ return
}
client.send(message)
})
})
- return frames
+ return {
+ frames,
+ heldCount: () => held.length,
+ releaseHeld: (predicate = () => true) => {
+ let released = 0
+ for (let index = 0; index < held.length;) {
+ const item = held[index]!
+ if (!predicate(item.frame)) {
+ index += 1
+ continue
+ }
+ held.splice(index, 1)
+ item.client.send(item.message)
+ released += 1
+ }
+ return released
+ },
+ replay: (frame) => {
+ const message = payloads.get(frame)
+ if (!message || !activeClient) throw new Error("community frame is not replayable")
+ activeClient.send(message)
+ },
+ }
}
-// Frozen compatibility surface from the pre-change browser at f1090ebe. The
-// dispatcher may change internal batching, but these exact browser-v1 shapes
-// must remain consumable without a new wire event.
-const F1090EBE_TYPES = new Set([
- "community:message.create",
- "community:unread.bump",
- "community:mention.create",
- "community:channel.member_add",
- "community:channel.child_update",
-])
-
-export function frozenF1090ebeDecoderAccepts(frame: CapturedCommunityFrame): boolean {
- if (frame.contractVersion !== 1 || !F1090EBE_TYPES.has(frame.type)) return false
- if (frame.type === "community:message.create") {
- return typeof frame.channelId === "string"
- && typeof frame.message?.id === "string"
- && typeof frame.message.seq === "number"
- && typeof frame.message.content === "string"
- }
- if (frame.type === "community:unread.bump") {
- return typeof frame.channelId === "string"
- && typeof frame.userId === "string"
- && typeof frame.isMention === "boolean"
- }
- if (frame.type === "community:mention.create") {
- return typeof frame.channelId === "string"
- && typeof frame.messageId === "string"
- && typeof frame.userId === "string"
- }
- if (frame.type === "community:channel.member_add") {
- return typeof frame.channelId === "string"
- && typeof frame.serverId === "string"
- && typeof frame.userId === "string"
- }
- return typeof frame.channelId === "string"
- && typeof frame.parentChannelId === "string"
- && typeof frame.changes === "object"
- && frame.changes !== null
+export function communityFrameEvents(frame: CapturedCommunityFrame): CapturedCommunityFrame[] {
+ return frame.type === "community:events.batch" && Array.isArray(frame.events)
+ ? frame.events
+ : [frame]
}
diff --git a/src/ws-do/src/community-browser-event-ingress.test.ts b/src/ws-do/src/community-browser-event-ingress.test.ts
index 0053cf619..d3eadf95c 100644
--- a/src/ws-do/src/community-browser-event-ingress.test.ts
+++ b/src/ws-do/src/community-browser-event-ingress.test.ts
@@ -2,8 +2,10 @@ import { describe, expect, it, vi } from "vitest"
import {
COMMUNITY_BROWSER_EVENT_MAX_BYTES,
COMMUNITY_BULK_BODY_MAX_BYTES,
+ deriveCommunityDeliveryOperationId,
encodeCommunityBrowserEvent,
encodeCommunityUserTargetPathSegment,
+ prepareCommunityDeliveryEvents,
utf8ByteLength,
type CommunityBotAuditEvent,
type CommunityMessageCreate,
@@ -18,6 +20,7 @@ import {
logCommunityBrowserEventRejected,
normalizeCommunityBrowserEvent,
readBoundedJsonRequest,
+ readCommunityBrowserEventBundleRequest,
readCommunityBrowserEventRequest,
} from "./community-browser-event-ingress"
@@ -150,6 +153,38 @@ describe("community browser event ingress", () => {
.resolves.toMatchObject({ ok: false, reason: "oversized" })
})
+ it("strictly validates bundle operation metadata and independently recomputes its digest", async () => {
+ const events = [
+ communityWsEventFixtures["community:message.create"],
+ communityWsEventFixtures["community:unread.bump"],
+ ]
+ const prepared = await prepareCommunityDeliveryEvents(events)
+ if (!prepared.ok) throw new Error("bundle fixture must prepare")
+ const operationId = await deriveCommunityDeliveryOperationId("message-1")
+ const body = {
+ operationId,
+ operationDigest: prepared.prepared.digest,
+ events: prepared.prepared.envelopes,
+ }
+ await expect(readCommunityBrowserEventBundleRequest(requestFromBytes(JSON.stringify(body))))
+ .resolves.toMatchObject({
+ ok: true,
+ operationId,
+ operationDigest: prepared.prepared.digest,
+ eventCount: 2,
+ })
+ for (const invalid of [
+ { ...body, operationId: "message:short" },
+ { ...body, operationDigest: "A".repeat(64) },
+ { ...body, operationDigest: "0".repeat(64) },
+ { ...body, events: [...body.events, { type: "community:future", contractVersion: 1 }] },
+ { ...body, extra: true },
+ ]) {
+ await expect(readCommunityBrowserEventBundleRequest(requestFromBytes(JSON.stringify(invalid))))
+ .resolves.toMatchObject({ ok: false, reason: "invalid-payload" })
+ }
+ })
+
it("locks target decoding and the exact worst-case strict bulk boundary", async () => {
const uuid = "123e4567-e89b-12d3-a456-426614174000"
expect(decodeCommunityTargetPathSegment(encodeCommunityUserTargetPathSegment(uuid))).toEqual({ ok: true, target: uuid })
diff --git a/src/ws-do/src/community-browser-event-ingress.ts b/src/ws-do/src/community-browser-event-ingress.ts
index e863c08d3..633fa5d6d 100644
--- a/src/ws-do/src/community-browser-event-ingress.ts
+++ b/src/ws-do/src/community-browser-event-ingress.ts
@@ -5,9 +5,15 @@ import {
COMMUNITY_USER_TARGET_PATH_PREFIX,
decodeCommunityBrowserEvent,
encodeCommunityBrowserEvent,
+ isCommunityDeliveryDigest,
+ isCommunityDeliveryOperationId,
isValidCommunityUserTarget,
+ prepareCommunityDeliveryEvents,
type CommunityBrowserEventFailureReason,
type CommunityBrowserEventEnvelopeV1,
+ type CommunityDeliveryOperationId,
+ type CommunityDeliveryDigest,
+ type PreparedCommunityDeliveryEvents,
type CommunityWsEvent,
} from "@alook/shared"
@@ -124,7 +130,13 @@ export async function readCommunityBrowserEventRequest(
export async function readCommunityBrowserEventBundleRequest(
request: Request,
): Promise<
- | { ok: true; bodies: string[]; eventCount: number }
+ | {
+ ok: true
+ operationId: CommunityDeliveryOperationId
+ operationDigest: CommunityDeliveryDigest
+ prepared: PreparedCommunityDeliveryEvents
+ eventCount: number
+ }
| CommunityBrowserEventIngressFailure
> {
const parsed = await readBoundedJsonRequest(request, MESSAGE_DELIVERY_BODY_MAX_BYTES)
@@ -133,12 +145,25 @@ export async function readCommunityBrowserEventBundleRequest(
typeof parsed.value !== "object"
|| parsed.value === null
|| Array.isArray(parsed.value)
- || Object.keys(parsed.value).length !== 1
+ || Object.keys(parsed.value).length !== 3
+ || !Object.prototype.hasOwnProperty.call(parsed.value, "operationId")
+ || !Object.prototype.hasOwnProperty.call(parsed.value, "operationDigest")
|| !Object.prototype.hasOwnProperty.call(parsed.value, "events")
) {
return { ok: false, reason: "invalid-payload", type: "unknown", byteCount: parsed.byteCount }
}
- const events = (parsed.value as { events?: unknown }).events
+ const input = parsed.value as {
+ operationId?: unknown
+ operationDigest?: unknown
+ events?: unknown
+ }
+ if (
+ !isCommunityDeliveryOperationId(input.operationId)
+ || !isCommunityDeliveryDigest(input.operationDigest)
+ ) {
+ return { ok: false, reason: "invalid-payload", type: "unknown", byteCount: parsed.byteCount }
+ }
+ const events = input.events
if (
!Array.isArray(events)
|| events.length === 0
@@ -146,13 +171,16 @@ export async function readCommunityBrowserEventBundleRequest(
) {
return { ok: false, reason: "invalid-payload", type: "unknown", byteCount: parsed.byteCount }
}
- const normalized = events.map((event) => normalizeCommunityBrowserEvent(event))
- const failure = normalized.find((event) => !event.ok)
- if (failure && !failure.ok) return failure
+ const prepared = await prepareCommunityDeliveryEvents(events)
+ if (!prepared.ok || prepared.prepared.digest !== input.operationDigest) {
+ return { ok: false, reason: "invalid-payload", type: "unknown", byteCount: parsed.byteCount }
+ }
return {
ok: true,
- bodies: normalized.map((event) => (event as CommunityBrowserEventIngressSuccess).body),
- eventCount: normalized.length,
+ operationId: input.operationId,
+ operationDigest: input.operationDigest,
+ prepared: prepared.prepared,
+ eventCount: events.length,
}
}
diff --git a/src/ws-do/src/community-delivery-receipt.test.ts b/src/ws-do/src/community-delivery-receipt.test.ts
new file mode 100644
index 000000000..293c1be41
--- /dev/null
+++ b/src/ws-do/src/community-delivery-receipt.test.ts
@@ -0,0 +1,103 @@
+import { describe, expect, it } from "vitest"
+import { deriveCommunityDeliveryOperationId } from "@alook/shared"
+import {
+ createCommunityDeliveryReceipt,
+ isExactCommunityDeliveryReceipt,
+} from "./community-delivery-receipt"
+
+describe("community delivery receipt conservation", () => {
+ it("accepts only an exact complete receipt whose aggregates project from results", async () => {
+ const operationId = await deriveCommunityDeliveryOperationId("message-1")
+ const operationDigest = "a".repeat(64)
+ const receipt = createCommunityDeliveryReceipt({
+ status: "complete",
+ operationId,
+ operationDigest,
+ eventCount: 3,
+ results: [
+ {
+ socketIndex: 0,
+ outcome: "enqueued",
+ frameCount: 1,
+ persistedNextFrameIndex: 1,
+ ambiguousClosed: false,
+ },
+ {
+ socketIndex: 1,
+ outcome: "alreadyEnqueued",
+ frameCount: 1,
+ persistedNextFrameIndex: 1,
+ ambiguousClosed: false,
+ },
+ ],
+ })
+ const expected = { operationId, operationDigest, eventCount: 3 }
+ expect(isExactCommunityDeliveryReceipt(receipt, expected)).toBe(true)
+ expect(isExactCommunityDeliveryReceipt({ ...receipt, matched: 3 }, expected)).toBe(false)
+ expect(isExactCommunityDeliveryReceipt({ ...receipt, extra: true }, expected)).toBe(false)
+ expect(isExactCommunityDeliveryReceipt({
+ ...receipt,
+ results: [{ ...receipt.results[0], persistedNextFrameIndex: 0 }, receipt.results[1]],
+ }, expected)).toBe(false)
+ expect(isExactCommunityDeliveryReceipt({
+ ...receipt,
+ ambiguousClosed: 1,
+ results: [{ ...receipt.results[0], ambiguousClosed: true }, receipt.results[1]],
+ }, expected)).toBe(false)
+ expect(isExactCommunityDeliveryReceipt({
+ ...receipt,
+ results: [{
+ ...receipt.results[0],
+ frameCount: 2,
+ persistedNextFrameIndex: 2,
+ }, receipt.results[1]],
+ }, expected)).toBe(false)
+ expect(isExactCommunityDeliveryReceipt({
+ ...receipt,
+ partial: 1,
+ enqueued: 0,
+ results: [{
+ ...receipt.results[0],
+ outcome: "partial",
+ persistedNextFrameIndex: 0,
+ }, receipt.results[1]],
+ }, expected)).toBe(false)
+ expect(isExactCommunityDeliveryReceipt({
+ ...receipt,
+ alreadyEnqueued: 0,
+ partial: 1,
+ results: [receipt.results[0], {
+ ...receipt.results[1],
+ outcome: "partial",
+ persistedNextFrameIndex: receipt.results[1].frameCount,
+ }],
+ }, expected)).toBe(false)
+ expect(isExactCommunityDeliveryReceipt({
+ ...receipt,
+ alreadyEnqueued: 0,
+ }, expected)).toBe(false)
+ })
+
+ it("does not accept incomplete or ambiguous receipts as router success", async () => {
+ const operationId = await deriveCommunityDeliveryOperationId("message-1")
+ const operationDigest = "b".repeat(64)
+ const receipt = createCommunityDeliveryReceipt({
+ status: "incomplete",
+ operationId,
+ operationDigest,
+ eventCount: 1,
+ results: [{
+ socketIndex: 0,
+ outcome: "failed",
+ frameCount: 1,
+ persistedNextFrameIndex: 0,
+ ambiguousClosed: true,
+ }],
+ })
+ expect(isExactCommunityDeliveryReceipt(receipt, {
+ operationId,
+ operationDigest,
+ eventCount: 1,
+ })).toBe(false)
+ })
+})
diff --git a/src/ws-do/src/community-delivery-receipt.ts b/src/ws-do/src/community-delivery-receipt.ts
new file mode 100644
index 000000000..9bef1dcd1
--- /dev/null
+++ b/src/ws-do/src/community-delivery-receipt.ts
@@ -0,0 +1,207 @@
+import {
+ isCommunityDeliveryDigest,
+ isCommunityDeliveryOperationId,
+} from "@alook/shared"
+
+type CommunityDeliveryOutcome =
+ | "enqueued"
+ | "alreadyEnqueued"
+ | "preflightFailed"
+ | "notAttempted"
+ | "partial"
+ | "failed"
+
+export type CommunityDeliverySocketResult = {
+ socketIndex: number
+ outcome: CommunityDeliveryOutcome
+ frameCount: number
+ persistedNextFrameIndex: number
+ ambiguousClosed: boolean
+}
+
+export type CommunityDeliveryReceipt = {
+ status: "complete" | "incomplete"
+ validated: true
+ operationId: string
+ operationDigest: string
+ eventCount: number
+ matched: number
+ attempted: number
+ enqueued: number
+ alreadyEnqueued: number
+ preflightFailed: number
+ notAttempted: number
+ partial: number
+ failed: number
+ ambiguousClosed: number
+ results: CommunityDeliverySocketResult[]
+}
+
+const RECEIPT_KEYS = [
+ "status",
+ "validated",
+ "operationId",
+ "operationDigest",
+ "eventCount",
+ "matched",
+ "attempted",
+ "enqueued",
+ "alreadyEnqueued",
+ "preflightFailed",
+ "notAttempted",
+ "partial",
+ "failed",
+ "ambiguousClosed",
+ "results",
+] as const
+
+const RESULT_KEYS = [
+ "socketIndex",
+ "outcome",
+ "frameCount",
+ "persistedNextFrameIndex",
+ "ambiguousClosed",
+] as const
+
+const OUTCOMES: ReadonlySet<string> = new Set<CommunityDeliveryOutcome>([
+ "enqueued",
+ "alreadyEnqueued",
+ "preflightFailed",
+ "notAttempted",
+ "partial",
+ "failed",
+])
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function hasExactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+ const actual = Object.keys(value).sort()
+ const expected = [...keys].sort()
+ return actual.length === expected.length && actual.every((key, index) => key === expected[index])
+}
+
+function isNonNegativeInteger(value: unknown): value is number {
+ return Number.isSafeInteger(value) && (value as number) >= 0
+}
+
+export function createCommunityDeliveryReceipt(input: {
+ status: "complete" | "incomplete"
+ operationId: string
+ operationDigest: string
+ eventCount: number
+ results: CommunityDeliverySocketResult[]
+}): CommunityDeliveryReceipt {
+ const count = (outcome: CommunityDeliveryOutcome) =>
+ input.results.filter((result) => result.outcome === outcome).length
+ const partial = count("partial")
+ const failed = count("failed")
+ return {
+ status: input.status,
+ validated: true,
+ operationId: input.operationId,
+ operationDigest: input.operationDigest,
+ eventCount: input.eventCount,
+ matched: input.results.length,
+ attempted: count("enqueued") + partial + failed,
+ enqueued: count("enqueued"),
+ alreadyEnqueued: count("alreadyEnqueued"),
+ preflightFailed: count("preflightFailed"),
+ notAttempted: count("notAttempted"),
+ partial,
+ failed,
+ ambiguousClosed: input.results.filter((result) => result.ambiguousClosed).length,
+ results: input.results,
+ }
+}
+
+export function isExactCommunityDeliveryReceipt(
+ value: unknown,
+ expected: { operationId: string; operationDigest: string; eventCount: number },
+): value is CommunityDeliveryReceipt {
+ if (!isRecord(value) || !hasExactKeys(value, RECEIPT_KEYS)) return false
+ if (
+ value.status !== "complete"
+ || value.validated !== true
+ || value.operationId !== expected.operationId
+ || value.operationDigest !== expected.operationDigest
+ || value.eventCount !== expected.eventCount
+ || !isCommunityDeliveryOperationId(value.operationId)
+ || !isCommunityDeliveryDigest(value.operationDigest)
+ ) return false
+ const numericKeys = [
+ "matched",
+ "attempted",
+ "enqueued",
+ "alreadyEnqueued",
+ "preflightFailed",
+ "notAttempted",
+ "partial",
+ "failed",
+ "ambiguousClosed",
+ ] as const
+ if (numericKeys.some((key) => !isNonNegativeInteger(value[key]))) return false
+ if (!Array.isArray(value.results) || value.results.length !== value.matched) return false
+
+ const projected = {
+ enqueued: 0,
+ alreadyEnqueued: 0,
+ preflightFailed: 0,
+ notAttempted: 0,
+ partial: 0,
+ failed: 0,
+ ambiguousClosed: 0,
+ }
+ for (let index = 0; index < value.results.length; index += 1) {
+ const result = value.results[index]
+ if (!isRecord(result) || !hasExactKeys(result, RESULT_KEYS)) return false
+ if (
+ result.socketIndex !== index
+ || typeof result.outcome !== "string"
+ || !OUTCOMES.has(result.outcome)
+ || !isNonNegativeInteger(result.frameCount)
+ || result.frameCount !== 1
+ || !isNonNegativeInteger(result.persistedNextFrameIndex)
+ || result.persistedNextFrameIndex > result.frameCount
+ || typeof result.ambiguousClosed !== "boolean"
+ ) return false
+ if (result.outcome === "partial" && (
+ result.persistedNextFrameIndex <= 0
+ || result.persistedNextFrameIndex >= result.frameCount
+ )) return false
+ if (
+ (result.outcome === "enqueued" || result.outcome === "alreadyEnqueued")
+ && result.persistedNextFrameIndex !== result.frameCount
+ ) return false
+ if (
+ result.ambiguousClosed
+ && result.outcome !== "partial"
+ && result.outcome !== "failed"
+ ) return false
+ projected[result.outcome as CommunityDeliveryOutcome] += 1
+ if (result.ambiguousClosed) projected.ambiguousClosed += 1
+ }
+ if (
+ projected.enqueued !== value.enqueued
+ || projected.alreadyEnqueued !== value.alreadyEnqueued
+ || projected.preflightFailed !== value.preflightFailed
+ || projected.notAttempted !== value.notAttempted
+ || projected.partial !== value.partial
+ || projected.failed !== value.failed
+ || projected.ambiguousClosed !== value.ambiguousClosed
+ ) return false
+ return value.matched === value.enqueued
+ + value.alreadyEnqueued
+ + value.preflightFailed
+ + value.notAttempted
+ + value.partial
+ + value.failed
+ && value.attempted === value.enqueued + value.partial + value.failed
+ && value.ambiguousClosed <= value.partial + value.failed
+ && value.preflightFailed === 0
+ && value.notAttempted === 0
+ && value.partial === 0
+ && value.failed === 0
+ && value.ambiguousClosed === 0
+}
diff --git a/src/ws-do/src/internal-user-broadcast.ts b/src/ws-do/src/internal-user-broadcast.ts
index 371dfe418..2e707863e 100644
--- a/src/ws-do/src/internal-user-broadcast.ts
+++ b/src/ws-do/src/internal-user-broadcast.ts
@@ -43,6 +43,8 @@ export function createInternalCommunityUserBroadcastRequest(
export function createInternalCommunityUserBundleRequest(
targetUserId: string,
+ operationId: string,
+ operationDigest: string,
events: readonly unknown[],
): Request {
const headers = new Headers({
@@ -52,7 +54,7 @@ export function createInternalCommunityUserBundleRequest(
return new Request("http://internal/community-broadcast-bundle", {
method: "POST",
headers,
- body: JSON.stringify({ events }),
+ body: JSON.stringify({ operationId, operationDigest, events }),
})
}
diff --git a/src/ws-do/src/routes/message-delivery.test.ts b/src/ws-do/src/routes/message-delivery.test.ts
index a48169c05..b32bfb06d 100644
--- a/src/ws-do/src/routes/message-delivery.test.ts
+++ b/src/ws-do/src/routes/message-delivery.test.ts
@@ -1,4 +1,9 @@
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import {
+ COMMUNITY_DELIVERY_OPERATION_ID_HEADER,
+ deriveCommunityDeliveryOperationId,
+} from "@alook/shared"
+import { createCommunityDeliveryReceipt } from "../community-delivery-receipt"
import { INTERNAL_USER_TARGET_HEADER } from "../internal-user-broadcast"
import {
createRouterTestContext,
@@ -40,6 +45,33 @@ const batch = {
parentProjectionUserIds: ["overlap", "parent-only"],
}
+type InternalBundleBody = {
+ operationId: string
+ operationDigest: string
+ events: Array<{ type: string }>
+}
+
+async function successfulReceipt(request: Request): Promise<Response> {
+ const body = await request.clone().json() as InternalBundleBody
+ return Response.json(createCommunityDeliveryReceipt({
+ status: "complete",
+ operationId: body.operationId,
+ operationDigest: body.operationDigest,
+ eventCount: body.events.length,
+ results: [],
+ }))
+}
+
+async function deliveryRequest(value: typeof batch = batch): Promise<Request> {
+ return new Request("http://localhost/broadcast/community/message-delivery", {
+ method: "POST",
+ headers: {
+ [COMMUNITY_DELIVERY_OPERATION_ID_HEADER]: await deriveCommunityDeliveryOperationId(value.messageId),
+ },
+ body: JSON.stringify(value),
+ })
+}
+
describe("message delivery route", () => {
let handler: RouterHandler
let doMock: RouterTestContext["doMock"]
@@ -60,15 +92,9 @@ describe("message delivery route", () => {
})
it("inverts buckets into one ordered bundle per user", async () => {
- doMock.stubFetch.mockImplementation(async (request: Request) => {
- const body = await request.clone().json() as { events: unknown[] }
- return Response.json({ accepted: body.events.length })
- })
+ doMock.stubFetch.mockImplementation(successfulReceipt)
- const response = await handler.fetch(new Request(
- "http://localhost/broadcast/community/message-delivery",
- { method: "POST", body: JSON.stringify(batch) },
- ), env as never)
+ const response = await handler.fetch(await deliveryRequest(), env as never)
expect(response.status).toBe(200)
await expect(response.json()).resolves.toEqual({ failedUserIds: [] })
@@ -77,82 +103,192 @@ describe("message delivery route", () => {
const req = request as Request
return {
userId: decodeURIComponent(req.headers.get(INTERNAL_USER_TARGET_HEADER)!),
- types: ((await req.clone().json()) as { events: Array<{ type: string }> }).events.map((event) => event.type),
+ body: await req.clone().json() as InternalBundleBody,
}
}))
expect(calls).toContainEqual({
userId: "overlap",
- types: [
- "community:message.create",
- "community:unread.bump",
- "community:mention.create",
- "community:channel.child_update",
- ],
+ body: expect.objectContaining({
+ operationId: await deriveCommunityDeliveryOperationId("message-1"),
+ operationDigest: expect.stringMatching(/^[0-9a-f]{64}$/),
+ events: expect.arrayContaining([]),
+ }),
})
- expect(calls).toContainEqual({ userId: "mention-only", types: ["community:mention.create"] })
- expect(calls).toContainEqual({ userId: "parent-only", types: ["community:channel.child_update"] })
+ const byUser = new Map(calls.map((call) => [call.userId, call.body]))
+ expect(byUser.get("overlap")?.events.map((event) => event.type)).toEqual([
+ "community:message.create",
+ "community:unread.bump",
+ "community:mention.create",
+ "community:channel.child_update",
+ ])
+ expect(byUser.get("mention-only")?.events.map((event) => event.type)).toEqual(["community:mention.create"])
+ expect(byUser.get("parent-only")?.events.map((event) => event.type)).toEqual(["community:channel.child_update"])
+ expect(new Set(calls.map((call) => call.body.operationId))).toEqual(new Set([
+ await deriveCommunityDeliveryOperationId("message-1"),
+ ]))
+ expect(byUser.get("author")?.operationDigest).not.toBe(byUser.get("overlap")?.operationDigest)
})
it("returns an exact failed subset while healthy siblings complete", async () => {
doMock.stubFetch.mockImplementation(async (request: Request) => {
const userId = decodeURIComponent(request.headers.get(INTERNAL_USER_TARGET_HEADER)!)
if (userId === "overlap") return new Response("bad", { status: 502 })
- const body = await request.clone().json() as { events: unknown[] }
- return Response.json({ accepted: body.events.length })
+ return successfulReceipt(request)
})
- const response = await handler.fetch(new Request(
- "http://localhost/broadcast/community/message-delivery",
- { method: "POST", body: JSON.stringify(batch) },
- ), env as never)
+ const response = await handler.fetch(await deliveryRequest(), env as never)
expect(response.status).toBe(207)
await expect(response.json()).resolves.toEqual({ failedUserIds: ["overlap"] })
expect(doMock.stubFetch).toHaveBeenCalledTimes(4)
})
- it.each([
- ["throws", () => Promise.reject(new Error("DO unavailable"))],
- ["returns invalid JSON", () => Promise.resolve(new Response("not-json"))],
- ["returns an invalid receipt", () => Promise.resolve(Response.json({ accepted: -1 }))],
- ])("returns only the failed target when one user DO %s", async (_label, failedResponse) => {
+ it("keeps the operation ID and per-user digest stable after an accepted enqueue response is lost", async () => {
+ const overlapBodies: InternalBundleBody[] = []
+ let overlapAttempts = 0
doMock.stubFetch.mockImplementation(async (request: Request) => {
const userId = decodeURIComponent(request.headers.get(INTERNAL_USER_TARGET_HEADER)!)
- if (userId === "overlap") return failedResponse()
- const body = await request.clone().json() as { events: unknown[] }
- return Response.json({ accepted: body.events.length })
+ if (userId !== "overlap") return successfulReceipt(request)
+ const body = await request.clone().json() as InternalBundleBody
+ overlapBodies.push(body)
+ overlapAttempts += 1
+ if (overlapAttempts === 1) return new Response("")
+ return successfulReceipt(request)
})
- const response = await handler.fetch(new Request(
+ const first = await handler.fetch(await deliveryRequest(), env as never)
+ expect(first.status).toBe(207)
+ await expect(first.json()).resolves.toEqual({ failedUserIds: ["overlap"] })
+
+ const retryBatch = {
+ ...batch,
+ contentUserIds: ["overlap"],
+ unreadMentionUserIds: ["overlap"],
+ mentionUserIds: ["overlap"],
+ memberAdded: undefined,
+ parentProjectionUserIds: ["overlap"],
+ }
+ const retry = await handler.fetch(await deliveryRequest(retryBatch), env as never)
+ expect(retry.status).toBe(200)
+ expect(overlapBodies).toHaveLength(2)
+ expect(overlapBodies[1]).toEqual(overlapBodies[0])
+ })
+
+ it("accepts only the operation ID derived from the committed message", async () => {
+ doMock.stubFetch.mockImplementation(successfulReceipt)
+ const expected = await deriveCommunityDeliveryOperationId(batch.messageId)
+ const accepted = await handler.fetch(new Request(
"http://localhost/broadcast/community/message-delivery",
- { method: "POST", body: JSON.stringify(batch) },
+ {
+ method: "POST",
+ headers: { [COMMUNITY_DELIVERY_OPERATION_ID_HEADER]: expected },
+ body: JSON.stringify(batch),
+ },
), env as never)
+ expect(accepted.status).toBe(200)
- expect(response.status).toBe(207)
- await expect(response.json()).resolves.toEqual({ failedUserIds: ["overlap"] })
- expect(doMock.stubFetch).toHaveBeenCalledTimes(4)
+ doMock.stubFetch.mockClear()
+ const mismatch = await handler.fetch(new Request(
+ "http://localhost/broadcast/community/message-delivery",
+ {
+ method: "POST",
+ headers: {
+ [COMMUNITY_DELIVERY_OPERATION_ID_HEADER]: await deriveCommunityDeliveryOperationId("other-message"),
+ },
+ body: JSON.stringify(batch),
+ },
+ ), env as never)
+ expect(mismatch.status).toBe(400)
+ expect(doMock.stubFetch).not.toHaveBeenCalled()
+
+ const missing = await handler.fetch(new Request(
+ "http://localhost/broadcast/community/message-delivery",
+ { method: "POST", body: JSON.stringify(batch) },
+ ), env as never)
+ expect(missing.status).toBe(400)
+ await expect(missing.json()).resolves.toMatchObject({ reason: "operation-id-mismatch" })
})
- it("delivers the maximum 1,000 distinct targets exactly once", async () => {
- const userIds = Array.from({ length: 1_000 }, (_, index) => `user-${index}`)
- doMock.stubFetch.mockImplementation(async () => Response.json({ accepted: 1 }))
+ it("rejects a committed message ID that cannot produce an operation ID", async () => {
+ const invalidMessageId = "\ud800"
const response = await handler.fetch(new Request(
"http://localhost/broadcast/community/message-delivery",
{
method: "POST",
body: JSON.stringify({
...batch,
- contentUserIds: userIds,
- unreadPlainUserIds: [],
- unreadMentionUserIds: [],
- mentionUserIds: [],
- memberAdded: undefined,
- parentProjection: undefined,
- parentProjectionUserIds: undefined,
+ messageId: invalidMessageId,
+ messageEvent: {
+ ...batch.messageEvent,
+ message: { ...batch.messageEvent.message, id: invalidMessageId },
+ },
}),
},
), env as never)
+ expect(response.status).toBe(400)
+ await expect(response.json()).resolves.toMatchObject({ reason: "invalid-message-id" })
+ expect(doMock.stubFetch).not.toHaveBeenCalled()
+ })
+
+ it.each([
+ ["throws", () => Promise.reject(new Error("DO unavailable"))],
+ ["returns invalid JSON", () => Promise.resolve(new Response("not-json"))],
+ ["returns an invalid receipt", () => Promise.resolve(Response.json({ accepted: -1 }))],
+ ])("returns only the failed target when one user DO %s", async (_label, failedResponse) => {
+ doMock.stubFetch.mockImplementation(async (request: Request) => {
+ const userId = decodeURIComponent(request.headers.get(INTERNAL_USER_TARGET_HEADER)!)
+ if (userId === "overlap") return failedResponse()
+ return successfulReceipt(request)
+ })
+
+ const response = await handler.fetch(await deliveryRequest(), env as never)
+
+ expect(response.status).toBe(207)
+ await expect(response.json()).resolves.toEqual({ failedUserIds: ["overlap"] })
+ expect(doMock.stubFetch).toHaveBeenCalledTimes(4)
+ })
+
+ it("classifies a complete receipt with frameCount=2 as invalid and returns the target in 207", async () => {
+ const frameCount = 2
+ doMock.stubFetch.mockImplementation(async (request: Request) => {
+ const userId = decodeURIComponent(request.headers.get(INTERNAL_USER_TARGET_HEADER)!)
+ if (userId !== "overlap") return successfulReceipt(request)
+ const body = await request.clone().json() as InternalBundleBody
+ return Response.json(createCommunityDeliveryReceipt({
+ status: "complete",
+ operationId: body.operationId,
+ operationDigest: body.operationDigest,
+ eventCount: body.events.length,
+ results: [{
+ socketIndex: 0,
+ outcome: "enqueued",
+ frameCount,
+ persistedNextFrameIndex: frameCount,
+ ambiguousClosed: false,
+ }],
+ }))
+ })
+
+ const response = await handler.fetch(await deliveryRequest(), env as never)
+ expect(response.status).toBe(207)
+ await expect(response.json()).resolves.toEqual({ failedUserIds: ["overlap"] })
+ })
+
+ it("delivers the maximum 1,000 distinct targets exactly once", async () => {
+ const userIds = Array.from({ length: 1_000 }, (_, index) => `user-${index}`)
+ doMock.stubFetch.mockImplementation(successfulReceipt)
+ const response = await handler.fetch(await deliveryRequest({
+ ...batch,
+ contentUserIds: userIds,
+ unreadPlainUserIds: [],
+ unreadMentionUserIds: [],
+ mentionUserIds: [],
+ memberAdded: undefined,
+ parentProjection: undefined,
+ parentProjectionUserIds: undefined,
+ }), env as never)
+
expect(response.status).toBe(200)
await expect(response.json()).resolves.toEqual({ failedUserIds: [] })
expect(doMock.stubFetch).toHaveBeenCalledTimes(1_000)
diff --git a/src/ws-do/src/routes/message-delivery.ts b/src/ws-do/src/routes/message-delivery.ts
index b2d088979..f57a90acb 100644
--- a/src/ws-do/src/routes/message-delivery.ts
+++ b/src/ws-do/src/routes/message-delivery.ts
@@ -1,11 +1,16 @@
import {
+ COMMUNITY_DELIVERY_OPERATION_ID_HEADER,
MESSAGE_DELIVERY_BODY_MAX_BYTES,
WS_EVENTS,
- encodeCommunityBrowserEvent,
+ deriveCommunityDeliveryOperationId,
+ isCommunityDeliveryOperationId,
parseMessageDeliveryBatch,
+ prepareCommunityDeliveryEvents,
+ type CommunityDeliveryOperationId,
type CommunityWsEvent,
} from "@alook/shared"
import { readBoundedJsonRequest } from "../community-browser-event-ingress"
+import { isExactCommunityDeliveryReceipt } from "../community-delivery-receipt"
import { createInternalCommunityUserBundleRequest } from "../internal-user-broadcast"
import type { RouterContext } from "../router-context"
import { settleInBatches } from "../settle-in-batches"
@@ -16,10 +21,6 @@ type TargetResult =
| { ok: true }
| { ok: false; kind: "throw" | "non-ok" | "invalid-json" | "invalid-receipt" }
-function isRecord(value: unknown): value is Record<string, unknown> {
- return typeof value === "object" && value !== null && !Array.isArray(value)
-}
-
function addEvent(
bundles: Map<string, CommunityWsEvent[]>,
userId: string,
@@ -34,17 +35,19 @@ async function deliverTarget(
env: Env,
userId: string,
events: CommunityWsEvent[],
+ operationId: CommunityDeliveryOperationId,
): Promise<TargetResult> {
- const envelopes: unknown[] = []
- for (const event of events) {
- const encoded = encodeCommunityBrowserEvent(event)
- if (!encoded.ok) return { ok: false, kind: "invalid-receipt" }
- envelopes.push(encoded.event)
- }
+ const prepared = await prepareCommunityDeliveryEvents(events)
+ if (!prepared.ok) return { ok: false, kind: "invalid-receipt" }
try {
const id = env.WS_DO.idFromName(`user:${userId}`)
const response = await env.WS_DO.get(id).fetch(
- createInternalCommunityUserBundleRequest(userId, envelopes),
+ createInternalCommunityUserBundleRequest(
+ userId,
+ operationId,
+ prepared.prepared.digest,
+ prepared.prepared.envelopes,
+ ),
)
if (!response.ok) return { ok: false, kind: "non-ok" }
let receipt: unknown
@@ -53,11 +56,11 @@ async function deliverTarget(
} catch {
return { ok: false, kind: "invalid-json" }
}
- if (
- !isRecord(receipt)
- || Object.keys(receipt).length !== 1
- || receipt.accepted !== events.length
- ) {
+ if (!isExactCommunityDeliveryReceipt(receipt, {
+ operationId,
+ operationDigest: prepared.prepared.digest,
+ eventCount: events.length,
+ })) {
return { ok: false, kind: "invalid-receipt" }
}
return { ok: true }
@@ -81,6 +84,20 @@ export async function handleMessageDelivery(
return Response.json({ error: "invalid message delivery", reason: parsed.reason }, { status: 400 })
}
const batch = parsed.batch
+ let derivedOperationId: CommunityDeliveryOperationId
+ try {
+ derivedOperationId = await deriveCommunityDeliveryOperationId(batch.messageId)
+ } catch {
+ return Response.json({ error: "invalid message delivery", reason: "invalid-message-id" }, { status: 400 })
+ }
+ const headerOperationId = request.headers.get(COMMUNITY_DELIVERY_OPERATION_ID_HEADER)?.trim()
+ if (
+ !isCommunityDeliveryOperationId(headerOperationId)
+ || headerOperationId !== derivedOperationId
+ ) {
+ return Response.json({ error: "invalid message delivery", reason: "operation-id-mismatch" }, { status: 400 })
+ }
+ const operationId = headerOperationId
const bundles = new Map<string, CommunityWsEvent[]>()
for (const userId of batch.contentUserIds) addEvent(bundles, userId, batch.messageEvent)
@@ -133,7 +150,7 @@ export async function handleMessageDelivery(
const startedAt = Date.now()
const results = await settleInBatches(
entries,
- ([userId, events]) => deliverTarget(env, userId, events),
+ ([userId, events]) => deliverTarget(env, userId, events, operationId),
targetBatchSize,
)
const failedUserIds: string[] = []
@@ -151,6 +168,7 @@ export async function handleMessageDelivery(
log.info("message_delivery_complete", {
traceId,
messageId: batch.messageId,
+ operationId,
targetCount: entries.length,
failedCount: failedUserIds.length,
failureCounts,
diff --git a/src/ws-do/src/ws-durable/community-delivery-state.test.ts b/src/ws-do/src/ws-durable/community-delivery-state.test.ts
new file mode 100644
index 000000000..4910bf104
--- /dev/null
+++ b/src/ws-do/src/ws-durable/community-delivery-state.test.ts
@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest"
+import { deriveCommunityDeliveryOperationId } from "@alook/shared"
+import {
+ preflightCommunityConnectionState,
+ readCommunityDeliveryProgress,
+ withCommunityDeliveryProgress,
+} from "./community-delivery-state"
+import {
+ COMMUNITY_CONNECTION_STATE_JSON_MAX_BYTES,
+ COMMUNITY_DELIVERY_PROGRESS_LIMIT,
+ type UserConnectionState,
+} from "./internal"
+
+describe("community delivery connection attachment state", () => {
+ it("keeps 64 compact entries under the application budget and evicts the oldest at 65", async () => {
+ let state: UserConnectionState = {
+ type: "user",
+ userId: "u".repeat(64),
+ targetUserId: "t".repeat(64),
+ authenticated: true,
+ name: "n".repeat(128),
+ discriminator: "1234",
+ }
+ const operationIds: string[] = []
+ for (let index = 0; index < COMMUNITY_DELIVERY_PROGRESS_LIMIT; index += 1) {
+ const operationId = await deriveCommunityDeliveryOperationId(`message-${index}`)
+ operationIds.push(operationId)
+ state = withCommunityDeliveryProgress(state, {
+ operationId,
+ operationDigest: index.toString(16).padStart(64, "0"),
+ nextFrameIndex: 1,
+ frameCount: 1,
+ })
+ }
+ const preflight = preflightCommunityConnectionState(state)
+ expect(preflight).toMatchObject({ ok: true })
+ if (preflight.ok) expect(preflight.jsonByteLength).toBeLessThan(COMMUNITY_CONNECTION_STATE_JSON_MAX_BYTES)
+ expect(readCommunityDeliveryProgress(state)).toMatchObject({
+ ok: true,
+ entries: expect.arrayContaining([
+ expect.objectContaining({ operationId: operationIds[0] }),
+ expect.objectContaining({ operationId: operationIds[63] }),
+ ]),
+ })
+
+ const sixtyFifth = await deriveCommunityDeliveryOperationId("message-64")
+ state = withCommunityDeliveryProgress(state, {
+ operationId: sixtyFifth,
+ operationDigest: "f".repeat(64),
+ nextFrameIndex: 1,
+ frameCount: 1,
+ })
+ const decoded = readCommunityDeliveryProgress(state)
+ expect(decoded.ok).toBe(true)
+ if (!decoded.ok) return
+ expect(decoded.entries).toHaveLength(COMMUNITY_DELIVERY_PROGRESS_LIMIT)
+ expect(decoded.entries[0].operationId).toBe(operationIds[1])
+ expect(decoded.entries.at(-1)?.operationId).toBe(sixtyFifth)
+ expect(preflightCommunityConnectionState(state)).toMatchObject({ ok: true })
+ })
+
+ it("fails closed for malformed, duplicate, non-cloneable, and over-budget states", async () => {
+ const operationId = await deriveCommunityDeliveryOperationId("message-1")
+ const base: UserConnectionState = {
+ type: "user",
+ userId: "user-1",
+ authenticated: true,
+ communityDeliveryProgress: [[operationId, "a".repeat(64), 1, 1]],
+ }
+ expect(preflightCommunityConnectionState({
+ ...base,
+ communityDeliveryProgress: [
+ ...base.communityDeliveryProgress!,
+ ...base.communityDeliveryProgress!,
+ ],
+ })).toMatchObject({ ok: false, reason: "invalid-progress" })
+ expect(readCommunityDeliveryProgress({
+ ...base,
+ communityDeliveryProgress: Array.from(
+ { length: COMMUNITY_DELIVERY_PROGRESS_LIMIT + 1 },
+ () => base.communityDeliveryProgress![0],
+ ),
+ })).toEqual({ ok: false })
+ expect(preflightCommunityConnectionState({
+ ...base,
+ name: "x".repeat(COMMUNITY_CONNECTION_STATE_JSON_MAX_BYTES),
+ })).toMatchObject({ ok: false, reason: "json-budget" })
+ expect(preflightCommunityConnectionState({
+ ...base,
+ name: (() => "not cloneable") as unknown as string,
+ })).toMatchObject({ ok: false, reason: "not-cloneable" })
+ })
+})
diff --git a/src/ws-do/src/ws-durable/community-delivery-state.ts b/src/ws-do/src/ws-durable/community-delivery-state.ts
new file mode 100644
index 000000000..1ecc729dd
--- /dev/null
+++ b/src/ws-do/src/ws-durable/community-delivery-state.ts
@@ -0,0 +1,100 @@
+import {
+ isCommunityDeliveryDigest,
+ isCommunityDeliveryOperationId,
+ utf8ByteLength,
+} from "@alook/shared"
+import {
+ COMMUNITY_CONNECTION_STATE_JSON_MAX_BYTES,
+ COMMUNITY_DELIVERY_PROGRESS_LIMIT,
+ type CompactCommunityDeliveryProgress,
+ type UserConnectionState,
+} from "./internal"
+export type CommunityDeliveryProgress = {
+ operationId: string
+ operationDigest: string
+ nextFrameIndex: number
+ frameCount: number
+}
+
+export type CommunityConnectionStatePreflight =
+ | { ok: true; jsonByteLength: number }
+ | { ok: false; reason: "invalid-progress" | "not-cloneable" | "json-budget"; jsonByteLength?: number }
+
+function isSafeIndex(value: unknown): value is number {
+ return Number.isSafeInteger(value) && (value as number) >= 0
+}
+
+function decodeProgressEntry(value: unknown): CommunityDeliveryProgress | null {
+ if (!Array.isArray(value) || value.length !== 4) return null
+ const [operationId, operationDigest, nextFrameIndex, frameCount] = value
+ if (
+ !isCommunityDeliveryOperationId(operationId)
+ || !isCommunityDeliveryDigest(operationDigest)
+ || !isSafeIndex(nextFrameIndex)
+ || !isSafeIndex(frameCount)
+ || frameCount < 1
+ || nextFrameIndex > frameCount
+ ) return null
+ return {
+ operationId,
+ operationDigest,
+ nextFrameIndex,
+ frameCount,
+ }
+}
+
+function encodeProgressEntry(value: CommunityDeliveryProgress): CompactCommunityDeliveryProgress {
+ return [
+ value.operationId,
+ value.operationDigest,
+ value.nextFrameIndex,
+ value.frameCount,
+ ]
+}
+
+export function readCommunityDeliveryProgress(
+ state: UserConnectionState,
+): { ok: true; entries: CommunityDeliveryProgress[] } | { ok: false } {
+ if (state.communityDeliveryProgress === undefined) return { ok: true, entries: [] }
+ if (
+ !Array.isArray(state.communityDeliveryProgress)
+ || state.communityDeliveryProgress.length > COMMUNITY_DELIVERY_PROGRESS_LIMIT
+ ) return { ok: false }
+ const entries: CommunityDeliveryProgress[] = []
+ const operationIds = new Set<string>()
+ for (const raw of state.communityDeliveryProgress) {
+ const entry = decodeProgressEntry(raw)
+ if (!entry || operationIds.has(entry.operationId)) return { ok: false }
+ operationIds.add(entry.operationId)
+ entries.push(entry)
+ }
+ return { ok: true, entries }
+}
+
+export function withCommunityDeliveryProgress(
+ state: UserConnectionState,
+ entry: CommunityDeliveryProgress,
+): UserConnectionState {
+ const decoded = readCommunityDeliveryProgress(state)
+ if (!decoded.ok) throw new Error("invalid community delivery progress attachment")
+ const next = decoded.entries.filter((candidate) => candidate.operationId !== entry.operationId)
+ next.push(entry)
+ const bounded = next.slice(-COMMUNITY_DELIVERY_PROGRESS_LIMIT).map(encodeProgressEntry)
+ return { ...state, communityDeliveryProgress: bounded }
+}
+
+export function preflightCommunityConnectionState(
+ state: UserConnectionState,
+): CommunityConnectionStatePreflight {
+ if (!readCommunityDeliveryProgress(state).ok) return { ok: false, reason: "invalid-progress" }
+ try {
+ structuredClone(state)
+ } catch {
+ return { ok: false, reason: "not-cloneable" }
+ }
+ const jsonByteLength = utf8ByteLength(JSON.stringify(state))
+ if (jsonByteLength > COMMUNITY_CONNECTION_STATE_JSON_MAX_BYTES) {
+ return { ok: false, reason: "json-budget", jsonByteLength }
+ }
+ return { ok: true, jsonByteLength }
+}
diff --git a/src/ws-do/src/ws-durable/internal.ts b/src/ws-do/src/ws-durable/internal.ts
index bd861ba1e..3c037dd5d 100644
--- a/src/ws-do/src/ws-durable/internal.ts
+++ b/src/ws-do/src/ws-durable/internal.ts
@@ -1,5 +1,15 @@
import type { Logger } from "@alook/shared"
+export const COMMUNITY_DELIVERY_PROGRESS_LIMIT = 64
+export const COMMUNITY_CONNECTION_STATE_JSON_MAX_BYTES = 12 * 1024
+
+export type CompactCommunityDeliveryProgress = [
+ operationId: string,
+ operationDigest: string,
+ nextFrameIndex: number,
+ frameCount: number,
+]
+
export type ConnectionState =
| {
type: "user"
@@ -8,6 +18,7 @@ export type ConnectionState =
authenticated: boolean
name?: string
discriminator?: string
+ communityDeliveryProgress?: CompactCommunityDeliveryProgress[]
}
| { type: "daemon"; daemonId: string; userId: string; authenticated: boolean }
| {
diff --git a/src/ws-do/src/ws-durable/test-harness.ts b/src/ws-do/src/ws-durable/test-harness.ts
index c8c7bc646..521479990 100644
--- a/src/ws-do/src/ws-durable/test-harness.ts
+++ b/src/ws-do/src/ws-durable/test-harness.ts
@@ -7,6 +7,11 @@ const loggerMocks = vi.hoisted(() => ({
mockLogWarn: vi.fn(),
mockLogError: vi.fn(),
}))
+const deliveryTransportMocks = vi.hoisted(() => ({
+ encodePreparedCommunityBrowserEventBatch: vi.fn(),
+}))
+export const mockEncodePreparedCommunityBrowserEventBatch =
+ deliveryTransportMocks.encodePreparedCommunityBrowserEventBatch
export const mockLogDebug = loggerMocks.mockLogDebug
const mockLogInfo = loggerMocks.mockLogInfo
export const mockLogWarn = loggerMocks.mockLogWarn
@@ -149,6 +154,10 @@ export const mockToSummary = vi.fn((row: any) => ({
vi.mock("@alook/shared", async () => {
const actual = await vi.importActual<typeof import("@alook/shared")>("@alook/shared")
+ mockEncodePreparedCommunityBrowserEventBatch.mockImplementation(
+ (input: Parameters<typeof actual.encodePreparedCommunityBrowserEventBatch>[0]) =>
+ actual.encodePreparedCommunityBrowserEventBatch(input),
+ )
const noopLogger = {
debug: mockLogDebug,
info: mockLogInfo,
@@ -299,6 +308,9 @@ vi.mock("@alook/shared", async () => {
}
return {
...actual,
+ encodePreparedCommunityBrowserEventBatch: (
+ input: Parameters<typeof actual.encodePreparedCommunityBrowserEventBatch>[0],
+ ) => mockEncodePreparedCommunityBrowserEventBatch(input),
// Real WS event-type strings the DO reads at runtime (#5 T2 — ws-do
// broadcasts now use WS_EVENTS.* instead of raw literals). Values match
// @alook/shared so the event assertions still hold.
diff --git a/src/ws-do/src/ws-durable/user-auth.test.ts b/src/ws-do/src/ws-durable/user-auth.test.ts
index e28771fef..0b0ee920e 100644
--- a/src/ws-do/src/ws-durable/user-auth.test.ts
+++ b/src/ws-do/src/ws-durable/user-auth.test.ts
@@ -1,7 +1,13 @@
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import {
+ deriveCommunityDeliveryOperationId,
+ prepareCommunityDeliveryEvents,
+} from "@alook/shared"
import { createMockWebSocket } from "../__mocks__/cf"
import { handleUpgrade } from "../routes/upgrade"
import { INTERNAL_USER_TARGET_HEADER } from "../internal-user-broadcast"
+import type { CommunityDeliveryReceipt } from "../community-delivery-receipt"
+import { COMMUNITY_CONNECTION_STATE_JSON_MAX_BYTES } from "./internal"
import {
CFResponse,
cleanupHarness,
@@ -9,6 +15,7 @@ import {
flushAsyncWork,
mockCheckAliveFetch,
mockCreateDb,
+ mockEncodePreparedCommunityBrowserEventBatch,
mockFindCredentialByHash,
mockGetBotBinding,
mockGetBotBindingWithOwner,
@@ -143,28 +150,77 @@ describe("WebSocketDurableObject", () => {
},
]
- it("validates all events before sending them in order to every target tab", async () => {
+ async function requestFor(
+ inputEvents: readonly unknown[] = events,
+ overrides: { operationId?: string; operationDigest?: string } = {},
+ ): Promise<Request> {
+ const prepared = await prepareCommunityDeliveryEvents(inputEvents)
+ if (!prepared.ok) throw new Error(`invalid fixture: ${prepared.reason}`)
+ return new Request("http://internal/community-broadcast-bundle", {
+ method: "POST",
+ headers: { [INTERNAL_USER_TARGET_HEADER]: encodeURIComponent("user-42") },
+ body: JSON.stringify({
+ operationId: overrides.operationId ?? await deriveCommunityDeliveryOperationId("m-1"),
+ operationDigest: overrides.operationDigest ?? prepared.prepared.digest,
+ events: prepared.prepared.envelopes,
+ }),
+ })
+ }
+
+ it("rejects an invalid internal target before decoding the bundle", async () => {
+ const { durable } = createDO()
+ const response = await durable.fetch(new Request(
+ "http://internal/community-broadcast-bundle",
+ { method: "POST", body: "{}" },
+ ))
+
+ expect(response.status).toBe(400)
+ await expect(response.json()).resolves.toMatchObject({
+ status: "invalid",
+ operationId: null,
+ code: "invalid_request",
+ })
+ })
+
+ it("sends one batch frame to every authenticated tab", async () => {
const { durable, ctx } = createDO()
const first = createMockWebSocket()
const second = createMockWebSocket()
- first.serializeAttachment({ type: "user", userId: "user-42", authenticated: true })
+ first.serializeAttachment({
+ type: "user",
+ userId: "user-42",
+ authenticated: true,
+ })
second.serializeAttachment({ type: "user", userId: "user-42", authenticated: true })
;(ctx.getWebSockets as ReturnType<typeof vi.fn>).mockReturnValue([first, second])
- const response = await durable.fetch(new Request("http://internal/community-broadcast-bundle", {
- method: "POST",
- headers: { [INTERNAL_USER_TARGET_HEADER]: encodeURIComponent("user-42") },
- body: JSON.stringify({ events }),
- }))
+ const response = await durable.fetch(await requestFor())
expect(response.status).toBe(200)
- await expect(response.json()).resolves.toEqual({ accepted: 3 })
- expect(first.send.mock.calls.map(([body]) => JSON.parse(body as string).type)).toEqual([
- "community:message.create",
- "community:unread.bump",
- "community:mention.create",
- ])
- expect(second.send).toHaveBeenCalledTimes(3)
+ const receipt = await response.json() as CommunityDeliveryReceipt
+ expect(receipt).toMatchObject({
+ status: "complete",
+ eventCount: 3,
+ matched: 2,
+ attempted: 2,
+ enqueued: 2,
+ })
+ expect(first.send).toHaveBeenCalledTimes(1)
+ expect(JSON.parse(first.send.mock.calls[0][0] as string)).toMatchObject({
+ type: "community:events.batch",
+ events: expect.any(Array),
+ })
+ expect(second.send).toHaveBeenCalledTimes(1)
+ expect(JSON.parse(second.send.mock.calls[0][0] as string)).toMatchObject({
+ type: "community:events.batch",
+ events: expect.any(Array),
+ })
+ expect(first.deserializeAttachment()).toMatchObject({
+ communityDeliveryProgress: [[expect.any(String), expect.any(String), 1, 1]],
+ })
+ expect(second.deserializeAttachment()).toMatchObject({
+ communityDeliveryProgress: [[expect.any(String), expect.any(String), 1, 1]],
+ })
})
it("sends zero frames when any event is invalid", async () => {
@@ -172,17 +228,259 @@ describe("WebSocketDurableObject", () => {
const ws = createMockWebSocket()
ws.serializeAttachment({ type: "user", userId: "user-42", authenticated: true })
;(ctx.getWebSockets as ReturnType<typeof vi.fn>).mockReturnValue([ws])
- const invalid = [...events, { type: "community:unknown", contractVersion: 1 }]
-
+ const prepared = await prepareCommunityDeliveryEvents(events)
+ if (!prepared.ok) throw new Error("fixture must prepare")
const response = await durable.fetch(new Request("http://internal/community-broadcast-bundle", {
method: "POST",
headers: { [INTERNAL_USER_TARGET_HEADER]: encodeURIComponent("user-42") },
- body: JSON.stringify({ events: invalid }),
+ body: JSON.stringify({
+ operationId: await deriveCommunityDeliveryOperationId("m-1"),
+ operationDigest: prepared.prepared.digest,
+ events: [...prepared.prepared.envelopes, { type: "community:unknown", contractVersion: 1 }],
+ }),
}))
expect(response.status).toBe(400)
expect(ws.send).not.toHaveBeenCalled()
})
+
+ it("suppresses a completed same-digest retry and rejects same-ID/different-digest before sends", async () => {
+ const { durable, ctx } = createDO()
+ const ws = createMockWebSocket()
+ ws.serializeAttachment({
+ type: "user",
+ userId: "user-42",
+ authenticated: true,
+ })
+ ;(ctx.getWebSockets as ReturnType<typeof vi.fn>).mockReturnValue([ws])
+
+ expect((await durable.fetch(await requestFor())).status).toBe(200)
+ expect(ws.send).toHaveBeenCalledTimes(1)
+ const retry = await durable.fetch(await requestFor())
+ expect(retry.status).toBe(200)
+ await expect(retry.json()).resolves.toMatchObject({
+ enqueued: 0,
+ alreadyEnqueued: 1,
+ attempted: 0,
+ })
+ expect(ws.send).toHaveBeenCalledTimes(1)
+
+ const conflict = await durable.fetch(await requestFor(events.slice(0, 2)))
+ expect(conflict.status).toBe(409)
+ expect(ws.send).toHaveBeenCalledTimes(1)
+ })
+
+ it("records a successful tab, reports a sibling batch send failure, and retries only the sibling", async () => {
+ const { durable, ctx } = createDO()
+ const first = createMockWebSocket()
+ first.serializeAttachment({ type: "user", userId: "user-42", authenticated: true })
+ const second = createMockWebSocket()
+ second.serializeAttachment({ type: "user", userId: "user-42", authenticated: true })
+ second.send.mockImplementationOnce(() => { throw new Error("send failed") })
+ ;(ctx.getWebSockets as ReturnType<typeof vi.fn>).mockReturnValue([first, second])
+
+ const response = await durable.fetch(await requestFor())
+ expect(response.status).toBe(503)
+ await expect(response.json()).resolves.toMatchObject({
+ attempted: 2,
+ enqueued: 1,
+ failed: 1,
+ partial: 0,
+ results: [
+ { socketIndex: 0, outcome: "enqueued", persistedNextFrameIndex: 1, frameCount: 1 },
+ { socketIndex: 1, outcome: "failed", persistedNextFrameIndex: 0, frameCount: 1 },
+ ],
+ })
+
+ first.send.mockClear()
+ second.send.mockReset()
+ const retry = await durable.fetch(await requestFor())
+ expect(retry.status).toBe(200)
+ await expect(retry.json()).resolves.toMatchObject({ attempted: 1, enqueued: 1, alreadyEnqueued: 1 })
+ expect(first.send).not.toHaveBeenCalled()
+ expect(second.send).toHaveBeenCalledTimes(1)
+ expect(JSON.parse(second.send.mock.calls[0][0] as string).type).toBe("community:events.batch")
+ })
+
+ it("aborts phase A for every socket when one attachment preflight fails", async () => {
+ const { durable, ctx } = createDO()
+ const ready = createMockWebSocket()
+ ready.serializeAttachment({
+ type: "user",
+ userId: "user-42",
+ authenticated: true,
+ })
+ const malformed = createMockWebSocket()
+ malformed.serializeAttachment({
+ type: "user",
+ userId: "user-42",
+ authenticated: true,
+ communityDeliveryProgress: [["not-an-operation-id", "a".repeat(64), 0, 1]],
+ })
+ ;(ctx.getWebSockets as ReturnType<typeof vi.fn>).mockReturnValue([ready, malformed])
+
+ const response = await durable.fetch(await requestFor())
+ expect(response.status).toBe(503)
+ await expect(response.json()).resolves.toMatchObject({
+ attempted: 0,
+ enqueued: 0,
+ preflightFailed: 1,
+ notAttempted: 1,
+ partial: 0,
+ failed: 0,
+ ambiguousClosed: 0,
+ results: [
+ { socketIndex: 0, outcome: "notAttempted" },
+ { socketIndex: 1, outcome: "preflightFailed" },
+ ],
+ })
+ expect(ready.send).not.toHaveBeenCalled()
+ expect(malformed.send).not.toHaveBeenCalled()
+ })
+
+ it("fails phase A when stored frame metadata conflicts with the fixed batch frame", async () => {
+ const { durable, ctx } = createDO()
+ const ws = createMockWebSocket()
+ const operationId = await deriveCommunityDeliveryOperationId("m-1")
+ const prepared = await prepareCommunityDeliveryEvents(events)
+ if (!prepared.ok) throw new Error("fixture must prepare")
+ ws.serializeAttachment({
+ type: "user",
+ userId: "user-42",
+ authenticated: true,
+ communityDeliveryProgress: [[operationId, prepared.prepared.digest, 0, 3]],
+ })
+ ;(ctx.getWebSockets as ReturnType<typeof vi.fn>).mockReturnValue([ws])
+
+ const response = await durable.fetch(await requestFor())
+
+ expect(response.status).toBe(503)
+ await expect(response.json()).resolves.toMatchObject({
+ preflightFailed: 1,
+ results: [{ outcome: "preflightFailed" }],
+ })
+ expect(ws.send).not.toHaveBeenCalled()
+ })
+
+ it("fails phase A when progress state becomes malformed during candidate construction", async () => {
+ const { durable, ctx } = createDO()
+ const ws = createMockWebSocket()
+ let progressReads = 0
+ const state = {
+ type: "user" as const,
+ userId: "user-42",
+ authenticated: true,
+ get communityDeliveryProgress() {
+ progressReads += 1
+ return progressReads === 1 ? undefined : [["invalid"]]
+ },
+ }
+ ws.deserializeAttachment.mockReturnValue(state)
+ ;(ctx.getWebSockets as ReturnType<typeof vi.fn>).mockReturnValue([ws])
+
+ const response = await durable.fetch(await requestFor())
+
+ expect(response.status).toBe(503)
+ await expect(response.json()).resolves.toMatchObject({ preflightFailed: 1 })
+ expect(ws.send).not.toHaveBeenCalled()
+ })
+
+ it("fails phase A when the next persisted cursor would exceed the attachment budget", async () => {
+ const { durable, ctx } = createDO()
+ const ws = createMockWebSocket()
+ ws.serializeAttachment({
+ type: "user",
+ userId: "user-42",
+ authenticated: true,
+ name: "x".repeat(COMMUNITY_CONNECTION_STATE_JSON_MAX_BYTES),
+ })
+ ;(ctx.getWebSockets as ReturnType<typeof vi.fn>).mockReturnValue([ws])
+
+ const response = await durable.fetch(await requestFor())
+
+ expect(response.status).toBe(503)
+ await expect(response.json()).resolves.toMatchObject({ preflightFailed: 1 })
+ expect(ws.send).not.toHaveBeenCalled()
+ })
+
+ it("treats a batch encoder invariant fault as all-socket zero-send", async () => {
+ const { durable, ctx } = createDO()
+ const first = createMockWebSocket()
+ first.serializeAttachment({
+ type: "user",
+ userId: "user-42",
+ authenticated: true,
+ })
+ const second = createMockWebSocket()
+ second.serializeAttachment({ type: "user", userId: "user-42", authenticated: true })
+ ;(ctx.getWebSockets as ReturnType<typeof vi.fn>).mockReturnValue([first, second])
+ mockEncodePreparedCommunityBrowserEventBatch.mockReturnValueOnce({
+ ok: false,
+ reason: "batch-invariant-oversized",
+ byteLength: 328_705,
+ })
+
+ const response = await durable.fetch(await requestFor())
+ expect(response.status).toBe(503)
+ await expect(response.json()).resolves.toMatchObject({
+ attempted: 0,
+ preflightFailed: 2,
+ notAttempted: 0,
+ results: [
+ { socketIndex: 0, outcome: "preflightFailed", frameCount: 1 },
+ { socketIndex: 1, outcome: "preflightFailed", frameCount: 1 },
+ ],
+ })
+ expect(first.send).not.toHaveBeenCalled()
+ expect(second.send).not.toHaveBeenCalled()
+ })
+
+ it("returns an exact complete zero-socket receipt", async () => {
+ const { durable, ctx } = createDO()
+ ;(ctx.getWebSockets as ReturnType<typeof vi.fn>).mockReturnValue([])
+
+ const response = await durable.fetch(await requestFor())
+ expect(response.status).toBe(200)
+ await expect(response.json()).resolves.toMatchObject({
+ status: "complete",
+ validated: true,
+ matched: 0,
+ attempted: 0,
+ enqueued: 0,
+ alreadyEnqueued: 0,
+ preflightFailed: 0,
+ notAttempted: 0,
+ partial: 0,
+ failed: 0,
+ ambiguousClosed: 0,
+ results: [],
+ })
+ })
+
+ it("closes a socket and reports ambiguity when attachment persistence fails after send", async () => {
+ const { durable, ctx } = createDO()
+ const ws = createMockWebSocket()
+ ws.serializeAttachment({
+ type: "user",
+ userId: "user-42",
+ authenticated: true,
+ })
+ ws.serializeAttachment.mockImplementationOnce(() => {
+ throw new Error("attachment failed")
+ })
+ ;(ctx.getWebSockets as ReturnType<typeof vi.fn>).mockReturnValue([ws])
+
+ const response = await durable.fetch(await requestFor())
+ expect(response.status).toBe(503)
+ await expect(response.json()).resolves.toMatchObject({
+ status: "incomplete",
+ failed: 1,
+ ambiguousClosed: 1,
+ results: [{ persistedNextFrameIndex: 0, ambiguousClosed: true }],
+ })
+ expect(ws.send).toHaveBeenCalledTimes(1)
+ expect(ws.close).toHaveBeenCalledWith(1011, "Delivery state unavailable")
+ })
})
@@ -255,6 +553,30 @@ describe("WebSocketDurableObject", () => {
})
})
+ it("preserves delivery progress when an existing user socket reauthenticates", async () => {
+ const { durable } = createDO()
+ mockGetValidSessionWithIdentity.mockResolvedValue({ userId: "user-42", name: "Ana", discriminator: "0012" })
+ const operationId = await deriveCommunityDeliveryOperationId("message-reauth")
+ const progress = [[operationId, "a".repeat(64), 1, 1]]
+ const ws = createMockWebSocket()
+ ws.serializeAttachment({
+ type: "user",
+ userId: "user-42",
+ targetUserId: "user-42",
+ authenticated: true,
+ communityDeliveryProgress: progress,
+ })
+
+ await durable.webSocketMessage(ws as any, JSON.stringify({ type: "auth", token: "valid-token" }))
+
+ expect(ws.deserializeAttachment()).toMatchObject({
+ type: "user",
+ userId: "user-42",
+ authenticated: true,
+ communityDeliveryProgress: progress,
+ })
+ })
+
it("retries a transient session lookup before authenticating", async () => {
const { durable } = createDO()
mockGetValidSessionWithIdentity
diff --git a/src/ws-do/src/ws-durable/user-auth.ts b/src/ws-do/src/ws-durable/user-auth.ts
index 59b3a2860..51b5da4e2 100644
--- a/src/ws-do/src/ws-durable/user-auth.ts
+++ b/src/ws-do/src/ws-durable/user-auth.ts
@@ -1,10 +1,15 @@
import {
createDb,
+ encodePreparedCommunityBrowserEventBatch,
isValidCommunityUserTarget,
queries,
readOrStale,
withD1Retry,
} from "@alook/shared"
+import {
+ createCommunityDeliveryReceipt,
+ type CommunityDeliverySocketResult,
+} from "../community-delivery-receipt"
import type {
CommunityMachineConnectionState,
ConnectionState,
@@ -26,6 +31,12 @@ import {
readCommunityBrowserEventBundleRequest,
readCommunityBrowserEventRequest,
} from "../community-browser-event-ingress"
+import {
+ preflightCommunityConnectionState,
+ readCommunityDeliveryProgress,
+ withCommunityDeliveryProgress,
+ type CommunityDeliveryProgress,
+} from "./community-delivery-state"
export async function handleUserFetch(
context: WsDurableContext,
@@ -37,17 +48,14 @@ export async function handleUserFetch(
if (!isValidCommunityUserTarget(targetUserId)) {
const failure = { ok: false, reason: "invalid-target", type: "unknown" } as const
logCommunityBrowserEventRejected(context.log, "target-do-bundle", failure)
- return invalidCommunityBrowserEventResponse(failure)
+ return deliveryErrorResponse(400, { operationId: null, code: "invalid_request" })
}
const bundle = await readCommunityBrowserEventBundleRequest(request)
if (!bundle.ok) {
logCommunityBrowserEventRejected(context.log, "target-do-bundle", bundle)
- return invalidCommunityBrowserEventResponse(bundle)
+ return deliveryErrorResponse(400, { operationId: null, code: "invalid_request" })
}
- broadcastBundle(context, bundle.bodies, targetUserId)
- return new Response(JSON.stringify({ accepted: bundle.eventCount }), {
- headers: { "Content-Type": "application/json" },
- })
+ return deliverCommunityBundle(context, bundle, targetUserId)
}
if (url.pathname === "/community-broadcast" && request.method === "POST") {
@@ -177,7 +185,12 @@ export async function handleWebSocketMessage(
return
}
- const msg = parsed as { type: string; token?: string; machineToken?: string; daemonId?: string }
+ const msg = parsed as {
+ type: string
+ token?: string
+ machineToken?: string
+ daemonId?: string
+ }
if (msg.type === "auth") {
if (msg.machineToken && msg.daemonId) {
@@ -237,6 +250,9 @@ export async function handleWebSocketMessage(
authenticated: true,
name,
discriminator,
+ ...(state?.type === "user" && state.communityDeliveryProgress
+ ? { communityDeliveryProgress: state.communityDeliveryProgress }
+ : {}),
} as ConnectionState)
context.log.info("websocket authenticated", { userId })
ws.send(JSON.stringify({ type: "auth.ok" }))
@@ -328,11 +344,73 @@ function broadcast(
return sent
}
-function broadcastBundle(
+type ValidCommunityBundle = Extract<
+ Awaited<ReturnType<typeof readCommunityBrowserEventBundleRequest>>,
+ { ok: true }
+>
+
+type DeliveryPlan = {
+ socketIndex: number
+ ws: WebSocket
+ state: Extract<ConnectionState, { type: "user" }>
+ frames: string[]
+ progress: CommunityDeliveryProgress | null
+ outcome?: "alreadyEnqueued" | "preflightFailed"
+}
+
+function jsonResponse(value: unknown, status = 200): Response {
+ return new Response(JSON.stringify(value), {
+ status,
+ headers: { "Content-Type": "application/json" },
+ })
+}
+
+function deliveryErrorResponse(
+ status: 400 | 409,
+ value:
+ | { operationId: string | null; code: "invalid_request" }
+ | { operationId: string; operationDigest: string; code: "operation_digest_conflict" },
+): Response {
+ return jsonResponse({
+ status: status === 400 ? "invalid" : "conflict",
+ validated: status !== 400,
+ ...value,
+ }, status)
+}
+
+function socketResult(
+ plan: DeliveryPlan,
+ outcome: CommunityDeliverySocketResult["outcome"],
+ persistedNextFrameIndex: number,
+ ambiguousClosed = false,
+): CommunityDeliverySocketResult {
+ return {
+ socketIndex: plan.socketIndex,
+ outcome,
+ frameCount: 1,
+ persistedNextFrameIndex,
+ ambiguousClosed,
+ }
+}
+
+function safeCloseAmbiguousSocket(ws: WebSocket): void {
+ try { ws.close(1011, "Delivery state unavailable") } catch { }
+}
+
+function deliverCommunityBundle(
context: WsDurableContext,
- messages: readonly string[],
+ bundle: ValidCommunityBundle,
targetUserId: string,
-): void {
+): Response {
+ const encodedBatch = encodePreparedCommunityBrowserEventBatch({
+ operationId: bundle.operationId,
+ operationDigest: bundle.operationDigest,
+ prepared: bundle.prepared,
+ })
+ const targetSockets: Array<{
+ ws: WebSocket
+ state: Extract<ConnectionState, { type: "user" }>
+ }> = []
for (const ws of context.ctx.getWebSockets()) {
const state = ws.deserializeAttachment() as ConnectionState
if (!state?.authenticated) continue
@@ -342,10 +420,155 @@ function broadcastBundle(
}
continue
}
- for (const message of messages) {
- try { ws.send(message) } catch { }
+ targetSockets.push({ ws, state })
+ }
+
+ const plans: DeliveryPlan[] = targetSockets.map(({ ws, state }, socketIndex) => ({
+ socketIndex,
+ ws,
+ state,
+ frames: encodedBatch.ok ? [encodedBatch.body] : [],
+ progress: null,
+ }))
+
+ if (!encodedBatch.ok) {
+ context.log.error("community_delivery_batch_encoder_invariant_failed", {
+ operationId: bundle.operationId,
+ reason: encodedBatch.reason,
+ ...(encodedBatch.byteLength === undefined ? {} : { byteLength: encodedBatch.byteLength }),
+ eventCount: bundle.eventCount,
+ matched: plans.length,
+ })
+ const results = plans.map((plan) => socketResult(plan, "preflightFailed", 0))
+ return jsonResponse(createCommunityDeliveryReceipt({
+ status: "incomplete",
+ operationId: bundle.operationId,
+ operationDigest: bundle.operationDigest,
+ eventCount: bundle.eventCount,
+ results,
+ }), 503)
+ }
+
+ let hasConflict = false
+ for (const plan of plans) {
+ const decoded = readCommunityDeliveryProgress(plan.state)
+ if (!decoded.ok) {
+ plan.outcome = "preflightFailed"
+ continue
+ }
+ const progress = decoded.entries.find((entry) => entry.operationId === bundle.operationId) ?? null
+ plan.progress = progress
+ if (progress?.operationDigest !== undefined && progress.operationDigest !== bundle.operationDigest) {
+ hasConflict = true
+ continue
}
+ if (progress && progress.frameCount !== plan.frames.length) {
+ plan.outcome = "preflightFailed"
+ continue
+ }
+ if (progress?.nextFrameIndex === plan.frames.length) {
+ plan.outcome = "alreadyEnqueued"
+ continue
+ }
+ let candidateState = plan.state
+ const startIndex = progress?.nextFrameIndex ?? 0
+ for (let nextFrameIndex = startIndex + 1; nextFrameIndex <= plan.frames.length; nextFrameIndex += 1) {
+ try {
+ candidateState = withCommunityDeliveryProgress(candidateState, {
+ operationId: bundle.operationId,
+ operationDigest: bundle.operationDigest,
+ nextFrameIndex,
+ frameCount: plan.frames.length,
+ })
+ } catch {
+ plan.outcome = "preflightFailed"
+ break
+ }
+ if (!preflightCommunityConnectionState(candidateState).ok) {
+ plan.outcome = "preflightFailed"
+ break
+ }
+ }
+ }
+
+ if (hasConflict) {
+ context.log.warn("community_delivery_operation_digest_conflict", {
+ operationId: bundle.operationId,
+ eventCount: bundle.eventCount,
+ matched: plans.length,
+ })
+ return deliveryErrorResponse(409, {
+ operationId: bundle.operationId,
+ operationDigest: bundle.operationDigest,
+ code: "operation_digest_conflict",
+ })
}
+
+ if (plans.some((plan) => plan.outcome === "preflightFailed")) {
+ const results = plans.map((plan) => {
+ const persisted = plan.progress?.nextFrameIndex ?? 0
+ if (plan.outcome === "alreadyEnqueued") return socketResult(plan, "alreadyEnqueued", persisted)
+ return socketResult(
+ plan,
+ plan.outcome === "preflightFailed" ? "preflightFailed" : "notAttempted",
+ persisted,
+ )
+ })
+ return jsonResponse(createCommunityDeliveryReceipt({
+ status: "incomplete",
+ operationId: bundle.operationId,
+ operationDigest: bundle.operationDigest,
+ eventCount: bundle.eventCount,
+ results,
+ }), 503)
+ }
+
+ const results: CommunityDeliverySocketResult[] = []
+ for (const plan of plans) {
+ let persisted = plan.progress?.nextFrameIndex ?? 0
+ if (plan.outcome === "alreadyEnqueued") {
+ results.push(socketResult(plan, "alreadyEnqueued", persisted))
+ continue
+ }
+ let state = plan.state
+ let terminal: CommunityDeliverySocketResult | null = null
+ for (let frameIndex = persisted; frameIndex < plan.frames.length; frameIndex += 1) {
+ try {
+ plan.ws.send(plan.frames[frameIndex])
+ } catch {
+ terminal = socketResult(plan, persisted > 0 ? "partial" : "failed", persisted)
+ break
+ }
+ const nextFrameIndex = frameIndex + 1
+ let nextState: typeof state
+ try {
+ nextState = withCommunityDeliveryProgress(state, {
+ operationId: bundle.operationId,
+ operationDigest: bundle.operationDigest,
+ nextFrameIndex,
+ frameCount: plan.frames.length,
+ })
+ plan.ws.serializeAttachment(nextState)
+ } catch {
+ safeCloseAmbiguousSocket(plan.ws)
+ terminal = socketResult(plan, persisted > 0 ? "partial" : "failed", persisted, true)
+ break
+ }
+ state = nextState
+ persisted = nextFrameIndex
+ }
+ results.push(terminal ?? socketResult(plan, "enqueued", persisted))
+ }
+
+ const complete = results.every((result) =>
+ result.outcome === "enqueued" || result.outcome === "alreadyEnqueued")
+ return jsonResponse(createCommunityDeliveryReceipt({
+ status: complete ? "complete" : "incomplete",
+ operationId: bundle.operationId,
+ operationDigest: bundle.operationDigest,
+ eventCount: bundle.eventCount,
+ results,
+ }), complete ? 200 : 503)
}
function invalidateMismatchedUserSocket(
diff --git a/src/ws-do/vitest.config.ts b/src/ws-do/vitest.config.ts
index 5a8caddbb..dc311cedf 100644
--- a/src/ws-do/vitest.config.ts
+++ b/src/ws-do/vitest.config.ts
@@ -4,5 +4,6 @@ import shared from "../../vitest.shared"
export default mergeConfig(shared, defineConfig({
test: {
include: ["src/**/*.test.ts"],
+ exclude: ["src/test-integration/**"],
},
}))