@hot-updater/server 0.36.7 → 1.0.0-rc.1

package/src/handlerReleaseCatalogRoutes.ts

@@ -0,0 +1,154 @@
+import type { ReleaseCatalog } from "@hot-updater/core";
+import { canonicalizeAppVersion } from "@hot-updater/plugin-core";
+
+import { requirePlatformParam, requireRouteParam } from "./handlerParameters";
+import type { RouteHandler } from "./handlerTypes";
+
+const CATALOG_CONTENT_TYPE =
+  "application/vnd.hot-updater.release-catalog+json; version=1";
+const ORIGIN_CACHE_TTL_MS = 5_000;
+const ORIGIN_CACHE_MAX_ENTRIES = 128;
+
+const privateNotFound = (): Response =>
+  Response.json(
+    { error: "Not found" },
+    {
+      status: 404,
+      headers: { "cache-control": "private, no-store" },
+    },
+  );
+
+const responseHash = async (body: string): Promise<string> => {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(body),
+  );
+  return [...new Uint8Array(digest)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+};
+
+const catalogResponse = async (
+  catalog: ReleaseCatalog | null,
+  request: Request,
+  clientAccessHeaderName: string,
+): Promise<Response> => {
+  if (catalog === null) return privateNotFound();
+  const body = JSON.stringify(catalog);
+  const etag = `"sha256:${await responseHash(body)}"`;
+  const headers = {
+    "cache-control": "public, max-age=0, s-maxage=5",
+    "content-type": CATALOG_CONTENT_TYPE,
+    etag,
+    vary: `Accept-Encoding, ${clientAccessHeaderName}`,
+  };
+  if (request.headers.get("if-none-match") === etag) {
+    return new Response(null, { headers, status: 304 });
+  }
+  return new Response(body, { headers, status: 200 });
+};
+
+export const createReleaseCatalogRouteHandlers = (
+  clientAccessHeaderName = "x-api-key",
+): Record<string, RouteHandler> => {
+  const cache = new Map<
+    string,
+    { readonly catalog: ReleaseCatalog; readonly expiresAt: number }
+  >();
+  const inFlight = new Map<string, Promise<ReleaseCatalog | null>>();
+  const loadCatalog = async (
+    key: string,
+    load: () => Promise<ReleaseCatalog | null>,
+  ): Promise<ReleaseCatalog | null> => {
+    const cached = cache.get(key);
+    if (cached !== undefined && cached.expiresAt > Date.now()) {
+      cache.delete(key);
+      cache.set(key, cached);
+      return cached.catalog;
+    }
+    if (cached !== undefined) cache.delete(key);
+    const pending = inFlight.get(key);
+    if (pending !== undefined) return pending;
+
+    const next = load().then((catalog) => {
+      if (catalog !== null) {
+        cache.set(key, {
+          catalog,
+          expiresAt: Date.now() + ORIGIN_CACHE_TTL_MS,
+        });
+        while (cache.size > ORIGIN_CACHE_MAX_ENTRIES) {
+          const oldestKey = cache.keys().next().value as string | undefined;
+          if (oldestKey === undefined) break;
+          cache.delete(oldestKey);
+        }
+      }
+      return catalog;
+    });
+    inFlight.set(key, next);
+    try {
+      return await next;
+    } finally {
+      inFlight.delete(key);
+    }
+  };
+
+  return {
+    appVersionReleaseCatalog: async (params, request, api) => {
+      if (api.getReleaseCatalog === undefined) return privateNotFound();
+      const rawAppVersion = requireRouteParam(params, "appVersion");
+      const appVersion = canonicalizeAppVersion(rawAppVersion);
+      if (appVersion === null || appVersion !== rawAppVersion) {
+        return Response.json(
+          { error: "Invalid app version" },
+          { status: 400, headers: { "cache-control": "private, no-store" } },
+        );
+      }
+      const input = {
+        appVersion,
+        channelKey: requireRouteParam(params, "channelKey"),
+        platform: requirePlatformParam(params),
+        strategy: "APP_VERSION",
+      } as const;
+      return catalogResponse(
+        await loadCatalog(`app-version:${JSON.stringify(input)}`, () =>
+          api.getReleaseCatalog!(input),
+        ),
+        request,
+        clientAccessHeaderName,
+      );
+    },
+
+    fingerprintReleaseCatalog: async (params, request, api) => {
+      if (api.getReleaseCatalog === undefined) return privateNotFound();
+      const input = {
+        channelKey: requireRouteParam(params, "channelKey"),
+        fingerprintHash: requireRouteParam(params, "fingerprintHash"),
+        platform: requirePlatformParam(params),
+        strategy: "FINGERPRINT",
+      } as const;
+      return catalogResponse(
+        await loadCatalog(`fingerprint:${JSON.stringify(input)}`, () =>
+          api.getReleaseCatalog!(input),
+        ),
+        request,
+        clientAccessHeaderName,
+      );
+    },
+
+    artifact: async (params, _request, api) => {
+      if (api.getArtifactInfo === undefined) return privateNotFound();
+      const info = await api.getArtifactInfo(
+        requireRouteParam(params, "targetBundleId"),
+        requireRouteParam(params, "currentBundleId"),
+      );
+      if (info === null) return privateNotFound();
+      return new Response(JSON.stringify(info), {
+        status: 200,
+        headers: {
+          "cache-control": "private, no-store",
+          "content-type": "application/json",
+        },
+      });
+    },
+  };
+};

