@hot-updater/server 0.30.12 → 0.31.0

package/src/handler.ts

@@ -1,4 +1,5 @@
 import type {
+  AppUpdateAvailableInfo,
   AppUpdateInfo,
   AppVersionGetBundlesArgs,
   Bundle,
@@ -9,6 +10,7 @@ import type {
   DatabaseBundleQueryOptions,
   HotUpdaterContext,
 } from "@hot-updater/plugin-core";
+import semver from "semver";
 
 import { addRoute, createRouter, findRoute } from "./internalRouter";
 import type { ChannelsResponse, PaginatedResult } from "./types";
@@ -19,7 +21,7 @@ export interface HandlerAPI<TContext = unknown> {
   getAppUpdateInfo: (
     args: AppVersionGetBundlesArgs | FingerprintGetBundlesArgs,
     context?: HotUpdaterContext<TContext>,
-  ) => Promise<AppUpdateInfo | null>;
+  ) => Promise<AppUpdateAvailableInfo | null>;
   getBundleById: (
     id: string,
     context?: HotUpdaterContext<TContext>,
@@ -88,6 +90,37 @@ class HandlerBadRequestError extends Error {
   }
 }
 
+const SDK_VERSION_HEADER = "Hot-Updater-SDK-Version";
+const EXPLICIT_NO_UPDATE_MIN_SDK_VERSION = "0.31.0";
+
+const supportsExplicitNoUpdateResponse = (request: Request) => {
+  const sdkVersion = request.headers.get(SDK_VERSION_HEADER)?.trim();
+  if (!sdkVersion) {
+    return false;
+  }
+
+  const normalizedSdkVersion = semver.valid(sdkVersion);
+  return (
+    normalizedSdkVersion !== null &&
+    semver.gte(normalizedSdkVersion, EXPLICIT_NO_UPDATE_MIN_SDK_VERSION)
+  );
+};
+
+const serializeUpdateInfo = (
+  updateInfo: AppUpdateAvailableInfo | null,
+  request: Request,
+): string => {
+  if (updateInfo) {
+    return JSON.stringify(updateInfo satisfies AppUpdateInfo);
+  }
+
+  if (supportsExplicitNoUpdateResponse(request)) {
+    return JSON.stringify({ status: "UP_TO_DATE" } satisfies AppUpdateInfo);
+  }
+
+  return JSON.stringify(null);
+};
+
 // Route handlers
 const handleVersion: RouteHandler = async () => {
   return new Response(JSON.stringify({ version: HOT_UPDATER_SERVER_VERSION }), {
@@ -121,6 +154,43 @@ const requireRouteParam = (
   return value;
 };
 
+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'.`,
+  );
+};
+
+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;
+};
+
+const parseStringArraySearchParam = (url: URL, key: string) => {
+  const values = url.searchParams.getAll(key);
+  return values.length > 0 ? values : undefined;
+};
+
 const requirePlatformParam = (params: Record<string, string>): Platform => {
   const platform = requireRouteParam(params, "platform");
 
@@ -156,7 +226,7 @@ const requireBundlePatchPayload = (
 
 const handleFingerprintUpdateWithCohort: RouteHandler = async (
   params,
-  _request,
+  request,
   api,
   context,
 ) => {
@@ -179,7 +249,7 @@ const handleFingerprintUpdateWithCohort: RouteHandler = async (
     context,
   );
 
-  return new Response(JSON.stringify(updateInfo), {
+  return new Response(serializeUpdateInfo(updateInfo, request), {
     status: 200,
     headers: { "Content-Type": "application/json" },
   });
@@ -187,7 +257,7 @@ const handleFingerprintUpdateWithCohort: RouteHandler = async (
 
 const handleAppVersionUpdateWithCohort: RouteHandler = async (
   params,
-  _request,
+  request,
   api,
   context,
 ) => {
@@ -210,7 +280,7 @@ const handleAppVersionUpdateWithCohort: RouteHandler = async (
     context,
   );
 
-  return new Response(JSON.stringify(updateInfo), {
+  return new Response(serializeUpdateInfo(updateInfo, request), {
     status: 200,
     headers: { "Content-Type": "application/json" },
   });
@@ -252,6 +322,29 @@ const handleGetBundles: RouteHandler = async (
   const offset = url.searchParams.get("offset");
   const after = url.searchParams.get("after") ?? undefined;
   const before = url.searchParams.get("before") ?? undefined;
+  const enabled = parseBooleanSearchParam(url, "enabled");
+  const targetAppVersion = parseNullableStringSearchParam(
+    url,
+    "targetAppVersion",
+  );
+  const targetAppVersionIn = parseStringArraySearchParam(
+    url,
+    "targetAppVersionIn",
+  );
+  const targetAppVersionNotNull = parseBooleanSearchParam(
+    url,
+    "targetAppVersionNotNull",
+  );
+  const fingerprintHash = parseNullableStringSearchParam(
+    url,
+    "fingerprintHash",
+  );
+  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
@@ -282,6 +375,25 @@ const handleGetBundles: RouteHandler = async (
       where: {
         ...(channel && { channel }),
         ...(platform && { platform }),
+        ...(enabled !== undefined && { enabled }),
+        ...(idEq || idGt || idGte || idLt || idLte || (idIn && idIn.length > 0)
+          ? {
+              id: {
+                ...(idEq && { eq: idEq }),
+                ...(idGt && { gt: idGt }),
+                ...(idGte && { gte: idGte }),
+                ...(idLt && { lt: idLt }),
+                ...(idLte && { lte: idLte }),
+                ...(idIn && idIn.length > 0 && { in: idIn }),
+              },
+            }
+          : {}),
+        ...(targetAppVersion !== undefined && { targetAppVersion }),
+        ...(targetAppVersionIn && { targetAppVersionIn }),
+        ...(targetAppVersionNotNull !== undefined && {
+          targetAppVersionNotNull,
+        }),
+        ...(fingerprintHash !== undefined && { fingerprintHash }),
       },
       limit,
       page,

package/src/runtime.spec.ts

@@ -3,7 +3,8 @@ import { NIL_UUID } from "@hot-updater/core";
 import type {
   DatabasePlugin,
   RequestEnvContext,
-  StoragePlugin,
+  RuntimeStoragePlugin,
+  RuntimeStorageProfile,
 } from "@hot-updater/plugin-core";
 import { createDatabasePlugin } from "@hot-updater/plugin-core";
 import { describe, expect, expectTypeOf, it, vi } from "vitest";
@@ -31,7 +32,71 @@ type TestEnv = {
 
 type TestContext = RequestEnvContext<TestEnv>;
 
+const createRuntimeStorage = (
+  getDownloadUrl: RuntimeStorageProfile<TestContext>["getDownloadUrl"],
+  readText: RuntimeStorageProfile<TestContext>["readText"] = async () => null,
+): RuntimeStoragePlugin<TestContext> => ({
+  name: "testStorage",
+  supportedProtocol: "s3",
+  profiles: {
+    runtime: {
+      getDownloadUrl,
+      readText,
+    },
+  },
+});
+
 describe("runtime createHotUpdater", () => {
+  it("requires storages to implement the runtime profile", () => {
+    const database: DatabasePlugin<TestContext> = {
+      name: "testDatabase",
+      async appendBundle() {},
+      async commitBundle() {},
+      async deleteBundle() {},
+      async getBundleById() {
+        return null;
+      },
+      async getBundles() {
+        return {
+          data: [],
+          pagination: {
+            currentPage: 1,
+            hasNextPage: false,
+            hasPreviousPage: false,
+            total: 0,
+            totalPages: 0,
+          },
+        };
+      },
+      async getChannels() {
+        return [];
+      },
+      async updateBundle() {},
+    };
+    const nodeOnlyStorage = {
+      name: "nodeOnlyStorage",
+      supportedProtocol: "s3",
+      profiles: {
+        node: {
+          delete: vi.fn(),
+          downloadFile: vi.fn(),
+          upload: vi.fn(),
+        },
+      },
+    };
+
+    expect(() =>
+      createHotUpdater({
+        database,
+        storages: [
+          nodeOnlyStorage as unknown as RuntimeStoragePlugin<TestContext>,
+        ],
+      }),
+    ).toThrow(
+      'nodeOnlyStorage does not implement the runtime storage profile for protocol "s3".',
+    );
+  });
+
   it("resolves storage URLs with handler context when database fast-path is used", async () => {
     const request = new Request(
       "https://updates.example.com/api/check-update/app-version/ios/1.0.0/production/" +
@@ -48,13 +113,13 @@ describe("runtime createHotUpdater", () => {
       status: "UPDATE",
       storageUri: bundle.storageUri,
     }));
-    const getDownloadUrl = vi.fn<StoragePlugin<TestContext>["getDownloadUrl"]>(
-      async (_storageUri, context) => {
-        return {
-          fileUrl: new URL("/bundle.zip", context?.env?.assetHost).toString(),
-        };
-      },
-    );
+    const getDownloadUrl = vi.fn<
+      RuntimeStorageProfile<TestContext>["getDownloadUrl"]
+    >(async (_storageUri, context) => {
+      return {
+        fileUrl: new URL("/bundle.zip", context?.env?.assetHost).toString(),
+      };
+    });
 
     const database: DatabasePlugin<TestContext> = {
       name: "testDatabase",
@@ -72,15 +137,7 @@ describe("runtime createHotUpdater", () => {
       async onUnmount() {},
       async updateBundle() {},
     };
-    const storage: StoragePlugin<TestContext> = {
-      name: "testStorage",
-      supportedProtocol: "s3",
-      async upload(key) {
-        return { storageUri: `s3://test-bucket/${key}` };
-      },
-      async delete() {},
-      getDownloadUrl,
-    };
+    const storage = createRuntimeStorage(getDownloadUrl);
 
     const hotUpdater = createHotUpdater({
       database,
@@ -156,13 +213,13 @@ describe("runtime createHotUpdater", () => {
         };
       },
     );
-    const getDownloadUrl = vi.fn<StoragePlugin<TestContext>["getDownloadUrl"]>(
-      async (_storageUri, context) => {
-        return {
-          fileUrl: new URL("/bundle.zip", context?.env?.assetHost).toString(),
-        };
-      },
-    );
+    const getDownloadUrl = vi.fn<
+      RuntimeStorageProfile<TestContext>["getDownloadUrl"]
+    >(async (_storageUri, context) => {
+      return {
+        fileUrl: new URL("/bundle.zip", context?.env?.assetHost).toString(),
+      };
+    });
 
     const database: DatabasePlugin<TestContext> = {
       name: "testDatabase",
@@ -179,15 +236,7 @@ describe("runtime createHotUpdater", () => {
       async onUnmount() {},
       async updateBundle() {},
     };
-    const storage: StoragePlugin<TestContext> = {
-      name: "testStorage",
-      supportedProtocol: "s3",
-      async upload(key) {
-        return { storageUri: `s3://test-bucket/${key}` };
-      },
-      async delete() {},
-      getDownloadUrl,
-    };
+    const storage = createRuntimeStorage(getDownloadUrl);
 
     const hotUpdater = createHotUpdater({
       database,
@@ -239,6 +288,205 @@ describe("runtime createHotUpdater", () => {
     );
   });
 
+  it("returns bsdiff patch metadata when the full asset fallback URL is unavailable", async () => {
+    const currentManifestStorageUri =
+      "s3://test-bucket/releases/00000000-0000-0000-0000-000000000001/manifest.json";
+    const nextManifestStorageUri =
+      "s3://test-bucket/releases/00000000-0000-0000-0000-000000000002/manifest.json";
+    const currentBundle: Bundle = {
+      ...bundle,
+      id: "00000000-0000-0000-0000-000000000001",
+      assetBaseStorageUri:
+        "s3://test-bucket/releases/00000000-0000-0000-0000-000000000001/files",
+      manifestFileHash: "sig:current-manifest",
+      manifestStorageUri: currentManifestStorageUri,
+      storageUri:
+        "s3://test-bucket/releases/00000000-0000-0000-0000-000000000001/bundle.zip",
+    };
+    const nextBundle: Bundle = {
+      ...bundle,
+      id: "00000000-0000-0000-0000-000000000002",
+      assetBaseStorageUri:
+        "s3://test-bucket/releases/00000000-0000-0000-0000-000000000002/files",
+      manifestFileHash: "sig:next-manifest",
+      manifestStorageUri: nextManifestStorageUri,
+      patches: [
+        {
+          baseBundleId: currentBundle.id,
+          baseFileHash: "hash-old-bundle",
+          patchFileHash: "hash-bsdiff",
+          patchStorageUri:
+            "s3://test-bucket/releases/00000000-0000-0000-0000-000000000002/patches/00000000-0000-0000-0000-000000000001/index.ios.bundle.bsdiff",
+        },
+      ],
+      storageUri:
+        "s3://test-bucket/releases/00000000-0000-0000-0000-000000000002/bundle.zip",
+    };
+    const request = new Request(
+      "https://updates.example.com/api/check-update/app-version/ios/1.0.0/production/" +
+        `${NIL_UUID}/${currentBundle.id}`,
+    );
+    const getBundles = vi.fn<DatabasePlugin<TestContext>["getBundles"]>(
+      async () => ({
+        data: [nextBundle],
+        pagination: {
+          hasNextPage: false,
+          hasPreviousPage: false,
+          currentPage: 1,
+          totalPages: 1,
+          total: 1,
+        },
+      }),
+    );
+    const getDownloadUrl = vi.fn<
+      RuntimeStorageProfile<TestContext>["getDownloadUrl"]
+    >(async (storageUri, context) => {
+      if (storageUri.endsWith("/files/index.ios.bundle")) {
+        throw new Error("full asset fallback is unavailable");
+      }
+
+      const storageUrl = new URL(storageUri);
+      return {
+        fileUrl: new URL(
+          storageUrl.pathname,
+          context?.env?.assetHost,
+        ).toString(),
+      };
+    });
+    const manifests = new Map([
+      [
+        currentManifestStorageUri,
+        JSON.stringify({
+          assets: {
+            "assets/logo.png": {
+              fileHash: "hash-logo",
+            },
+            "index.ios.bundle": {
+              fileHash: "hash-old-bundle",
+            },
+          },
+          bundleId: currentBundle.id,
+        }),
+      ],
+      [
+        nextManifestStorageUri,
+        JSON.stringify({
+          assets: {
+            "assets/logo.png": {
+              fileHash: "hash-logo",
+            },
+            "index.ios.bundle": {
+              fileHash: "hash-new-bundle",
+            },
+          },
+          bundleId: nextBundle.id,
+        }),
+      ],
+    ]);
+    const readText = vi.fn<RuntimeStorageProfile<TestContext>["readText"]>(
+      async (storageUri) => manifests.get(storageUri) ?? null,
+    );
+    const fetchMock = vi.fn<typeof fetch>(async () => {
+      return new Response("manifest fetch should not be used", {
+        status: 500,
+      });
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const database: DatabasePlugin<TestContext> = {
+      name: "testDatabase",
+      async appendBundle() {},
+      async commitBundle() {},
+      async deleteBundle() {},
+      async getBundleById(id) {
+        if (id === currentBundle.id) {
+          return currentBundle;
+        }
+        if (id === nextBundle.id) {
+          return nextBundle;
+        }
+        return null;
+      },
+      getBundles,
+      async getChannels() {
+        return ["production"];
+      },
+      async onUnmount() {},
+      async updateBundle() {},
+    };
+    const storage = createRuntimeStorage(getDownloadUrl, readText);
+
+    try {
+      const hotUpdater = createHotUpdater({
+        database,
+        storages: [storage],
+        basePath: "/api/check-update",
+        routes: {
+          updateCheck: true,
+          bundles: false,
+        },
+      });
+
+      const response = await hotUpdater.handler(request, {
+        env: {
+          assetHost: "https://assets.example.com",
+        },
+        request,
+      });
+
+      await expect(response.json()).resolves.toEqual({
+        changedAssets: {
+          "index.ios.bundle": {
+            file: {
+              compression: "br",
+              url: "https://assets.example.com/releases/00000000-0000-0000-0000-000000000002/files/index.ios.bundle.br",
+            },
+            fileHash: "hash-new-bundle",
+            patch: {
+              algorithm: "bsdiff",
+              baseBundleId: "00000000-0000-0000-0000-000000000001",
+              baseFileHash: "hash-old-bundle",
+              patchFileHash: "hash-bsdiff",
+              patchUrl:
+                "https://assets.example.com/releases/00000000-0000-0000-0000-000000000002/patches/00000000-0000-0000-0000-000000000001/index.ios.bundle.bsdiff",
+            },
+          },
+        },
+        fileHash: "hash123",
+        fileUrl:
+          "https://assets.example.com/releases/00000000-0000-0000-0000-000000000002/bundle.zip",
+        id: "00000000-0000-0000-0000-000000000002",
+        manifestFileHash: "sig:next-manifest",
+        manifestUrl:
+          "https://assets.example.com/releases/00000000-0000-0000-0000-000000000002/manifest.json",
+        message: "Test bundle",
+        shouldForceUpdate: false,
+        status: "UPDATE",
+      });
+      expect(readText).toHaveBeenCalledWith(
+        nextManifestStorageUri,
+        expect.objectContaining({
+          env: {
+            assetHost: "https://assets.example.com",
+          },
+          request: expect.any(Request),
+        }),
+      );
+      expect(readText).toHaveBeenCalledWith(
+        currentManifestStorageUri,
+        expect.objectContaining({
+          env: {
+            assetHost: "https://assets.example.com",
+          },
+          request: expect.any(Request),
+        }),
+      );
+      expect(fetchMock).not.toHaveBeenCalled();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
   it("does not inject the request into context unless explicitly provided", async () => {
     const getBundles = vi.fn<DatabasePlugin<TestContext>["getBundles"]>(
       async () => {
@@ -270,17 +518,9 @@ describe("runtime createHotUpdater", () => {
       async onUnmount() {},
       async updateBundle() {},
     };
-    const storage: StoragePlugin<TestContext> = {
-      name: "testStorage",
-      supportedProtocol: "s3",
-      async upload(key) {
-        return { storageUri: `s3://test-bucket/${key}` };
-      },
-      async delete() {},
-      async getDownloadUrl() {
-        return { fileUrl: "https://assets.example.com/bundle.zip" };
-      },
-    };
+    const storage = createRuntimeStorage(async () => {
+      return { fileUrl: "https://assets.example.com/bundle.zip" };
+    });
 
     const hotUpdater = createHotUpdater({
       database,
@@ -343,17 +583,9 @@ describe("runtime createHotUpdater", () => {
       async onUnmount() {},
       async updateBundle() {},
     };
-    const storage: StoragePlugin<TestContext> = {
-      name: "testStorage",
-      supportedProtocol: "s3",
-      async upload(key) {
-        return { storageUri: `s3://test-bucket/${key}` };
-      },
-      async delete() {},
-      async getDownloadUrl() {
-        return { fileUrl: "https://assets.example.com/bundle.zip" };
-      },
-    };
+    const storage = createRuntimeStorage(async () => {
+      return { fileUrl: "https://assets.example.com/bundle.zip" };
+    });
 
     const hotUpdater = createHotUpdater({
       database,

package/src/runtime.ts

@@ -1,7 +1,8 @@
 import type {
   HotUpdaterContext,
-  StoragePlugin,
+  RuntimeStoragePlugin,
 } from "@hot-updater/plugin-core";
+import { assertRuntimeStoragePlugin } from "@hot-updater/plugin-core";
 
 import { createPluginDatabaseCore } from "./db/pluginCore";
 import {
@@ -13,6 +14,7 @@ import {
 } from "./db/types";
 import { createHandler, type HandlerRoutes } from "./handler";
 import { normalizeBasePath } from "./route";
+import { createStorageAccess } from "./storageAccess";
 
 export type HotUpdaterAPI<TContext = unknown> = DatabaseAPI<TContext> & {
   basePath: string;
@@ -25,8 +27,14 @@ export type HotUpdaterAPI<TContext = unknown> = DatabaseAPI<TContext> & {
 
 export interface CreateHotUpdaterOptions<TContext = unknown> {
   database: DatabaseAdapter<TContext>;
-  storages?: (StoragePlugin<TContext> | StoragePluginFactory<TContext>)[];
-  storagePlugins?: (StoragePlugin<TContext> | StoragePluginFactory<TContext>)[];
+  storages?: (
+    | RuntimeStoragePlugin<TContext>
+    | StoragePluginFactory<TContext>
+  )[];
+  storagePlugins?: (
+    | RuntimeStoragePlugin<TContext>
+    | StoragePluginFactory<TContext>
+  )[];
   basePath?: string;
   cwd?: string;
   routes?: HandlerRoutes;
@@ -38,39 +46,14 @@ export function createHotUpdater<TContext = unknown>(
   const database = options.database;
   const basePath = normalizeBasePath(options.basePath ?? "/api");
   const storagePlugins = (options.storages ?? options.storagePlugins ?? []).map(
-    (plugin) => (typeof plugin === "function" ? plugin() : plugin),
+    (plugin) => {
+      const storagePlugin = typeof plugin === "function" ? plugin() : plugin;
+      assertRuntimeStoragePlugin(storagePlugin);
+      return storagePlugin;
+    },
   );
-
-  const resolveStoragePluginUrl = async (
-    storageUri: string | null,
-    context?: HotUpdaterContext<TContext>,
-  ): Promise<string | null> => {
-    if (!storageUri) {
-      return null;
-    }
-
-    const url = new URL(storageUri);
-    const protocol = url.protocol.replace(":", "");
-
-    if (protocol === "http" || protocol === "https") {
-      return storageUri;
-    }
-
-    const plugin = storagePlugins.find(
-      (item) => item.supportedProtocol === protocol,
-    );
-
-    if (!plugin) {
-      throw new Error(`No storage plugin for protocol: ${protocol}`);
-    }
-
-    const { fileUrl } = await plugin.getDownloadUrl(storageUri, context);
-    if (!fileUrl) {
-      throw new Error("Storage plugin returned empty fileUrl");
-    }
-
-    return fileUrl;
-  };
+  const { readStorageText, resolveFileUrl } =
+    createStorageAccess(storagePlugins);
 
   if (!isDatabasePluginFactory(database) && !isDatabasePlugin(database)) {
     throw new Error(
@@ -81,12 +64,13 @@ export function createHotUpdater<TContext = unknown>(
   const plugin = isDatabasePluginFactory(database) ? database() : database;
   const core = createPluginDatabaseCore<TContext>(
     () => plugin,
-    resolveStoragePluginUrl,
+    resolveFileUrl,
     isDatabasePluginFactory(database)
       ? {
           createMutationPlugin: () => database(),
+          readStorageText,
         }
-      : undefined,
+      : { readStorageText },
   );
 
   const api = {

package/src/schema/v0_21_0.ts

@@ -11,7 +11,7 @@ export const v0_21_0 = schema({
       file_hash: column("file_hash", "string"),
       git_commit_hash: column("git_commit_hash", "string").nullable(),
       message: column("message", "string").nullable(),
-      channel: column("channel", "string"),
+      channel: column("channel", "string").defaultTo("production"),
       storage_uri: column("storage_uri", "string"),
       target_app_version: column("target_app_version", "string").nullable(),
       fingerprint_hash: column("fingerprint_hash", "string").nullable(),