@loaders.gl/core 5.0.0-alpha.12 → 5.0.0-alpha.13

package/dist/loader-utils/lib/files/http-file-transport.js

@@ -0,0 +1,290 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+/** Owns HTTP request construction, response validation, identity checks, and transport telemetry. */
+export class HttpFileTransport {
+    /** Remote object URL. */
+    url;
+    /** Fetch implementation used for range requests. */
+    fetchFunction;
+    /** Persistent fetch options copied from the caller. */
+    fetchOptions;
+    /** Validator enforcement mode. */
+    consistency;
+    /** Caller-supplied identity information. */
+    identityHints;
+    /** Failure objects already included in telemetry. */
+    countedFailures = new WeakSet();
+    /** Mutable counters backing immutable telemetry snapshots. */
+    telemetry = {
+        requestedBytes: 0,
+        downloadedBytes: 0,
+        requestCount: 0,
+        networkTimeMs: 0,
+        abortCount: 0,
+        errorCount: 0
+    };
+    /** Creates the transport for one remote object. */
+    constructor(url, options) {
+        validateKnownByteLength(options.byteLength);
+        this.url = url;
+        this.fetchFunction = options.fetch || ((input, init) => globalThis.fetch(input, init));
+        this.fetchOptions = options.fetchOptions
+            ? { ...options.fetchOptions, headers: new Headers(options.fetchOptions.headers) }
+            : undefined;
+        this.consistency = options.consistency || 'best-effort';
+        this.identityHints = {
+            byteLength: options.byteLength,
+            etag: normalizeHeaderValue(options.etag),
+            lastModified: normalizeHeaderValue(options.lastModified)
+        };
+    }
+    /** Returns an identity that is complete enough to avoid an opening request. */
+    getInitialIdentity() {
+        const { byteLength, etag, lastModified } = this.identityHints;
+        if (byteLength !== undefined && (etag !== undefined || lastModified !== undefined)) {
+            return createIdentity(byteLength, etag, lastModified);
+        }
+        if (byteLength === 0 && this.consistency === 'best-effort') {
+            return createIdentity(0);
+        }
+        return null;
+    }
+    /** Returns an immutable point-in-time copy of the transport counters. */
+    getTelemetry() {
+        return Object.freeze({ ...this.telemetry });
+    }
+    /** Counts each failure object once even when it passes through several async layers. */
+    trackFailure(error) {
+        if (typeof error === 'object' && error !== null) {
+            if (this.countedFailures.has(error)) {
+                return;
+            }
+            this.countedFailures.add(error);
+        }
+        if (isAbortError(error)) {
+            this.telemetry.abortCount++;
+        }
+        else {
+            this.telemetry.errorCount++;
+        }
+    }
+    /** Performs and validates one exact HTTP range request. */
+    async requestRange(offset, length, signal, expectedIdentity) {
+        const requestStartTime = getTimestamp();
+        const abortContext = createCombinedAbortContext(signal, this.fetchOptions?.signal);
+        this.telemetry.requestCount++;
+        this.telemetry.requestedBytes += length;
+        try {
+            const response = await this.fetchFunction(this.url, createFetchOptions(this.fetchOptions, offset, length, abortContext.signal));
+            if (isEmptyIdentityProbeResponse(response, offset, length, expectedIdentity)) {
+                return await this.readEmptyIdentityProbe(response, requestStartTime);
+            }
+            if (response.status !== 206) {
+                await cancelResponse(response);
+                throw new Error(`HTTP byte-range request expected 206, received ${response.status}`);
+            }
+            const contentRange = await readContentRange(response);
+            const responseIdentity = getResponseIdentity(response, contentRange.byteLength);
+            const responseError = getIdentityError(expectedIdentity, responseIdentity, this.identityHints, this.consistency) || getRangeError(contentRange, offset, length);
+            if (responseError) {
+                await cancelResponse(response);
+                throw new Error(responseError);
+            }
+            const arrayBuffer = await response.arrayBuffer();
+            this.telemetry.downloadedBytes += arrayBuffer.byteLength;
+            if (arrayBuffer.byteLength !== length) {
+                throw new Error(`HTTP byte-range response contained ${arrayBuffer.byteLength} bytes; expected ${length}`);
+            }
+            return {
+                arrayBuffer,
+                identity: resolveIdentity(expectedIdentity, responseIdentity, this.identityHints),
+                status: response.status,
+                transportBytes: arrayBuffer.byteLength,
+                networkTimeMs: getTimestamp() - requestStartTime
+            };
+        }
+        catch (error) {
+            if (expectedIdentity === null || !isAbortError(error)) {
+                this.trackFailure(error);
+            }
+            throw error;
+        }
+        finally {
+            abortContext.removeAbortListeners();
+            this.telemetry.networkTimeMs += getTimestamp() - requestStartTime;
+        }
+    }
+    /** Validates and consumes the special empty-object identity response. */
+    async readEmptyIdentityProbe(response, requestStartTime) {
+        const responseIdentity = getResponseIdentity(response, 0);
+        const identityError = getIdentityError(null, responseIdentity, this.identityHints, this.consistency);
+        await cancelResponse(response);
+        if (identityError) {
+            throw new Error(identityError);
+        }
+        return {
+            arrayBuffer: new ArrayBuffer(0),
+            identity: resolveIdentity(null, responseIdentity, this.identityHints),
+            status: response.status,
+            transportBytes: 0,
+            networkTimeMs: getTimestamp() - requestStartTime
+        };
+    }
+}
+/** Creates fetch options while preserving caller headers and forcing an exact GET range. */
+function createFetchOptions(fetchOptions, offset, length, signal) {
+    const headers = new Headers(fetchOptions?.headers);
+    headers.set('Range', `bytes=${offset}-${offset + length - 1}`);
+    return {
+        ...fetchOptions,
+        method: 'GET',
+        body: undefined,
+        headers,
+        signal
+    };
+}
+/** Returns whether a response is the valid empty-object form of an opening probe. */
+function isEmptyIdentityProbeResponse(response, offset, length, expectedIdentity) {
+    return (response.status === 416 &&
+        expectedIdentity === null &&
+        offset === 0 &&
+        length === 1 &&
+        /^bytes \*\/0$/i.test(response.headers.get('Content-Range') || ''));
+}
+/** Parses Content-Range and cancels the body when the header is invalid. */
+async function readContentRange(response) {
+    try {
+        return parseContentRange(response.headers.get('Content-Range'));
+    }
+    catch (error) {
+        await cancelResponse(response);
+        throw error;
+    }
+}
+/** Parses an exact byte Content-Range response header. */
+function parseContentRange(contentRange) {
+    const match = contentRange?.match(/^bytes (\d+)-(\d+)\/(\d+)$/);
+    if (!match) {
+        throw new Error('HTTP byte-range response has an invalid Content-Range header');
+    }
+    return {
+        offset: Number(match[1]),
+        endOffset: Number(match[2]),
+        byteLength: Number(match[3])
+    };
+}
+/** Reads a normalized object identity from response headers. */
+function getResponseIdentity(response, byteLength) {
+    return createIdentity(byteLength, normalizeHeaderValue(response.headers.get('ETag')), normalizeHeaderValue(response.headers.get('Last-Modified')));
+}
+/** Resolves the pinned identity from an expected identity, response, and caller hints. */
+function resolveIdentity(expectedIdentity, responseIdentity, identityHints) {
+    return (expectedIdentity ||
+        createIdentity(responseIdentity.byteLength, responseIdentity.etag ?? identityHints.etag, responseIdentity.lastModified ?? identityHints.lastModified));
+}
+/** Returns an error message when a response does not cover the requested range. */
+function getRangeError(contentRange, offset, length) {
+    if (!Number.isSafeInteger(contentRange.offset) ||
+        !Number.isSafeInteger(contentRange.endOffset) ||
+        !Number.isSafeInteger(contentRange.byteLength) ||
+        contentRange.offset < 0 ||
+        contentRange.endOffset < contentRange.offset ||
+        contentRange.endOffset >= contentRange.byteLength) {
+        return 'HTTP byte-range response has invalid range bounds';
+    }
+    if (contentRange.offset !== offset || contentRange.endOffset !== offset + length - 1) {
+        return 'HTTP byte-range response does not match the requested range';
+    }
+    return null;
+}
+/** Returns an error message when response identity is inconsistent with the open file. */
+function getIdentityError(expectedIdentity, responseIdentity, identityHints, consistency) {
+    const expectedByteLength = expectedIdentity?.byteLength ?? identityHints.byteLength;
+    if (expectedByteLength !== undefined && responseIdentity.byteLength !== expectedByteLength) {
+        return 'HTTP file length changed while the file was open';
+    }
+    const expectedEtag = expectedIdentity?.etag ?? identityHints.etag;
+    const expectedLastModified = expectedIdentity?.lastModified ?? identityHints.lastModified;
+    if (expectedEtag) {
+        if (responseIdentity.etag) {
+            return expectedEtag === responseIdentity.etag
+                ? null
+                : 'HTTP file ETag changed while the file was open';
+        }
+        if (consistency === 'strict') {
+            return 'HTTP byte-range response is missing the pinned ETag';
+        }
+        if (expectedLastModified &&
+            responseIdentity.lastModified &&
+            expectedLastModified !== responseIdentity.lastModified) {
+            return 'HTTP file Last-Modified value changed while the file was open';
+        }
+        return null;
+    }
+    if (expectedLastModified) {
+        if (responseIdentity.lastModified && expectedLastModified !== responseIdentity.lastModified) {
+            return 'HTTP file Last-Modified value changed while the file was open';
+        }
+        if (consistency === 'strict' && !responseIdentity.lastModified) {
+            return 'HTTP byte-range response is missing the pinned Last-Modified value';
+        }
+        return null;
+    }
+    if (consistency === 'strict' && !responseIdentity.etag && !responseIdentity.lastModified) {
+        return 'HTTP byte-range response does not provide an ETag or Last-Modified validator';
+    }
+    return null;
+}
+/** Creates a frozen normalized identity. */
+function createIdentity(byteLength, etag, lastModified) {
+    return Object.freeze({ byteLength, etag, lastModified });
+}
+/** Validates a caller-provided object length. */
+function validateKnownByteLength(byteLength) {
+    if (byteLength !== undefined && (!Number.isSafeInteger(byteLength) || byteLength < 0)) {
+        throw new Error('HttpFile byteLength must be a non-negative safe integer');
+    }
+}
+/** Cancels a response body without obscuring the validation error. */
+async function cancelResponse(response) {
+    await response.body?.cancel().catch(() => { });
+}
+/** Normalizes empty response-header values to undefined. */
+function normalizeHeaderValue(value) {
+    return value || undefined;
+}
+/** Returns a high-resolution timestamp when available. */
+function getTimestamp() {
+    return globalThis.performance?.now() ?? Date.now();
+}
+/** Returns whether an arbitrary failure represents cancellation. */
+function isAbortError(error) {
+    return ((error instanceof Error && error.name === 'AbortError') ||
+        (error instanceof Error && /aborted/i.test(error.message)));
+}
+/** Creates one fetch signal that follows both a per-read and persistent source signal. */
+function createCombinedAbortContext(...signals) {
+    const abortController = new AbortController();
+    const uniqueSignals = [
+        ...new Set(signals.filter((signal) => Boolean(signal)))
+    ];
+    const abortListener = () => abortController.abort();
+    for (const signal of uniqueSignals) {
+        if (signal.aborted) {
+            abortController.abort();
+        }
+        else {
+            signal.addEventListener('abort', abortListener, { once: true });
+        }
+    }
+    return {
+        signal: abortController.signal,
+        removeAbortListeners: () => {
+            for (const signal of uniqueSignals) {
+                signal.removeEventListener('abort', abortListener);
+            }
+        }
+    };
+}
+//# sourceMappingURL=http-file-transport.js.map

