@hot-updater/server 0.36.6 → 1.0.0-rc.0

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 { createAnalyticsProvider } from "./analytics/bounded/provider";
+export type * from "./analytics/domain";
+export type { AnalyticsProvider } from "./analytics/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/node.spec.ts

@@ -4,14 +4,12 @@ import { toNodeHandler } from "./node";
 
 describe("server node entry", () => {
   it("converts a Web Request handler to Node middleware", async () => {
-    const hotUpdater = {
-      handler: async (request: Request) =>
-        Response.json({
-          method: request.method,
-          pathname: new URL(request.url).pathname,
-        }),
-    };
-    const middleware = toNodeHandler(hotUpdater);
+    const middleware = toNodeHandler(async (request: Request) =>
+      Response.json({
+        method: request.method,
+        pathname: new URL(request.url).pathname,
+      }),
+    );
     const headers = new Map<string, string | string[]>();
     const response = {
       body: "",
@@ -23,8 +21,8 @@ describe("server node entry", () => {
       setHeader(name: string, value: string | string[]) {
         headers.set(name, value);
       },
-      send(body: string) {
-        this.body = body;
+      send(body: Uint8Array) {
+        this.body = new TextDecoder().decode(body);
       },
       end() {},
     };
@@ -47,4 +45,75 @@ describe("server node entry", () => {
       pathname: "/api/check",
     });
   });
+
+  it("uses the mount-relative URL supplied by Express", async () => {
+    const middleware = toNodeHandler(async (request: Request) =>
+      Response.json({ pathname: new URL(request.url).pathname }),
+    );
+    const response = {
+      body: "",
+      statusCode: 0,
+      status(code: number) {
+        this.statusCode = code;
+        return this;
+      },
+      setHeader() {},
+      send(body: Uint8Array) {
+        this.body = new TextDecoder().decode(body);
+      },
+      end() {},
+    };
+
+    await middleware(
+      {
+        method: "GET",
+        url: "/channels",
+        headers: { host: "example.com" },
+        protocol: "https",
+        get: (name: string) => (name === "host" ? "example.com" : undefined),
+      },
+      response,
+    );
+
+    expect(JSON.parse(response.body)).toEqual({
+      pathname: "/channels",
+    });
+  });
+
+  it("preserves binary response bytes", async () => {
+    const bytes = new Uint8Array([0x50, 0x4b, 0x03, 0x04, 0xff, 0xfe, 0x00]);
+    const middleware = toNodeHandler(
+      async () =>
+        new Response(bytes, {
+          headers: { "content-type": "application/zip" },
+        }),
+    );
+    const response = {
+      body: new Uint8Array(),
+      statusCode: 0,
+      status(code: number) {
+        this.statusCode = code;
+        return this;
+      },
+      setHeader() {},
+      send(body: Uint8Array) {
+        this.body = new Uint8Array(body);
+      },
+      end() {},
+    };
+
+    await middleware(
+      {
+        method: "GET",
+        url: "/hot-updater/storage/token/signature",
+        headers: { host: "example.com" },
+        protocol: "https",
+        get: (name: string) => (name === "host" ? "example.com" : undefined),
+      },
+      response,
+    );
+
+    expect(response.statusCode).toBe(200);
+    expect([...response.body]).toEqual([...bytes]);
+  });
 });

package/src/node.ts

@@ -14,16 +14,13 @@ interface NodeRequest {
 interface NodeResponse {
   status(code: number): NodeResponse;
   setHeader(name: string, value: string | string[]): void;
-  send(body: string): void;
+  send(body: string | Uint8Array): void;
   end(): void;
   [key: string]: unknown;
 }
 
-type HandlerHotUpdaterAPI = {
-  readonly handler: (request: Request) => Promise<Response>;
-};
-
 export { HOT_UPDATER_SERVER_VERSION } from "./version";
+export { HOT_UPDATER_INFRASTRUCTURE_GENERATION } from "./handlerVersionRoutes";
 
 /**
  * Converts a Hot Updater handler to a Node.js-compatible middleware
@@ -36,22 +33,28 @@ export { HOT_UPDATER_SERVER_VERSION } from "./version";
  *
  * const app = express();
  *
- * // Mount middleware
- * app.use(express.json());
- *
- * // Mount hot-updater handler
- * app.all("/hot-updater/*", toNodeHandler(hotUpdater));
+ * app.use(
+ *   "/hot-updater/admin",
+ *   bearerMiddleware,
+ *   express.json({ limit: "1mb" }),
+ *   toNodeHandler(hotUpdater.handlers.admin),
+ * );
+ * app.use(
+ *   "/hot-updater",
+ *   express.json({ limit: "1mb" }),
+ *   toNodeHandler(hotUpdater.handlers.client),
+ * );
  * ```
  */
 export function toNodeHandler(
-  hotUpdater: HandlerHotUpdaterAPI,
+  handler: HotUpdaterHandler,
 ): (req: any, res: any, next?: any) => Promise<void> {
   return async (req: NodeRequest, res: NodeResponse) => {
     try {
       // Build full URL
       const protocol = req.protocol || "http";
       const host = req.get?.("host") || "localhost";
-      const url = `${protocol}://${host}${req.url || "/"}`;
+      const url = `${protocol}://${host}${req.url ?? "/"}`;
 
       // Convert headers to Web Headers
       const headers = new Headers();
@@ -80,8 +83,7 @@ export function toNodeHandler(
         body,
       });
 
-      // Call hot-updater handler
-      const response = await hotUpdater.handler(webRequest);
+      const response = await handler(webRequest);
 
       // Set status code
       res.status(response.status);
@@ -92,9 +94,9 @@ export function toNodeHandler(
       });
 
       // Send response body
-      const text = await response.text();
-      if (text) {
-        res.send(text);
+      const responseBody = Buffer.from(await response.arrayBuffer());
+      if (responseBody.length > 0) {
+        res.send(responseBody);
       } else {
         res.end();
       }
@@ -106,3 +108,4 @@ export function toNodeHandler(
     }
   };
 }
+import type { HotUpdaterHandler } from "./handlerTypes";