package/src/handlerReleaseManagementRoutes.ts

@@ -0,0 +1,213 @@
+import {
+  ReleaseCatalogMutationError,
+  ReleaseManagementError,
+  type DatabaseCommit,
+  type ReleasePolicyPatch,
+} from "@hot-updater/plugin-core";
+
+import { HandlerBadRequestError } from "./handlerErrors";
+import { decodeMaybe, requireRouteParam } from "./handlerParameters";
+import type { RouteHandler } from "./handlerTypes";
+
+const unavailable = (): Response =>
+  Response.json({ error: "Not found" }, { status: 404 });
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const parseRevision = (value: unknown): number | undefined => {
+  if (value === undefined || value === null || value === "") return undefined;
+  const revision = typeof value === "number" ? value : Number(value);
+  if (!Number.isSafeInteger(revision) || revision < 1) {
+    throw new HandlerBadRequestError("Invalid expected Release revision");
+  }
+  return revision;
+};
+
+const parsePolicyInput = async (
+  request: Request,
+): Promise<{
+  readonly expectedRevision?: number;
+  readonly patch: ReleasePolicyPatch;
+}> => {
+  const body: unknown = await request.json();
+  if (!isRecord(body) || !isRecord(body.patch)) {
+    throw new HandlerBadRequestError("Invalid Release policy mutation");
+  }
+  return {
+    expectedRevision: parseRevision(body.expectedRevision),
+    patch: body.patch as ReleasePolicyPatch,
+  };
+};
+
+const mutationResponse = async <T>(operation: () => Promise<T>) => {
+  try {
+    return Response.json({ data: await operation() });
+  } catch (error) {
+    if (
+      error instanceof ReleaseManagementError ||
+      error instanceof ReleaseCatalogMutationError
+    ) {
+      const status =
+        error.code === "RELEASE_NOT_FOUND"
+          ? 404
+          : error.code === "VERSION_CONFLICT"
+            ? 409
+            : 400;
+      return Response.json(
+        { code: error.code, error: error.message },
+        { status },
+      );
+    }
+    throw error;
+  }
+};
+
+export const createReleaseManagementRouteHandlers = (): Record<
+  string,
+  RouteHandler
+> => ({
+  getRelease: async (params, _request, api) => {
+    if (api.getReleaseById === undefined) return unavailable();
+    const row = await api.getReleaseById(requireRouteParam(params, "id"));
+    return row === null
+      ? unavailable()
+      : Response.json({ data: row }, { status: 200 });
+  },
+
+  getReleases: async (_params, request, api) => {
+    const url = new URL(request.url);
+    const scopeKey = url.searchParams.get("scopeKey");
+    const limit = Number(url.searchParams.get("limit") ?? "100");
+    if (!Number.isSafeInteger(limit) || limit <= 0 || limit > 1000) {
+      throw new HandlerBadRequestError("Invalid Release scope query");
+    }
+    if (scopeKey !== null) {
+      if (scopeKey.length === 0 || api.getReleasesByScope === undefined) {
+        throw new HandlerBadRequestError("Invalid Release scope query");
+      }
+      const afterReleaseId =
+        url.searchParams.get("afterReleaseId") ?? undefined;
+      return Response.json({
+        data: await api.getReleasesByScope({
+          ...(afterReleaseId === undefined ? {} : { afterReleaseId }),
+          limit,
+          scopeKey,
+        }),
+      });
+    }
+    if (api.getReleases === undefined) return unavailable();
+    const enabledValue = url.searchParams.get("enabled");
+    const enabled =
+      enabledValue === null
+        ? undefined
+        : enabledValue === "true"
+          ? true
+          : enabledValue === "false"
+            ? false
+            : null;
+    const platformValue = url.searchParams.get("platform");
+    const platform =
+      platformValue === null
+        ? undefined
+        : platformValue === "ios" || platformValue === "android"
+          ? platformValue
+          : null;
+    if (enabled === null || platform === null) {
+      throw new HandlerBadRequestError("Invalid Release list filter");
+    }
+    return Response.json({
+      data: await api.getReleases({
+        afterReleaseId: url.searchParams.get("afterReleaseId") ?? undefined,
+        beforeReleaseId: url.searchParams.get("beforeReleaseId") ?? undefined,
+        bundleId: url.searchParams.get("bundleId") ?? undefined,
+        channelId: url.searchParams.get("channelId") ?? undefined,
+        enabled,
+        limit,
+        platform,
+        targetAppVersion: url.searchParams.get("targetAppVersion") ?? undefined,
+      }),
+    });
+  },
+
+  getReleaseCatalogRow: async (params, _request, api) => {
+    if (api.getReleaseCatalogByScopeKey === undefined) return unavailable();
+    const row = await api.getReleaseCatalogByScopeKey(
+      decodeMaybe(requireRouteParam(params, "scopeKey")) ?? "",
+    );
+    return row === null
+      ? unavailable()
+      : Response.json({ data: row }, { status: 200 });
+  },
+
+  getReleaseCatalogs: async (_params, request, api) => {
+    if (api.getReleaseCatalogs === undefined) return unavailable();
+    const url = new URL(request.url);
+    const limit = Number(url.searchParams.get("limit") ?? "100");
+    if (!Number.isSafeInteger(limit) || limit <= 0 || limit > 1000) {
+      throw new HandlerBadRequestError("Invalid Release catalog list query");
+    }
+    return Response.json({
+      data: await api.getReleaseCatalogs({
+        afterScopeKey: url.searchParams.get("afterScopeKey") ?? undefined,
+        limit,
+      }),
+    });
+  },
+
+  updateRelease: async (params, request, api) => {
+    if (api.updateReleasePolicy === undefined) return unavailable();
+    const input = await parsePolicyInput(request);
+    return mutationResponse(() =>
+      api.updateReleasePolicy!({
+        ...input,
+        releaseId: requireRouteParam(params, "id"),
+      }),
+    );
+  },
+
+  preflightRelease: async (params, request, api) => {
+    if (api.preflightReleasePolicy === undefined) return unavailable();
+    const input = await parsePolicyInput(request);
+    return mutationResponse(() =>
+      api.preflightReleasePolicy!({
+        ...input,
+        releaseId: requireRouteParam(params, "id"),
+      }),
+    );
+  },
+
+  deleteRelease: async (params, request, api) => {
+    if (api.deleteRelease === undefined) return unavailable();
+    const releaseId = requireRouteParam(params, "id");
+    const url = new URL(request.url);
+    if (url.searchParams.get("confirm") !== releaseId) {
+      throw new HandlerBadRequestError(
+        "Release hard deletion requires confirm=<release-id>",
+      );
+    }
+    return mutationResponse(() =>
+      api.deleteRelease!({
+        expectedRevision: parseRevision(
+          url.searchParams.get("expectedRevision"),
+        ),
+        releaseId,
+      }),
+    );
+  },
+
+  rebuildReleaseCatalog: async (params, _request, api) => {
+    if (api.rebuildReleaseCatalog === undefined) return unavailable();
+    return mutationResponse(() =>
+      api.rebuildReleaseCatalog!(
+        decodeMaybe(requireRouteParam(params, "scopeKey")) ?? "",
+      ),
+    );
+  },
+
+  commitDatabase: async (_params, request, api) => {
+    if (api.commitDatabase === undefined) return unavailable();
+    const input = (await request.json()) as DatabaseCommit;
+    return Response.json({ data: await api.commitDatabase(input) });
+  },
+});

