@hot-updater/server 1.0.0-rc.18 → 1.0.0-rc.21

package/src/plugins/insights/insightsRollout.integration.spec.ts

@@ -1,186 +0,0 @@
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-import {
-  runContentionHarness,
-  withAdapterLatency,
-} from "@hot-updater/test-utils";
-import { assertDockerComposeAvailable } from "@hot-updater/test-utils/node";
-import { execa } from "execa";
-import pg from "pg";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-
-import { createDatabaseEngine } from "../../database/database";
-import type { RetryOptions } from "../../database/engineTransaction";
-import { resolveSchema } from "../../database/resolveSchema";
-import { createSqlAdapter } from "../../database/sql/sqlAdapter";
-import { pgExecutor } from "../../database/sql/sqlTestExecutors";
-import type { CoreReader } from "../definePlugin";
-import type { BundleEventRow } from "./eventRow";
-import { insights, insightsSchema } from "./index";
-
-assertDockerComposeAvailable(
-  "The Insights rollout gate needs Docker Compose and a running Docker daemon.",
-);
-
-const compose = [
-  "compose",
-  "-f",
-  path.join(
-    path.dirname(fileURLToPath(import.meta.url)),
-    "../../database/sql/docker-compose.yml",
-  ),
-  "-p",
-  "hot-updater-insights-rollout",
-];
-
-/**
- * PRD B3: every event moves an installation from release A to B on one
- * channel, with zero conflict errors and at most 5% retried. The retried share
- * grows with the host's latency, so on CI, a shared runner, the case checks
- * every move commits and records the share; elsewhere it holds the bound.
- */
-const ENFORCE_RETRIED_BOUND = !process.env.CI;
-const INSTALLS = 6000;
-const RATE_PER_SECOND = 100;
-const CONNECTIONS = 16;
-const LATENCY_MS = 5;
-
-const uuid = (n: number) =>
-  `01900000-0000-7000-8000-${String(n).padStart(12, "0")}`;
-
-const move = (
-  n: number,
-  install: number,
-  release: "a" | "b",
-  receivedAt: number,
-): BundleEventRow =>
-  ({
-    id: uuid(n),
-    type: "UPDATE_APPLIED",
-    install_id: `install-${install}`,
-    user_id: `user-${install}`,
-    from_release_id: release === "b" ? "release-a" : "release-0",
-    from_bundle_id: release === "b" ? "bundle-a" : "bundle-0",
-    to_release_id: `release-${release}`,
-    to_bundle_id: `bundle-${release}`,
-    platform: "ios",
-    app_version: "1.0.0",
-    channel: "production",
-    metadata: {
-      cohort: "1",
-      update_strategy: "appVersion",
-      fingerprint_hash: null,
-      sdk_version: null,
-    },
-    received_at_ms: receivedAt,
-  }) as BundleEventRow;
-
-let pool: pg.Pool;
-
-beforeAll(async () => {
-  await execa("docker", [...compose, "up", "-d", "--wait", "postgres"]);
-  pool = new pg.Pool({
-    connectionString:
-      "postgres://postgres:hot_updater@127.0.0.1:55432/hot_updater",
-    max: CONNECTIONS,
-  });
-  for (let attempt = 0; ; attempt += 1) {
-    try {
-      await pool.query("SELECT 1");
-      break;
-    } catch (error) {
-      if (attempt > 60) throw error;
-      await new Promise((resolve) => setTimeout(resolve, 1000));
-    }
-  }
-}, 180_000);
-
-afterAll(async () => {
-  await pool?.end();
-  await execa("docker", [...compose, "down", "-v"]);
-}, 60_000);
-
-describe("Insights rollout gate on PostgreSQL", () => {
-  it(`records ${INSTALLS} A→B moves at ${RATE_PER_SECOND}/s over ${CONNECTIONS} connections with ${LATENCY_MS} ms latency, with no conflict errors and at most 5% retried`, async () => {
-    const module = { id: "insights", schema: insightsSchema } as const;
-    const schema = resolveSchema([module]);
-    const sql = createSqlAdapter({
-      executor: pgExecutor(pool),
-      tablePrefix: `rollout_${Date.now()}_`,
-    });
-    await sql.migrations?.apply(schema.tables);
-    const plugin = insights();
-    const apiOf = (latencyMs: number, retry?: RetryOptions) =>
-      plugin.init({
-        db: createDatabaseEngine({
-          adapter: latencyMs > 0 ? withAdapterLatency(sql, latencyMs) : sql,
-          schema,
-          ...(retry === undefined ? {} : { retry }),
-        }).database(module),
-        // Insights never reads core.
-        core: {} as CoreReader,
-        now: Date.now,
-      }).api;
-
-    const seeded = apiOf(0, { attempts: 64, baseDelayMs: 1, maxDelayMs: 20 });
-    const start = Date.now() - 2 * 3_600_000;
-    const seed = await runContentionHarness({
-      transactions: INSTALLS,
-      ratePerSecond: 5000,
-      // Setup, not the gate: few writers, so one hour's rows are not a hot spot.
-      concurrency: 4,
-      run: (install) =>
-        seeded.recordEvent(move(install, install, "a", start + install)),
-    });
-    expect(seed.errors).toEqual({});
-
-    const retries = { rerun: 0, resend: 0, retriedTransactions: 0 };
-    const rollout = apiOf(LATENCY_MS, {
-      onRetry: (kind, attempt) => {
-        retries[kind] += 1;
-        if (attempt === 1) retries.retriedTransactions += 1;
-      },
-    });
-    const report = await runContentionHarness({
-      transactions: INSTALLS,
-      ratePerSecond: RATE_PER_SECOND,
-      concurrency: CONNECTIONS,
-      run: (install) =>
-        rollout.recordEvent(move(INSTALLS + install, install, "b", Date.now())),
-    });
-    const retried = retries.retriedTransactions / INSTALLS;
-    console.info(
-      "insights-rollout-gate",
-      JSON.stringify({ ...report, ...retries, retried }),
-    );
-    expect(report.errors).toEqual({});
-    expect(report.committed).toBe(INSTALLS);
-    if (ENFORCE_RETRIED_BOUND) expect(retried).toBeLessThanOrEqual(0.05);
-
-    const latest = await seeded.countLatestEvents({
-      platform: "ios",
-      channel: "production",
-      sinceMs: 0,
-      bundle: [
-        { field: "to_bundle_id", value: "bundle-b", types: ["UPDATE_APPLIED"] },
-        { field: "to_bundle_id", value: "bundle-a", types: ["UPDATE_APPLIED"] },
-      ],
-    });
-    expect(latest).toBe(INSTALLS);
-    await expect(
-      seeded.countLatestEvents({
-        platform: "ios",
-        channel: "production",
-        sinceMs: 0,
-        bundle: [
-          {
-            field: "to_bundle_id",
-            value: "bundle-a",
-            types: ["UPDATE_APPLIED"],
-          },
-        ],
-      }),
-    ).resolves.toBe(0);
-  }, 300_000);
-});

