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

package/src/handlerAuth.integration.spec.ts

@@ -0,0 +1,33 @@
+import { Hono } from "hono";
+import { bearerAuth } from "hono/bearer-auth";
+import { describe, expect, it } from "vitest";
+
+import { createInMemoryDatabasePlugin } from "../../test-utils/test/inMemoryDatabasePlugin";
+import { createHotUpdater } from "./index";
+
+describe("framework-owned admin authentication", () => {
+  it("protects admin without affecting the client handler", async () => {
+    const hotUpdater = createHotUpdater({
+      database: createInMemoryDatabasePlugin(),
+      clientAccess: { type: "public" },
+    });
+    const adminToken = "test-management-token";
+    const app = new Hono();
+    app.use("/hot-updater/admin/*", bearerAuth({ token: adminToken }));
+    app.mount("/hot-updater/admin", hotUpdater.handlers.admin);
+    app.mount("/hot-updater", hotUpdater.handlers.client);
+
+    const clientResponse = await app.request("/hot-updater/version");
+    const unauthorizedAdmin = await app.request("/hot-updater/admin/channels");
+    const authorizedAdmin = await app.request("/hot-updater/admin/channels", {
+      headers: { Authorization: `Bearer ${adminToken}` },
+    });
+
+    expect(clientResponse.status).toBe(200);
+    expect(unauthorizedAdmin.status).toBe(401);
+    expect(authorizedAdmin.status).toBe(200);
+    expect(authorizedAdmin.headers.get("cache-control")).toBe(
+      "private, no-store",
+    );
+  });
+});

package/src/handlerBundleRoutes.ts