package/src/handlerTypes.ts

@@ -0,0 +1,96 @@
+import type { ArtifactInfo, Bundle, ReleaseCatalog } from "@hot-updater/core";
+import type {
+  ChannelDeleteInput,
+  ChannelDeleteResult,
+  ChannelInsertInput,
+  ChannelInsertResult,
+  ChannelRow,
+  DatabaseBundleQueryOptions,
+  DatabaseCommit,
+  DatabaseCommitResult,
+  ReleaseCatalogRow,
+  ReleaseCatalogMutationPreflight,
+  ReleaseCatalogMutationResult,
+  ReleaseCatalogRebuildResult,
+  ReleasePolicyPatch,
+  ReleaseRow,
+} from "@hot-updater/plugin-core";
+
+import type { ReleaseCatalogRequest } from "./db/releaseCatalog";
+import type { PaginatedResult } from "./types";
+
+export interface HandlerAPI {
+  getReleaseCatalog?: (
+    input: ReleaseCatalogRequest,
+  ) => Promise<ReleaseCatalog | null>;
+  getArtifactInfo?: (
+    targetBundleId: string,
+    currentBundleId: string,
+  ) => Promise<ArtifactInfo | null>;
+  getReleaseById?: (id: string) => Promise<ReleaseRow | null>;
+  getReleasesByScope?: (input: {
+    readonly scopeKey: string;
+    readonly afterReleaseId?: string;
+    readonly limit: number;
+  }) => Promise<readonly ReleaseRow[]>;
+  getReleases?: (input: {
+    readonly afterReleaseId?: string;
+    readonly beforeReleaseId?: string;
+    readonly bundleId?: string;
+    readonly channelId?: string;
+    readonly enabled?: boolean;
+    readonly platform?: "ios" | "android";
+    readonly targetAppVersion?: string;
+    readonly limit: number;
+  }) => Promise<readonly ReleaseRow[]>;
+  getReleaseCatalogByScopeKey?: (
+    scopeKey: string,
+  ) => Promise<ReleaseCatalogRow | null>;
+  getReleaseCatalogs?: (input: {
+    readonly afterScopeKey?: string;
+    readonly limit: number;
+  }) => Promise<readonly ReleaseCatalogRow[]>;
+  updateReleasePolicy?: (input: {
+    readonly expectedRevision?: number;
+    readonly patch: ReleasePolicyPatch;
+    readonly releaseId: string;
+  }) => Promise<ReleaseCatalogMutationResult>;
+  preflightReleasePolicy?: (input: {
+    readonly expectedRevision?: number;
+    readonly patch: ReleasePolicyPatch;
+    readonly releaseId: string;
+  }) => Promise<ReleaseCatalogMutationPreflight>;
+  deleteRelease?: (input: {
+    readonly expectedRevision?: number;
+    readonly releaseId: string;
+  }) => Promise<ReleaseCatalogMutationResult>;
+  rebuildReleaseCatalog?: (
+    scopeKey: string,
+  ) => Promise<ReleaseCatalogRebuildResult>;
+  commitDatabase?: (input: DatabaseCommit) => Promise<DatabaseCommitResult>;
+  getBundleById: (id: string) => Promise<Bundle | null>;
+  getBundles: (options: DatabaseBundleQueryOptions) => Promise<PaginatedResult>;
+  insertBundle: (bundle: Bundle) => Promise<void>;
+  insertBundles?: (bundles: readonly Bundle[]) => Promise<void>;
+  updateBundleById: (
+    bundleId: string,
+    bundle: Partial<Bundle>,
+  ) => Promise<void>;
+  deleteBundleById: (bundleId: string) => Promise<void>;
+  getChannels: () => Promise<readonly ChannelRow[]>;
+  insertChannel: (input: ChannelInsertInput) => Promise<ChannelInsertResult>;
+  deleteChannel: (input: ChannelDeleteInput) => Promise<ChannelDeleteResult>;
+}
+
+export type HotUpdaterHandler = (request: Request) => Promise<Response>;
+
+export interface HotUpdaterHandlers {
+  readonly client: HotUpdaterHandler;
+  readonly admin: HotUpdaterHandler;
+}
+
+export type RouteHandler = (
+  params: Record<string, string>,
+  request: Request,
+  api: HandlerAPI,
+) => Promise<Response>;

