feat(hermes-base): support native package fallback

Author: sunnylqm

src/utils/hermes-base.ts

@@ -28,9 +28,9 @@ export interface HermesBaseSelection {
   bundleHash: string;
   /** server version id when the base came from the server */
   versionId?: number;
-  /** server object key of the base ppk when known */
+  /** server object key of the base artifact when known */
   hash?: string;
-  source: 'cache' | 'download' | 'local' | 'latest-version';
+  source: 'cache' | 'download' | 'local' | 'latest-version' | 'native-package';
 }
 
 /** Metadata attached to version/create so the server can track the chain. */
@@ -397,8 +397,9 @@ export async function downloadToFile(
 // ---------------------------------------------------------------------------
 
 export interface HermesBaseServerRecord {
-  versionId: number;
+  versionId?: number | null;
   hash: string;
+  artifactType?: 'ppk' | 'apk' | 'ipa' | 'app';
   bundleHash?: string | null;
   bytecodeVersion?: number | null;
   url: string;
@@ -412,8 +413,8 @@ export interface ResolveHermesBaseParams {
   cacheMaxMb?: number;
   /**
    * server lookup; returns null when the app has no usable base. The server
-   * itself falls back to the newest version when the epoch is still unknown
-   * (its bytecodeVersion is then null and verified here after download).
+   * itself falls back to the newest legacy version, then the newest native
+   * package (bytecodeVersion is null and verified here after download).
    */
   fetchBase: (
     appId: string,
@@ -480,7 +481,11 @@ export async function resolveHermesBase(
     return null;
   }
   const source: HermesBaseSelection['source'] =
-    record?.bytecodeVersion == null ? 'latest-version' : 'download';
+    record?.artifactType && record.artifactType !== 'ppk'
+      ? 'native-package'
+      : record?.bytecodeVersion == null
+        ? 'latest-version'
+        : 'download';
   if (!record) {
     log(t('hermesBaseNone', { reason: 'no published version yet' }));
     return null;
@@ -502,15 +507,15 @@ export async function resolveHermesBase(
     if (hit) {
       log(
         t('hermesBaseUsing', {
-          source: `cache ${record.bundleHash.slice(0, 12)} (version ${record.versionId})`,
+          source: `cache ${record.bundleHash.slice(0, 12)}${record.versionId == null ? '' : ` (version ${record.versionId})`}`,
           version: bytecodeVersion,
         }),
       );
       return {
         path: hit,
         bytecodeVersion,
         bundleHash: record.bundleHash,
-        versionId: record.versionId,
+        versionId: record.versionId ?? undefined,
         hash: record.hash,
         source: 'cache',
       };
@@ -520,9 +525,14 @@ export async function resolveHermesBase(
   for (let attempt = 1; attempt <= 2; attempt++) {
     const dir = tmpDir();
     await fs.ensureDir(dir);
+    const artifactType = ['ppk', 'apk', 'ipa', 'app'].includes(
+      record.artifactType ?? '',
+    )
+      ? record.artifactType
+      : 'ppk';
     const archive = path.join(
       dir,
-      `base-${process.pid}-${Date.now()}-${attempt}.ppk`,
+      `base-${process.pid}-${Date.now()}-${attempt}.${artifactType}`,
     );
     try {
       log(t('hermesBaseDownloading', { url: record.url }));
@@ -548,15 +558,18 @@ export async function resolveHermesBase(
       const cached = await cachePut(bundle, params.cacheMaxMb);
       log(
         t('hermesBaseUsing', {
-          source: `version ${record.versionId} ${record.hash.slice(0, 8)}`,
+          source:
+            record.versionId == null
+              ? `native package ${record.hash.slice(0, 8)}`
+              : `version ${record.versionId} ${record.hash.slice(0, 8)}`,
           version: bytecodeVersion,
         }),
       );
       return {
         path: cached.path,
         bytecodeVersion,
         bundleHash: cached.bundleHash,
-        versionId: record.versionId,
+        versionId: record.versionId ?? undefined,
         hash: record.hash,
         source,
       };

tests/hermes-base.test.ts

@@ -283,11 +283,16 @@ describe('resolveHermesBase', () => {
     const bundleHash = sha256Hex(bundle);
     const ppk = path.join(dir, 'server.ppk');
     await writeZip(ppk, { 'main.jsbundle': bundle });
+    const nativeBundle = fakeHbc(98, 'native');
+    const apk = path.join(dir, 'native.apk');
+    await writeZip(apk, { 'assets/index.android.bundle': nativeBundle });
     const server = Bun.serve({
       port: 0,
       fetch: async (req) => {
         if (new URL(req.url).pathname === '/good.ppk')
           return new Response(Bun.file(ppk));
+        if (new URL(req.url).pathname === '/native.apk')
+          return new Response(Bun.file(apk));
         return new Response('nope', { status: 404 });
       },
     });
@@ -335,6 +340,26 @@ describe('resolveHermesBase', () => {
         fetchBase: async () => legacy,
       });
       expect(fromLatest?.source).toBe('latest-version');
+      await cleanCache();
+      const fromNativePackage = await resolveHermesBase({
+        ...common,
+        option: 'auto',
+        appId: '1',
+        fetchBase: async () => ({
+          versionId: null,
+          hash: 'nativekey',
+          artifactType: 'apk',
+          bundleHash: sha256Hex(nativeBundle),
+          bytecodeVersion: null,
+          url: `http://127.0.0.1:${server.port}/native.apk`,
+        }),
+      });
+      expect(fromNativePackage?.source).toBe('native-package');
+      expect(fromNativePackage?.versionId).toBeUndefined();
+      expect(fromNativePackage?.hash).toBe('nativekey');
+      expect(
+        fs.readFileSync(fromNativePackage!.path).equals(nativeBundle),
+      ).toBe(true);
       // server has a different epoch → no base
       expect(
         await resolveHermesBase({