@byline/core 6.12.1 → 6.13.0

package/dist/extraction/work.js

@@ -0,0 +1,102 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { EXTRACTION_ARTIFACT_SCHEMA_VERSION } from './artifact.js';
+import { isSourceVerificationEvidence } from './evidence.js';
+import { assertDeploymentIdentifier } from './producer.js';
+/**
+ * Decides whether a reference needs extraction, before any bytes are read.
+ *
+ * - A reference with no `fileHash` is an identity problem. `force` does not bypass it.
+ * - `force` always yields `work`. It bypasses reuse, never the verified read.
+ * - `reuse` needs a complete, verified artifact for the reference's hash, valid
+ *   evidence for that hash, the same provider and configuration, a version that
+ *   passes the version rules, and the current schema. Follow it with
+ *   `probeVerifiedSource`.
+ * - A `null` current engine version never yields a version reason, so an unknown
+ *   version cannot cause repeated work.
+ * - An artifact with a `null` `producerConfigHash` is historical output whose
+ *   configuration was never recorded. Only that hash and a `null` recorded version go
+ *   uncompared, and `reuse` then reports `producerUnchecked: true`. A provider
+ *   mismatch, two known versions that differ, and every other reason apply unchanged.
+ *
+ * The decision is synchronous and cannot recompute the hash, so it trusts that
+ * `producer.deploymentIdentifier` is the value hashed into `producerConfigHash`.
+ * `buildExtractionProducer` guarantees that. It checks the identifier's form and
+ * throws a `TypeError` when malformed.
+ *
+ * Hosts may add their own reasons and treat the union as the decision.
+ *
+ * @provisional
+ */
+export function decideExtractionWork(input) {
+    const { reference, producer, existing } = input;
+    if (producer.deploymentIdentifier !== null) {
+        assertDeploymentIdentifier(producer.deploymentIdentifier);
+    }
+    const fileHash = reference.fileHash;
+    if (fileHash === undefined || fileHash === null || fileHash === '') {
+        return { kind: 'identity-problem', problem: 'missing-hash' };
+    }
+    const versionUnchecked = producer.providerVersion === null && producer.deploymentIdentifier === null;
+    const reasons = new Set();
+    if (input.force === true)
+        reasons.add('force');
+    const artifact = existing?.artifact;
+    if (existing?.state === 'failed' || existing?.state === 'identity-problem') {
+        reasons.add('previous-attempt-unsuccessful');
+    }
+    else if (artifact === undefined) {
+        reasons.add('no-artifact');
+    }
+    let evidence;
+    if (artifact !== undefined) {
+        if (artifact.schemaVersion !== EXTRACTION_ARTIFACT_SCHEMA_VERSION)
+            reasons.add('schema-changed');
+        if (artifact.contentHash === null || !artifact.sourceVerified) {
+            reasons.add('unverified');
+        }
+        else if (artifact.contentHash !== fileHash) {
+            reasons.add('source-changed');
+        }
+        else if (isSourceVerificationEvidence(existing?.evidence, { expectedHash: fileHash })) {
+            evidence = existing?.evidence;
+        }
+        else {
+            reasons.add('unverified');
+        }
+        if (producerChanged(artifact, producer))
+            reasons.add('producer-changed');
+    }
+    if (reasons.size > 0 || evidence === undefined || artifact === undefined) {
+        return { kind: 'work', reasons: [...reasons], versionUnchecked };
+    }
+    return {
+        kind: 'reuse',
+        evidence,
+        versionUnchecked,
+        producerUnchecked: artifact.producerConfigHash === null,
+    };
+}
+function producerChanged(artifact, producer) {
+    if (artifact.provider !== producer.provider)
+        return true;
+    const recordedConfiguration = artifact.producerConfigHash !== null;
+    if (recordedConfiguration && artifact.producerConfigHash !== producer.producerConfigHash) {
+        return true;
+    }
+    // A null current version never yields a reason, so it cannot cause repeated work.
+    if (producer.providerVersion === null)
+        return false;
+    if (artifact.providerVersion === null) {
+        // Recorded before versions were known: work once, and the new artifact then
+        // records the version. Historical output with no recorded configuration is
+        // exempt, because adopting these contracts must not cause re-extraction.
+        return recordedConfiguration;
+    }
+    return artifact.providerVersion !== producer.providerVersion;
+}