package/dist/loader-utils/lib/files/http-file-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-file-transport.js","sourceRoot":"","sources":["../../../../src/loader-utils/lib/files/http-file-transport.ts"],"names":[],"mappings":"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"}

package/dist/loader-utils/lib/files/http-file-types.d.ts

@@ -0,0 +1,49 @@
+import type { RangeRequestScheduler, RangeRequestSchedulerProps } from "../request-utils/range-request-scheduler.js";
+/** Controls how rigorously an HTTP file verifies response validators. */
+export type HttpFileConsistency = 'strict' | 'best-effort';
+/** Fetch implementation accepted by `HttpFile`. */
+export type HttpFileFetch = (url: string, options?: RequestInit) => Promise<Response>;
+/** Options for opening a byte-range-addressable HTTP file. */
+export type HttpFileOptions = {
+    /** Optional fetch implementation. */
+    fetch?: HttpFileFetch;
+    /** Fetch options applied to every request. The Range header and signal are supplied per read. */
+    fetchOptions?: RequestInit;
+    /** Known object length. Supplying a validator as well avoids an opening probe request. */
+    byteLength?: number;
+    /** Known object ETag. */
+    etag?: string;
+    /** Known object Last-Modified value. */
+    lastModified?: string;
+    /** Whether missing validators are rejected. Defaults to best-effort. */
+    consistency?: HttpFileConsistency;
+    /** Optional shared byte-range scheduler. */
+    rangeScheduler?: RangeRequestScheduler;
+    /** Configuration used when creating a private scheduler. */
+    rangeSchedulerProps?: RangeRequestSchedulerProps;
+};
+/** Immutable identity pinned for an open HTTP file. */
+export type HttpFileIdentity = Readonly<{
+    /** Authoritative object length in bytes. */
+    byteLength: number;
+    /** Pinned ETag, when exposed by the server. */
+    etag?: string;
+    /** Pinned Last-Modified value, when exposed by the server. */
+    lastModified?: string;
+}>;
+/** Immutable snapshot of one HTTP file's transport counters. */
+export type HttpFileTelemetry = Readonly<{
+    /** Bytes requested from HTTP after range coalescing, including the opening probe. */
+    requestedBytes: number;
+    /** Response body bytes consumed by the file. */
+    downloadedBytes: number;
+    /** Actual HTTP requests started by the file. */
+    requestCount: number;
+    /** Aggregate wall time spent awaiting HTTP requests and response bodies. */
+    networkTimeMs: number;
+    /** Failed or cancelled operations caused by an abort signal. */
+    abortCount: number;
+    /** Failed operations not caused by cancellation. */
+    errorCount: number;
+}>;
+//# sourceMappingURL=http-file-types.d.ts.map

