fix(hermes-base): integer Range deadlines; reject a non-HBC base from its head

- timeoutFor() returned a fractional ms count for entries over 64 KB, which
  Node's AbortSignal.timeout() rejects, so every range download fell back to
  the whole package. Round it up.
- When the server does not know the base's HBC version, read the bundle's
  first 128 bytes (header + head in one small request, a truncated deflate
  stream inflated as far as it goes) and give up before fetching the body
  if it is plain JS or another HBC version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: sunnylqm

src/utils/hermes-base.ts

@@ -33,6 +33,7 @@ import { webFetch } from './runtime';
 import { enumZipEntries, readEntry } from './zip-entries';
 import {
   fetchZipEntryData,
+  fetchZipEntryHead,
   openRemoteZip,
   RangeUnsupportedError,
   readRemoteZipEntry,
@@ -56,6 +57,19 @@ export class BundleHashMismatchError extends PermanentBaseError {
   }
 }
 
+/** The base bundle is not Hermes bytecode of the version being compiled. */
+export class HbcVersionMismatchError extends PermanentBaseError {
+  constructor(
+    readonly version: number | null,
+    readonly expected: number,
+  ) {
+    super(`downloaded base is HBC ${version ?? 'n/a'}, need ${expected}`);
+  }
+}
+
+/** bytes `getHbcVersion` needs to read the version */
+const HBC_HEAD_BYTES = 128;
+
 /** time allowed for a response to start (headers) */
 const FETCH_HEADERS_TIMEOUT_MS = 30_000;
 /** a download that receives nothing for this long is abandoned */
@@ -613,6 +627,9 @@ interface FetchedBaseBundle {
   totalBytes?: number;
 }
 
