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

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

@@ -1,285 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-
-import { createValidatedInsightsModel } from "./contract";
-import type { BundleEventRow } from "./eventRow";
-import type {
-  InsightsFindLatestEventsInput,
-  InsightsListEventsInput,
-  InsightsModel,
-} from "./modelTypes";
-
-const event: BundleEventRow = {
-  id: "00000000-0000-7000-8000-000000000001",
-  type: "UPDATE_APPLIED",
-  install_id: "install",
-  user_id: "user",
-  metadata: {
-    cohort: "0",
-    update_strategy: "appVersion",
-    fingerprint_hash: null,
-    sdk_version: null,
-  },
-  from_bundle_id: "bundle-a",
-  to_bundle_id: "bundle-b",
-  from_release_id: null,
-  to_release_id: null,
-  platform: "ios",
-  app_version: "1",
-  channel: "production",
-
-  received_at_ms: 100,
-};
-
-/** A provider that stores nothing, behind the validating wrapper under test. */
-const emptyModel: InsightsModel = {
-  recordEvent: async () => undefined,
-  listEvents: async () => [],
-  findLatestEvents: async () => [],
-  countLatestEvents: async () => 0,
-  countEvents: async () => 0,
-  getReleaseActivity: async () => ({
-    coverage: { kind: "complete", sinceMs: 0 },
-    data: [],
-    measuredAtMs: 0,
-  }),
-  getAppUsage: async () => ({
-    coverage: { kind: "complete", sinceMs: 0 },
-    activeInstallations: 0,
-    points: [],
-    appVersions: [],
-    versions: [],
-    platforms: [],
-    bundleDistribution: [],
-    measuredAtMs: 0,
-  }),
-};
-
-const createModel = (overrides: Partial<InsightsModel>) =>
-  createValidatedInsightsModel({ ...emptyModel, ...overrides });
-
-describe("public Insights validation", () => {
-  it("prevents malformed Unicode and noncanonical event IDs from reaching providers", async () => {
-    const recordEvent = vi.fn(async () => undefined);
-    const model = createModel({ recordEvent });
-    for (const invalid of [
-      { ...event, install_id: "broken-\ud800" },
-      { ...event, user_id: "broken-\udc00" },
-      { ...event, metadata: { ...event.metadata, cohort: "broken-\ud800" } },
-      { ...event, id: "not-a-uuid" },
-    ]) {
-      await expect(
-        model.recordEvent({
-          event: invalid,
-        }),
-      ).rejects.toMatchObject({ code: "invalid-data" });
-    }
-    expect(recordEvent).not.toHaveBeenCalled();
-  });
-
-  it("takes an update failure with what failed, and refuses one without it", async () => {
-    const recordEvent = vi.fn(async () => undefined);
-    const model = createModel({ recordEvent });
-    const failed = {
-      ...event,
-      type: "UPDATE_FAILED",
-      metadata: {
-        ...event.metadata,
-        failure: {
-          stage: "download",
-          reason: "http",
-          resource: "artifact",
-          http_status: 403,
-          origin_code: "AccessDenied",
-        },
-      },
-    } as BundleEventRow;
-    await model.recordEvent({ event: failed });
-    expect(recordEvent).toHaveBeenCalledTimes(1);
-    for (const invalid of [
-      { ...failed, metadata: event.metadata },
-      { ...failed, from_bundle_id: null },
-      {
-        ...failed,
-        metadata: {
-          ...failed.metadata,
-          failure: { stage: "download", reason: "http", http_status: "403" },
-        },
-      },
-      {
-        ...failed,
-        metadata: { ...failed.metadata, failure: { stage: "download" } },
-      },
-      {
-        ...event,
-        type: "UPDATE_DOWNLOADED",
-        metadata: { ...event.metadata, patch_fallback: "yes" },
-      },
-    ]) {
-      await expect(
-        model.recordEvent({ event: invalid as BundleEventRow }),
-      ).rejects.toMatchObject({ code: "invalid-data" });
-    }
-    expect(recordEvent).toHaveBeenCalledTimes(1);
-  });
-
-  it.each([
-    { installId: "install", userId: "user", limit: 1 },
-    { installId: "install", limit: 1 },
-    { userId: "user", limit: 102 },
-    { userId: "user", limit: 1, afterInstallId: "\ud800" },
-    { userId: "user", limit: 0 },
-  ])(
-    "rejects invalid installation query form %j before provider I/O",
-    async (input) => {
-      const findLatestEvents = vi.fn(async () => []);
-      const model = createModel({ findLatestEvents });
-      await expect(
-        model.findLatestEvents(input as InsightsFindLatestEventsInput),
-      ).rejects.toMatchObject({ code: "invalid-query" });
-      expect(findLatestEvents).not.toHaveBeenCalled();
-    },
-  );
-
-  it("rejects cursors outside their interval and conflicting raw bundle predicates", async () => {
-    const listEvents = vi.fn(async () => []);
-    const model = createModel({ listEvents });
-    const query: InsightsListEventsInput = {
-      filter: { kind: "all" },
-      sinceMs: 100,
-      beforeReceivedAtMs: 200,
-      limit: 10,
-    };
-    for (const receivedAtMs of [99, 200]) {
-      await expect(
-        model.listEvents({ ...query, after: { receivedAtMs, id: event.id } }),
-      ).rejects.toMatchObject({ code: "invalid-query" });
-    }
-    await expect(
-      model.listEvents({
-        ...query,
-        filter: {
-          kind: "bundle",
-          type: "RECOVERED",
-          platform: "ios",
-          channel: "production",
-          fromBundleId: "bundle-b",
-          toBundleId: "bundle-a",
-        },
-      } as InsightsListEventsInput),
-    ).rejects.toMatchObject({ code: "invalid-query" });
-    expect(listEvents).not.toHaveBeenCalled();
-  });
-
-  it("rejects provider rows that violate the requested filter, range, or cursor order", async () => {
-    const query: InsightsListEventsInput = {
-      filter: { kind: "all" },
-      sinceMs: 100,
-      beforeReceivedAtMs: 200,
-      limit: 10,
-    };
-    for (const rows of [
-      [{ ...event, received_at_ms: 99 }],
-      [{ ...event, received_at_ms: 200 }],
-      [event, event],
-    ]) {
-      await expect(
-        createModel({ listEvents: async () => rows }).listEvents(query),
-      ).rejects.toMatchObject({ code: "invalid-result" });
-    }
-    await expect(
-      createModel({ listEvents: async () => [event] }).listEvents({
-        ...query,
-        filter: {
-          kind: "bundle",
-          platform: "ios",
-          channel: "production",
-          type: "RECOVERED",
-          fromBundleId: "bundle-b",
-        },
-      }),
-    ).rejects.toMatchObject({ code: "invalid-result" });
-    await expect(
-      createModel({ listEvents: async () => [event] }).listEvents({
-        ...query,
-        after: { receivedAtMs: event.received_at_ms, id: event.id },
-      }),
-    ).rejects.toMatchObject({ code: "invalid-result" });
-  });
-
-  it("rejects stale user membership and incorrectly ordered identity results", async () => {
-    const row = event;
-    await expect(
-      createModel({ findLatestEvents: async () => [row] }).findLatestEvents({
-        userId: "different",
-        limit: 10,
-      }),
-    ).rejects.toMatchObject({ code: "invalid-result" });
-    await expect(
-      createModel({
-        findLatestEvents: async () => [row, row],
-      }).findLatestEvents({ installId: "install" }),
-    ).rejects.toMatchObject({ code: "invalid-result" });
-    await expect(
-      createModel({
-        findLatestEvents: async () => [
-          { ...row, install_id: "😀" },
-          { ...row, install_id: "\ue000" },
-        ],
-      }).findLatestEvents({ userId: "user", limit: 10 }),
-    ).rejects.toMatchObject({ code: "invalid-result" });
-  });
-
-  it("passes bundle predicates on both fields that share a type to the model", async () => {
-    const countLatestEvents = vi.fn(async () => 1);
-    const model = createModel({ countLatestEvents });
-    const input = {
-      platform: "ios",
-      channel: "production",
-      sinceMs: 0,
-      bundle: [
-        { field: "from_bundle_id", value: "A", types: ["UPDATE_DOWNLOADED"] },
-        {
-          field: "to_bundle_id",
-          value: "B",
-          types: ["UPDATE_APPLIED", "UPDATE_DOWNLOADED"],
-        },
-      ],
-    } as const;
-    await expect(model.countLatestEvents(input)).resolves.toBe(1);
-    expect(countLatestEvents).toHaveBeenCalledWith(input);
-  });
-
-  it("propagates native failures and rejects invalid scalar counts", async () => {
-    const failure = new Error("native query failed");
-    const countInput = {
-      platform: "ios",
-      channel: "production",
-      sinceMs: 0,
-    } as const;
-    await expect(
-      createModel({
-        countLatestEvents: async () => {
-          throw failure;
-        },
-      }).countLatestEvents(countInput),
-    ).rejects.toBe(failure);
-    await expect(
-      createModel({
-        listEvents: async () => {
-          throw failure;
-        },
-      }).listEvents({
-        filter: { kind: "all" },
-        beforeReceivedAtMs: 200,
-        limit: 10,
-      }),
-    ).rejects.toBe(failure);
-    for (const count of [-1, 0.5, Number.MAX_SAFE_INTEGER + 1, Number.NaN]) {
-      await expect(
-        createModel({
-          countLatestEvents: async () => count,
-        }).countLatestEvents(countInput),
-      ).rejects.toMatchObject({ code: "invalid-result" });
-    }
-  });
-});