package/src/plugins/insights/model.spec.ts

@@ -1,64 +0,0 @@
-import { PGlite } from "@electric-sql/pglite";
-import {
-  createMemoryAdapter,
-  type DatabaseAdapter,
-} from "@hot-updater/plugin-core/internal";
-import { createPluginTestHarness } from "@hot-updater/test-utils";
-import { afterAll } from "vitest";
-
-import * as engine from "../../database";
-import { createSqlAdapter } from "../../database/sql/sqlAdapter";
-import { pgliteExecutor } from "../../database/sql/sqlTestExecutors";
-import { createInsightsModel, insights } from "./index";
-import type { InsightsModel } from "./modelTypes";
-import { setupInsightsModelTestSuite } from "./testing";
-
-/** The plugin's model on a fresh adapter per test, behind one stable model. */
-const onFreshAdapter = (adapter: () => DatabaseAdapter) => {
-  let model: InsightsModel | undefined;
-  const current = () => {
-    if (model === undefined) throw new Error("Insights is reset per test.");
-    return model;
-  };
-  const stable: InsightsModel = {
-    recordEvent: (input) => current().recordEvent(input),
-    listEvents: (input) => current().listEvents(input),
-    findLatestEvents: (input) => current().findLatestEvents(input),
-    countLatestEvents: (input) => current().countLatestEvents(input),
-    countEvents: (input) => current().countEvents(input),
-    getReleaseActivity: (input) => current().getReleaseActivity(input),
-    getAppUsage: (input) => current().getAppUsage(input),
-  };
-  return {
-    migrate: () => undefined,
-    createDatabase: () => stable,
-    reset: async () => {
-      const harness = await createPluginTestHarness(insights(), {
-        engine,
-        adapter: adapter(),
-      });
-      model = createInsightsModel(harness.api);
-    },
-    dispose: () => undefined,
-  };
-};
-
-setupInsightsModelTestSuite({
-  name: "the Insights plugin's model on the memory adapter",
-  ...onFreshAdapter(() => createMemoryAdapter()),
-});
-
-const pglite = new PGlite();
-afterAll(() => pglite.close());
-let resets = 0;
-
-setupInsightsModelTestSuite({
-  name: "the Insights plugin's model on PGlite",
-  ...onFreshAdapter(() => {
-    resets += 1;
-    return createSqlAdapter({
-      executor: pgliteExecutor(pglite),
-      tablePrefix: `t${resets}_`,
-    });
-  }),
-});