+/** the head at a recorded bundle location is not the expected bytecode */
+class StaleHeadError extends Error {}
+
 function hasBundleLocation(record: HermesBaseServerRecord): boolean {
   return (
     record.bundleOffset != null &&
@@ -674,12 +691,19 @@ async function saveResponse(
  * recorded location is stale, so the directory transport (2) still runs; a
  * mismatch of the entry itself (2, 3) is final — the same bytes would come
  * back however they are fetched — and raises BundleHashMismatchError.
+ *
+ * With `expectHbcVersion` (the server does not know the base's version), the
+ * bundle's first bytes are checked before its body is fetched; a base of
+ * another HBC version, or plain JS, raises HbcVersionMismatchError without
+ * downloading the rest. A head read at a recorded location (1) may be stale,
+ * so only the directory transport (2) decides.
  */
 export async function fetchBaseBundle(
   record: HermesBaseServerRecord,
   artifactType: BaseArtifactType,
   archive: string,
   log: (message: string) => void = () => {},
+  expectHbcVersion?: number,
 ): Promise<FetchedBaseBundle> {
   const matches = bundleEntryMatcher(artifactType);
   const verified = (
@@ -707,14 +731,21 @@ export async function fetchBaseBundle(
   // harmony .app nests the bundle in a second zip, so a location inside the
   // outer archive is never reported for it
   if (artifactType !== 'app' && hasBundleLocation(record)) {
+    const location = {
+      dataOffset: record.bundleOffset as number,
+      compressedSize: record.bundleCompressedSize as number,
+      compressionMethod: record.bundleCompression as number,
+    };
     try {
+      const headMatches =
+        expectHbcVersion === undefined ||
+        getHbcVersion(
+          await fetchZipEntryHead(record.url, location, HBC_HEAD_BYTES),
+        ) === expectHbcVersion;
+      if (!headMatches) throw new StaleHeadError();
       const { data, fetchedBytes, totalBytes } = await fetchZipEntryData(
         record.url,
-        {
-          dataOffset: record.bundleOffset as number,
-          compressedSize: record.bundleCompressedSize as number,
-          compressionMethod: record.bundleCompression as number,
-        },
+        location,
       );
       return {
         ...verified(data),
@@ -727,7 +758,10 @@ export async function fetchBaseBundle(
         skip('server ignores Range');
         return fromFullResponse(error.response);
       }
-      skip(`entry range: ${error?.message ?? error}`);
+      // not a transport failure: the directory read below settles it
+      if (!(error instanceof StaleHeadError)) {
+        skip(`entry range: ${error?.message ?? error}`);
+      }
     }
   }
 
@@ -742,6 +776,17 @@ export async function fetchBaseBundle(
         remote.zipFile,
         matches,
         remote.reader,
+        expectHbcVersion === undefined
+          ? undefined
+          : {
+              bytes: HBC_HEAD_BYTES,
+              check: (head) => {
+                const version = getHbcVersion(head);
+                if (version !== expectHbcVersion) {
+                  throw new HbcVersionMismatchError(version, expectHbcVersion);
+                }
+              },
+            },
       );
       return {
         ...verified(bundle),
@@ -916,7 +961,14 @@ export async function resolveHermesBase(
     );
     try {
       log(t('hermesBaseDownloading', { url: record.url }));
-      const fetched = await fetchBaseBundle(record, artifactType, archive, log);
+      const fetched = await fetchBaseBundle(
+        record,
+        artifactType,
+        archive,
+        log,
+        // a server that knows the version already matched it above
+        record.bytecodeVersion == null ? bytecodeVersion : undefined,
+      );
       const { bundle, bundleHash: actualHash } = fetched;
       if (fetched.transport !== 'full') {
         log(
@@ -928,12 +980,7 @@ export async function resolveHermesBase(
       }
       const version = getHbcVersion(bundle);
       if (version !== bytecodeVersion) {
-        log(
-          t('hermesBaseNone', {
-            reason: `downloaded base is HBC ${version ?? 'n/a'}, need ${bytecodeVersion}`,
-          }),
-        );
-        return null;
+        throw new HbcVersionMismatchError(version, bytecodeVersion);
       }
       const cached = await cachePut(bundle, params.cacheMaxMb, actualHash);
       log(
@@ -954,6 +1001,10 @@ export async function resolveHermesBase(
         source,
       };
     } catch (error: any) {
+      if (error instanceof HbcVersionMismatchError) {
+        log(t('hermesBaseNone', { reason: error.message }));
+        return null;
+      }
       if (attempt === 2 || error instanceof PermanentBaseError) {
         log(
           t('hermesBaseNone', {

src/utils/zip-range.ts

@@ -15,7 +15,7 @@ import {
   RandomAccessReader,
   type ZipFile,
 } from 'yauzl';
-import { inflateRawSync } from 'zlib';
+import { inflateRawSync, constants as zlibConstants } from 'zlib';
 import { webFetch } from './runtime';
 import { readEntry } from './zip-entries';
 
@@ -33,6 +33,11 @@ const TAIL_BYTES = 22 + 0xffff + 20;
 const CHUNK_BYTES = 64 * 1024;
 /** extra bytes past a hinted entry, covering a longer local extra field */
 const HINT_SLACK_BYTES = 4 * 1024;
+/**
+ * compressed bytes fetched to decode the head of a deflated entry: the
+ * dynamic Huffman header plus the first literals fit comfortably
+ */
+const HEAD_PROBE_BYTES = 4 * 1024;
 
 export interface ZipEntryLocation {
   fileName: string;
@@ -199,10 +204,11 @@ function timeoutFor(bytes: number, options: RangeOptions): number {
   if (bytes <= CHUNK_BYTES) {
     return options.headerTimeoutMs ?? DEFAULT_HEADER_TIMEOUT_MS;
   }
-  return (
+  // AbortSignal.timeout() rejects a fractional delay
+  return Math.ceil(
     (options.dataTimeoutMs ?? DEFAULT_DATA_TIMEOUT_MS) +
-    ((options.dataTimeoutPerMbMs ?? DEFAULT_DATA_TIMEOUT_PER_MB_MS) * bytes) /
-      (1024 * 1024)
+      ((options.dataTimeoutPerMbMs ?? DEFAULT_DATA_TIMEOUT_PER_MB_MS) * bytes) /
+        (1024 * 1024),
   );
 }
 
@@ -360,6 +366,65 @@ export async function fetchZipEntryData(
   };
 }
 
+/**
+ * Up to `bytes` leading bytes of an entry, decoded from a prefix of its
+ * compressed data (a truncated deflate stream is inflated as far as it goes).
+ */
+export function decodeEntryHead(
+  raw: Buffer,
+  compressionMethod: number,
+  bytes: number,
+): Buffer {
+  if (compressionMethod === ZIP_STORED) return raw.subarray(0, bytes);
+  if (compressionMethod !== ZIP_DEFLATED) {
+    throw new Error(`unsupported compression method ${compressionMethod}`);
+  }
+  return inflateRawSync(raw, {
+    finishFlush: zlibConstants.Z_SYNC_FLUSH,
+  }).subarray(0, bytes);
+}
+
+/** compressed bytes needed to decode the first `bytes` of an entry */
+function headProbeSize(
+  compressedSize: number,
+  compressionMethod: number,
+  bytes: number,
+): number {
+  return Math.min(
+    compressedSize,
+    compressionMethod === ZIP_STORED ? bytes : HEAD_PROBE_BYTES,
+  );
+}
+
+/**
+ * The first `bytes` of an entry whose compressed bytes are already located,
+ * from one small Range request (see `fetchZipEntryData`).
+ */
+export async function fetchZipEntryHead(
+  url: string,
+  location: Pick<
+    ZipEntryLocation,
+    'dataOffset' | 'compressedSize' | 'compressionMethod'
+  >,
+  bytes: number,
+  options: RangeOptions = {},
+): Promise<Buffer> {
+  const { dataOffset, compressedSize, compressionMethod } = location;
+  if (
+    !Number.isInteger(dataOffset) ||
+    !Number.isInteger(compressedSize) ||
+    dataOffset < 0 ||
+    compressedSize <= 0
+  ) {
+    throw new Error('invalid bundle location');
+  }
+  const size = headProbeSize(compressedSize, compressionMethod, bytes);
+  const { data } = await fetchRangeBuffer(url, dataOffset, dataOffset + size, {
+    timeoutMs: timeoutFor(size, options),
+  });
+  return decodeEntryHead(data, compressionMethod, bytes);
+}
+
 export interface HttpRangeReaderOptions extends RangeOptions {
   /** validator of the archive (see `rangeValidator`), sent as If-Range */
   ifRange?: string;
@@ -693,14 +758,67 @@ export async function openRemoteZip(
   return { kind: 'zip', zipFile, reader };
 }
 
+/** `reader.read` as a promise */
+function readAt(
+  reader: HttpRangeReader,
+  position: number,
+  length: number,
+): Promise<Buffer> {
+  const buffer = Buffer.alloc(length);
+  return new Promise((resolve, reject) =>
+    reader.read(buffer, 0, length, position, (error) =>
+      error ? reject(error) : resolve(buffer),
+    ),
+  );
+}
+
+/** The first `bytes` of `entry`, read through `reader` without its body. */
+async function remoteEntryHead(
+  reader: HttpRangeReader,
+  entry: Entry,
+  bytes: number,
+): Promise<Buffer> {
+  const start = entry.relativeOffsetOfLocalHeader;
+  const header = await readAt(reader, start, LOCAL_HEADER_SIZE);
+  if (header.readUInt32LE(0) !== LOCAL_HEADER_SIGNATURE) {
+    throw new Error('invalid local file header signature');
+  }
+  const dataOffset =
+    start +
+    LOCAL_HEADER_SIZE +
+    header.readUInt16LE(26) +
+    header.readUInt16LE(28);
+  const size = headProbeSize(
+    entry.compressedSize,
+    entry.compressionMethod,
+    bytes,
+  );
+  if (size <= 0) return Buffer.alloc(0);
+  return decodeEntryHead(
+    await readAt(reader, dataOffset, size),
+    entry.compressionMethod,
+    bytes,
+  );
+}
+
+/** Look at the head of the matched entry before its body is fetched. */
+export interface EntryHeadCheck {
+  bytes: number;
+  /** throw to abandon the entry; the error is passed on as is */
+  check: (head: Buffer) => void;
+}
+
 /**
  * Read the first matching entry of an opened remote zip, then close it. With
- * `reader` given, the entry's header and data are fetched in one request.
+ * `reader` given, the entry's header and data are fetched in one request —
+ * or, with `head` too, its first bytes are checked first (header and head
+ * share one small request, the rest of the body follows only if they pass).
  */
 export function readRemoteZipEntry(
   zipFile: ZipFile,
   matches: (name: string) => boolean,
   reader?: HttpRangeReader,
+  head?: EntryHeadCheck,
 ): Promise<Buffer | null> {
   return new Promise((resolve, reject) => {
     let settled = false;
@@ -717,11 +835,17 @@ export function readRemoteZipEntry(
         zipFile.readEntry();
         return;
       }
-      reader?.hintEntry(entry);
-      readEntry(entry, zipFile).then(
-        (data) => finish(null, data),
-        (error) => finish(error),
-      );
+      const probe =
+        reader && head
+          ? remoteEntryHead(reader, entry, head.bytes).then(head.check)
+          : // without a probe the header read may take the body along
+            Promise.resolve(reader?.hintEntry(entry));
+      probe
+        .then(() => readEntry(entry, zipFile))
+        .then(
+          (data) => finish(null, data),
+          (error) => finish(error),
+        );
     });
     zipFile.readEntry();
   });