@indigoai-us/hq-cloud 6.14.49 → 6.15.0

package/src/sync/realtime-rollout.ts

@@ -0,0 +1,262 @@
+import type { AuthTokenSource, FetchLike } from "./push-transport.js";
+
+export const REALTIME_SYNC_CONTRACT_VERSION = 2 as const;
+export const MAX_REALTIME_ROLLOUT_CACHE_MS = 30_000;
+export const DEFAULT_REALTIME_AUTHORIZATION_TIMEOUT_MS = 15_000;
+
+export interface RealtimeCapabilityVector {
+  hqCloud: string;
+  hqDesktop: string | "none";
+  protocol: 2;
+  journal: number;
+  durableApply: number;
+}
+
+export type RealtimeInventoryState =
+  | { state: "legacy"; v1Allowed: true }
+  | { state: "qualifying" | "frozen" | "seeding"; retryAfterMs: number }
+  | { state: "bootstrap-required"; snapshotDescriptorId: string }
+  | { state: "v2-ready"; cursor: string }
+  | { state: "paused"; reasonCode: string }
+  | { state: "reset-required"; resetId: string; snapshotDescriptorId: string }
+  | { state: "revoked"; localMaterialPolicy: string }
+  | { state: "restoring"; retryAfterMs: number }
+  | { state: "blocked"; reasonCode: string };
+
+export type RealtimeInventoryGrant = RealtimeInventoryState & {
+  scopeUid: string;
+  scopeHandle: string;
+  scopeRevision: string;
+};
+
+export interface RealtimeInventory {
+  scopes: readonly RealtimeInventoryGrant[];
+}
+
+export interface RealtimeInventoryRequest {
+  /** A changed token must never reuse a positive inventory result. */
+  bearer: string;
+  deviceId: string;
+  capabilityVector: RealtimeCapabilityVector;
+  /** Identifies the active client configuration/capability selection. */
+  configurationFingerprint: string;
+  /** Identifies the scopes this guarded pass is about to touch. */
+  scopeFingerprint: string;
+}
+
+export interface RealtimeRolloutClientOptions {
+  apiUrl: string;
+  fetchImpl?: FetchLike;
+  now?: () => number;
+  maxCacheAgeMs?: number;
+  authorizationTimeoutMs?: number;
+}
+
+interface CachedInventory {
+  expiresAt: number;
+  value: RealtimeInventory;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function nonEmpty(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`realtime inventory: ${field} must be a non-empty string`);
+  }
+  return value;
+}
+
+function exactKeys(value: Record<string, unknown>, allowed: readonly string[], label: string): void {
+  if (Object.keys(value).some((key) => !allowed.includes(key))) {
+    throw new Error(`realtime inventory: ${label} contains an unknown field`);
+  }
+}
+
+function parseState(value: unknown): RealtimeInventoryState {
+  if (!isRecord(value) || typeof value.state !== "string") {
+    throw new Error("realtime inventory: scope state is invalid");
+  }
+  switch (value.state) {
+    case "legacy":
+      exactKeys(value, ["state", "v1Allowed"], "legacy state");
+      if (value.v1Allowed !== true) throw new Error("realtime inventory: legacy must explicitly allow v1");
+      return { state: "legacy", v1Allowed: true };
+    case "qualifying":
+    case "frozen":
+    case "seeding":
+    case "restoring":
+      exactKeys(value, ["state", "retryAfterMs"], `${value.state} state`);
+      if (
+        typeof value.retryAfterMs !== "number" ||
+        !Number.isSafeInteger(value.retryAfterMs) ||
+        value.retryAfterMs < 0
+      ) {
+        throw new Error(`realtime inventory: ${value.state} retryAfterMs is invalid`);
+      }
+      return { state: value.state, retryAfterMs: value.retryAfterMs };
+    case "bootstrap-required":
+      exactKeys(value, ["state", "snapshotDescriptorId"], "bootstrap-required state");
+      return { state: value.state, snapshotDescriptorId: nonEmpty(value.snapshotDescriptorId, "snapshotDescriptorId") };
+    case "v2-ready":
+      exactKeys(value, ["state", "cursor"], "v2-ready state");
+      return { state: value.state, cursor: nonEmpty(value.cursor, "cursor") };
+    case "paused":
+    case "blocked":
+      exactKeys(value, ["state", "reasonCode"], `${value.state} state`);
+      return { state: value.state, reasonCode: nonEmpty(value.reasonCode, "reasonCode") };
+    case "reset-required":
+      exactKeys(value, ["state", "resetId", "snapshotDescriptorId"], "reset-required state");
+      return {
+        state: value.state,
+        resetId: nonEmpty(value.resetId, "resetId"),
+        snapshotDescriptorId: nonEmpty(value.snapshotDescriptorId, "snapshotDescriptorId"),
+      };
+    case "revoked":
+      exactKeys(value, ["state", "localMaterialPolicy"], "revoked state");
+      return { state: value.state, localMaterialPolicy: nonEmpty(value.localMaterialPolicy, "localMaterialPolicy") };
+    default:
+      throw new Error(`realtime inventory: unsupported scope state ${value.state}`);
+  }
+}
+
+export function parseRealtimeInventory(value: unknown): RealtimeInventory {
+  if (!isRecord(value)) throw new Error("realtime inventory: response is not an object");
+  exactKeys(value, ["scopes"], "response");
+  if (!Array.isArray(value.scopes)) throw new Error("realtime inventory: scopes is not an array");
+  const scopeHandles = new Set<string>();
+  const scopes = value.scopes.map((entry): RealtimeInventoryGrant => {
+    if (!isRecord(entry)) throw new Error("realtime inventory: scope grant is not an object");
+    const { scopeUid, scopeHandle, scopeRevision, ...state } = entry;
+    const parsedState = parseState(state);
+    const grant = {
+      scopeUid: nonEmpty(scopeUid, "scopeUid"),
+      scopeHandle: nonEmpty(scopeHandle, "scopeHandle"),
+      scopeRevision: nonEmpty(scopeRevision, "scopeRevision"),
+      ...parsedState,
+    } as RealtimeInventoryGrant;
+    if (scopeHandles.has(grant.scopeHandle)) {
+      throw new Error("realtime inventory: duplicate scopeHandle");
+    }
+    scopeHandles.add(grant.scopeHandle);
+    return grant;
+  });
+  return { scopes };
+}
+
+function inventoryCacheKey(request: RealtimeInventoryRequest): string {
+  const capability = request.capabilityVector;
+  return JSON.stringify([
+    request.bearer,
+    request.deviceId,
+    request.configurationFingerprint,
+    request.scopeFingerprint,
+    capability.hqCloud,
+    capability.hqDesktop,
+    capability.protocol,
+    capability.journal,
+    capability.durableApply,
+  ]);
+}
+
+function cacheAgeForInventory(inventory: RealtimeInventory, maximum: number): number {
+  return inventory.scopes.reduce((age, grant) => {
+    if (
+      grant.state === "qualifying" ||
+      grant.state === "frozen" ||
+      grant.state === "seeding" ||
+      grant.state === "restoring"
+    ) return Math.min(age, grant.retryAfterMs);
+    if (grant.state === "legacy" || grant.state === "v2-ready") return age;
+    return 0;
+  }, maximum);
+}
+
+/**
+ * Strict client for the authenticated inventory endpoint. The cache is keyed
+ * by bearer, device, capability/configuration, and the scope selection. A
+ * positive inventory record is only an optimization: callers must still mint
+ * a new lease before I/O, where the server strongly rechecks all authority.
+ */
+export class RealtimeRolloutClient {
+  private readonly apiUrl: string;
+  private readonly fetchImpl: FetchLike;
+  private readonly now: () => number;
+  private readonly maxCacheAgeMs: number;
+  private readonly authorizationTimeoutMs: number;
+  private readonly cache = new Map<string, CachedInventory>();
+
+  constructor(options: RealtimeRolloutClientOptions) {
+    if (!options.apiUrl.trim()) throw new Error("realtime inventory: apiUrl is required");
+    this.apiUrl = options.apiUrl.replace(/\/+$/, "");
+    this.fetchImpl = options.fetchImpl ?? ((input, init) => (globalThis.fetch as unknown as FetchLike)(input, init));
+    this.now = options.now ?? Date.now;
+    this.maxCacheAgeMs = options.maxCacheAgeMs ?? MAX_REALTIME_ROLLOUT_CACHE_MS;
+    if (!Number.isSafeInteger(this.maxCacheAgeMs) || this.maxCacheAgeMs < 0 || this.maxCacheAgeMs > MAX_REALTIME_ROLLOUT_CACHE_MS) {
+      throw new Error(`realtime inventory: maxCacheAgeMs must be within 0-${MAX_REALTIME_ROLLOUT_CACHE_MS}`);
+    }
+    this.authorizationTimeoutMs = options.authorizationTimeoutMs ?? DEFAULT_REALTIME_AUTHORIZATION_TIMEOUT_MS;
+    if (!Number.isSafeInteger(this.authorizationTimeoutMs) || this.authorizationTimeoutMs <= 0) {
+      throw new Error("realtime inventory: authorizationTimeoutMs must be a positive integer");
+    }
+  }
+
+  invalidate(): void {
+    this.cache.clear();
+  }
+
+  async inventory(request: RealtimeInventoryRequest): Promise<RealtimeInventory> {
+    const now = this.now();
+    for (const [key, entry] of this.cache) {
+      if (entry.expiresAt <= now) this.cache.delete(key);
+    }
+    const cacheKey = inventoryCacheKey(request);
+    const cached = this.cache.get(cacheKey);
+    if (cached && now < cached.expiresAt) return cached.value;
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.authorizationTimeoutMs);
+    let response: Awaited<ReturnType<FetchLike>>;
+    try {
+      response = await this.fetchImpl(`${this.apiUrl}/v2/sync/scopes`, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${request.bearer}`,
+          Accept: "application/json",
+          "X-HQ-Sync-Contract": String(REALTIME_SYNC_CONTRACT_VERSION),
+          "X-HQ-Device-ID": request.deviceId,
+          "X-HQ-Cloud-Version": request.capabilityVector.hqCloud,
+          "X-HQ-Desktop-Version": request.capabilityVector.hqDesktop,
+          "X-HQ-Sync-Journal": String(request.capabilityVector.journal),
+          "X-HQ-Sync-Durable-Apply": String(request.capabilityVector.durableApply),
+        },
+        signal: controller.signal,
+      });
+    } catch (error) {
+      throw new Error(`realtime inventory: GET /v2/sync/scopes failed: ${error instanceof Error ? error.message : String(error)}`);
+    } finally {
+      clearTimeout(timeout);
+    }
+    const text = await response.text().catch((error: unknown) => {
+      throw new Error(`realtime inventory: unable to read response: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    if (!response.ok) throw new Error(`realtime inventory: GET /v2/sync/scopes failed (${response.status}): ${text.slice(0, 300)}`);
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text);
+    } catch (error) {
+      throw new Error(`realtime inventory: response is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const inventory = parseRealtimeInventory(parsed);
+    const cacheAgeMs = cacheAgeForInventory(inventory, this.maxCacheAgeMs);
+    if (cacheAgeMs > 0) this.cache.set(cacheKey, { value: inventory, expiresAt: this.now() + cacheAgeMs });
+    return inventory;
+  }
+}
+
+export async function resolveRealtimeBearer(source: AuthTokenSource): Promise<string> {
+  const bearer = typeof source === "function" ? await source() : source;
+  if (typeof bearer !== "string" || bearer.trim() === "") throw new Error("realtime authorization: access token is empty");
+  return bearer;
+}

package/src/sync/state-store.test.ts

@@ -0,0 +1,194 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { StateStore, StateStoreCorruptionError } from "./state-store.js";
+
+interface TestState {
+  values: string[];
+}
+
+const RECORD = 7;
+const roots: string[] = [];
+
+afterEach(() => {
+  for (const root of roots.splice(0)) fs.rmSync(root, { recursive: true, force: true });
+});
+
+function openStore(root = makeRoot(), threshold = 256): StateStore<TestState> {
+  return StateStore.open<TestState>({
+    rootDir: root,
+    scopeId: "prs_test_scope",
+    initialState: { values: [] },
+    maxRecordsBeforeCompaction: threshold,
+    reduce: (state, record) => {
+      if (record.type !== RECORD || typeof record.payload !== "string") {
+        throw new Error("test reducer received an invalid record");
+      }
+      return { values: [...state.values, record.payload] };
+    },
+  });
+}
+
+function makeRoot(): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "hq-state-store-test-"));
+  roots.push(root);
+  return root;
+}
+
+describe("StateStore WAL v3", () => {
+  it("writes protocol byte headers and appends frames without rewriting the snapshot hot path", () => {
+    const root = makeRoot();
+    const store = openStore(root);
+    const snapshot = path.join(store.stateDir, "snapshot-1.bin");
+    const wal = path.join(store.stateDir, "wal-1.bin");
+    const before = fs.statSync(snapshot);
+    const beforeWalSize = fs.statSync(wal).size;
+
+    store.append(RECORD, "first", 3);
+
+    const after = fs.statSync(snapshot);
+    const walBytes = fs.readFileSync(wal);
+    expect(after.ino).toBe(before.ino);
+    expect(fs.statSync(wal).size).toBeGreaterThan(beforeWalSize);
+    expect(walBytes.subarray(0, 8).toString("ascii")).toBe("HQWAL3\0\0");
+    expect(walBytes.readUInt32BE(80)).toBe(0x48515733);
+    expect(walBytes.readBigUInt64BE(88)).toBe(1n);
+    expect(walBytes.readUInt16BE(96)).toBe(RECORD);
+    expect(walBytes.readUInt16BE(98)).toBe(3);
+  });
+
+  it("truncates every incomplete tail at the last good frame boundary", () => {
+    const root = makeRoot();
+    const first = openStore(root);
+    first.append(RECORD, "durable");
+    const wal = path.join(first.stateDir, "wal-1.bin");
+    const validLength = fs.statSync(wal).size;
+    fs.appendFileSync(wal, Buffer.from([0x48, 0x51, 0x57]));
+
+    const recovered = openStore(root);
+
+    expect(recovered.getState()).toEqual({ values: ["durable"] });
+    expect(fs.statSync(wal).size).toBe(validLength);
+  });
+
+  it("never skips a complete frame with a bad checksum", () => {
+    const root = makeRoot();
+    const store = openStore(root);
+    store.append(RECORD, "bad");
+    const wal = path.join(store.stateDir, "wal-1.bin");
+    const bytes = fs.readFileSync(wal);
+    bytes[bytes.length - 1] ^= 0xff;
+    fs.writeFileSync(wal, bytes);
+
+    expect(() => openStore(root)).toThrow(StateStoreCorruptionError);
+  });
+
+  it("falls back to the retained last-good generation after a later complete frame corrupts", () => {
+    const root = makeRoot();
+    const store = openStore(root);
+    store.append(RECORD, "last-good");
+    store.compact();
+    store.append(RECORD, "corrupt-later");
+    const wal = path.join(store.stateDir, "wal-2.bin");
+    const bytes = fs.readFileSync(wal);
+    bytes[bytes.length - 1] ^= 0xff;
+    fs.writeFileSync(wal, bytes);
+
+    const recovered = openStore(root);
+
+    expect(recovered.getGeneration()).toBe(1);
+    expect(recovered.getState()).toEqual({ values: ["last-good"] });
+  });
+
+  it("allocates above a rejected generation when compaction resumes from last-good", () => {
+    const root = makeRoot();
+    const store = openStore(root);
+    store.append(RECORD, "last-good");
+    store.compact();
+    store.append(RECORD, "corrupt-later");
+    const wal = path.join(store.stateDir, "wal-2.bin");
+    const bytes = fs.readFileSync(wal);
+    bytes[bytes.length - 1] ^= 0xff;
+    fs.writeFileSync(wal, bytes);
+
+    const recovered = openStore(root);
+    recovered.compact();
+
+    expect(recovered.getGeneration()).toBe(3);
+    expect(openStore(root).getState()).toEqual({ values: ["last-good"] });
+  });
+
+  it("rejects a corrupted final frame length instead of truncating it as torn", () => {
+    const root = makeRoot();
+    const store = openStore(root);
+    store.append(RECORD, "durable");
+    const wal = path.join(store.stateDir, "wal-1.bin");
+    const bytes = fs.readFileSync(wal);
+    bytes.writeUInt32BE(bytes.readUInt32BE(84) + 1, 84);
+    fs.writeFileSync(wal, bytes);
+
+    expect(() => openStore(root)).toThrow(StateStoreCorruptionError);
+    expect(fs.statSync(wal).size).toBe(bytes.length);
+  });
+
+  it("chooses the highest fully valid generation even when an interrupted rename left a stale pointer", () => {
+    const root = makeRoot();
+    const store = openStore(root);
+    store.append(RECORD, "one");
+    store.compact();
+    fs.writeFileSync(path.join(store.stateDir, "current"), "1\n");
+
+    const recovered = openStore(root);
+
+    expect(recovered.getGeneration()).toBe(2);
+    expect(recovered.getState()).toEqual({ values: ["one"] });
+  });
+
+  it("compacts bounded WAL generations and preserves record sequence", () => {
+    const root = makeRoot();
+    const store = openStore(root, 2);
+    store.append(RECORD, "one");
+    store.append(RECORD, "two");
+    expect(store.getGeneration()).toBe(2);
+    store.append(RECORD, "three");
+
+    const recovered = openStore(root, 2);
+
+    expect(recovered.getGeneration()).toBe(2);
+    expect(recovered.getLastRecordSequence()).toBe(3);
+    expect(recovered.getState()).toEqual({ values: ["one", "two", "three"] });
+  });
+
+  it("serializes stale handles so records keep contiguous sequence numbers", () => {
+    const root = makeRoot();
+    const first = openStore(root);
+    const second = openStore(root);
+
+    first.append(RECORD, "one");
+    second.append(RECORD, "two");
+
+    expect(openStore(root).getState()).toEqual({ values: ["one", "two"] });
+  });
+
+  it("does not durably append a record rejected by the reducer", () => {
+    const root = makeRoot();
+    const store = openStore(root);
+
+    expect(() => store.append(99, "unsupported")).toThrow(/invalid record/);
+    expect(openStore(root).getState()).toEqual({ values: [] });
+  });
+
+  it("surfaces incompatible reducer records instead of falling back to stale state", () => {
+    const root = makeRoot();
+    const writer = openStore(root);
+    writer.append(RECORD, "newer-record");
+
+    expect(() => StateStore.open<TestState>({
+      rootDir: root,
+      scopeId: "prs_test_scope",
+      initialState: { values: [] },
+      reduce: () => { throw new Error("unsupported record type"); },
+    })).toThrow(/reducer rejected generation/);
+  });
+});