package/dist/loader-utils/lib/files/http-file-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-file-types.d.ts","sourceRoot":"","sources":["../../../../src/loader-utils/lib/files/http-file-types.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,qBAAqB,EACrB,0BAA0B,EAC3B,oDAAiD;AAElD,yEAAyE;AACzE,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,aAAa,CAAC;AAE3D,mDAAmD;AACnD,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEtF,8DAA8D;AAC9D,MAAM,MAAM,eAAe,GAAG;IAC5B,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,iGAAiG;IACjG,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B,0FAA0F;IAC1F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yBAAyB;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,4CAA4C;IAC5C,cAAc,CAAC,EAAE,qBAAqB,CAAC;IACvC,4DAA4D;IAC5D,mBAAmB,CAAC,EAAE,0BAA0B,CAAC;CAClD,CAAC;AAEF,uDAAuD;AACvD,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC,CAAC;AAEH,gEAAgE;AAChE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,qFAAqF;IACrF,cAAc,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,eAAe,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC,CAAC"}

package/dist/loader-utils/lib/files/http-file-types.js

@@ -0,0 +1,5 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+export {};
+//# sourceMappingURL=http-file-types.js.map

package/dist/loader-utils/lib/files/http-file-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-file-types.js","sourceRoot":"","sources":["../../../../src/loader-utils/lib/files/http-file-types.ts"],"names":[],"mappings":"AAAA,aAAa;AACb,+BAA+B;AAC/B,oCAAoC"}