@@ -0,0 +1,259 @@
+import type { Bundle } from "@hot-updater/core";
+import type { ChannelInsertInput } from "@hot-updater/plugin-core";
+
+import { HandlerBadRequestError } from "./handlerErrors";
+import {
+  decodeMaybe,
+  isPlatform,
+  parsePositiveIntegerSearchParam,
+  parseStringArraySearchParam,
+  requireRouteParam,
+} from "./handlerParameters";
+import type { RouteHandler } from "./handlerTypes";
+import type { ChannelsResponse } from "./types";
+
+const BUNDLE_LIST_BOUNDS = { defaultValue: 50, maxValue: 100 } as const;
+
+const isChannelText = (value: unknown): value is string => {
+  if (typeof value !== "string" || value.length === 0) return false;
+  let codePoints = 0;
+  for (const _codePoint of value) {
+    codePoints += 1;
+    if (codePoints > 255) return false;
+  }
+  return true;
+};
+
+const requireChannelInsertInput = (value: unknown): ChannelInsertInput => {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    !("row" in value) ||
+    !value.row ||
+    typeof value.row !== "object" ||
+    Array.isArray(value.row) ||
+    !("id" in value.row) ||
+    !isChannelText(value.row.id) ||
+    !("name" in value.row) ||
+    !isChannelText(value.row.name) ||
+    !("onConflict" in value) ||
+    value.onConflict !== "returnExisting"
+  ) {
+    throw new HandlerBadRequestError("Invalid Channel insert payload");
+  }
+  return {
+    row: { id: value.row.id, name: value.row.name },
+    onConflict: value.onConflict,
+  };
+};
+
+type BundlePatchPayload = Partial<Bundle> & { readonly id?: string };
+
+const requireBundlePatchPayload = (
+  payload: unknown,
+  bundleId: string,
+): Partial<Bundle> => {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new HandlerBadRequestError("Invalid bundle payload");
+  }
+  const bundlePatch = payload as BundlePatchPayload;
+  if (bundlePatch.id !== undefined && bundlePatch.id !== bundleId) {
+    throw new HandlerBadRequestError("Bundle id mismatch");
+  }
+  const { id: _ignoredId, ...rest } = bundlePatch;
+  return rest;
+};
+
+export const createBundleRouteHandlers = (): Record<string, RouteHandler> => ({
+  getBundle: async (params, _request, api) => {
+    const bundle = await api.getBundleById(requireRouteParam(params, "id"));
+    if (!bundle) {
+      return new Response(JSON.stringify({ error: "Bundle not found" }), {
+        status: 404,
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+    return new Response(JSON.stringify(bundle), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  },
+
+  getBundles: async (_params, request, api) => {
+    const url = new URL(request.url);
+    const platform = url.searchParams.get("platform");
+    const limit = parsePositiveIntegerSearchParam(
+      url,
+      "limit",
+      BUNDLE_LIST_BOUNDS,
+    );
+    const pageParam = url.searchParams.get("page");
+    const offset = url.searchParams.get("offset");
+    const after = url.searchParams.get("after") ?? undefined;
+    const before = url.searchParams.get("before") ?? undefined;
+    const orderDirection = url.searchParams.get("orderDirection");
+    const idEq = url.searchParams.get("idEq") ?? undefined;
+    const idGt = url.searchParams.get("idGt") ?? undefined;
+    const idGte = url.searchParams.get("idGte") ?? undefined;
+    const idLt = url.searchParams.get("idLt") ?? undefined;
+    const idLte = url.searchParams.get("idLte") ?? undefined;
+    const idIn = parseStringArraySearchParam(url, "idIn");
+    const page =
+      pageParam === null
+        ? undefined
+        : Number.isSafeInteger(Number(pageParam)) &&
+            Number(pageParam) > 0 &&
+            Number.isSafeInteger((Number(pageParam) - 1) * limit)
+          ? Number(pageParam)
+          : null;
+    if (offset !== null) {
+      throw new HandlerBadRequestError(
+        "The 'offset' query parameter has been removed. Use 'after' or 'before' cursor pagination instead.",
+      );
+    }
+    if (page === null) {
+      throw new HandlerBadRequestError(
+        "The 'page' query parameter must be a positive integer.",
+      );
+    }
+    if (after !== undefined && before !== undefined) {
+      throw new HandlerBadRequestError(
+        "The 'after' and 'before' query parameters cannot be combined.",
+      );
+    }
+    if (page !== undefined && (after !== undefined || before !== undefined)) {
+      throw new HandlerBadRequestError(
+        "The 'page' query parameter cannot be combined with 'after' or 'before'.",
+      );
+    }
+    if (platform !== null && !isPlatform(platform)) {
+      throw new HandlerBadRequestError(
+        `Invalid platform: ${platform}. Expected 'ios' or 'android'.`,
+      );
+    }
+    if (
+      orderDirection !== null &&
+      orderDirection !== "asc" &&
+      orderDirection !== "desc"
+    ) {
+      throw new HandlerBadRequestError(
+        "The 'orderDirection' query parameter must be 'asc' or 'desc'.",
+      );
+    }
+    const cursor =
+      after !== undefined
+        ? { after }
+        : before !== undefined
+          ? { before }
+          : undefined;
+    const pagination =
+      page === undefined
+        ? { cursor, page: undefined }
+        : { cursor: undefined, page };
+    const result = await api.getBundles({
+      where: {
+        ...(platform && { platform }),
+        ...(idEq || idGt || idGte || idLt || idLte || idIn?.length
+          ? {
+              id: {
+                ...(idEq && { eq: idEq }),
+                ...(idGt && { gt: idGt }),
+                ...(idGte && { gte: idGte }),
+                ...(idLt && { lt: idLt }),
+                ...(idLte && { lte: idLte }),
+                ...(idIn?.length && { in: idIn }),
+              },
+            }
+          : {}),
+      },
+      limit,
+      ...pagination,
+      ...(orderDirection && {
+        orderBy: { field: "id", direction: orderDirection },
+      }),
+    });
+    return new Response(JSON.stringify(result), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  },
+
+  createBundles: async (_params, request, api) => {
+    const body = await request.json();
+    const bundles = Array.isArray(body) ? body : [body];
+    if (api.insertBundles) {
+      await api.insertBundles(bundles as Bundle[]);
+    } else {
+      if (bundles.length > 1) {
+        throw new HandlerBadRequestError(
+          "This server does not support atomic bundle batches",
+        );
+      }
+      const bundle = bundles[0];
+      if (bundle !== undefined) {
+        await api.insertBundle(bundle as Bundle);
+      }
+    }
+    return new Response(JSON.stringify({ success: true }), {
+      status: 201,
+      headers: { "Content-Type": "application/json" },
+    });
+  },
+
+  updateBundle: async (params, request, api) => {
+    const bundleId = requireRouteParam(params, "id");
+    const body = await request.json();
+    const payload = Array.isArray(body) ? body[0] : body;
+    await api.updateBundleById(
+      bundleId,
+      requireBundlePatchPayload(payload, bundleId),
+    );
+    return new Response(JSON.stringify({ success: true }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  },
+
+  deleteBundle: async (params, _request, api) => {
+    await api.deleteBundleById(requireRouteParam(params, "id"));
+    return new Response(JSON.stringify({ success: true }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  },
+
+  getChannels: async (_params, _request, api) => {
+    const response: ChannelsResponse = {
+      data: { channels: await api.getChannels() },
+    };
+    return new Response(JSON.stringify(response), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  },
+
+  createChannel: async (_params, request, api) => {
+    const result = await api.insertChannel(
+      requireChannelInsertInput(await request.json()),
+    );
+    return new Response(JSON.stringify({ data: result }), {
+      status: result.inserted ? 201 : 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  },
+
+  deleteChannel: async (params, _request, api) => {
+    const result = await api.deleteChannel({
+      id: decodeMaybe(requireRouteParam(params, "id")) ?? "",
+    });
+    if (result.deleted) {
+      return new Response(null, { status: 204 });
+    }
+    const status = result.reason === "not_found" ? 404 : 409;
+    return new Response(JSON.stringify({ data: result }), {
+      status,
+      headers: { "Content-Type": "application/json" },
+    });
+  },
+});

package/src/handlerErrors.ts

@@ -0,0 +1,7 @@
+export class HandlerBadRequestError extends Error {
+  readonly name = "HandlerBadRequestError";
+
+  constructor(message: string) {
+    super(message);
+  }
+}

package/src/handlerManagement.spec.ts

@@ -0,0 +1,262 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  createApi,
+  createAdminHandler,
+  testBundle,
+} from "./handler.testFixtures";
+
+describe("createHandlers admin routes", () => {
+  it("does not match client routes", async () => {
+    const api = createApi();
+    const handler = createAdminHandler(api);
+    const response = await handler(new Request("http://localhost/version"));
+
+    expect(response.status).toBe(404);
+  });
+
+  it("exposes the canonical Channel-row route and removes the legacy path", async () => {
+    const api = createApi();
+    const handler = createAdminHandler(api);
+
+    const response = await handler(new Request("http://localhost/channels"));
+    const legacyResponse = await handler(
+      new Request("http://localhost/bundles/channels"),
+    );
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toEqual({
+      data: {
+        channels: [{ id: "channel-production", name: "production" }],
+      },
+    });
+    expect(legacyResponse.status).toBe(404);
+  });
+
+  it("returns 201 when the canonical route inserts a Channel", async () => {
+    const api = createApi();
+    api.insertChannel.mockResolvedValueOnce({
+      row: { id: "candidate-id", name: "preview" },
+      inserted: true,
+    });
+    const handler = createAdminHandler(api);
+
+    const response = await handler(
+      new Request("http://localhost/channels", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          row: { id: "candidate-id", name: "preview" },
+          onConflict: "returnExisting",
+        }),
+      }),
+    );
+
+    expect(response.status).toBe(201);
+    await expect(response.json()).resolves.toEqual({
+      data: {
+        row: { id: "candidate-id", name: "preview" },
+        inserted: true,
+      },
+    });
+  });
+
+  it("returns the canonical row when a Channel already exists", async () => {
+    const api = createApi();
+    api.insertChannel.mockResolvedValueOnce({
+      row: { id: "canonical-id", name: "preview" },
+      inserted: false,
+    });
+    const handler = createAdminHandler(api);
+
+    const response = await handler(
+      new Request("http://localhost/channels", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          row: { id: "candidate-id", name: "preview" },
+          onConflict: "returnExisting",
+        }),
+      }),
+    );
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toEqual({
+      data: {
+        row: { id: "canonical-id", name: "preview" },
+        inserted: false,
+      },
+    });
+    expect(api.insertChannel).toHaveBeenCalledWith({
+      row: { id: "candidate-id", name: "preview" },
+      onConflict: "returnExisting",
+    });
+  });
+
+  it.each([
+    { row: { name: "preview" } },
+    { row: { id: "", name: "preview" }, onConflict: "returnExisting" },
+    { row: { id: "channel-preview", name: "" }, onConflict: "returnExisting" },
+    {
+      row: { id: "channel-preview", name: "x".repeat(256) },
+      onConflict: "returnExisting",
+    },
+  ])(
+    "rejects malformed Channel insert input before persistence",
+    async (body) => {
+      const api = createApi();
+      const handler = createAdminHandler(api);
+
+      const response = await handler(
+        new Request("http://localhost/channels", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(body),
+        }),
+      );
+
+      expect(response.status).toBe(400);
+      expect(api.insertChannel).not.toHaveBeenCalled();
+    },
+  );
+
+  it("returns no content after deleting an empty Channel", async () => {
+    const api = createApi();
+    api.deleteChannel.mockResolvedValueOnce({ deleted: true });
+    const handler = createAdminHandler(api);
+
+    const response = await handler(
+      new Request("http://localhost/channels/channel-preview", {
+        method: "DELETE",
+      }),
+    );
+
+    expect(response.status).toBe(204);
+    await expect(response.text()).resolves.toBe("");
+  });
+
+  it.each([
+    [{ deleted: false, reason: "not_found" } as const, 404],
+    [{ deleted: false, reason: "not_empty" } as const, 409],
+  ])("maps Channel deletion result %j to HTTP %i", async (result, status) => {
+    const api = createApi();
+    api.deleteChannel.mockResolvedValueOnce(result);
+    const handler = createAdminHandler(api);
+
+    const response = await handler(
+      new Request("http://localhost/channels/channel-preview", {
+        method: "DELETE",
+      }),
+    );
+
+    expect(response.status).toBe(status);
+    await expect(response.json()).resolves.toEqual({ data: result });
+    expect(api.deleteChannel).toHaveBeenCalledWith({ id: "channel-preview" });
+  });
+
+  it("mounts bundle routes when explicitly enabled", async () => {
+    const api = createApi();
+    api.getBundles.mockResolvedValueOnce({
+      data: [],
+      pagination: {
+        total: 0,
+        hasNextPage: false,
+        hasPreviousPage: false,
+        currentPage: 1,
+        totalPages: 0,
+      },
+    });
+    const handler = createAdminHandler(api);
+    const response = await handler(new Request("http://localhost/bundles"));
+
+    expect(response.status).toBe(200);
+    expect(api.getBundles).toHaveBeenCalledWith({
+      cursor: undefined,
+      limit: 50,
+      page: undefined,
+      where: {},
+    });
+  });
+
+  it("forwards an explicit bundle id order direction", async () => {
+    const api = createApi();
+    const handler = createAdminHandler(api);
+
+    const response = await handler(
+      new Request("http://localhost/bundles?orderDirection=asc"),
+    );
+
+    expect(response.status).toBe(200);
+    expect(api.getBundles).toHaveBeenCalledWith({
+      cursor: undefined,
+      limit: 50,
+      orderBy: { field: "id", direction: "asc" },
+      page: undefined,
+      where: {},
+    });
+  });
+
+  it("does not treat Release policy query parameters as Bundle filters", async () => {
+    const api = createApi();
+    const handler = createAdminHandler(api);
+
+    const response = await handler(
+      new Request(
+        "http://localhost/bundles?channel=production&enabled=true&targetAppVersion=1.0.0&fingerprintHash=abc",
+      ),
+    );
+
+    expect(response.status).toBe(200);
+    expect(api.getBundles).toHaveBeenCalledWith({
+      cursor: undefined,
+      limit: 50,
+      page: undefined,
+      where: {},
+    });
+  });
+
+  it("rejects an invalid bundle id order direction", async () => {
+    const api = createApi();
+    const handler = createAdminHandler(api);
+
+    const response = await handler(
+      new Request("http://localhost/bundles?orderDirection=random"),
+    );
+
+    expect(response.status).toBe(400);
+    expect(api.getBundles).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    "after=bundle-2&before=bundle-4",
+    "page=2&after=bundle-2",
+    "page=2&before=bundle-4",
+    `page=${Number.MAX_SAFE_INTEGER}`,
+  ])("rejects invalid pagination parameters: %s", async (query) => {
+    const api = createApi();
+    const handler = createAdminHandler(api);
+
+    const response = await handler(
+      new Request(`http://localhost/bundles?${query}`),
+    );
+
+    expect(response.status).toBe(400);
+    expect(api.getBundles).not.toHaveBeenCalled();
+  });
+
+  it("rejects a bundle batch before mutation when atomic insertion is unavailable", async () => {
+    const api = createApi();
+    const handler = createAdminHandler(api);
+
+    const response = await handler(
+      new Request("http://localhost/bundles", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify([testBundle, { ...testBundle, id: "bundle-2" }]),
+      }),
+    );
+
+    expect(response.status).toBe(400);
+    expect(api.insertBundle).not.toHaveBeenCalled();
+  });
+});

package/src/handlerParameters.ts

@@ -0,0 +1,105 @@
+import type { Platform } from "@hot-updater/core";
+
+import { HandlerBadRequestError } from "./handlerErrors";
+
+type PositiveIntegerBounds = {
+  readonly defaultValue: number;
+  readonly maxValue: number;
+};
+
+export const decodeMaybe = (value: string | undefined): string | undefined => {
+  if (value === undefined) return undefined;
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+};
+
+export const isPlatform = (value: string): value is Platform =>
+  value === "ios" || value === "android";
+
+export const requireRouteParam = (
+  params: Record<string, string>,
+  key: string,
+): string => {
+  const value = params[key];
+  if (!value) {
+    throw new HandlerBadRequestError(`Missing route parameter: ${key}`);
+  }
+  return value;
+};
+
+export const requirePlatformParam = (
+  params: Record<string, string>,
+): Platform => {
+  const platform = requireRouteParam(params, "platform");
+  if (!isPlatform(platform)) {
+    throw new HandlerBadRequestError(
+      `Invalid platform: ${platform}. Expected 'ios' or 'android'.`,
+    );
+  }
+  return platform;
+};
+
+export const parseBooleanSearchParam = (
+  url: URL,
+  key: string,
+): boolean | undefined => {
+  const value = url.searchParams.get(key);
+  if (value === null) return undefined;
+  if (value === "true") return true;
+  if (value === "false") return false;
+  throw new HandlerBadRequestError(
+    `The '${key}' query parameter must be 'true' or 'false'.`,
+  );
+};
+
+export const parseNullableStringSearchParam = (
+  url: URL,
+  key: string,
+): string | null | undefined => {
+  const value = url.searchParams.get(key);
+  if (value === null) return undefined;
+  return value === "null" ? null : value;
+};
+
+export const parseStringArraySearchParam = (
+  url: URL,
+  key: string,
+): string[] | undefined => {
+  const values = url.searchParams.getAll(key);
+  return values.length > 0 ? values : undefined;
+};
+
+export const parsePositiveIntegerSearchParam = (
+  url: URL,
+  key: string,
+  bounds: PositiveIntegerBounds,
+): number => {
+  const value = url.searchParams.get(key);
+  if (value === null) return bounds.defaultValue;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > bounds.maxValue) {
+    throw new HandlerBadRequestError(
+      `The '${key}' query parameter must be a positive integer between 1 and ${bounds.maxValue}.`,
+    );
+  }
+  return parsed;
+};
+
+export const parseNonNegativeIntegerSearchParam = (
+  url: URL,
+  key: string,
+  defaultValue: number,
+): number => {
+  const value = url.searchParams.get(key);
+  if (value === null) return defaultValue;
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 0) {
+    throw new HandlerBadRequestError(
+      `The '${key}' query parameter must be a non-negative integer.`,
+    );
+  }
+  return parsed;
+};