@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/sync/lease-client.ts

@@ -1,207 +0,0 @@
-import type { AuthTokenSource, FetchLike } from "./push-transport.js";
-import {
-  DEFAULT_REALTIME_AUTHORIZATION_TIMEOUT_MS,
-  REALTIME_SYNC_CONTRACT_VERSION,
-  type RealtimeCapabilityVector,
-  type RealtimeInventoryGrant,
-  type RealtimeInventoryRequest,
-  type RealtimeRolloutClient,
-  resolveRealtimeBearer,
-} from "./realtime-rollout.js";
-
-export const MAX_REALTIME_LEASE_MS = 60_000;
-export const MAX_REALTIME_LEASE_CLOCK_SKEW_MS = 5_000;
-
-export interface RealtimeLease {
-  lease: string;
-  issuedAt: string;
-  expiresAt: string;
-  authorizationEpoch: string;
-}
-
-export interface RealtimeLeaseRequest {
-  bearer: string;
-  deviceId: string;
-  capabilityVector: RealtimeCapabilityVector;
-  scopeHandle: string;
-  scopeRevision: string;
-}
-
-export interface RealtimeLeaseClientOptions {
-  apiUrl: string;
-  fetchImpl?: FetchLike;
-  now?: () => number;
-  authorizationTimeoutMs?: number;
-}
-
-function asNonEmptyString(value: unknown, field: string): string {
-  if (typeof value !== "string" || value.trim() === "") throw new Error(`realtime lease: ${field} must be a non-empty string`);
-  return value;
-}
-
-function parseLease(value: unknown, now: number): RealtimeLease {
-  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("realtime lease: response is not an object");
-  const record = value as Record<string, unknown>;
-  if (Object.keys(record).some((key) => !["lease", "issuedAt", "expiresAt", "authorizationEpoch"].includes(key))) {
-    throw new Error("realtime lease: response contains an unknown field");
-  }
-  const lease: RealtimeLease = {
-    lease: asNonEmptyString(record.lease, "lease"),
-    issuedAt: asNonEmptyString(record.issuedAt, "issuedAt"),
-    expiresAt: asNonEmptyString(record.expiresAt, "expiresAt"),
-    authorizationEpoch: asNonEmptyString(record.authorizationEpoch, "authorizationEpoch"),
-  };
-  const issuedAtMs = Date.parse(lease.issuedAt);
-  const expiresAtMs = Date.parse(lease.expiresAt);
-  if (
-    !Number.isFinite(issuedAtMs) ||
-    !Number.isFinite(expiresAtMs) ||
-    issuedAtMs > now + MAX_REALTIME_LEASE_CLOCK_SKEW_MS ||
-    expiresAtMs <= now ||
-    expiresAtMs <= issuedAtMs ||
-    expiresAtMs - issuedAtMs > MAX_REALTIME_LEASE_MS ||
-    expiresAtMs > now + MAX_REALTIME_LEASE_MS
-  ) {
-    throw new Error("realtime lease: invalid lease lifetime");
-  }
-  return lease;
-}
-
-/** Issues a non-cacheable, <=60 second lease for one exact inventory grant. */
-export class RealtimeLeaseClient {
-  private readonly apiUrl: string;
-  private readonly fetchImpl: FetchLike;
-  private readonly now: () => number;
-  private readonly authorizationTimeoutMs: number;
-
-  constructor(options: RealtimeLeaseClientOptions) {
-    if (!options.apiUrl.trim()) throw new Error("realtime lease: 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.authorizationTimeoutMs = options.authorizationTimeoutMs ?? DEFAULT_REALTIME_AUTHORIZATION_TIMEOUT_MS;
-    if (!Number.isSafeInteger(this.authorizationTimeoutMs) || this.authorizationTimeoutMs <= 0) {
-      throw new Error("realtime lease: authorizationTimeoutMs must be a positive integer");
-    }
-  }
-
-  assertUsable(lease: RealtimeLease): void {
-    const expiresAtMs = Date.parse(lease.expiresAt);
-    if (!Number.isFinite(expiresAtMs) || expiresAtMs <= this.now()) {
-      throw new Error("realtime lease: expired before guarded I/O");
-    }
-  }
-
-  async issue(request: RealtimeLeaseRequest): Promise<RealtimeLease> {
-    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/leases`, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${request.bearer}`,
-          Accept: "application/json",
-          "Content-Type": "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,
-        },
-        body: JSON.stringify({
-          scopeHandle: request.scopeHandle,
-          scopeRevision: request.scopeRevision,
-          capabilityVector: request.capabilityVector,
-        }),
-        signal: controller.signal,
-      });
-    } catch (error) {
-      throw new Error(`realtime lease: POST /v2/sync/leases failed: ${error instanceof Error ? error.message : String(error)}`);
-    } finally {
-      clearTimeout(timeout);
-    }
-    const text = await response.text().catch((error: unknown) => {
-      throw new Error(`realtime lease: unable to read response: ${error instanceof Error ? error.message : String(error)}`);
-    });
-    if (!response.ok) throw new Error(`realtime lease: POST /v2/sync/leases failed (${response.status}): ${text.slice(0, 300)}`);
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(text);
-    } catch (error) {
-      throw new Error(`realtime lease: response is not JSON: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    return parseLease(parsed, this.now());
-  }
-}
-
-export interface RealtimeScopeAuthorization {
-  grant: RealtimeInventoryGrant & { state: "v2-ready" };
-  lease: RealtimeLease;
-}
-
-export interface RealtimePassAuthorization {
-  /** One resolved bearer is reused by every inventory and lease request in this pass. */
-  bearer: string;
-  scopes: readonly RealtimeScopeAuthorization[];
-}
-
-export interface RealtimePassRequest {
-  deviceId: string;
-  capabilityVector: RealtimeCapabilityVector;
-  configurationFingerprint: string;
-  scopeFingerprint: string;
-  scopeUids: readonly string[];
-}
-
-/**
- * The only pre-I/O admission seam for later V2 work. It intentionally has no
- * V1 fallback: malformed, stale, revoked, or non-ready inventory never gives
- * an operation a lease. It resolves its bearer once, then reissues leases on
- * every guarded pass so cached positives cannot cross server config/scope
- * changes.
- */
-export class RealtimePassAuthorizer {
-  constructor(
-    private readonly authToken: AuthTokenSource,
-    private readonly inventoryClient: RealtimeRolloutClient,
-    private readonly leaseClient: RealtimeLeaseClient,
-  ) {}
-
-  async authorize(request: RealtimePassRequest): Promise<RealtimePassAuthorization> {
-    const bearer = await resolveRealtimeBearer(this.authToken);
-    const inventoryRequest: RealtimeInventoryRequest = {
-      bearer,
-      deviceId: request.deviceId,
-      capabilityVector: request.capabilityVector,
-      configurationFingerprint: request.configurationFingerprint,
-      scopeFingerprint: request.scopeFingerprint,
-    };
-    const inventory = await this.inventoryClient.inventory(inventoryRequest);
-    const requested = new Set(request.scopeUids);
-    if (requested.size === 0) throw new Error("realtime authorization: guarded pass has no scopes");
-    const grants = inventory.scopes.filter((grant) => requested.has(grant.scopeUid));
-    if (grants.length !== requested.size || grants.some((grant) => grant.state !== "v2-ready")) {
-      throw new Error("realtime authorization: inventory does not authorize every requested scope");
-    }
-    const scopes = await Promise.all(grants.map(async (grant) => ({
-      grant: grant as RealtimeInventoryGrant & { state: "v2-ready" },
-      lease: await this.leaseClient.issue({
-        bearer,
-        deviceId: request.deviceId,
-        capabilityVector: request.capabilityVector,
-        scopeHandle: grant.scopeHandle,
-        scopeRevision: grant.scopeRevision,
-      }),
-    })));
-    const authorizationEpoch = scopes[0]?.lease.authorizationEpoch;
-    if (!authorizationEpoch || scopes.some((scope) => scope.lease.authorizationEpoch !== authorizationEpoch)) {
-      throw new Error("realtime authorization: leases disagree on authorization epoch");
-    }
-    for (const scope of scopes) this.leaseClient.assertUsable(scope.lease);
-    return { bearer, scopes };
-  }
-
-  async runBeforeIo<T>(request: RealtimePassRequest, operation: (authorization: RealtimePassAuthorization) => Promise<T>): Promise<T> {
-    return operation(await this.authorize(request));
-  }
-}

package/src/sync/logger.test.ts

@@ -1,242 +0,0 @@
-/**
- * US-011 — unit tests for the pino logger factory + the 3-log diagnostic
- * chain's CLIENT-side correlated fields.
- *
- * The PRD requires three correlated logs sharing the same `sequenceNumber`:
- *   1. `watcher.emit`    — client push (US-008 PushEventEmitter)   [client]
- *   2. `push.receive`    — server (hq-pro)                          [server]
- *   3. `fanout.receive`  — client fanout-receive (US-009 receiver)  [client]
- *
- * This package owns the two CLIENT-side links. These tests prove:
- *   - `createLogger` stamps the `component` tag on every line and respects
- *     level + injected destination.
- *   - the watcher emits `event=watcher.emit` carrying `sequenceNumber`.
- *   - the receiver emits `event=fanout.receive` carrying the SAME
- *     `sequenceNumber` → an operator can join the two client links (and the
- *     server `push.receive` line, which carries the same key) end-to-end.
- */
-
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { Writable } from "node:stream";
-
-import { afterEach, describe, expect, it } from "vitest";
-
-import { createLogger } from "./logger.js";
-import { encodePushEvent, type PushEvent } from "./push-event.js";
-import { NoopPushTransport } from "./push-transport.js";
-import { StaticFlagProvider } from "./feature-flags.js";
-import {
-  SqsPushReceiver,
-  type SqsClientLike,
-  type SqsMessageLike,
-} from "./push-receiver.js";
-import { PushEventEmitter, type TreeChangeBatch } from "../watcher.js";
-
-const TENANT = "tenant-indigo";
-
-// ── Capture stream + JSON line reader ─────────────────────────────────────────
-
-function captureStream(): { stream: Writable; lines: () => Array<Record<string, unknown>> } {
-  const chunks: string[] = [];
-  const stream = new Writable({
-    write(chunk, _enc, cb) {
-      chunks.push(
-        typeof chunk === "string" ? chunk : (chunk as Buffer).toString("utf8"),
-      );
-      cb();
-    },
-  });
-  return {
-    stream,
-    lines: () =>
-      chunks
-        .join("")
-        .split("\n")
-        .filter((s) => s.length > 0)
-        .map((s) => JSON.parse(s) as Record<string, unknown>),
-  };
-}
-
-async function until(predicate: () => boolean, timeoutMs = 1000): Promise<void> {
-  const start = Date.now();
-  while (!predicate()) {
-    if (Date.now() - start > timeoutMs) throw new Error("until() timed out");
-    await new Promise((r) => setTimeout(r, 5));
-  }
-}
-
-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.000Z",
-    ...overrides,
-  };
-}
-
-class OneBatchSqs implements SqsClientLike {
-  private batch: SqsMessageLike[] | null;
-  constructor(messages: SqsMessageLike[]) {
-    this.batch = messages;
-  }
-  async receiveMessage(args: {
-    queueUrl: string;
-    maxMessages: number;
-    waitTimeSeconds: number;
-    signal: AbortSignal;
-  }): Promise<{ messages: SqsMessageLike[] }> {
-    if (this.batch) {
-      const b = this.batch;
-      this.batch = null;
-      return { messages: b };
-    }
-    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(): Promise<void> {
-    /* no-op */
-  }
-}
-
-// ── createLogger ──────────────────────────────────────────────────────────────
-
-describe("createLogger", () => {
-  it("stamps the `component` tag on every line", () => {
-    const { stream, lines } = captureStream();
-    const log = createLogger({
-      component: "sync-watcher",
-      destination: stream,
-      level: "info",
-    });
-    log.info({ event: "x" }, "hello");
-    log.warn({ event: "y" }, "world");
-    const out = lines();
-    expect(out).toHaveLength(2);
-    expect(out.every((l) => l.component === "sync-watcher")).toBe(true);
-  });
-
-  it("respects the injected level (debug below info is dropped at info)", () => {
-    const { stream, lines } = captureStream();
-    const log = createLogger({
-      component: "c",
-      destination: stream,
-      level: "info",
-    });
-    log.debug({ event: "d" }, "dropped");
-    log.info({ event: "i" }, "kept");
-    const out = lines();
-    expect(out).toHaveLength(1);
-    expect(out[0]!.event).toBe("i");
-  });
-});
-
-// ── 3-log chain: client-side correlated fields share sequenceNumber ───────────
-
-describe("3-log diagnostic chain (client links share sequenceNumber)", () => {
-  let tmp: string | undefined;
-  let receiver: SqsPushReceiver | undefined;
-
-  afterEach(async () => {
-    if (receiver) {
-      await receiver.dispose();
-      receiver = undefined;
-    }
-    if (tmp) {
-      await rm(tmp, { recursive: true, force: true });
-      tmp = undefined;
-    }
-  });
-
-  it("watcher.emit and fanout.receive carry the SAME sequenceNumber", async () => {
-    const SEQ = 4242;
-
-    // ── Link 1: watcher.emit (client push side) ──────────────────────────
-    tmp = await mkdtemp(join(tmpdir(), "us011-logger-"));
-    const absPath = join(tmp, "notes.md");
-    await writeFile(absPath, "hello world", "utf8");
-
-    const watcherCap = captureStream();
-    const watcherLog = createLogger({
-      component: "sync-watcher",
-      destination: watcherCap.stream,
-      level: "info",
-    });
-
-    const emitter = new PushEventEmitter({
-      originTenantId: TENANT,
-      originDeviceId: "device-A",
-      transport: new NoopPushTransport(),
-      flagProvider: new StaticFlagProvider([TENANT]),
-      getSequenceNumber: () => SEQ,
-      logger: watcherLog,
-    });
-
-    const batch: TreeChangeBatch = {
-      paths: new Map([[absPath, "companies/indigo/notes.md"]]),
-    };
-    await emitter.emitForBatch(batch);
-
-    const emitLine = watcherCap
-      .lines()
-      .find((l) => l.event === "watcher.emit");
-    expect(emitLine).toBeDefined();
-    expect(emitLine!.sequenceNumber).toBe(SEQ);
-    expect(emitLine!.component).toBe("sync-watcher");
-
-    // ── Link 3: fanout.receive (client receive side) ─────────────────────
-    const receiverCap = captureStream();
-    const receiverLog = createLogger({
-      component: "sync-receiver",
-      destination: receiverCap.stream,
-      level: "info",
-    });
-    const event = makeEvent({ sequenceNumber: SEQ });
-
-    receiver = new SqsPushReceiver({
-      tenantId: TENANT,
-      queueUrl: "https://sqs.local/q",
-      sqs: new OneBatchSqs([{ Body: encodePushEvent(event), ReceiptHandle: "rh" }]),
-      syncFn: async () => {
-        /* success */
-      },
-      enabled: true,
-      logger: receiverLog,
-      // Inject a no-op metric so no real AWS is touched.
-      publishMetric: async () => {},
-    });
-
-    await receiver.start();
-    await until(() =>
-      receiverCap.lines().some((l) => l.event === "fanout.receive"),
-    );
-
-    const recvLine = receiverCap
-      .lines()
-      .find((l) => l.event === "fanout.receive");
-    expect(recvLine).toBeDefined();
-    expect(recvLine!.sequenceNumber).toBe(SEQ);
-    expect(recvLine!.component).toBe("sync-receiver");
-
-    // ── The join key matches across both client links ────────────────────
-    expect(emitLine!.sequenceNumber).toBe(recvLine!.sequenceNumber);
-  });
-});

package/src/sync/logger.ts

@@ -1,79 +0,0 @@
-/**
- * Component-tagged logger factory for the hq-cloud sync subsystem
- * (project event-driven-sync-menubar US-011).
- *
- * Every log line emitted from a sync module SHOULD carry a `component` field
- * so operators can grep / route by subsystem in the aggregated JSON stream.
- * `createLogger({ component: "sync-watcher" })` is the canonical entry point —
- * modules call this once at module-load time and use the returned logger for
- * the lifetime of the process.
- *
- * The 3-log diagnostic chain (US-011)
- * ───────────────────────────────────
- * Three correlated log lines share a single `sequenceNumber` join key so an
- * operator can walk one event end-to-end:
- *   1. `event=watcher.emit`    — client push side (US-008 PushEventEmitter)
- *   2. `event=push.receive`    — server side (hq-pro; context only here)
- *   3. `event=fanout.receive`  — client fanout-receive side (US-009 receiver)
- * The watcher.emit + fanout.receive halves live in this client package; the
- * push.receive half lives server-side in hq-pro. All three stamp the same
- * `sequenceNumber` for log-chain correlation.
- *
- * Output format: pino's default newline-delimited JSON. No transports, no
- * pretty-printing — the daemon consumes the raw JSON stream. (Operators who
- * want pretty output pipe through `pino-pretty` themselves.)
- *
- * Destination injection: tests pass a `destination` stream so they can capture
- * log lines and assert on them. Production callers omit it and pino defaults
- * to `process.stdout`.
- *
- * Adapted from indigoai-us/hq-pro PR #112 (src/sync/logger.ts) into
- * @indigoai-us/hq-cloud (Path B).
- */
-
-import {
-  pino,
-  type DestinationStream,
-  type Level,
-  type Logger,
-  type LoggerOptions,
-} from "pino";
-
-export interface CreateLoggerOptions {
-  /**
-   * Component tag stamped on every log line as `"component": <value>`.
-   * Required so daemon / watcher / receiver lines never appear in the stream
-   * untagged.
-   */
-  component: string;
-  /**
-   * Optional pino level. Default: pino's own default (`info`). Set via
-   * `LOG_LEVEL` env var, command-line flag, or test injection.
-   */
-  level?: Level;
-  /**
-   * Optional pino destination. Default: `process.stdout`. Tests inject a
-   * memory stream here to capture lines for assertion.
-   */
-  destination?: DestinationStream;
-}
-
-/**
- * Build a pino logger pre-bound to a `component` tag.
- *
- * Use this — not a bare `pino()` call — so every sync module's log lines carry
- * the tag uniformly. Adding more bound fields (e.g. `deviceId`, `tenantId`) is
- * a `logger.child({ ... })` call away.
- */
-export function createLogger(opts: CreateLoggerOptions): Logger {
-  const { component, level, destination } = opts;
-  const pinoOpts: LoggerOptions = {
-    base: { component },
-    ...(level === undefined ? {} : { level }),
-  };
-  return destination === undefined
-    ? pino(pinoOpts)
-    : pino(pinoOpts, destination);
-}
-
-export type { Logger } from "pino";