@hot-updater/server 0.31.4 → 0.33.0

package/src/db/updateArtifacts.ts

@@ -8,7 +8,10 @@ import {
   type Bundle,
   type ChangedAsset,
 } from "@hot-updater/core";
-import type { HotUpdaterContext } from "@hot-updater/plugin-core";
+import {
+  resolveManifestAssetStorageUri,
+  type HotUpdaterContext,
+} from "@hot-updater/plugin-core";
 
 type BundleManifest = {
   bundleId: string;
@@ -74,21 +77,6 @@ const isBundleManifest = (value: unknown): value is BundleManifest => {
   );
 };
 
-const createChildStorageUri = (
-  baseStorageUri: string,
-  relativePath: string,
-) => {
-  const baseUrl = new URL(baseStorageUri);
-  const normalizedBasePath = baseUrl.pathname.replace(/\/+$/, "");
-  const relativeSegments = relativePath
-    .split("/")
-    .filter(Boolean)
-    .map((segment) => encodeURIComponent(segment));
-
-  baseUrl.pathname = `${normalizedBasePath}/${relativeSegments.join("/")}`;
-  return baseUrl.toString();
-};
-
 export const parseBundleMetadata = (
   value: unknown,
 ): Bundle["metadata"] | undefined => {
@@ -213,10 +201,11 @@ async function resolveChangedAssets<TContext>({
 
       const usesBrotliAsset = BR_COMPRESSED_ASSET_PATH_RE.test(assetPath);
       const downloadPath = usesBrotliAsset ? `${assetPath}.br` : assetPath;
-      const storageUri = createChildStorageUri(
+      const storageUri = resolveManifestAssetStorageUri({
         assetBaseStorageUri,
-        downloadPath,
-      );
+        assetPath: downloadPath,
+        fileHash: asset.fileHash,
+      });
       const patch =
         patchDescriptor?.assetPath === assetPath ? patchDescriptor.patch : null;
 

package/src/handler-standalone.integration.spec.ts

@@ -34,6 +34,10 @@ const api = createHotUpdater({
     provider: "postgresql",
   }),
   basePath: "/hot-updater",
+  routes: {
+    updateCheck: true,
+    bundles: true,
+  },
 });
 
 // Setup MSW server to intercept HTTP requests
@@ -341,6 +345,10 @@ describe("Handler <-> Standalone Repository Integration", () => {
         provider: "postgresql",
       }),
       basePath: "/api/v2",
+      routes: {
+        updateCheck: true,
+        bundles: true,
+      },
     });
 
     // Setup MSW for custom basePath