package/dist/loader-utils/lib/files/http-file.d.ts

@@ -0,0 +1,55 @@
+import type { ReadableFile, Stat } from "./file.js";
+import type { HttpFileIdentity, HttpFileOptions, HttpFileTelemetry } from "./http-file-types.js";
+export type { HttpFileConsistency, HttpFileFetch, HttpFileIdentity, HttpFileOptions, HttpFileTelemetry } from "./http-file-types.js";
+/** A reusable, validator-aware, byte-range-addressable HTTP file. */
+export declare class HttpFile implements ReadableFile {
+    /** URL used as the ReadableFile handle. */
+    readonly handle: string;
+    /** Remote object URL. */
+    readonly url: string;
+    /** HTTP transport and response validator for this file. */
+    private readonly transport;
+    /** Scheduler used to coalesce compatible range reads. */
+    private readonly rangeScheduler;
+    /** Unique key that prevents coalescing across transport or credential contexts. */
+    private readonly schedulerIsolationKey;
+    /** Caller-supplied length available before identity discovery. */
+    private readonly suppliedByteLength?;
+    /** Pinned remote object identity. */
+    private identity;
+    /** Shared opening probe, while identity discovery is in progress. */
+    private openPromise;
+    /** Whether the file has stopped accepting operations. */
+    private closed;
+    /** Creates a lazy HTTP file. Use {@link HttpFile.open} when identity must be pinned immediately. */
+    constructor(url: string, options?: HttpFileOptions);
+    /** Opens a file and pins its byte length and available validators. */
+    static open(url: string, options?: HttpFileOptions, signal?: AbortSignal): Promise<HttpFile>;
+    /** Pins this file's byte length and available validators. */
+    open(signal?: AbortSignal): Promise<this>;
+    /** Pinned file length, or zero before a lazy file has opened. */
+    get size(): number;
+    /** Pinned file length as a bigint, or zero before a lazy file has opened. */
+    get bigsize(): bigint;
+    /** Returns the pinned identity, or null before a lazy file has opened. */
+    getIdentitySnapshot(): HttpFileIdentity | null;
+    /** Returns an immutable point-in-time copy of this file's transport counters. */
+    getTelemetry(): HttpFileTelemetry;
+    /** Prevents new operations. Active fetches remain controlled by their read signals. */
+    close(): Promise<void>;
+    /** Returns pinned file information without issuing a HEAD request. */
+    stat(): Promise<Stat>;
+    /** Reads exactly one byte range, with optional cancellation. */
+    read(offset?: number | bigint, length?: number, signal?: AbortSignal): Promise<ArrayBuffer>;
+    /** Reads a range and returns a Response for legacy ReadableFile consumers. */
+    fetchRange(offset: number | bigint, length: number, signal?: AbortSignal): Promise<Response>;
+    /** Stable scheduler callback used by every read from this file. */
+    private readonly fetchScheduledRange;
+    /** Returns the shared lazy identity promise, retrying after a failed probe. */
+    private getIdentity;
+    /** Uses a one-byte GET range to discover object length and validators. */
+    private probeIdentity;
+    /** Throws when the file has been closed. */
+    private assertOpen;
+}
+//# sourceMappingURL=http-file.d.ts.map

