@sorisdk/matcher 0.6.1 → 0.6.3

package/README.md

@@ -67,6 +67,26 @@ const session = new MatcherSession({
 - `string`
 - `URL`
 
+Pack loading is bounded and transactional. Browser sources are limited to
+64 MiB by default: a valid oversized `Content-Length` is rejected before the
+body is consumed, and streamed/chunked responses are canceled when their bytes
+cross the same limit. The Rust/WASM parser independently enforces its aggregate
+pack, instruction, entry-buffer, and footer limits. Any failed load preserves
+the session's previous database.
+
+Set an intentional browser-source override when constructing the session:
+
+```ts
+const session = new MatcherSession({
+  maxPackBytes: 96 * 1024 * 1024
+});
+```
+
+`DEFAULT_MAX_PACK_BYTES` exports the 64 MiB default for applications that need
+to align their own transport controls. The same override is passed to the
+Rust/WASM total-input budget; instruction, cumulative-entry, footer, and
+per-entry limits remain independently enforced.
+
 If you want campaign events and browser recognition flow on top of matching, use `@sorisdk/web-audio`.
 
 ## Metadata lookup

package/dist/generated/core.d.ts

@@ -10,6 +10,8 @@ export class WasmMatcherDatabase {
     getEntryMetadata(name: string): any;
     loadPackBytes(bytes: Uint8Array): void;
     loadPackBytesAppend(bytes: Uint8Array): void;
+    loadPackBytesAppendWithMaxBytes(bytes: Uint8Array, max_pack_bytes: number): void;
+    loadPackBytesWithMaxBytes(bytes: Uint8Array, max_pack_bytes: number): void;
     constructor();
     removeEntry(name: string): void;
     setEntryVariantMetadata(name: string, encoded_metadata: string): void;

package/dist/generated/core_bg.js

@@ -85,6 +85,30 @@ export class WasmMatcherDatabase {
             throw takeFromExternrefTable0(ret[0]);
         }
     }
+    /**
+     * @param {Uint8Array} bytes
+     * @param {number} max_pack_bytes
+     */
+    loadPackBytesAppendWithMaxBytes(bytes, max_pack_bytes) {
+        const ptr0 = passArray8ToWasm0(bytes, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmmatcherdatabase_loadPackBytesAppendWithMaxBytes(this.__wbg_ptr, ptr0, len0, max_pack_bytes);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
+    /**
+     * @param {Uint8Array} bytes
+     * @param {number} max_pack_bytes
+     */
+    loadPackBytesWithMaxBytes(bytes, max_pack_bytes) {
+        const ptr0 = passArray8ToWasm0(bytes, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmmatcherdatabase_loadPackBytesWithMaxBytes(this.__wbg_ptr, ptr0, len0, max_pack_bytes);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
     constructor() {
         const ret = wasm.wasmmatcherdatabase_new();
         this.__wbg_ptr = ret >>> 0;
@@ -618,6 +642,10 @@ export function __wbg_new_227d7c05414eb861() {
     const ret = new Error();
     return ret;
 }
+export function __wbg_new_24a82d8799c298c3(arg0, arg1) {
+    const ret = new TypeError(getStringFromWasm0(arg0, arg1));
+    return ret;
+}
 export function __wbg_new_34d45cc8e36aaead() {
     const ret = new Map();
     return ret;

package/dist/generated/core_bg.wasm.d.ts

@@ -17,6 +17,8 @@ export const wasmmatcherdatabase_getEntryMetadata: (a: number, b: number, c: num
 export const wasmmatcherdatabase_length: (a: number) => number;
 export const wasmmatcherdatabase_loadPackBytes: (a: number, b: number, c: number) => [number, number];
 export const wasmmatcherdatabase_loadPackBytesAppend: (a: number, b: number, c: number) => [number, number];
+export const wasmmatcherdatabase_loadPackBytesAppendWithMaxBytes: (a: number, b: number, c: number, d: number) => [number, number];
+export const wasmmatcherdatabase_loadPackBytesWithMaxBytes: (a: number, b: number, c: number, d: number) => [number, number];
 export const wasmmatcherdatabase_new: () => number;
 export const wasmmatcherdatabase_removeEntry: (a: number, b: number, c: number) => [number, number];
 export const wasmmatcherdatabase_setEntryVariantMetadata: (a: number, b: number, c: number, d: number, e: number) => [number, number];

package/dist/index.d.ts

@@ -139,6 +139,8 @@ type MatcherSessionEventName = keyof MatcherSessionEventMap;
 type MatcherSessionListener<T extends MatcherSessionEventName> = (payload: MatcherSessionEventMap[T]) => void;
 
 type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/** Default browser-side ceiling for one AudioPack response or byte source (64 MiB). */
+declare const DEFAULT_MAX_PACK_BYTES: number;
 
 interface MatcherEphemeralKeyExchangeOptions {
     endpoint: string | URL;
@@ -192,22 +194,28 @@ interface InitMatcherOptions {
     loader?: () => Promise<unknown>;
     wasmModule?: unknown;
     wasmInitInput?: unknown;
+    embeddedPackLoader?: () => Promise<Uint8Array>;
     auth?: MatcherEphemeralAuthOptions;
 }
 interface MatcherSessionOptions extends InitMatcherOptions {
     fetch?: FetchLike;
+    /** Browser-side maximum for one pack source before it reaches WASM. Defaults to 64 MiB. */
+    maxPackBytes?: number;
 }
 type InitMatcherResult = MatcherEphemeralAuthResult;
 declare function initMatcher(options?: InitMatcherOptions): Promise<InitMatcherResult | void>;
 declare class MatcherSession {
     private readonly events;
     private readonly fetcher?;
+    private readonly maxPackBytes;
     private readonly initOptions;
+    private readonly embeddedPackLoader?;
     private readyPromise;
     private bindings;
     private database;
     private matcher;
     private destroyed;
+    private packLoadTail;
     private readonly distinctMatchDeduper;
     constructor(options?: MatcherSessionOptions);
     on<T extends MatcherSessionEventName>(eventName: T, listener: MatcherSessionListener<T>): this;
@@ -215,6 +223,7 @@ declare class MatcherSession {
     once<T extends MatcherSessionEventName>(eventName: T, listener: MatcherSessionListener<T>): this;
     ready(): Promise<void>;
     loadPack(source: PackSource): Promise<void>;
+    private loadPackExclusive;
     addEntry(name: string, afpType: AudioFingerprintType, fingerprint: Uint8Array): Promise<void>;
     addOrReplace(name: string, afpType: AudioFingerprintType, fingerprint: Uint8Array, metadata?: EntryMetadata | null): Promise<void>;
     setEntryVariantMetadata(name: string, encodedMetadata: string): Promise<void>;
@@ -235,6 +244,7 @@ declare class MatcherSession {
     private ensureLiveReady;
     private ensureNotDestroyed;
     private matcherOrThrow;
+    private bindingsOrThrow;
     private databaseOrThrow;
     private emitDistinctMatchEvent;
 }
@@ -242,4 +252,4 @@ declare function __setMatcherWasmModuleForTests(moduleLike: unknown): void;
 declare function __setMatcherEmbeddedPackForTests(bytes: Uint8Array): void;
 declare function __resetMatcherWasmForTests(): void;
 
-export { AudioFingerprintType, type AudioMarkerCode, type AudioMarkerConfig, type AudioMarkerDetection, type EntryMetadata, type InitMatcherOptions, type InitMatcherResult, type MatchConfig, type MatchResult, type MatcherEphemeralAuthOptions, type MatcherEphemeralAuthResult, type MatcherEphemeralKeyExchangeMetadata, type MatcherEphemeralKeyExchangeOptions, MatcherSession, type MatcherSessionEventMap, type MatcherSessionEventName, type MatcherSessionListener, type MatcherSessionOptions, type PackSource, type PitchRatioEstimate, type PitchReferenceEstimate, type VariantDecision, type VariantDecisionStatus, type VariantMatch, type VariantMatchConfig, type VariantMatchQuery, __resetMatcherWasmForTests, __setMatcherEmbeddedPackForTests, __setMatcherWasmModuleForTests, initMatcher };
+export { AudioFingerprintType, type AudioMarkerCode, type AudioMarkerConfig, type AudioMarkerDetection, DEFAULT_MAX_PACK_BYTES, type EntryMetadata, type InitMatcherOptions, type InitMatcherResult, type MatchConfig, type MatchResult, type MatcherEphemeralAuthOptions, type MatcherEphemeralAuthResult, type MatcherEphemeralKeyExchangeMetadata, type MatcherEphemeralKeyExchangeOptions, MatcherSession, type MatcherSessionEventMap, type MatcherSessionEventName, type MatcherSessionListener, type MatcherSessionOptions, type PackSource, type PitchRatioEstimate, type PitchReferenceEstimate, type VariantDecision, type VariantDecisionStatus, type VariantMatch, type VariantMatchConfig, type VariantMatchQuery, __resetMatcherWasmForTests, __setMatcherEmbeddedPackForTests, __setMatcherWasmModuleForTests, initMatcher };

package/dist/index.js

@@ -174,6 +174,7 @@ function __resetEmbeddedPackLoaderForTests() {
 }
 
 // src/source.ts
+var DEFAULT_MAX_PACK_BYTES = 64 * 1024 * 1024;
 function hasCtor(name) {
   return typeof globalThis[name] !== "undefined";
 }
@@ -183,6 +184,20 @@ function copyToUint8Array(input) {
 function toUint8Array(buffer) {
   return new Uint8Array(buffer.slice(0));
 }
+function validateMaxPackBytes(maxPackBytes) {
+  if (!Number.isSafeInteger(maxPackBytes) || maxPackBytes <= 0 || maxPackBytes > 4294967295) {
+    throw new Error("maxPackBytes must be a positive 32-bit unsigned integer");
+  }
+  return maxPackBytes;
+}
+function packSizeError(maxPackBytes) {
+  return new Error(`Pack source exceeds maximum size of ${maxPackBytes} bytes`);
+}
+function assertKnownByteLength(byteLength, maxPackBytes) {
+  if (byteLength > maxPackBytes) {
+    throw packSizeError(maxPackBytes);
+  }
+}
 function classifyPackSource(source) {
   if (source instanceof Uint8Array) {
     return "uint8array";
@@ -216,29 +231,68 @@ function resolveFetch3(fetcher) {
   }
   return globalThis.fetch.bind(globalThis);
 }
-async function readResponseAsBytes(response) {
+async function readResponseAsBytes(response, maxPackBytes) {
   if (!response.ok) {
     throw new Error(`Failed to load pack: HTTP ${response.status}`);
   }
-  return toUint8Array(await response.arrayBuffer());
+  const contentLength = response.headers.get("content-length");
+  if (contentLength !== null && /^\d+$/.test(contentLength.trim())) {
+    const declaredLength = Number(contentLength);
+    if (Number.isSafeInteger(declaredLength)) {
+      assertKnownByteLength(declaredLength, maxPackBytes);
+    }
+  }
+  if (!response.body) {
+    return new Uint8Array();
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let byteLength = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      byteLength += value.byteLength;
+      if (byteLength > maxPackBytes) {
+        await reader.cancel();
+        throw packSizeError(maxPackBytes);
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(byteLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
 }
-async function normalizePackSource(source, fetcher) {
+async function normalizePackSource(source, fetcher, maxPackBytes = DEFAULT_MAX_PACK_BYTES) {
+  maxPackBytes = validateMaxPackBytes(maxPackBytes);
   const sourceType = classifyPackSource(source);
   if (source instanceof Uint8Array) {
+    assertKnownByteLength(source.byteLength, maxPackBytes);
     return { sourceType, bytes: copyToUint8Array(source) };
   }
   if (source instanceof ArrayBuffer) {
+    assertKnownByteLength(source.byteLength, maxPackBytes);
     return { sourceType, bytes: toUint8Array(source) };
   }
   if (hasCtor("Blob") && source instanceof Blob) {
+    assertKnownByteLength(source.size, maxPackBytes);
     return { sourceType, bytes: toUint8Array(await source.arrayBuffer()) };
   }
   if (hasCtor("Response") && source instanceof Response) {
-    return { sourceType, bytes: await readResponseAsBytes(source) };
+    return { sourceType, bytes: await readResponseAsBytes(source, maxPackBytes) };
   }
   if (typeof source === "string" || source instanceof URL || hasCtor("Request") && source instanceof Request) {
     const response = await resolveFetch3(fetcher)(source);
-    return { sourceType, bytes: await readResponseAsBytes(response) };
+    return { sourceType, bytes: await readResponseAsBytes(response, maxPackBytes) };
   }
   throw new Error("Unsupported pack source type");
 }
@@ -328,7 +382,15 @@ var WrappedDatabase = class {
     }
     fn.call(this.inner);
   }
-  loadPackBytes(bytes) {
+  loadPackBytes(bytes, maxPackBytes) {
+    const limitedFn = getCallable(this.inner, [
+      "loadPackBytesWithMaxBytes",
+      "load_pack_bytes_with_max_bytes"
+    ]);
+    if (maxPackBytes !== void 0 && limitedFn) {
+      limitedFn.call(this.inner, bytes, maxPackBytes);
+      return;
+    }
     const fn = getCallable(this.inner, [
       "loadPackBytes",
       "loadPack",
@@ -340,7 +402,15 @@ var WrappedDatabase = class {
     }
     fn.call(this.inner, bytes);
   }
-  loadPackBytesAppend(bytes) {
+  loadPackBytesAppend(bytes, maxPackBytes) {
+    const limitedFn = getCallable(this.inner, [
+      "loadPackBytesAppendWithMaxBytes",
+      "load_pack_bytes_append_with_max_bytes"
+    ]);
+    if (maxPackBytes !== void 0 && limitedFn) {
+      limitedFn.call(this.inner, bytes, maxPackBytes);
+      return;
+    }
     const appendFn = getCallable(this.inner, ["loadPackBytesAppend", "load_pack_bytes_append"]);
     if (!appendFn) {
       throw new Error("WASM database is missing loadPackBytesAppend-compatible method");
@@ -844,19 +914,25 @@ async function initMatcher(options) {
 var MatcherSession = class {
   events = new TypedEventEmitter();
   fetcher;
+  maxPackBytes;
   initOptions;
+  embeddedPackLoader;
   readyPromise;
   bindings = null;
   database = null;
   matcher = null;
   destroyed = false;
+  packLoadTail = Promise.resolve();
   distinctMatchDeduper = new DistinctMatchDeduper();
   constructor(options) {
     this.fetcher = options?.fetch;
+    this.maxPackBytes = options?.maxPackBytes ?? DEFAULT_MAX_PACK_BYTES;
+    this.embeddedPackLoader = options?.embeddedPackLoader;
     this.initOptions = {
       loader: options?.loader,
       wasmModule: options?.wasmModule,
-      wasmInitInput: options?.wasmInitInput
+      wasmInitInput: options?.wasmInitInput,
+      embeddedPackLoader: options?.embeddedPackLoader
     };
     this.readyPromise = this.bootstrap();
   }
@@ -875,17 +951,30 @@ var MatcherSession = class {
   async ready() {
     await this.readyPromise;
   }
-  async loadPack(source) {
+  loadPack(source) {
+    const load = this.packLoadTail.then(() => this.loadPackExclusive(source));
+    this.packLoadTail = load.catch(() => void 0);
+    return load;
+  }
+  async loadPackExclusive(source) {
     try {
       await this.ensureLiveReady();
       const sourceType = classifyPackSource(source);
       this.events.emit("packloadstart", { sourceType });
-      const database = this.databaseOrThrow();
-      const normalized = await normalizePackSource(source, this.fetcher);
-      const embeddedPackBytes = await loadEmbeddedPackBytes();
-      database.clear();
-      database.loadPackBytes(embeddedPackBytes);
-      database.loadPackBytesAppend(normalized.bytes);
+      const previousDatabase = this.databaseOrThrow();
+      const normalized = await normalizePackSource(source, this.fetcher, this.maxPackBytes);
+      const embeddedPackBytes = this.embeddedPackLoader ? await this.embeddedPackLoader() : await loadEmbeddedPackBytes();
+      const bindings = this.bindingsOrThrow();
+      const stagedDatabase = bindings.createDatabase();
+      try {
+        stagedDatabase.loadPackBytes(embeddedPackBytes);
+        stagedDatabase.loadPackBytesAppend(normalized.bytes, this.maxPackBytes);
+      } catch (error) {
+        stagedDatabase.destroy();
+        throw error;
+      }
+      this.database = stagedDatabase;
+      previousDatabase.destroy();
       this.distinctMatchDeduper.reset();
       this.matcher?.resetDistinctMatchState?.();
       this.events.emit("packload", {
@@ -1187,6 +1276,12 @@ var MatcherSession = class {
     }
     return this.matcher;
   }
+  bindingsOrThrow() {
+    if (!this.bindings) {
+      throw new Error("Matcher bindings are not initialized");
+    }
+    return this.bindings;
+  }
   databaseOrThrow() {
     if (!this.database) {
       throw new Error("Database is not initialized");
@@ -1226,6 +1321,7 @@ var AudioFingerprintType = /* @__PURE__ */ ((AudioFingerprintType2) => {
 })(AudioFingerprintType || {});
 export {
   AudioFingerprintType,
+  DEFAULT_MAX_PACK_BYTES,
   MatcherSession,
   __resetMatcherWasmForTests,
   __setMatcherEmbeddedPackForTests,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sorisdk/matcher",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Browser WASM SDK for audio fingerprint matching",
   "type": "module",
   "main": "./dist/index.js",