package/src/plugins/insights/model.ts

@@ -1,18 +0,0 @@
-import { createValidatedInsightsModel } from "./contract";
-import type { InsightsApi } from "./index";
-import type { InsightsModel } from "./modelTypes";
-
-/**
- * The plugin's API as `InsightsModel`, validated at its boundary: what the
- * Insights routes, the console, and the e2e harness read through.
- */
-export const createInsightsModel = (api: InsightsApi): InsightsModel =>
-  createValidatedInsightsModel({
-    recordEvent: ({ event }) => api.recordEvent(event),
-    listEvents: api.listEvents,
-    findLatestEvents: api.findLatestEvents,
-    countLatestEvents: api.countLatestEvents,
-    countEvents: api.countEvents,
-    getReleaseActivity: api.getReleaseActivity,
-    getAppUsage: api.getAppUsage,
-  });

package/src/plugins/insights/modelTypes.ts

@@ -1,197 +0,0 @@
-import type { BundleEventRow } from "./eventRow";
-
-export interface InsightsEventCursor {
-  readonly receivedAtMs: number;
-  readonly id: string;
-}
-
-export interface InsightsScope {
-  readonly platform: "ios" | "android";
-  readonly channel: string;
-}
-
-/**
- * Raw event predicates; recovery is attributed to the source bundle. An
- * UNCHANGED report is kept as no event, so no filter names it.
- */
-export type InsightsBundleEventFilter = InsightsScope &
-  (
-    | { readonly type: "RECOVERED"; readonly fromBundleId: string }
-    | {
-        readonly type: "UPDATE_DOWNLOADED" | "UPDATE_APPLIED" | "UPDATE_FAILED";
-        readonly toBundleId: string;
-      }
-  );
-
-export type InsightsEventFilter =
-  | { readonly kind: "all" }
-  | {
-      readonly kind: "installationMovement";
-      readonly installId: string;
-    }
-  | ({ readonly kind: "bundle" } & InsightsBundleEventFilter);
-
-export interface InsightsRecordEventInput {
-  readonly event: BundleEventRow;
-}
-
-export interface InsightsListEventsInput {
-  readonly filter: InsightsEventFilter;
-  readonly sinceMs?: number;
-  readonly beforeReceivedAtMs: number;
-  readonly after?: InsightsEventCursor;
-  readonly limit: number;
-}
-
-export type InsightsFindLatestEventsInput =
-  | { readonly installId: string }
-  | {
-      readonly userId: string;
-      readonly afterInstallId?: string;
-      readonly limit: number;
-    };
-
-export interface InsightsCountLatestEventsInput extends InsightsScope {
-  /** A UTC day's start: latest events are counted by the day they fall in. */
-  readonly sinceMs: number;
-  /** Optional OR of one or two fixed predicates; count a matching event once. */
-  readonly bundle?: readonly {
-    readonly field: "from_bundle_id" | "to_bundle_id";
-    readonly value: string;
-    readonly types: readonly BundleEventRow["type"][];
-  }[];
-}
-
-export interface InsightsCountEventsInput {
-  readonly filter: InsightsBundleEventFilter;
-  readonly sinceMs: number;
-  readonly beforeReceivedAtMs: number;
-}
-
-export interface ReleaseReference {
-  readonly releaseId: string;
-  readonly platform: "ios" | "android";
-  readonly channel: string;
-}
-
-export interface InsightsTimeRange {
-  /** Inclusive UTC Unix timestamp in milliseconds. */
-  readonly start: number;
-  /** Exclusive UTC Unix timestamp in milliseconds. */
-  readonly end: number;
-}
-
-export type InsightsCoverage =
-  | { readonly kind: "complete"; readonly sinceMs: number }
-  | { readonly kind: "partial"; readonly sinceMs: number | null };
-
-export interface ReleaseActivityMetrics {
-  readonly downloads: number;
-  readonly launches: number;
-  readonly failedLaunches: number;
-  /** Omitted for lifetime-only bundle-row reads. */
-  readonly uniqueUsers?: number;
-  /** Daily points, present only for period reads. */
-  readonly series?: readonly {
-    readonly startMs: number;
-    readonly launches: number;
-    readonly failedLaunches: number;
-  }[];
-}
-
-export type InsightsGetReleaseActivityInput =
-  | {
-      readonly releases: readonly ReleaseReference[];
-      readonly timeRange?: InsightsTimeRange;
-      readonly scope?: never;
-    }
-  | {
-      readonly scope: InsightsScope;
-      readonly timeRange: InsightsTimeRange;
-      readonly releases?: never;
-    };
-
-export interface InsightsGetReleaseActivityResult {
-  readonly coverage: InsightsCoverage;
-  readonly data: readonly {
-    readonly release?: ReleaseReference;
-    readonly scope?: InsightsScope;
-    readonly metrics: ReleaseActivityMetrics;
-  }[];
-  readonly measuredAtMs: number;
-}
-
-export interface InsightsGetAppUsageInput {
-  readonly channel: string;
-  readonly platform: "all" | "ios" | "android";
-  readonly appVersion?: string;
-  readonly timeRange: InsightsTimeRange;
-  readonly intervalMs: number;
-}
-
-export interface InsightsGetAppUsageResult {
-  readonly coverage: InsightsCoverage;
-  readonly activeInstallations: number;
-  readonly points: readonly {
-    readonly startMs: number;
-    readonly installations: number;
-  }[];
-  readonly appVersions: readonly string[];
-  readonly versions: readonly {
-    readonly name: string;
-    readonly installations: number;
-  }[];
-  readonly platforms: readonly {
-    readonly name: string;
-    readonly installations: number;
-  }[];
-  readonly bundleDistribution: readonly {
-    readonly appVersion: string;
-    readonly platform: "ios" | "android";
-    readonly releaseId: string | null;
-    readonly installations: number;
-  }[];
-  readonly measuredAtMs: number;
-}
-
-export interface InsightsModel {
-  /**
-   * Persist the immutable event once. A private latest-event index, if used,
-   * advances atomically for a greater (received_at_ms, id). Duplicate event
-   * IDs are complete no-ops, whichever installation sends them.
-   * Retry the identical prepared input after an ambiguous commit outcome.
-   */
-  recordEvent(input: InsightsRecordEventInput): Promise<void>;
-  /**
-   * Descending (received_at_ms, id), in [sinceMs ?? 0, beforeReceivedAtMs).
-   * Apply filters and the exclusive cursor before limit (1..101). Return the
-   * complete matching prefix; native continuation pages must not truncate it.
-   * A global or bundle list may reject a range longer than 90 × 24 hours;
-   * the server asks for older events with an earlier range instead.
-   */
-  listEvents(
-    input: InsightsListEventsInput,
-  ): Promise<readonly BundleEventRow[]>;
-  /**
-   * Choose each installation's greatest (received_at_ms, id) before filtering.
-   * Exact installation lookup returns zero or one canonical event. User lookup
-   * returns current membership ordered by UTF-8 installation ID, exclusive
-   * afterInstallId and limit 1..101. Check lagging index candidates against
-   * canonical state; newly indexed associations may temporarily be absent.
-   */
-  findLatestEvents(
-    input: InsightsFindLatestEventsInput,
-  ): Promise<readonly BundleEventRow[]>;
-  /** Count latest events once per installation, then apply the supplied predicates. */
-  countLatestEvents(input: InsightsCountLatestEventsInput): Promise<number>;
-  /** Count accepted reports in [sinceMs, beforeReceivedAtMs), across all pages. */
-  countEvents(input: InsightsCountEventsInput): Promise<number>;
-  /** Read maintained release/scope summaries without scanning raw events. */
-  getReleaseActivity(
-    input: InsightsGetReleaseActivityInput,
-  ): Promise<InsightsGetReleaseActivityResult>;
-  /** Read maintained App usage summaries and latest-report distribution. */
-  getAppUsage(
-    input: InsightsGetAppUsageInput,
-  ): Promise<InsightsGetAppUsageResult>;
-}