package/dist/extraction/work.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/extraction/work.test.node.js

@@ -0,0 +1,409 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it } from 'vitest';
+import { buildExtractionProducer } from './producer.js';
+import { decideExtractionWork } from './work.js';
+const HASH = 'a'.repeat(64);
+const OTHER_HASH = 'c'.repeat(64);
+const CONFIG_HASH = 'b'.repeat(64);
+const OTHER_CONFIG_HASH = 'd'.repeat(64);
+const EVIDENCE = {
+    expectedHash: HASH,
+    contentHash: HASH,
+    validator: { kind: 's3-etag', value: '"abc"' },
+    verifiedAt: '2026-10-31T06:00:00.000Z',
+};
+function producer(change) {
+    return {
+        provider: 'tika',
+        providerVersion: '3.0.0',
+        producerConfigHash: CONFIG_HASH,
+        deploymentIdentifier: null,
+        ...change,
+    };
+}
+function existing(artifact) {
+    return {
+        state: 'complete',
+        evidence: EVIDENCE,
+        artifact: {
+            contentHash: HASH,
+            sourceVerified: true,
+            provider: 'tika',
+            providerVersion: '3.0.0',
+            producerConfigHash: CONFIG_HASH,
+            schemaVersion: 1,
+            ...artifact,
+        },
+    };
+}
+const reference = { fileHash: HASH };
+describe('decideExtractionWork', () => {
+    describe('source identity', () => {
+        it.each([
+            ['undefined', undefined],
+            ['null', null],
+            ['empty', ''],
+        ])('reports a %s fileHash as an identity problem, not a work reason', (_label, fileHash) => {
+            expect(decideExtractionWork({
+                reference: { fileHash },
+                producer: producer(),
+                existing: existing(),
+            })).toEqual({ kind: 'identity-problem', problem: 'missing-hash' });
+        });
+        it('does not let force bypass a missing hash', () => {
+            expect(decideExtractionWork({ force: true, reference: {}, producer: producer(), existing: null })).toEqual({ kind: 'identity-problem', problem: 'missing-hash' });
+        });
+    });
+    describe('reuse', () => {
+        it('reuses a complete, verified artifact for the same producer', () => {
+            expect(decideExtractionWork({ reference, producer: producer(), existing: existing() })).toEqual({
+                kind: 'reuse',
+                evidence: EVIDENCE,
+                versionUnchecked: false,
+                producerUnchecked: false,
+            });
+        });
+    });
+    describe('reasons', () => {
+        it.each([
+            ['no existing record', null, ['no-artifact']],
+            ['an undefined record', undefined, ['no-artifact']],
+            ['a complete record with no artifact', { state: 'complete' }, ['no-artifact']],
+            ['a failed attempt', { state: 'failed' }, ['previous-attempt-unsuccessful']],
+            [
+                'an identity problem',
+                { state: 'identity-problem' },
+                ['previous-attempt-unsuccessful'],
+            ],
+            [
+                'a failed attempt over a usable artifact',
+                { ...existing(), state: 'failed' },
+                ['previous-attempt-unsuccessful'],
+            ],
+            ['a different source', existing({ contentHash: OTHER_HASH }), ['source-changed']],
+            ['an unverified artifact', existing({ sourceVerified: false }), ['unverified']],
+            ['a legacy artifact', existing({ contentHash: null, sourceVerified: false }), ['unverified']],
+            ['missing evidence', { ...existing(), evidence: undefined }, ['unverified']],
+            ['copied-only evidence', { ...existing(), evidence: { expectedHash: HASH } }, ['unverified']],
+            [
+                'evidence for another hash',
+                {
+                    ...existing(),
+                    evidence: { ...EVIDENCE, expectedHash: OTHER_HASH, contentHash: OTHER_HASH },
+                },
+                ['unverified'],
+            ],
+            ['a different provider', existing({ provider: 'docling' }), ['producer-changed']],
+            [
+                'a different configuration',
+                existing({ producerConfigHash: OTHER_CONFIG_HASH }),
+                ['producer-changed'],
+            ],
+            ['an unknown schema version', existing({ schemaVersion: 2 }), ['schema-changed']],
+        ])('reports %s', (_label, record, reasons) => {
+            expect(decideExtractionWork({ reference, producer: producer(), existing: record })).toEqual({
+                kind: 'work',
+                reasons,
+                versionUnchecked: false,
+            });
+        });
+        it('reports several reasons once each', () => {
+            const decision = decideExtractionWork({
+                reference,
+                producer: producer(),
+                existing: existing({
+                    provider: 'docling',
+                    producerConfigHash: OTHER_CONFIG_HASH,
+                    schemaVersion: 2,
+                }),
+            });
+            expect(decision).toEqual({
+                kind: 'work',
+                reasons: ['schema-changed', 'producer-changed'],
+                versionUnchecked: false,
+            });
+        });
+        it('does not add unverified for evidence of a source that changed anyway', () => {
+            const decision = decideExtractionWork({
+                reference: { fileHash: OTHER_HASH },
+                producer: producer(),
+                existing: existing(),
+            });
+            expect(decision).toEqual({
+                kind: 'work',
+                reasons: ['source-changed'],
+                versionUnchecked: false,
+            });
+        });
+    });
+    describe('force', () => {
+        it('yields work on reuse-eligible input', () => {
+            expect(decideExtractionWork({ force: true, reference, producer: producer(), existing: existing() })).toEqual({ kind: 'work', reasons: ['force'], versionUnchecked: false });
+        });
+        it('is reported with any other reasons', () => {
+            expect(decideExtractionWork({ force: true, reference, producer: producer(), existing: null })).toEqual({ kind: 'work', reasons: ['force', 'no-artifact'], versionUnchecked: false });
+        });
+    });
+    describe('engine version', () => {
+        it('reuses when the known versions are equal', () => {
+            expect(decideExtractionWork({ reference, producer: producer(), existing: existing() }).kind).toBe('reuse');
+        });
+        it('reports producer-changed when the known versions differ', () => {
+            expect(decideExtractionWork({
+                reference,
+                producer: producer({ providerVersion: '4.0.0' }),
+                existing: existing(),
+            })).toEqual({ kind: 'work', reasons: ['producer-changed'], versionUnchecked: false });
+        });
+        it('reports producer-changed when a recorded hash has a null version and the current is known', () => {
+            expect(decideExtractionWork({
+                reference,
+                producer: producer(),
+                existing: existing({ providerVersion: null }),
+            })).toEqual({ kind: 'work', reasons: ['producer-changed'], versionUnchecked: false });
+        });
+        it.each([
+            ['a recorded version', '3.0.0'],
+            ['no recorded version', null],
+        ])('gives no version reason with an unknown current version and %s', (_label, version) => {
+            expect(decideExtractionWork({
+                reference,
+                producer: producer({ providerVersion: null }),
+                existing: existing({ providerVersion: version }),
+            })).toEqual({
+                kind: 'reuse',
+                evidence: EVIDENCE,
+                versionUnchecked: true,
+                producerUnchecked: false,
+            });
+        });
+        it('reports versionUnchecked false when a deployment identifier is configured', () => {
+            expect(decideExtractionWork({
+                reference,
+                producer: producer({ providerVersion: null, deploymentIdentifier: 'image-a' }),
+                existing: existing({ providerVersion: null }),
+            })).toEqual({
+                kind: 'reuse',
+                evidence: EVIDENCE,
+                versionUnchecked: false,
+                producerUnchecked: false,
+            });
+        });
+        it('reports versionUnchecked on work too', () => {
+            expect(decideExtractionWork({
+                reference,
+                producer: producer({ providerVersion: null }),
+                existing: null,
+            })).toEqual({ kind: 'work', reasons: ['no-artifact'], versionUnchecked: true });
+        });
+    });
+    describe('deployment identifier form', () => {
+        it.each([
+            ['empty', ''],
+            ['untrimmed', ' image'],
+            ['not a string', 7],
+        ])('rejects an identifier that is %s', (_label, deploymentIdentifier) => {
+            expect(() => decideExtractionWork({
+                reference,
+                producer: producer({ deploymentIdentifier: deploymentIdentifier }),
+            })).toThrow(TypeError);
+        });
+    });
+    describe('historical output with no recorded producer', () => {
+        const historical = () => existing({ providerVersion: null, producerConfigHash: null });
+        it.each([
+            ['a known current version', '3.0.0', false],
+            ['an unknown current version', null, true],
+        ])('reuses without work, with %s', (_label, providerVersion, versionUnchecked) => {
+            expect(decideExtractionWork({
+                reference,
+                producer: producer({ providerVersion }),
+                existing: historical(),
+            })).toEqual({
+                kind: 'reuse',
+                evidence: EVIDENCE,
+                versionUnchecked,
+                producerUnchecked: true,
+            });
+        });
+        it('does not detect a changed deployment identifier', () => {
+            expect(decideExtractionWork({
+                reference,
+                producer: producer({ deploymentIdentifier: 'image-b' }),
+                existing: historical(),
+            })).toMatchObject({ kind: 'reuse', producerUnchecked: true });
+        });
+        it('still compares a recorded version with a known current one', () => {
+            expect(decideExtractionWork({
+                reference,
+                producer: producer({ providerVersion: '4.0.0' }),
+                existing: existing({ providerVersion: '3.0.0', producerConfigHash: null }),
+            })).toEqual({ kind: 'work', reasons: ['producer-changed'], versionUnchecked: false });
+        });
+        it('reuses when a recorded version equals the known current one', () => {
+            expect(decideExtractionWork({
+                reference,
+                producer: producer(),
+                existing: existing({ providerVersion: '3.0.0', producerConfigHash: null }),
+            })).toMatchObject({ kind: 'reuse', producerUnchecked: true });
+        });
+        it.each([
+            ['a provider mismatch', { provider: 'docling' }, 'producer-changed'],
+            ['a changed source hash', { contentHash: OTHER_HASH }, 'source-changed'],
+            ['an unverified artifact', { sourceVerified: false }, 'unverified'],
+            ['a legacy artifact', { contentHash: null, sourceVerified: false }, 'unverified'],
+            ['a different schema', { schemaVersion: 2 }, 'schema-changed'],
+        ])('still reports %s', (_label, change, reason) => {
+            expect(decideExtractionWork({
+                reference,
+                producer: producer(),
+                existing: existing({ providerVersion: null, producerConfigHash: null, ...change }),
+            })).toEqual({ kind: 'work', reasons: [reason], versionUnchecked: false });
+        });
+        it('still requires evidence', () => {
+            expect(decideExtractionWork({
+                reference,
+                producer: producer(),
+                existing: { ...historical(), evidence: undefined },
+            })).toEqual({ kind: 'work', reasons: ['unverified'], versionUnchecked: false });
+        });
+        it.each(['failed', 'identity-problem'])('still retries a %s state', (state) => {
+            expect(decideExtractionWork({
+                reference,
+                producer: producer(),
+                existing: { ...historical(), state },
+            })).toEqual({
+                kind: 'work',
+                reasons: ['previous-attempt-unsuccessful'],
+                versionUnchecked: false,
+            });
+        });
+        it('still honours force', () => {
+            expect(decideExtractionWork({
+                force: true,
+                reference,
+                producer: producer(),
+                existing: historical(),
+            })).toEqual({ kind: 'work', reasons: ['force'], versionUnchecked: false });
+        });
+        it('never reports producerUnchecked for a recorded configuration', () => {
+            const decision = decideExtractionWork({
+                reference,
+                producer: producer({ providerVersion: null }),
+                existing: existing({ providerVersion: null }),
+            });
+            expect(decision).toMatchObject({ kind: 'reuse', producerUnchecked: false });
+        });
+    });
+    describe('successive runs', () => {
+        // A small orchestration loop over the real helpers: each run decides, and work
+        // records an artifact the way the specification requires.
+        function createHarness(options) {
+            const provider = {
+                name: 'fake',
+                capabilities: {
+                    ocr: false,
+                    markdown: false,
+                    tables: false,
+                    formulas: false,
+                    charts: false,
+                    coordinates: false,
+                    pageMap: false,
+                    structure: false,
+                    formats: ['*/*'],
+                },
+                ...(options.resolveVersion != null && { resolveVersion: options.resolveVersion }),
+                extract: async () => {
+                    const version = options.engineVersion();
+                    return {
+                        provider: 'fake',
+                        ...(version != null && { providerVersion: version }),
+                        plainText: 'text',
+                        metadata: {},
+                        signals: { totalChars: 4 },
+                    };
+                },
+            };
+            let record = null;
+            let extractions = 0;
+            return {
+                get extractions() {
+                    return extractions;
+                },
+                async run(deploymentIdentifier) {
+                    const resolved = (await provider.resolveVersion?.()) ?? null;
+                    const current = await buildExtractionProducer({
+                        provider,
+                        providerVersion: resolved,
+                        deploymentIdentifier,
+                    });
+                    const decision = decideExtractionWork({ reference, producer: current, existing: record });
+                    if (decision.kind === 'work') {
+                        extractions += 1;
+                        const result = await provider.extract({ data: new Uint8Array() });
+                        record = {
+                            state: 'complete',
+                            evidence: EVIDENCE,
+                            artifact: {
+                                contentHash: HASH,
+                                sourceVerified: true,
+                                provider: result.provider,
+                                // The result's own version wins, then the version resolved for the run.
+                                providerVersion: result.providerVersion ?? resolved,
+                                producerConfigHash: current.producerConfigHash,
+                                schemaVersion: 1,
+                            },
+                        };
+                    }
+                    return decision;
+                },
+            };
+        }
+        it('re-extracts once when a configured deployment identifier changes', async () => {
+            const harness = createHarness({ engineVersion: () => undefined });
+            const run1 = await harness.run('A');
+            const run2 = await harness.run('A');
+            const run3 = await harness.run('B');
+            const run4 = await harness.run('B');
+            expect(run1).toMatchObject({ kind: 'work', reasons: ['no-artifact'] });
+            expect(run2).toMatchObject({ kind: 'reuse', versionUnchecked: false });
+            expect(run3).toMatchObject({ kind: 'work', reasons: ['producer-changed'] });
+            expect(run4).toMatchObject({ kind: 'reuse', versionUnchecked: false });
+            expect(harness.extractions).toBe(2);
+        });
+        it('records the resolved version when the result reports none, then reuses', async () => {
+            const harness = createHarness({
+                engineVersion: () => undefined,
+                resolveVersion: async () => '3.0.0',
+            });
+            expect(await harness.run(null)).toMatchObject({ kind: 'work' });
+            expect(await harness.run(null)).toMatchObject({ kind: 'reuse', versionUnchecked: false });
+            expect(harness.extractions).toBe(1);
+        });
+        it('records the result version after a mid-run upgrade, then reuses', async () => {
+            let resolved = '3.0.0';
+            const harness = createHarness({
+                // The engine was upgraded while the first run was in progress.
+                engineVersion: () => '4.0.0',
+                resolveVersion: async () => resolved,
+            });
+            expect(await harness.run(null)).toMatchObject({ kind: 'work' });
+            resolved = '4.0.0';
+            expect(await harness.run(null)).toMatchObject({ kind: 'reuse' });
+            expect(harness.extractions).toBe(1);
+        });
+        it('never repeats work for a driver with no version and no identifier', async () => {
+            const harness = createHarness({ engineVersion: () => undefined });
+            await harness.run(null);
+            expect(await harness.run(null)).toMatchObject({ kind: 'reuse', versionUnchecked: true });
+            expect(await harness.run(null)).toMatchObject({ kind: 'reuse', versionUnchecked: true });
+            expect(harness.extractions).toBe(1);
+        });
+    });
+});

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
 export { resolvePasskeyConfig } from './config/validate-passkey-config.js';
 export { type BylineCore, getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
+export * from './extraction/index.js';
 export { getHostRequestBridge, type HostCookieSetOptions, type HostRequestBridge, registerHostRequestBridge, tryGetHostRequestBridge, } from './host/host-request-bridge.js';
 export { BylineError, type DbErrorClassification, type DbErrorCode, DbErrorCodes, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_DOCUMENT_HOOK_COMMITTED, ERR_DOCUMENT_STALE, ERR_LOCK_CONFLICT, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_STORAGE_PRECONDITION, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, type ErrorReport, getLockConflictDetails, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
 export { generateKeyBetween, generateNKeysBetween, validateOrderKey, } from './lib/fractional-index.js';

package/dist/index.js

@@ -20,6 +20,7 @@ export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
 export { resolvePasskeyConfig } from './config/validate-passkey-config.js';
 export { getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
+export * from './extraction/index.js';
 export { getHostRequestBridge, registerHostRequestBridge, tryGetHostRequestBridge, } from './host/host-request-bridge.js';
 export { BylineError, DbErrorCodes, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_DOCUMENT_HOOK_COMMITTED, ERR_DOCUMENT_STALE, ERR_LOCK_CONFLICT, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_STORAGE_PRECONDITION, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, getLockConflictDetails, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
 export { generateKeyBetween, generateNKeysBetween, validateOrderKey, } from './lib/fractional-index.js';

package/dist/storage/stored-files-server.d.ts

@@ -8,6 +8,7 @@
 import type { IDbAdapter } from '../@types/db-types.js';
 import type { IStorageProvider, StoredFileLocation, UploadFileOptions } from '../@types/storage-types.js';
 import type { BylineLogger } from '../lib/logger.js';
+export { probeVerifiedSource, readVerifiedSource, type SourceProbe, VERIFIED_SOURCE_SPOOL_PREFIX, type VerifiedSourceBody, type VerifiedSourceRead, } from './verified-read.js';
 /** SHA-256 (lower-case hex) and byte count of a stream, read to its end. */
 export declare function hashStream(stream: NodeJS.ReadableStream, options?: {
     signal?: AbortSignal;

package/dist/storage/stored-files-server.js

@@ -11,30 +11,19 @@
 import { createHash } from 'node:crypto';
 import { Transform } from 'node:stream';
 import { ERR_STORAGE, ERR_VALIDATION } from '../lib/errors.js';
+import { consumeStream, destroyStream } from './verified-read.js';
+export { probeVerifiedSource, readVerifiedSource, VERIFIED_SOURCE_SPOOL_PREFIX, } from './verified-read.js';
 /** SHA-256 (lower-case hex) and byte count of a stream, read to its end. */
 export async function hashStream(stream, options) {
     const hash = createHash('sha256');
     let size = 0;
-    const signal = options?.signal;
-    if (signal?.aborted) {
-        // An already-aborted signal never fires 'abort'; release the stream here.
-        // Destroy without an error: nothing listens to this stream yet, so an
-        // error argument would surface as an unhandled 'error' event.
-        destroyStream(stream);
-        signal.throwIfAborted();
-    }
-    const onAbort = () => destroyStream(stream, signal?.reason);
-    signal?.addEventListener('abort', onAbort, { once: true });
-    try {
-        for await (const chunk of stream) {
-            const bytes = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
-            hash.update(bytes);
-            size += bytes.length;
-        }
-    }
-    finally {
-        signal?.removeEventListener('abort', onAbort);
-    }
+    await consumeStream(stream, {
+        ...(options?.signal !== undefined && { signal: options.signal }),
+        onChunk: (chunk) => {
+            hash.update(chunk);
+            size += chunk.length;
+        },
+    });
     return { fileHash: hash.digest('hex'), size };
 }
 /**
@@ -135,10 +124,6 @@ export async function uploadWithContentHash(storage, input, options) {
     input.removeListener('error', onInputError);
     return { location, fileHash: hash.digest('hex') };
 }
-function destroyStream(stream, reason) {
-    const destroyable = stream;
-    destroyable.destroy?.(reason instanceof Error ? reason : undefined);
-}
 /** Maximum entries kept in each summary path list. Counts are never capped. */
 const BACKFILL_REPORT_LIMIT = 1000;
 /**

package/dist/storage/stored-files-server.test.node.js

@@ -61,6 +61,12 @@ const opts = (size, extra) => ({
     ...extra,
 });
 describe('hashStream', () => {
+    it('rejects when the signal fires as the stream ends', async () => {
+        const controller = new AbortController();
+        const stream = Readable.from([Buffer.from('abc')]);
+        stream.on('end', () => controller.abort(new Error('stop')));
+        await expect(hashStream(stream, { signal: controller.signal })).rejects.toThrow('stop');
+    });
     it('hashes a stream to its end and counts bytes', async () => {
         const bytes = Buffer.from('hello world');
         await expect(hashStream(Readable.from([bytes.subarray(0, 5), bytes.subarray(5)]))).resolves.toEqual({