package/src/handlerVersionRoutes.ts

@@ -0,0 +1,12 @@
+import type { RouteHandler } from "./handlerTypes";
+import { HOT_UPDATER_SERVER_VERSION } from "./version";
+
+export const HOT_UPDATER_INFRASTRUCTURE_GENERATION = 1;
+
+export const createVersionRouteHandlers = (): Record<string, RouteHandler> => ({
+  version: async () =>
+    Response.json({
+      infrastructureGeneration: HOT_UPDATER_INFRASTRUCTURE_GENERATION,
+      version: HOT_UPDATER_SERVER_VERSION,
+    }),
+});

package/src/index.ts

@@ -1,10 +1,30 @@
-export { createHandler } from "./handler";
-export type { HandlerAPI, HandlerOptions, HandlerRoutes } from "./handler";
+export { createHandlers } from "./handler";
+export type {
+  HandlerAPI,
+  HotUpdaterHandler,
+  HotUpdaterHandlers,
+} from "./handler";
+export { createInsightsProvider } from "./insights/bounded/provider";
+export type * from "./insights/domain";
+export type { InsightsProvider } from "./insights/types";
+export {
+  API_KEY_HEADER_NAME,
+  createApiKey,
+  provisionApiKey,
+  registerApiKey,
+} from "./apiKeys";
+export type {
+  ApiKeyManagementAPI,
+  ApiKeyMetadata,
+  CreatedApiKey,
+} from "./apiKeys";
 export { createHotUpdater } from "./createHotUpdaterCore";
 export type {
+  ClientAccessPolicy,
   CreateHotUpdaterOptions,
   HotUpdaterAPI,
   RuntimeHotUpdaterAPI,
 } from "./createHotUpdaterCore";
 export * from "./types";
 export { HOT_UPDATER_SERVER_VERSION } from "./version";