package/dist/loader-utils/lib/files/http-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-file.d.ts","sourceRoot":"","sources":["../../../../src/loader-utils/lib/files/http-file.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAC,YAAY,EAAE,IAAI,EAAC,kBAAe;AAG/C,OAAO,KAAK,EAAC,gBAAgB,EAAE,eAAe,EAAE,iBAAiB,EAAC,6BAA0B;AAG5F,YAAY,EACV,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EAClB,6BAA0B;AAE3B,qEAAqE;AACrE,qBAAa,QAAS,YAAW,YAAY;IAC3C,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yBAAyB;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,yDAAyD;IACzD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwB;IACvD,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAM;IAC5C,kEAAkE;IAClE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAS;IAE7C,qCAAqC;IACrC,OAAO,CAAC,QAAQ,CAA0B;IAC1C,qEAAqE;IACrE,OAAO,CAAC,WAAW,CAA0C;IAC7D,yDAAyD;IACzD,OAAO,CAAC,MAAM,CAAS;IAEvB,oGAAoG;gBACxF,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;IAWtD,sEAAsE;WACzD,IAAI,CACf,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,eAAoB,EAC7B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,QAAQ,CAAC;IAMpB,6DAA6D;IACvD,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAW/C,iEAAiE;IACjE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,6EAA6E;IAC7E,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,0EAA0E;IAC1E,mBAAmB,IAAI,gBAAgB,GAAG,IAAI;IAI9C,iFAAiF;IACjF,YAAY,IAAI,iBAAiB;IAIjC,uFAAuF;IACjF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,sEAAsE;IAChE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3B,gEAAgE;IAC1D,IAAI,CACR,MAAM,GAAE,MAAM,GAAG,MAAU,EAC3B,MAAM,GAAE,MAAU,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,WAAW,CAAC;IA8BvB,8EAA8E;IACxE,UAAU,CACd,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,QAAQ,CAAC;IAOpB,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAalC;IAEF,+EAA+E;IAC/E,OAAO,CAAC,WAAW;IAsBnB,0EAA0E;YAC5D,aAAa;IAW3B,4CAA4C;IAC5C,OAAO,CAAC,UAAU;CAKnB"}