package/src/plugins/insights/contract.ts

@@ -1,372 +0,0 @@
-import { DatabasePluginInputError, isUUIDv7 } from "@hot-updater/plugin-core";
-
-import {
-  type BundleEventRow,
-  isRecord,
-  validateBundleEventFields,
-} from "./eventRow";
-import type { InsightsEventFilter, InsightsModel } from "./modelTypes";
-
-const encoder = new TextEncoder();
-
-/** Exact UTF-8 byte ordering, without case folding or Unicode normalization. */
-export const compareInsightsText = (left: string, right: string): number => {
-  const a = encoder.encode(left);
-  const b = encoder.encode(right);
-  for (let index = 0; index < Math.min(a.length, b.length); index += 1) {
-    if (a[index] !== b[index]) return a[index]! - b[index]!;
-  }
-  return a.length - b.length;
-};
-
-const isWellFormedText = (value: string): boolean => {
-  for (const character of value) {
-    const point = character.codePointAt(0)!;
-    if (point >= 0xd800 && point <= 0xdfff) return false;
-  }
-  return true;
-};
-
-const isIdentity = (value: unknown): value is string =>
-  typeof value === "string" &&
-  value.length > 0 &&
-  value.length <= 255 &&
-  isWellFormedText(value);
-
-const isText = (value: unknown): value is string =>
-  typeof value === "string" && value.length > 0 && isWellFormedText(value);
-
-const isTimestamp = (value: unknown): value is number =>
-  typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
-
-const isLimit = (value: unknown): value is number =>
-  isTimestamp(value) && value >= 1 && value <= 101;
-
-const hasOnlyKeys = (
-  value: Readonly<Record<string, unknown>>,
-  keys: readonly string[],
-): boolean => Object.keys(value).every((key) => keys.includes(key));
-
-const hasScope = (value: Readonly<Record<string, unknown>>): boolean =>
-  (value.platform === "ios" || value.platform === "android") &&
-  isText(value.channel);
-
-const isBundleFilter = (value: unknown, withKind = false): boolean => {
-  if (!isRecord(value) || !hasScope(value)) return false;
-  const keys = ["platform", "channel", "type", ...(withKind ? ["kind"] : [])];
-  return value.type === "RECOVERED"
-    ? isText(value.fromBundleId) &&
-        hasOnlyKeys(value, [...keys, "fromBundleId"])
-    : (value.type === "UPDATE_DOWNLOADED" ||
-        value.type === "UPDATE_APPLIED" ||
-        value.type === "UPDATE_FAILED") &&
-        isText(value.toBundleId) &&
-        hasOnlyKeys(value, [...keys, "toBundleId"]);
-};
-
-const isEventFilter = (value: unknown): boolean => {
-  if (!isRecord(value)) return false;
-  if (value.kind === "all") return hasOnlyKeys(value, ["kind"]);
-  if (value.kind === "installationMovement") {
-    return (
-      isIdentity(value.installId) && hasOnlyKeys(value, ["kind", "installId"])
-    );
-  }
-  return value.kind === "bundle" && isBundleFilter(value, true);
-};
-
-const validateRow = (
-  model: "bundle_events",
-  row: unknown,
-  result = false,
-): void => {
-  try {
-    validateBundleEventFields(row);
-    if (
-      !isRecord(row) ||
-      typeof row.id !== "string" ||
-      !isUUIDv7(row.id) ||
-      [
-        ...Object.values(row),
-        ...(isRecord(row.metadata) ? Object.values(row.metadata) : []),
-      ].some((value) => typeof value === "string" && !isWellFormedText(value))
-    ) {
-      throw new DatabasePluginInputError("invalid-data");
-    }
-  } catch (error) {
-    if (result) throw new DatabasePluginInputError("invalid-result");
-    throw error;
-  }
-};
-
-/** Throws `invalid-data` unless `row` is a complete, well-formed bundle event row. */
-export const assertBundleEventRow = (row: unknown): void =>
-  validateRow("bundle_events", row);
-
-/** Downloads, applies, recoveries, and failed updates belong in installation history. */
-export const isInsightsMovementEvent = (
-  event: Pick<BundleEventRow, "type">,
-): boolean =>
-  event.type === "UPDATE_DOWNLOADED" ||
-  event.type === "UPDATE_APPLIED" ||
-  event.type === "RECOVERED" ||
-  event.type === "UPDATE_FAILED";
-
-export const matchesInsightsEventFilter = (
-  event: BundleEventRow,
-  filter: InsightsEventFilter,
-): boolean => {
-  if (filter.kind === "all") return true;
-  if (filter.kind === "installationMovement") {
-    return (
-      event.install_id === filter.installId && isInsightsMovementEvent(event)
-    );
-  }
-  // A failed check's `to_bundle_id` is the running bundle, not a target, so
-  // no bundle filter matches it.
-  return (
-    event.type === filter.type &&
-    event.platform === filter.platform &&
-    event.channel === filter.channel &&
-    (filter.type === "RECOVERED"
-      ? event.from_bundle_id === filter.fromBundleId
-      : event.to_bundle_id === filter.toBundleId &&
-        event.metadata.failure?.stage !== "check")
-  );
-};
-
-const invalidQuery = (): never => {
-  throw new DatabasePluginInputError("invalid-query");
-};
-const invalidResult = (): never => {
-  throw new DatabasePluginInputError("invalid-result");
-};
-const validateCount = (count: number): number =>
-  isTimestamp(count) ? count : invalidResult();
-
-const isTimeRange = (value: unknown): value is { start: number; end: number } =>
-  isRecord(value) &&
-  hasOnlyKeys(value, ["start", "end"]) &&
-  isTimestamp(value.start) &&
-  isTimestamp(value.end) &&
-  (value.start as number) < (value.end as number);
-
-const isReleaseReference = (value: unknown): boolean =>
-  isRecord(value) &&
-  hasOnlyKeys(value, ["releaseId", "platform", "channel"]) &&
-  isIdentity(value.releaseId) &&
-  hasScope(value);
-
-const validateAggregateResult = (value: unknown): void => {
-  const result = isRecord(value) ? value : invalidResult();
-  if (!isTimestamp(result.measuredAtMs)) invalidResult();
-  const coverage = result.coverage;
-  if (
-    !isRecord(coverage) ||
-    (coverage.kind !== "complete" && coverage.kind !== "partial") ||
-    (coverage.sinceMs !== null && !isTimestamp(coverage.sinceMs))
-  ) {
-    invalidResult();
-  }
-};
-
-/** Validate custom and bundled providers at the same public boundary. */
-export const createValidatedInsightsModel = (
-  model: InsightsModel,
-): InsightsModel => ({
-  async recordEvent(input) {
-    if (!isRecord(input) || !hasOnlyKeys(input, ["event"])) {
-      throw new DatabasePluginInputError("invalid-data");
-    }
-    validateRow("bundle_events", input.event);
-    await model.recordEvent(input);
-  },
-  async listEvents(input) {
-    if (
-      !isRecord(input) ||
-      !hasOnlyKeys(input, [
-        "filter",
-        "sinceMs",
-        "beforeReceivedAtMs",
-        "after",
-        "limit",
-      ]) ||
-      !isEventFilter(input.filter) ||
-      !isLimit(input.limit) ||
-      !isTimestamp(input.beforeReceivedAtMs) ||
-      (input.sinceMs !== undefined && !isTimestamp(input.sinceMs))
-    )
-      invalidQuery();
-    const sinceMs = input.sinceMs ?? 0;
-    if (
-      sinceMs > input.beforeReceivedAtMs ||
-      (input.after !== undefined &&
-        (!isRecord(input.after) ||
-          !hasOnlyKeys(input.after, ["receivedAtMs", "id"]) ||
-          !isTimestamp(input.after.receivedAtMs) ||
-          typeof input.after.id !== "string" ||
-          !isUUIDv7(input.after.id) ||
-          input.after.receivedAtMs < sinceMs ||
-          input.after.receivedAtMs >= input.beforeReceivedAtMs))
-    )
-      invalidQuery();
-    const rows = await model.listEvents(input);
-    if (!Array.isArray(rows) || rows.length > input.limit) invalidResult();
-    let previous = input.after;
-    for (const row of rows) {
-      validateRow("bundle_events", row, true);
-      if (
-        row.received_at_ms < sinceMs ||
-        row.received_at_ms >= input.beforeReceivedAtMs ||
-        !matchesInsightsEventFilter(row, input.filter) ||
-        (previous !== undefined &&
-          (row.received_at_ms > previous.receivedAtMs ||
-            (row.received_at_ms === previous.receivedAtMs &&
-              row.id >= previous.id)))
-      )
-        invalidResult();
-      previous = { receivedAtMs: row.received_at_ms, id: row.id };
-    }
-    return rows;
-  },
-  async findLatestEvents(input) {
-    if (!isRecord(input)) invalidQuery();
-    if ("installId" in input) {
-      if (!hasOnlyKeys(input, ["installId"]) || !isIdentity(input.installId))
-        invalidQuery();
-    } else if (
-      !hasOnlyKeys(input, ["userId", "afterInstallId", "limit"]) ||
-      !isIdentity(input.userId) ||
-      !isLimit(input.limit) ||
-      (input.afterInstallId !== undefined && !isIdentity(input.afterInstallId))
-    )
-      invalidQuery();
-    const rows = await model.findLatestEvents(input);
-    if (
-      !Array.isArray(rows) ||
-      rows.length > ("installId" in input ? 1 : input.limit)
-    )
-      invalidResult();
-    let previous = "installId" in input ? undefined : input.afterInstallId;
-    for (const row of rows) {
-      validateRow("bundle_events", row, true);
-      if (
-        "installId" in input
-          ? row.install_id !== input.installId
-          : row.user_id !== input.userId ||
-            (previous !== undefined &&
-              compareInsightsText(row.install_id, previous) <= 0)
-      )
-        invalidResult();
-      previous = row.install_id;
-    }
-    return rows;
-  },
-  async countLatestEvents(input) {
-    if (
-      !isRecord(input) ||
-      !hasOnlyKeys(input, ["platform", "channel", "sinceMs", "bundle"]) ||
-      !hasScope(input) ||
-      !isTimestamp(input.sinceMs) ||
-      (input.bundle !== undefined &&
-        (!Array.isArray(input.bundle) ||
-          input.bundle.length < 1 ||
-          input.bundle.length > 2 ||
-          input.bundle.some(
-            (bundle) =>
-              !isRecord(bundle) ||
-              !hasOnlyKeys(bundle, ["field", "value", "types"]) ||
-              (bundle.field !== "from_bundle_id" &&
-                bundle.field !== "to_bundle_id") ||
-              !isText(bundle.value) ||
-              !Array.isArray(bundle.types) ||
-              bundle.types.length === 0 ||
-              bundle.types.some(
-                (type) =>
-                  ![
-                    "UNCHANGED",
-                    "UPDATE_DOWNLOADED",
-                    "UPDATE_APPLIED",
-                    "RECOVERED",
-                  ].includes(type),
-              ),
-          )))
-    )
-      invalidQuery();
-    return validateCount(await model.countLatestEvents(input));
-  },
-  async countEvents(input) {
-    if (
-      !isRecord(input) ||
-      !hasOnlyKeys(input, ["filter", "sinceMs", "beforeReceivedAtMs"]) ||
-      !isBundleFilter(input.filter) ||
-      !isTimestamp(input.sinceMs) ||
-      !isTimestamp(input.beforeReceivedAtMs) ||
-      input.sinceMs > input.beforeReceivedAtMs
-    )
-      invalidQuery();
-    return validateCount(await model.countEvents(input));
-  },
-  async getReleaseActivity(input) {
-    if (
-      !isRecord(input) ||
-      !hasOnlyKeys(input, ["releases", "scope", "timeRange"])
-    ) {
-      invalidQuery();
-    }
-    const releases = input.releases;
-    const scope = input.scope;
-    const timeRange = input.timeRange;
-    const releaseQuery =
-      Array.isArray(releases) &&
-      releases.length > 0 &&
-      releases.length <= 100 &&
-      releases.every(isReleaseReference) &&
-      scope === undefined &&
-      (timeRange === undefined || isTimeRange(timeRange));
-    const scopeQuery =
-      releases === undefined &&
-      isRecord(scope) &&
-      hasOnlyKeys(scope, ["platform", "channel"]) &&
-      hasScope(scope) &&
-      isTimeRange(timeRange);
-    if (!releaseQuery && !scopeQuery) invalidQuery();
-    const result = await model.getReleaseActivity(input);
-    validateAggregateResult(result);
-    if (!Array.isArray(result.data)) invalidResult();
-    return result;
-  },
-  async getAppUsage(input) {
-    if (
-      !isRecord(input) ||
-      !hasOnlyKeys(input, [
-        "channel",
-        "platform",
-        "appVersion",
-        "timeRange",
-        "intervalMs",
-      ]) ||
-      !isText(input.channel) ||
-      !["all", "ios", "android"].includes(input.platform) ||
-      (input.appVersion !== undefined && !isText(input.appVersion)) ||
-      !isTimeRange(input.timeRange) ||
-      !isTimestamp(input.intervalMs) ||
-      input.intervalMs < 3_600_000
-    ) {
-      invalidQuery();
-    }
-    const result = await model.getAppUsage(input);
-    validateAggregateResult(result);
-    if (
-      !isTimestamp(result.activeInstallations) ||
-      !Array.isArray(result.points) ||
-      !Array.isArray(result.appVersions) ||
-      !Array.isArray(result.versions) ||
-      !Array.isArray(result.platforms) ||
-      !Array.isArray(result.bundleDistribution)
-    ) {
-      invalidResult();
-    }
-    return result;
-  },
-});