package/src/plugins/insights/overview.spec.ts

@@ -1,64 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import type { BundleEventRow } from "./eventRow";
-import { insightsOverviewDeltas } from "./overview";
-
-const event = (type: BundleEventRow["type"]): BundleEventRow =>
-  ({
-    id: "01993e00-0000-7000-8000-000000000001",
-    type,
-    install_id: "install-a",
-    user_id: null,
-    from_release_id: type === "UNCHANGED" ? null : "source-release",
-    from_bundle_id: type === "UNCHANGED" ? null : "source-bundle",
-    to_release_id: "destination-release",
-    to_bundle_id: "destination-bundle",
-    platform: "ios",
-    app_version: "1.0.0",
-    channel: "production",
-    metadata: {
-      cohort: "default",
-      update_strategy: null,
-      fingerprint_hash: null,
-      sdk_version: null,
-    },
-    received_at_ms: 3_600_001,
-  }) as BundleEventRow;
-
-describe("Insights overview event contributions", () => {
-  it("attributes recovery failure to the source and readiness to the destination", () => {
-    const rows = insightsOverviewDeltas(event("RECOVERED"));
-    const lifetime = rows.filter(
-      ({ identity }) =>
-        identity.scopeKind === "release" && identity.periodKind === "lifetime",
-    );
-    expect(lifetime).toEqual(
-      expect.arrayContaining([
-        expect.objectContaining({
-          identity: expect.objectContaining({ releaseId: "source-release" }),
-          failedLaunches: 1,
-          launches: 0,
-        }),
-        expect.objectContaining({
-          identity: expect.objectContaining({
-            releaseId: "destination-release",
-          }),
-          failedLaunches: 0,
-          launches: 1,
-        }),
-      ]),
-    );
-  });
-
-  it("counts downloads without treating them as launches", () => {
-    const lifetime = insightsOverviewDeltas(event("UPDATE_DOWNLOADED")).find(
-      ({ identity }) =>
-        identity.scopeKind === "release" && identity.periodKind === "lifetime",
-    );
-    expect(lifetime).toMatchObject({
-      downloads: 1,
-      launches: 0,
-      failedLaunches: 0,
-    });
-  });
-});