@@ -411,6 +419,10 @@ describe("Handler <-> Standalone Repository Integration", () => {
     const blobApi = createHotUpdater({
       database: createInMemoryBlobDatabase(store),
       basePath: "/blob-hot-updater",
+      routes: {
+        updateCheck: true,
+        bundles: true,
+      },
     });
     const handleBlobRequest = async (request: Request) => {
       const response = await blobApi.handler(request);

package/src/handler.spec.ts

@@ -1,7 +1,7 @@
 import { type Bundle, NIL_UUID } from "@hot-updater/core";
 import { describe, expect, it, vi } from "vitest";
 
-import { createHandler, type HandlerAPI } from "./handler";
+import { createHandler, type HandlerAPI, type HandlerRoutes } from "./handler";
 import { HOT_UPDATER_SERVER_VERSION } from "./version";
 
 const NEXT_SDK_VERSION_FOR_TEST = "0.31.0";
@@ -51,6 +51,19 @@ const createApi = () =>
     deleteBundleById: vi.fn<HandlerAPI<TestContext>["deleteBundleById"]>(),
   }) satisfies HandlerAPI<TestContext>;
 
+const createManagementHandler = (
+  api: HandlerAPI<TestContext>,
+  routes: Partial<HandlerRoutes> = {},
+) =>
+  createHandler(api, {
+    basePath: "/hot-updater",
+    routes: {
+      updateCheck: true,
+      bundles: true,
+      ...routes,
+    },
+  });
+
 describe("createHandler", () => {
   it("supports the app-version route without a cohort segment", async () => {
     const api = createApi();
@@ -218,44 +231,113 @@ describe("createHandler", () => {
     expect(updateResponse.status).toBe(200);
   });
 
-  it("can disable the version route independently", async () => {
+  it("does not mount bundle routes by default", async () => {
+    const api = createApi();
+    const handler = createHandler(api, { basePath: "/hot-updater" });
+
+    const versionResponse = await handler(
+      new Request("http://localhost/hot-updater/version"),
+    );
+    const bundlesResponse = await handler(
+      new Request("http://localhost/hot-updater/api/bundles"),
+    );
+    const updateResponse = await handler(
+      new Request(
+        "http://localhost/hot-updater/app-version/ios/1.0.0/production/default/default",
+      ),
+    );
+
+    expect(versionResponse.status).toBe(200);
+    expect(bundlesResponse.status).toBe(404);
+    expect(updateResponse.status).toBe(200);
+  });
+
+  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 = createHandler(api, {
       basePath: "/hot-updater",
       routes: {
         updateCheck: true,
-        version: false,
-        bundles: false,
+        bundles: true,
       },
     });
 
-    const versionResponse = await handler(
-      new Request("http://localhost/hot-updater/version"),
-    );
-    const bundlesResponse = await handler(
+    const response = await handler(
       new Request("http://localhost/hot-updater/api/bundles"),
     );
+
+    expect(response.status).toBe(200);
+    expect(api.getBundles).toHaveBeenCalledWith(
+      {
+        cursor: undefined,
+        limit: 50,
+        page: undefined,
+        where: {},
+      },
+      undefined,
+    );
+  });
+
+  it("keeps update-check routes mounted for partial runtime route config", async () => {
+    const api = createApi();
+    const handler = createHandler(api, {
+      basePath: "/hot-updater",
+      routes: JSON.parse('{"bundles":true}') as HandlerRoutes,
+    });
+
     const updateResponse = await handler(
       new Request(
         "http://localhost/hot-updater/app-version/ios/1.0.0/production/default/default",
       ),
     );
 
-    expect(versionResponse.status).toBe(404);
-    expect(bundlesResponse.status).toBe(404);
     expect(updateResponse.status).toBe(200);
   });
 
-  it("can mount bundle routes without update-check routes", async () => {
+  it("keeps the version route mounted when update-check routes are disabled", async () => {
     const api = createApi();
     const handler = createHandler(api, {
       basePath: "/hot-updater",
       routes: {
         updateCheck: false,
-        bundles: true,
+        bundles: false,
       },
     });
 
+    const versionResponse = await handler(
+      new Request("http://localhost/hot-updater/version"),
+    );
+    const bundlesResponse = await handler(
+      new Request("http://localhost/hot-updater/api/bundles"),
+    );
+    const updateResponse = await handler(
+      new Request(
+        "http://localhost/hot-updater/app-version/ios/1.0.0/production/default/default",
+      ),
+    );
+
+    expect(versionResponse.status).toBe(200);
+    await expect(versionResponse.json()).resolves.toEqual({
+      version: HOT_UPDATER_SERVER_VERSION,
+    });
+    expect(bundlesResponse.status).toBe(404);
+    expect(updateResponse.status).toBe(404);
+  });
+
+  it("can mount bundle routes without update-check routes", async () => {
+    const api = createApi();
+    const handler = createManagementHandler(api, { updateCheck: false });
+
     const versionResponse = await handler(
       new Request("http://localhost/hot-updater/version"),
     );
@@ -294,7 +376,7 @@ describe("createHandler", () => {
         totalPages: 26,
       },
     });
-    const handler = createHandler(api, { basePath: "/hot-updater" });
+    const handler = createManagementHandler(api);
 
     const response = await handler(
       new Request(
@@ -339,7 +421,7 @@ describe("createHandler", () => {
         totalPages: 1,
       },
     });
-    const handler = createHandler(api, { basePath: "/hot-updater" });
+    const handler = createManagementHandler(api);
 
     const response = await handler(
       new Request(
@@ -382,7 +464,7 @@ describe("createHandler", () => {
         previousCursor: "bundle-9",
       },
     });
-    const handler = createHandler(api, { basePath: "/hot-updater" });
+    const handler = createManagementHandler(api);
 
     const response = await handler(
       new Request(
@@ -421,7 +503,7 @@ describe("createHandler", () => {
         previousCursor: null,
       },
     });
-    const handler = createHandler(api, { basePath: "/hot-updater" });
+    const handler = createManagementHandler(api);
 
     const response = await handler(
       new Request(
@@ -448,7 +530,7 @@ describe("createHandler", () => {
 
   it("returns 400 when bundle list requests still send offset pagination", async () => {
     const api = createApi();
-    const handler = createHandler(api, { basePath: "/hot-updater" });
+    const handler = createManagementHandler(api);
 
     const response = await handler(
       new Request(
@@ -478,7 +560,7 @@ describe("createHandler", () => {
         previousCursor: "bundle-9",
       },
     });
-    const handler = createHandler(api, { basePath: "/hot-updater" });
+    const handler = createManagementHandler(api);
 
     const response = await handler(
       new Request(
@@ -505,7 +587,7 @@ describe("createHandler", () => {
 
   it("returns 400 when bundle list requests send an invalid page", async () => {
     const api = createApi();
-    const handler = createHandler(api, { basePath: "/hot-updater" });
+    const handler = createManagementHandler(api);
 
     const response = await handler(
       new Request("http://localhost/hot-updater/api/bundles?limit=20&page=0"),
@@ -518,6 +600,22 @@ describe("createHandler", () => {
     expect(api.getBundles).not.toHaveBeenCalled();
   });
 
+  it("returns 400 when bundle list limit exceeds the maximum", async () => {
+    const api = createApi();
+    const handler = createManagementHandler(api);
+
+    const response = await handler(
+      new Request("http://localhost/hot-updater/api/bundles?limit=101"),
+    );
+
+    expect(response.status).toBe(400);
+    await expect(response.json()).resolves.toEqual({
+      error:
+        "The 'limit' query parameter must be a positive integer between 1 and 100.",
+    });
+    expect(api.getBundles).not.toHaveBeenCalled();
+  });
+
   it("returns 400 when the platform route parameter is invalid", async () => {
     const api = createApi();
     const handler = createHandler(api, { basePath: "/hot-updater" });

package/src/handler.ts

@@ -52,28 +52,27 @@ export interface HandlerOptions {
    * @default "/api"
    */
   basePath?: string;
+  /**
+   * Route groups to mount. Omit this option to use the default route groups.
+   * When provided, both route groups must be specified explicitly.
+   * The `/version` endpoint is always mounted for diagnostics.
+   */
   routes?: HandlerRoutes;
 }
 
 export interface HandlerRoutes {
   /**
    * Controls whether update-check routes are mounted.
-   * @default true
+   * Defaults to `true` only when `routes` is omitted.
    */
-  updateCheck?: boolean;
-  /**
-   * Controls whether the `/version` endpoint is mounted.
-   * Useful for diagnostics and lightweight health/version checks.
-   * @default true
-   */
-  version?: boolean;
+  updateCheck: boolean;
   /**
    * Controls whether bundle management routes are mounted.
    * This includes `/api/bundles*`, which are used by the
    * CLI `standaloneRepository` plugin.
-   * @default true
+   * Defaults to `false` only when `routes` is omitted.
    */
-  bundles?: boolean;
+  bundles: boolean;
 }
 
 type RouteHandler<TContext = unknown> = (
@@ -92,6 +91,8 @@ class HandlerBadRequestError extends Error {
 
 const SDK_VERSION_HEADER = "Hot-Updater-SDK-Version";
 const EXPLICIT_NO_UPDATE_MIN_SDK_VERSION = "0.31.0";
+const DEFAULT_BUNDLE_LIST_LIMIT = 50;
+const MAX_BUNDLE_LIST_LIMIT = 100;
 
 const supportsExplicitNoUpdateResponse = (request: Request) => {
   const sdkVersion = request.headers.get(SDK_VERSION_HEADER)?.trim();
@@ -191,6 +192,27 @@ const parseStringArraySearchParam = (url: URL, key: string) => {
   return values.length > 0 ? values : undefined;
 };
 
+const parsePositiveIntegerSearchParam = (
+  url: URL,
+  key: string,
+  defaultValue: number,
+  maxValue: number,
+): number => {
+  const value = url.searchParams.get(key);
+  if (value === null) {
+    return defaultValue;
+  }
+
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > maxValue) {
+    throw new HandlerBadRequestError(
+      `The '${key}' query parameter must be a positive integer between 1 and ${maxValue}.`,
+    );
+  }
+
+  return parsed;
+};
+
 const requirePlatformParam = (params: Record<string, string>): Platform => {
   const platform = requireRouteParam(params, "platform");
 
@@ -317,7 +339,12 @@ const handleGetBundles: RouteHandler = async (
   const url = new URL(request.url);
   const channel = url.searchParams.get("channel") ?? undefined;
   const platform = url.searchParams.get("platform");
-  const limit = Number(url.searchParams.get("limit")) || 50;
+  const limit = parsePositiveIntegerSearchParam(
+    url,
+    "limit",
+    DEFAULT_BUNDLE_LIST_LIMIT,
+    MAX_BUNDLE_LIST_LIMIT,
+  );
   const pageParam = url.searchParams.get("page");
   const offset = url.searchParams.get("offset");
   const after = url.searchParams.get("after") ?? undefined;
@@ -511,19 +538,18 @@ export function createHandler<TContext = unknown>(
   context?: HotUpdaterContext<TContext>,
 ) => Promise<Response> {
   const basePath = options.basePath ?? "/api";
-  const updateCheckEnabled = options.routes?.updateCheck ?? true;
-  const versionEnabled = options.routes?.version ?? true;
-  const bundlesEnabled = options.routes?.bundles ?? true;
+  const routeOptions = {
+    updateCheck: options.routes?.updateCheck ?? true,
+    bundles: options.routes?.bundles ?? false,
+  };
 
   // Create and configure router
   const router = createRouter();
 
   // Register routes
-  if (versionEnabled) {
-    addRoute(router, "GET", "/version", "version");
-  }
+  addRoute(router, "GET", "/version", "version");
 
-  if (updateCheckEnabled) {
+  if (routeOptions.updateCheck) {
     addRoute(
       router,
       "GET",
@@ -550,7 +576,7 @@ export function createHandler<TContext = unknown>(
     );
   }
 
-  if (bundlesEnabled) {
+  if (routeOptions.bundles) {
     addRoute(router, "GET", "/api/bundles/channels", "getChannels");
     addRoute(router, "GET", "/api/bundles/:id", "getBundle");
     addRoute(router, "GET", "/api/bundles", "getBundles");
@@ -583,8 +609,8 @@ export function createHandler<TContext = unknown>(
         });
       }
 
-      // Get handler and execute
-      const handler = routes[match.data as string] as RouteHandler<TContext>;
+      const routeName = match.data as string;
+      const handler = routes[routeName] as RouteHandler<TContext>;
       if (!handler) {
         return new Response(JSON.stringify({ error: "Handler not found" }), {
           status: 500,

package/src/runtime.spec.ts

@@ -80,6 +80,7 @@ describe("runtime createHotUpdater", () => {
         node: {
           delete: vi.fn(),
           downloadFile: vi.fn(),
+          exists: vi.fn(async () => false),
           upload: vi.fn(),
         },
       },
@@ -660,7 +661,7 @@ describe("runtime createHotUpdater", () => {
     });
   });
 
-  it("can disable the version route independently", async () => {
+  it("keeps the version route mounted when update-check routes are disabled", async () => {
     const database = createDatabasePlugin({
       name: "version-disabled-plugin",
       factory: () => ({
@@ -690,8 +691,7 @@ describe("runtime createHotUpdater", () => {
       database,
       basePath: "/api/check-update",
       routes: {
-        updateCheck: true,
-        version: false,
+        updateCheck: false,
         bundles: false,
       },
     });
@@ -700,7 +700,49 @@ describe("runtime createHotUpdater", () => {
       new Request("https://updates.example.com/api/check-update/version"),
     );
 
-    expect(response.status).toBe(404);
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toEqual({
+      version: HOT_UPDATER_SERVER_VERSION,
+    });
+  });
+
+  it("keeps optional maintenance capabilities lazy", () => {
+    const factory = vi.fn(() => ({
+      async getBundleById() {
+        return null;
+      },
+      async getBundles() {
+        return {
+          data: [],
+          pagination: {
+            hasNextPage: false,
+            hasPreviousPage: false,
+            currentPage: 1,
+            totalPages: 1,
+            total: 0,
+          },
+        };
+      },
+      async getChannels() {
+        return [];
+      },
+      async commitBundle() {},
+    }));
+    const database = createDatabasePlugin({
+      name: "lazyRuntimePlugin",
+      factory,
+    })({});
+
+    const hotUpdater = createHotUpdater({
+      database,
+      basePath: "/api/check-update",
+    });
+
+    expect(factory).not.toHaveBeenCalled();
+    expect(hotUpdater.diagnostics).toBeUndefined();
+    expect(factory).not.toHaveBeenCalled();
+    expect(hotUpdater.diagnostics).toBeUndefined();
+    expect(factory).not.toHaveBeenCalled();
   });
 
   it("clears pending plugin changes after a failed mutation commit", async () => {

package/src/runtime.ts

@@ -73,14 +73,10 @@ export function createHotUpdater<TContext = unknown>(
       : { readStorageText },
   );
 
-  const api = {
-    ...core.api,
-    handler: createHandler(core.api, {
-      basePath,
-      routes: options.routes,
-    }),
-    adapterName: core.adapterName,
-  };
+  const internalHandler = createHandler(core.api, {
+    basePath,
+    routes: options.routes,
+  });
 
   // Some framework adapters strip the mounted base path or pass extra
   // bindings/execution context arguments. Ignore those extras here so the
@@ -91,17 +87,19 @@ export function createHotUpdater<TContext = unknown>(
     ...extraArgs: unknown[]
   ) => {
     if (extraArgs.length > 0) {
-      return api.handler(request);
+      return internalHandler(request);
     }
 
-    return api.handler(request, context);
+    return internalHandler(request, context);
   };
 
-  return {
-    ...api,
+  const api = {
     basePath,
+    adapterName: core.adapterName,
     handler,
   };
+  Object.defineProperties(api, Object.getOwnPropertyDescriptors(core.api));
+  return api as HotUpdaterAPI<TContext>;
 }
 
 export { createHandler };