@indigoai-us/hq-cloud 5.25.0 → 5.27.0

package/src/sync/push-receiver.test.ts

@@ -0,0 +1,545 @@
+/**
+ * US-009 — push-receiver unit tests.
+ *
+ * Covers the five required behaviors from the PRD AC, against the SQS-backed
+ * {@link SqsPushReceiver} (mocked SQS client — NO real AWS) and the
+ * {@link InMemoryPushReceiver} (in-process fanout analogue):
+ *
+ *   1. subscribe lifecycle — start opens the poll loop / subscription, dispose
+ *      stops it; double-start is a no-op; flag-OFF stays dormant.
+ *   2. dedupe              — an event with sequenceNumber <= the highest seen
+ *      for its path is skipped; per-path counters are independent.
+ *   3. reconnect-replay    — a transient receiveMessage failure backs off and
+ *      resumes; SQS retention redelivers the buffered events; dedupe absorbs
+ *      redelivery (in-memory: disconnect buffers, reconnect drains).
+ *   4. flag gating         — dormant when the per-tenant flag is OFF; no queue
+ *      polled, connected stays false.
+ *   5. dispose drain       — dispose aborts + awaits the in-flight syncFn, then
+ *      disconnects; the loop terminates with no leaked timers.
+ *
+ * The live per-client SQS queue is NOT provisioned yet (server provisioning
+ * Lambda is an unbuilt follow-up — see references.md). Every test injects a
+ * fake SQS client / in-memory fanout.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { encodePushEvent, type PushEvent } from "./push-event.js";
+import { StaticFlagProvider } from "./feature-flags.js";
+import {
+  InMemoryFanout,
+  InMemoryPushReceiver,
+  NoopPushReceiver,
+  SqsPushReceiver,
+  createPushReceiver,
+  type SqsClientLike,
+  type SqsMessageLike,
+  type SyncEngineFn,
+} from "./push-receiver.js";
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+const TENANT = "tenant-indigo";
+const QUEUE_URL = "https://sqs.us-east-1.amazonaws.com/123456789012/sync-push-indigo-deviceA";
+
+function makeEvent(overrides: Partial<PushEvent> = {}): PushEvent {
+  return {
+    relativePath: "companies/indigo/notes.md",
+    contentHash:
+      "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+    mtime: "2026-05-21T12:34:56.000Z",
+    originDeviceId: "device-A",
+    originTenantId: TENANT,
+    sequenceNumber: 1,
+    eventTimestamp: "2026-05-21T12:34:56.500Z",
+    ...overrides,
+  };
+}
+
+function msg(event: PushEvent, receiptHandle = `rh-${event.sequenceNumber}`): SqsMessageLike {
+  return {
+    Body: encodePushEvent(event),
+    ReceiptHandle: receiptHandle,
+    MessageId: `m-${event.relativePath}-${event.sequenceNumber}`,
+  };
+}
+
+/**
+ * A scriptable fake SQS client. `enqueue` adds batches that successive
+ * `receiveMessage` calls drain (one batch per call); once drained, it blocks
+ * on the abort signal (modeling an idle long-poll) so dispose ends it cleanly.
+ * `failNext(n)` makes the next `n` receiveMessage calls reject (transient).
+ */
+class FakeSqs implements SqsClientLike {
+  private batches: SqsMessageLike[][] = [];
+  private failCount = 0;
+  readonly deleted: string[] = [];
+  receiveCalls = 0;
+
+  enqueue(messages: SqsMessageLike[]): void {
+    this.batches.push(messages);
+  }
+  failNext(n: number): void {
+    this.failCount += n;
+  }
+
+  async receiveMessage(args: {
+    queueUrl: string;
+    maxMessages: number;
+    waitTimeSeconds: number;
+    signal: AbortSignal;
+  }): Promise<{ messages: SqsMessageLike[] }> {
+    this.receiveCalls += 1;
+    if (this.failCount > 0) {
+      this.failCount -= 1;
+      throw new Error("simulated SQS receive failure");
+    }
+    const next = this.batches.shift();
+    if (next && next.length > 0) {
+      return { messages: next };
+    }
+    // Idle long-poll: resolve empty on the next tick (or promptly on abort).
+    return new Promise((resolve) => {
+      if (args.signal.aborted) return resolve({ messages: [] });
+      const t = setTimeout(() => resolve({ messages: [] }), 5);
+      (t as { unref?: () => void }).unref?.();
+      args.signal.addEventListener(
+        "abort",
+        () => {
+          clearTimeout(t);
+          resolve({ messages: [] });
+        },
+        { once: true },
+      );
+    });
+  }
+
+  async deleteMessage(args: { queueUrl: string; receiptHandle: string }): Promise<void> {
+    this.deleted.push(args.receiptHandle);
+  }
+}
+
+/** Wait until `predicate()` is true or `timeoutMs` elapses. */
+async function waitFor(predicate: () => boolean, timeoutMs = 1000): Promise<void> {
+  const start = Date.now();
+  while (!predicate()) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error("waitFor: timed out");
+    }
+    await new Promise((r) => setTimeout(r, 5));
+  }
+}
+
+// fast, abortable sleep so backoff doesn't slow the suite
+const fastSleep = (ms: number, signal: AbortSignal): Promise<void> =>
+  new Promise((resolve) => {
+    if (signal.aborted) return resolve();
+    const t = setTimeout(resolve, Math.min(ms, 5));
+    signal.addEventListener("abort", () => { clearTimeout(t); resolve(); }, { once: true });
+  });
+
+// ─── SqsPushReceiver ─────────────────────────────────────────────────────────
+
+describe("US-009: SqsPushReceiver — subscribe lifecycle", () => {
+  it("start opens the poll loop and processes a received event via syncFn, then deletes it", async () => {
+    const sqs = new FakeSqs();
+    const seen: string[] = [];
+    const syncFn: SyncEngineFn = async (ctx) => {
+      seen.push(ctx.event.relativePath);
+    };
+    sqs.enqueue([msg(makeEvent({ sequenceNumber: 1 }))]);
+
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn,
+      enabled: true,
+      sleep: fastSleep,
+    });
+
+    await receiver.start();
+    expect(receiver.connected).toBe(true);
+    await waitFor(() => receiver.processedCount === 1);
+    expect(seen).toEqual(["companies/indigo/notes.md"]);
+    expect(sqs.deleted).toContain("rh-1");
+
+    await receiver.dispose();
+    expect(receiver.connected).toBe(false);
+  });
+
+  it("double-start is a no-op (single poll loop)", async () => {
+    const sqs = new FakeSqs();
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn: async () => undefined,
+      enabled: true,
+      sleep: fastSleep,
+    });
+    await receiver.start();
+    await receiver.start();
+    // Let a couple poll iterations happen; a duplicated loop would roughly
+    // double the receive call rate. We just assert it stays connected + clean.
+    await new Promise((r) => setTimeout(r, 30));
+    expect(receiver.connected).toBe(true);
+    await receiver.dispose();
+  });
+
+  it("subscribes ONLY to its own tenant's queue (cross-tenant isolation boundary)", async () => {
+    const sqs = new FakeSqs();
+    const urls: string[] = [];
+    const spy: SqsClientLike = {
+      receiveMessage: (a) => {
+        urls.push(a.queueUrl);
+        return sqs.receiveMessage(a);
+      },
+      deleteMessage: (a) => sqs.deleteMessage(a),
+    };
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs: spy,
+      syncFn: async () => undefined,
+      enabled: true,
+      sleep: fastSleep,
+    });
+    await receiver.start();
+    await waitFor(() => urls.length >= 1);
+    await receiver.dispose();
+    expect(new Set(urls)).toEqual(new Set([QUEUE_URL]));
+  });
+
+  it("constructor rejects empty tenantId / queueUrl", () => {
+    expect(
+      () =>
+        new SqsPushReceiver({
+          tenantId: "",
+          queueUrl: QUEUE_URL,
+          sqs: new FakeSqs(),
+          syncFn: async () => undefined,
+          enabled: true,
+        }),
+    ).toThrow(/tenantId is required/);
+    expect(
+      () =>
+        new SqsPushReceiver({
+          tenantId: TENANT,
+          queueUrl: "",
+          sqs: new FakeSqs(),
+          syncFn: async () => undefined,
+          enabled: true,
+        }),
+    ).toThrow(/queueUrl is required/);
+  });
+});
+
+describe("US-009: SqsPushReceiver — dedupe", () => {
+  it("skips an event whose sequenceNumber <= the highest seen for that path", async () => {
+    const sqs = new FakeSqs();
+    const processed: number[] = [];
+    const syncFn: SyncEngineFn = async (ctx) => {
+      processed.push(ctx.event.sequenceNumber);
+    };
+    // seq 1, then a redelivery of 1, then 2 — same path.
+    sqs.enqueue([msg(makeEvent({ sequenceNumber: 1 }), "rh-a")]);
+    sqs.enqueue([msg(makeEvent({ sequenceNumber: 1 }), "rh-b")]);
+    sqs.enqueue([msg(makeEvent({ sequenceNumber: 2 }), "rh-c")]);
+
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn,
+      enabled: true,
+      sleep: fastSleep,
+    });
+    await receiver.start();
+    await waitFor(() => receiver.processedCount === 2);
+    await receiver.dispose();
+
+    expect(processed).toEqual([1, 2]);
+    expect(receiver.dedupedCount).toBe(1);
+    // The deduped redelivery is still deleted (we don't need it again).
+    expect(sqs.deleted).toContain("rh-b");
+  });
+
+  it("dedupe is per-path — same sequence number on different paths both process", async () => {
+    const sqs = new FakeSqs();
+    const processed: string[] = [];
+    const syncFn: SyncEngineFn = async (ctx) => {
+      processed.push(ctx.event.relativePath);
+    };
+    sqs.enqueue([
+      msg(makeEvent({ relativePath: "companies/indigo/a.md", sequenceNumber: 5 }), "rh-1"),
+      msg(makeEvent({ relativePath: "companies/indigo/b.md", sequenceNumber: 5 }), "rh-2"),
+    ]);
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn,
+      enabled: true,
+      sleep: fastSleep,
+    });
+    await receiver.start();
+    await waitFor(() => receiver.processedCount === 2);
+    await receiver.dispose();
+    expect(new Set(processed)).toEqual(
+      new Set(["companies/indigo/a.md", "companies/indigo/b.md"]),
+    );
+    expect(receiver.dedupedCount).toBe(0);
+  });
+
+  it("drops an undecodable message at the wire boundary without crashing the loop", async () => {
+    const sqs = new FakeSqs();
+    sqs.enqueue([{ Body: "{not json", ReceiptHandle: "rh-bad", MessageId: "m-bad" }]);
+    sqs.enqueue([msg(makeEvent({ sequenceNumber: 1 }), "rh-good")]);
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn: async () => undefined,
+      enabled: true,
+      sleep: fastSleep,
+    });
+    await receiver.start();
+    await waitFor(() => receiver.processedCount === 1);
+    await receiver.dispose();
+    expect(receiver.decodeFailureCount).toBe(1);
+    expect(sqs.deleted).toContain("rh-bad"); // poison message deleted
+    expect(sqs.deleted).toContain("rh-good");
+  });
+});
+
+describe("US-009: SqsPushReceiver — reconnect / catch-up replay", () => {
+  it("recovers from transient receiveMessage failures (backoff + resume) and replays the queue", async () => {
+    const sqs = new FakeSqs();
+    sqs.failNext(2); // two transient disconnects before the message lands
+    sqs.enqueue([msg(makeEvent({ sequenceNumber: 1 }), "rh-1")]);
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn: async () => undefined,
+      enabled: true,
+      sleep: fastSleep,
+      reconnect: { initialMs: 1, maxMs: 4, jitter: false },
+    });
+    await receiver.start();
+    await waitFor(() => receiver.processedCount === 1);
+    await receiver.dispose();
+    expect(receiver.receiveErrorCount).toBe(2);
+    expect(sqs.deleted).toContain("rh-1");
+  });
+
+  it("a syncFn throw does not crash the loop and the next event still processes", async () => {
+    const sqs = new FakeSqs();
+    let calls = 0;
+    const syncFn: SyncEngineFn = async () => {
+      calls += 1;
+      if (calls === 1) throw new Error("boom");
+    };
+    sqs.enqueue([msg(makeEvent({ relativePath: "companies/indigo/x.md", sequenceNumber: 1 }), "rh-1")]);
+    sqs.enqueue([msg(makeEvent({ relativePath: "companies/indigo/y.md", sequenceNumber: 1 }), "rh-2")]);
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn,
+      enabled: true,
+      sleep: fastSleep,
+    });
+    await receiver.start();
+    await waitFor(() => calls === 2);
+    await receiver.dispose();
+    // First threw (processedCount not incremented), second succeeded.
+    expect(receiver.processedCount).toBe(1);
+    expect(sqs.deleted).toEqual(expect.arrayContaining(["rh-1", "rh-2"]));
+  });
+});
+
+describe("US-009: SqsPushReceiver — flag gating", () => {
+  it("is dormant when the per-tenant flag is OFF (no queue polled, connected stays false)", async () => {
+    const sqs = new FakeSqs();
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn: async () => undefined,
+      flagProvider: new StaticFlagProvider([]), // tenant NOT enabled
+      sleep: fastSleep,
+    });
+    await receiver.start();
+    await new Promise((r) => setTimeout(r, 20));
+    expect(receiver.connected).toBe(false);
+    expect(sqs.receiveCalls).toBe(0);
+    await receiver.dispose();
+  });
+
+  it("is active when the per-tenant flag includes the tenant", async () => {
+    const sqs = new FakeSqs();
+    sqs.enqueue([msg(makeEvent({ sequenceNumber: 1 }))]);
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn: async () => undefined,
+      flagProvider: new StaticFlagProvider([TENANT]),
+      sleep: fastSleep,
+    });
+    await receiver.start();
+    await waitFor(() => receiver.processedCount === 1);
+    expect(receiver.connected).toBe(true);
+    await receiver.dispose();
+  });
+
+  it("explicit enabled wins over the provider", async () => {
+    const sqs = new FakeSqs();
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn: async () => undefined,
+      enabled: false,
+      flagProvider: new StaticFlagProvider([TENANT]),
+      sleep: fastSleep,
+    });
+    await receiver.start();
+    await new Promise((r) => setTimeout(r, 20));
+    expect(receiver.connected).toBe(false);
+    expect(sqs.receiveCalls).toBe(0);
+    await receiver.dispose();
+  });
+});
+
+describe("US-009: SqsPushReceiver — dispose drain", () => {
+  it("aborts and drains the in-flight syncFn, then disconnects", async () => {
+    const sqs = new FakeSqs();
+    let aborted = false;
+    let resolveSync: (() => void) | null = null;
+    const syncFn: SyncEngineFn = (ctx) =>
+      new Promise<void>((resolve) => {
+        resolveSync = resolve;
+        ctx.signal.addEventListener("abort", () => {
+          aborted = true;
+          resolve();
+        });
+      });
+    sqs.enqueue([msg(makeEvent({ sequenceNumber: 1 }))]);
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn,
+      enabled: true,
+      sleep: fastSleep,
+      disposeDrainMs: 200,
+    });
+    await receiver.start();
+    await waitFor(() => resolveSync !== null);
+    await receiver.dispose();
+    expect(aborted).toBe(true);
+    expect(receiver.connected).toBe(false);
+  });
+
+  it("dispose is idempotent", async () => {
+    const sqs = new FakeSqs();
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn: async () => undefined,
+      enabled: true,
+      sleep: fastSleep,
+    });
+    await receiver.start();
+    await Promise.all([receiver.dispose(), receiver.dispose()]);
+    expect(receiver.connected).toBe(false);
+  });
+});
+
+// ─── InMemoryPushReceiver (transport analogue) ───────────────────────────────
+
+describe("US-009: InMemoryPushReceiver — disconnect buffering + reconnect drain", () => {
+  it("buffers events during disconnect and drains them on reconnect, deduping replays", async () => {
+    const fanout = new InMemoryFanout();
+    const processed: number[] = [];
+    const receiver = new InMemoryPushReceiver({
+      tenantId: TENANT,
+      fanout,
+      enabled: true,
+      syncFn: async (ctx) => {
+        processed.push(ctx.event.sequenceNumber);
+      },
+    });
+    await receiver.start();
+
+    fanout.publish(encodePushEvent(makeEvent({ sequenceNumber: 1 })));
+    await waitFor(() => receiver.processedCount === 1);
+
+    receiver.simulateDisconnect();
+    expect(receiver.connected).toBe(false);
+    // Published while disconnected — buffered, not processed.
+    fanout.publish(encodePushEvent(makeEvent({ sequenceNumber: 2 })));
+    fanout.publish(encodePushEvent(makeEvent({ sequenceNumber: 1 }))); // stale replay
+    expect(receiver.bufferedCount).toBe(2);
+
+    receiver.simulateReconnect();
+    await waitFor(() => receiver.processedCount === 2);
+    await receiver.dispose();
+
+    // seq 2 processed; the stale seq-1 replay deduped.
+    expect(processed).toEqual([1, 2]);
+    expect(receiver.dedupedCount).toBe(1);
+  });
+
+  it("is dormant when the flag is OFF", async () => {
+    const fanout = new InMemoryFanout();
+    let calls = 0;
+    const receiver = new InMemoryPushReceiver({
+      tenantId: TENANT,
+      fanout,
+      flagProvider: new StaticFlagProvider([]),
+      syncFn: async () => {
+        calls += 1;
+      },
+    });
+    await receiver.start();
+    fanout.publish(encodePushEvent(makeEvent()));
+    await new Promise((r) => setTimeout(r, 20));
+    expect(receiver.connected).toBe(false);
+    expect(calls).toBe(0);
+    await receiver.dispose();
+  });
+});
+
+// ─── Factory + Noop ──────────────────────────────────────────────────────────
+
+describe("US-009: createPushReceiver factory", () => {
+  it("returns NoopPushReceiver for kind:noop", () => {
+    const r = createPushReceiver({ kind: "noop" });
+    expect(r).toBeInstanceOf(NoopPushReceiver);
+  });
+
+  it("returns SqsPushReceiver when a queue + sqs client are supplied", () => {
+    const r = createPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs: new FakeSqs(),
+      syncFn: async () => undefined,
+      enabled: true,
+    });
+    expect(r).toBeInstanceOf(SqsPushReceiver);
+  });
+
+  it("NoopPushReceiver flips connected on start/dispose with no work", async () => {
+    const r = new NoopPushReceiver();
+    expect(r.connected).toBe(false);
+    await r.start();
+    expect(r.connected).toBe(true);
+    await r.dispose();
+    expect(r.connected).toBe(false);
+  });
+});