@indigoai-us/hq-cloud 6.15.0 → 6.15.2

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

@@ -1,566 +0,0 @@
-/**
- * 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 { describe, expect, it } from "vitest";
-
-import { encodePushEvent, type PushEvent } from "./push-event.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",
-    kind: "upsert",
-    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,
-      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,
-      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,
-      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,
-        }),
-    ).toThrow(/tenantId is required/);
-    expect(
-      () =>
-        new SqsPushReceiver({
-          tenantId: TENANT,
-          queueUrl: "",
-          sqs: new FakeSqs(),
-          syncFn: async () => undefined,
-        }),
-    ).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,
-      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,
-      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,
-      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,
-      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,
-      sleep: fastSleep,
-    });
-    await receiver.start();
-    await waitFor(() => calls === 2);
-    await receiver.dispose();
-    // First threw (processedCount not incremented), second succeeded.
-    expect(receiver.processedCount).toBe(1);
-    // F10: a failed targeted pull is left undeleted for SQS redelivery; only the
-    // successful message (rh-2) is acknowledged. The thrown one (rh-1) stays on
-    // the queue so the visibility-timeout redelivery can retry it.
-    expect(sqs.deleted).toContain("rh-2");
-    expect(sqs.deleted).not.toContain("rh-1");
-  });
-
-  it("F10: leaves failed targeted pull messages undeleted so redelivery retries", async () => {
-    const sqs = new FakeSqs();
-    let calls = 0;
-    const syncFn: SyncEngineFn = async () => {
-      calls += 1;
-      if (calls === 1) throw new Error("targeted pull failed");
-    };
-    const event = makeEvent({
-      relativePath: "companies/indigo/retry-after-failure.md",
-      sequenceNumber: 7,
-    });
-    sqs.enqueue([msg(event, "rh-first-attempt")]);
-    sqs.enqueue([msg(event, "rh-redelivery")]);
-
-    const receiver = new SqsPushReceiver({
-      tenantId: TENANT,
-      queueUrl: QUEUE_URL,
-      sqs,
-      syncFn,
-      sleep: fastSleep,
-    });
-    await receiver.start();
-    await waitFor(() => sqs.deleted.includes("rh-redelivery"));
-    await receiver.dispose();
-
-    expect(calls).toBe(2);
-    expect(receiver.processedCount).toBe(1);
-    expect(receiver.dedupedCount).toBe(0);
-    expect(sqs.deleted).not.toContain("rh-first-attempt");
-    expect(sqs.deleted).toContain("rh-redelivery");
-  });
-
-  it("F29: bounds dedupe state by evicting least-recently-used paths", 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: 1 }), "rh-a1")]);
-    sqs.enqueue([msg(makeEvent({ relativePath: "companies/indigo/b.md", sequenceNumber: 1 }), "rh-b1")]);
-    sqs.enqueue([msg(makeEvent({ relativePath: "companies/indigo/c.md", sequenceNumber: 1 }), "rh-c1")]);
-    sqs.enqueue([msg(makeEvent({ relativePath: "companies/indigo/a.md", sequenceNumber: 1 }), "rh-a-redelivered")]);
-
-    const receiver = new SqsPushReceiver({
-      tenantId: TENANT,
-      queueUrl: QUEUE_URL,
-      sqs,
-      syncFn,
-      sleep: fastSleep,
-      dedupeMaxPaths: 2,
-    });
-    await receiver.start();
-    await waitFor(() => receiver.processedCount === 4);
-    await receiver.dispose();
-
-    expect(processed).toEqual([
-      "companies/indigo/a.md",
-      "companies/indigo/b.md",
-      "companies/indigo/c.md",
-      "companies/indigo/a.md",
-    ]);
-    expect(receiver.dedupedCount).toBe(0);
-    expect(sqs.deleted).toContain("rh-a-redelivered");
-  });
-});
-
-describe("U15: SqsPushReceiver — server-granted handoff", () => {
-  it("starts from supplied server queue material with no tenant client gate", async () => {
-    const sqs = new FakeSqs();
-    sqs.enqueue([msg(makeEvent({ sequenceNumber: 1 }))]);
-    const receiver = new SqsPushReceiver({
-      tenantId: TENANT,
-      queueUrl: QUEUE_URL,
-      sqs,
-      syncFn: async () => undefined,
-      sleep: fastSleep,
-    });
-    await receiver.start();
-    await waitFor(() => receiver.processedCount === 1);
-    expect(receiver.connected).toBe(true);
-    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,
-      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,
-      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,
-      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("does not derive activation from a tenant flag", async () => {
-    const fanout = new InMemoryFanout();
-    let calls = 0;
-    const receiver = new InMemoryPushReceiver({
-      tenantId: TENANT,
-      fanout,
-      syncFn: async () => {
-        calls += 1;
-      },
-    });
-    await receiver.start();
-    fanout.publish(encodePushEvent(makeEvent()));
-    await new Promise((r) => setTimeout(r, 20));
-    await waitFor(() => calls === 1);
-    expect(receiver.connected).toBe(true);
-    expect(calls).toBe(1);
-    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,
-    });
-    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);
-  });
-});