package/dist/loader-utils/lib/files/http-file.js

@@ -0,0 +1,213 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+import { waitForPromiseWithSignal } from "../request-utils/abort-utils.js";
+import { RangeRequestScheduler } from "../request-utils/range-request-scheduler.js";
+import { HttpFileTransport } from "./http-file-transport.js";
+/** A reusable, validator-aware, byte-range-addressable HTTP file. */
+export class HttpFile {
+    /** URL used as the ReadableFile handle. */
+    handle;
+    /** Remote object URL. */
+    url;
+    /** HTTP transport and response validator for this file. */
+    transport;
+    /** Scheduler used to coalesce compatible range reads. */
+    rangeScheduler;
+    /** Unique key that prevents coalescing across transport or credential contexts. */
+    schedulerIsolationKey = {};
+    /** Caller-supplied length available before identity discovery. */
+    suppliedByteLength;
+    /** Pinned remote object identity. */
+    identity;
+    /** Shared opening probe, while identity discovery is in progress. */
+    openPromise = null;
+    /** Whether the file has stopped accepting operations. */
+    closed = false;
+    /** Creates a lazy HTTP file. Use {@link HttpFile.open} when identity must be pinned immediately. */
+    constructor(url, options = {}) {
+        this.handle = url;
+        this.url = url;
+        this.transport = new HttpFileTransport(url, options);
+        this.rangeScheduler =
+            options.rangeScheduler ||
+                new RangeRequestScheduler({ batchDelayMs: 0, ...options.rangeSchedulerProps });
+        this.suppliedByteLength = options.byteLength;
+        this.identity = this.transport.getInitialIdentity();
+    }
+    /** Opens a file and pins its byte length and available validators. */
+    static async open(url, options = {}, signal) {
+        const file = new HttpFile(url, options);
+        await file.open(signal);
+        return file;
+    }
+    /** Pins this file's byte length and available validators. */
+    async open(signal) {
+        this.assertOpen();
+        if (signal?.aborted) {
+            const error = createAbortError();
+            this.transport.trackFailure(error);
+            throw error;
+        }
+        await this.getIdentity(signal);
+        return this;
+    }
+    /** Pinned file length, or zero before a lazy file has opened. */
+    get size() {
+        return this.identity?.byteLength ?? this.suppliedByteLength ?? 0;
+    }
+    /** Pinned file length as a bigint, or zero before a lazy file has opened. */
+    get bigsize() {
+        return BigInt(this.size);
+    }
+    /** Returns the pinned identity, or null before a lazy file has opened. */
+    getIdentitySnapshot() {
+        return this.identity;
+    }
+    /** Returns an immutable point-in-time copy of this file's transport counters. */
+    getTelemetry() {
+        return this.transport.getTelemetry();
+    }
+    /** Prevents new operations. Active fetches remain controlled by their read signals. */
+    async close() {
+        this.closed = true;
+    }
+    /** Returns pinned file information without issuing a HEAD request. */
+    async stat() {
+        this.assertOpen();
+        const identity = await this.getIdentity();
+        return {
+            size: identity.byteLength,
+            bigsize: BigInt(identity.byteLength),
+            isDirectory: false
+        };
+    }
+    /** Reads exactly one byte range, with optional cancellation. */
+    async read(offset = 0, length = 0, signal) {
+        this.assertOpen();
+        if (signal?.aborted) {
+            const error = createAbortError();
+            this.transport.trackFailure(error);
+            throw error;
+        }
+        const identity = await this.getIdentity(signal);
+        const numericOffset = normalizeOffset(offset);
+        validateRange(numericOffset, length, identity.byteLength);
+        if (length === 0) {
+            return new ArrayBuffer(0);
+        }
+        try {
+            return await this.rangeScheduler.scheduleRequest({
+                sourceId: this.url,
+                isolationKey: this.schedulerIsolationKey,
+                offset: numericOffset,
+                length,
+                signal,
+                fetchRange: this.fetchScheduledRange
+            });
+        }
+        catch (error) {
+            this.transport.trackFailure(error);
+            throw error;
+        }
+    }
+    /** Reads a range and returns a Response for legacy ReadableFile consumers. */
+    async fetchRange(offset, length, signal) {
+        const numericOffset = normalizeOffset(offset);
+        const arrayBuffer = await this.read(numericOffset, length, signal);
+        const headers = createIdentityHeaders(this.identity, numericOffset, length);
+        return new Response(arrayBuffer, { status: 206, headers });
+    }
+    /** Stable scheduler callback used by every read from this file. */
+    fetchScheduledRange = async (offset, length, signal) => {
+        const identity = await this.getIdentity(signal);
+        const result = await this.transport.requestRange(offset, length, signal, identity);
+        return {
+            arrayBuffer: result.arrayBuffer,
+            status: result.status,
+            transportBytes: result.transportBytes,
+            networkTimeMs: result.networkTimeMs
+        };
+    };
+    /** Returns the shared lazy identity promise, retrying after a failed probe. */
+    getIdentity(signal) {
+        if (this.identity) {
+            return Promise.resolve(this.identity);
+        }
+        if (!this.openPromise) {
+            // The shared probe must not be owned by the first caller's cancellation signal.
+            // Each caller can independently stop waiting while the probe populates the cache.
+            const nextOpenPromise = this.probeIdentity();
+            const cachedOpenPromise = nextOpenPromise.catch(error => {
+                if (this.openPromise === cachedOpenPromise) {
+                    this.openPromise = null;
+                }
+                throw error;
+            });
+            this.openPromise = cachedOpenPromise;
+        }
+        return waitForPromiseWithSignal(this.openPromise, signal).catch(error => {
+            this.transport.trackFailure(error);
+            throw error;
+        });
+    }
+    /** Uses a one-byte GET range to discover object length and validators. */
+    async probeIdentity() {
+        try {
+            const result = await this.transport.requestRange(0, 1, undefined, null);
+            this.identity = result.identity;
+            return result.identity;
+        }
+        catch (error) {
+            this.transport.trackFailure(error);
+            throw error;
+        }
+    }
+    /** Throws when the file has been closed. */
+    assertOpen() {
+        if (this.closed) {
+            throw new Error('HttpFile is closed');
+        }
+    }
+}
+/** Creates the identity headers returned by the compatibility fetchRange method. */
+function createIdentityHeaders(identity, offset, length) {
+    const headers = new Headers();
+    if (length > 0 && identity) {
+        headers.set('Content-Range', `bytes ${offset}-${offset + length - 1}/${identity.byteLength}`);
+    }
+    if (identity?.etag) {
+        headers.set('ETag', identity.etag);
+    }
+    if (identity?.lastModified) {
+        headers.set('Last-Modified', identity.lastModified);
+    }
+    return headers;
+}
+/** Converts and validates a number or bigint offset. */
+function normalizeOffset(offset) {
+    const numericOffset = Number(offset);
+    if (!Number.isSafeInteger(numericOffset) || numericOffset < 0) {
+        throw new Error('HTTP byte-range offset must be a non-negative safe integer');
+    }
+    return numericOffset;
+}
+/** Validates a requested byte range against the pinned object length. */
+function validateRange(offset, length, byteLength) {
+    if (!Number.isSafeInteger(length) || length < 0) {
+        throw new Error('HTTP byte-range length must be a non-negative safe integer');
+    }
+    if (offset + length > byteLength) {
+        throw new Error('HTTP byte range extends beyond the end of the file');
+    }
+}
+/** Creates a conventional abort error without requiring DOMException in every host. */
+function createAbortError() {
+    if (typeof DOMException !== 'undefined') {
+        return new DOMException('Request aborted', 'AbortError');
+    }
+    const error = new Error('Request aborted');
+    error.name = 'AbortError';
+    return error;
+}
+//# sourceMappingURL=http-file.js.map

package/dist/loader-utils/lib/files/http-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-file.js","sourceRoot":"","sources":["../../../../src/loader-utils/lib/files/http-file.ts"],"names":[],"mappings":"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"}