+export { HOT_UPDATER_INFRASTRUCTURE_GENERATION } from "./handlerVersionRoutes";

package/src/insights/bounded/activeOverview.spec.ts

@@ -0,0 +1,189 @@
+import { describe, expect, it } from "vitest";
+
+import type { BundleEventPersistenceRow } from "../persistence";
+import { collectActiveInstallationOverview } from "./activeOverview";
+
+const HOUR_MS = 60 * 60 * 1_000;
+const DAY_MS = 24 * HOUR_MS;
+
+type EventRowOptions = {
+  readonly id: string;
+  readonly receivedAtMs: number;
+  readonly installId?: string;
+  readonly userId?: string | null;
+  readonly bundleId?: string;
+};
+
+type SeriesWindow = {
+  readonly startMs: number;
+  readonly bucketCount: number;
+  readonly bucketSizeMs: number;
+};
+
+function eventRow(options: EventRowOptions): BundleEventPersistenceRow {
+  return {
+    id: options.id,
+    type: "UPDATE_APPLIED",
+    install_id: options.installId ?? `install-${options.id}`,
+    user_id: options.userId ?? null,
+    username: null,
+    from_release_id: null,
+    from_bundle_id: "old",
+    to_release_id: null,
+    to_bundle_id: options.bundleId ?? "new",
+    platform: "ios",
+    app_version: "1.0.0",
+    channel: "production",
+    cohort: "default",
+    update_strategy: "fingerprint",
+    fingerprint_hash: null,
+    sdk_version: null,
+    received_at_ms: options.receivedAtMs,
+  };
+}
+
+function expectedSeries(
+  window: SeriesWindow,
+  values: Readonly<Record<number, number>>,
+): { readonly bucketStartMs: number; readonly value: number }[] {
+  return Array.from({ length: window.bucketCount }, (_, index) => ({
+    bucketStartMs: window.startMs + index * window.bucketSizeMs,
+    value: values[index] ?? 0,
+  }));
+}
+
+describe("collectActiveInstallationOverview", () => {
+  it("uses the strict window and latest installation rows for a user", () => {
+    const asOfMs = 100 * HOUR_MS;
+    const windowStartMs = asOfMs - 24 * HOUR_MS;
+    const window = {
+      startMs: windowStartMs,
+      bucketCount: 24,
+      bucketSizeMs: HOUR_MS,
+    } as const;
+    const rows = [
+      eventRow({
+        id: "a-start",
+        receivedAtMs: windowStartMs,
+        installId: "install-a",
+        userId: "user-a",
+        bundleId: "bundle-b",
+      }),
+      eventRow({
+        id: "a-latest",
+        receivedAtMs: asOfMs - 1,
+        installId: "install-a",
+        userId: "user-a",
+        bundleId: "bundle-a",
+      }),
+      eventRow({
+        id: "before-window",
+        receivedAtMs: windowStartMs - 1,
+        userId: "user-a",
+      }),
+      eventRow({
+        id: "at-cutoff",
+        receivedAtMs: asOfMs,
+        userId: "user-a",
+      }),
+      eventRow({
+        id: "tie-a",
+        receivedAtMs: asOfMs - HOUR_MS,
+        installId: "install-tie",
+        userId: "user-a",
+        bundleId: "bundle-b",
+      }),
+      eventRow({
+        id: "tie-z",
+        receivedAtMs: asOfMs - HOUR_MS,
+        installId: "install-tie",
+        userId: "user-a",
+        bundleId: "bundle-c",
+      }),
+      eventRow({
+        id: "changed-user-old",
+        receivedAtMs: windowStartMs,
+        installId: "install-changed-user",
+        userId: "user-a",
+      }),
+      eventRow({
+        id: "changed-user-new",
+        receivedAtMs: asOfMs - 1,
+        installId: "install-changed-user",
+        userId: "user-b",
+      }),
+    ];
+
+    expect(
+      collectActiveInstallationOverview({
+        rows,
+        asOfMs,
+        window: "24h",
+        userId: "user-a",
+      }),
+    ).toEqual({
+      asOfMs,
+      window: "24h",
+      activeInstallations: 2,
+      series: expectedSeries(window, { 0: 1, 23: 2 }),
+      bundleSeries: [
+        {
+          bundleId: "bundle-a",
+          series: expectedSeries(window, { 23: 1 }),
+        },
+        {
+          bundleId: "bundle-b",
+          series: expectedSeries(window, { 0: 1 }),
+        },
+        {
+          bundleId: "bundle-c",
+          series: expectedSeries(window, { 23: 1 }),
+        },
+      ],
+      bundles: [
+        { bundleId: "bundle-a", installations: 1 },
+        { bundleId: "bundle-c", installations: 1 },
+      ],
+    });
+  });
+
+  it("includes installations with any user when the filter is omitted", () => {
+    const asOfMs = 10 * DAY_MS;
+    const windowStartMs = asOfMs - 7 * DAY_MS;
+    const window = {
+      startMs: windowStartMs,
+      bucketCount: 7,
+      bucketSizeMs: DAY_MS,
+    } as const;
+    const rows = [
+      eventRow({
+        id: "user-a",
+        receivedAtMs: windowStartMs,
+        userId: "user-a",
+        bundleId: "bundle-b",
+      }),
+      eventRow({
+        id: "anonymous",
+        receivedAtMs: asOfMs - 1,
+        bundleId: "bundle-a",
+      }),
+    ];
+
+    const result = collectActiveInstallationOverview({
+      rows,
+      asOfMs,
+      window: "7d",
+    });
+
+    expect(result.activeInstallations).toBe(2);
+    expect(result.series).toEqual(expectedSeries(window, { 0: 1, 6: 1 }));
+    expect(result.bundles).toEqual([
+      { bundleId: "bundle-a", installations: 1 },
+      { bundleId: "bundle-b", installations: 1 },
+    ]);
+    expect(result.bundleSeries.map(({ bundleId }) => bundleId)).toEqual([
+      "bundle-a",
+      "bundle-b",
+    ]);
+  });
+});