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

package/dist/loader-utils/lib/request-utils/range-request-scheduler.js

@@ -0,0 +1,636 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+import { Stats } from 'probe.gl/stats';
+/** probe.gl `Stats` counter names used for typed range scheduler snapshots. */
+const RANGE_STATS_KEYS = {
+    logicalRanges: 'Logical Range Requests',
+    rangeBatches: 'Range Request Batches',
+    transportRanges: 'Transport Ranges Created',
+    completedTransportRanges: 'Range Transport Requests Completed',
+    coalescedRanges: 'Coalesced Logical Ranges',
+    requestedBytes: 'Logical Range Request Bytes',
+    transportBytes: 'Range Transport Bytes Requested',
+    responseBytes: 'Range Response Bytes',
+    networkTimeMs: 'Range Network Time',
+    overfetchBytes: 'Range Overfetch Bytes',
+    failedTransportRanges: 'Range Transport Requests Failed',
+    abortedLogicalRanges: 'Aborted Logical Range Requests',
+    fullResponseFallbacks: 'Full Response Fallbacks'
+};
+const DEFAULT_PROPS = {
+    batchDelayMs: 50,
+    maxGapBytes: 65536,
+    rangeExpansionBytes: 65536,
+    maxMergedBytes: 8388608,
+    maxConcurrency: 6,
+    maxQueueSize: 4096,
+    maxRangeBytes: 64 * 1024 * 1024,
+    maxTotalBytes: Number.MAX_SAFE_INTEGER,
+    stats: createRangeStats('range-request-scheduler-default'),
+    onEvent: () => { }
+};
+/**
+ * Coalesces nearby byte range requests and carves the merged response back
+ * into the originally requested byte ranges.
+ */
+export class RangeRequestScheduler {
+    /** Runtime scheduler configuration with defaults filled in. */
+    props;
+    /** Runtime counters for range batching and transport behavior. */
+    stats;
+    /** Optional event callback for range batching diagnostics. */
+    onEvent;
+    pendingRequests = [];
+    /** Merged transports waiting for a concurrency slot. */
+    transportQueue = [];
+    /** Number of active transports. */
+    activeTransports = 0;
+    /** Bytes reserved by started transports; failures and cancellation do not refund this budget. */
+    reservedTransportBytes = 0;
+    /** Number of unsettled logical requests. */
+    queuedRequests = 0;
+    /** Unsettled requests retained until completion or disposal. */
+    logicalRequests = new Set();
+    /** Controllers for transports owned by this scheduler. */
+    transportControllers = new Set();
+    /** Disposal prevents further enqueueing. */
+    finalized = false;
+    /** Pending batch window, independent of in-flight transport requests. */
+    flushTimer = null;
+    /** Creates a scheduler for one group of byte-range-addressable resources. */
+    constructor(props = {}) {
+        const rangeExpansionBytes = props.rangeExpansionBytes ?? props.maxGapBytes ?? DEFAULT_PROPS.rangeExpansionBytes;
+        this.props = {
+            batchDelayMs: props.batchDelayMs ?? DEFAULT_PROPS.batchDelayMs,
+            maxGapBytes: props.maxGapBytes ?? rangeExpansionBytes,
+            rangeExpansionBytes,
+            maxMergedBytes: props.maxMergedBytes ?? DEFAULT_PROPS.maxMergedBytes,
+            maxConcurrency: props.maxConcurrency ?? 6,
+            maxQueueSize: props.maxQueueSize ?? 4096,
+            maxRangeBytes: props.maxRangeBytes ?? 64 * 1024 * 1024,
+            maxTotalBytes: props.maxTotalBytes ?? DEFAULT_PROPS.maxTotalBytes
+        };
+        for (const value of [
+            this.props.maxConcurrency,
+            this.props.maxQueueSize,
+            this.props.maxRangeBytes,
+            this.props.maxTotalBytes
+        ]) {
+            if (!Number.isSafeInteger(value) || value <= 0)
+                throw new Error('Range scheduler limits must be positive integers');
+        }
+        this.stats = props.stats || createRangeStats('range-request-scheduler');
+        this.onEvent = props.onEvent;
+        initializeStats(this.stats);
+    }
+    /**
+     * Enqueues one byte range request and resolves with the exact requested byte slice.
+     */
+    scheduleRequest(request) {
+        if (this.finalized)
+            return Promise.reject(new Error('Range scheduler is finalized'));
+        if (!Number.isSafeInteger(request.offset) ||
+            request.offset < 0 ||
+            !Number.isSafeInteger(request.length) ||
+            request.length > this.props.maxRangeBytes ||
+            !Number.isSafeInteger(request.offset + request.length))
+            return Promise.reject(new Error('Invalid or oversized byte range'));
+        if (this.queuedRequests >= this.props.maxQueueSize)
+            return Promise.reject(new Error('Range scheduler queue limit exceeded'));
+        if (request.length < 0) {
+            return Promise.reject(new Error('Byte range length cannot be negative'));
+        }
+        if (request.signal?.aborted) {
+            return Promise.reject(request.signal.reason ?? createAbortError());
+        }
+        if (request.length === 0) {
+            return Promise.resolve(new ArrayBuffer(0));
+        }
+        this.queuedRequests++;
+        let pendingRequest;
+        const promise = new Promise((resolve, reject) => {
+            pendingRequest = { ...request, resolve, reject, settled: false };
+            this.logicalRequests.add(pendingRequest);
+            if (request.signal) {
+                pendingRequest.abortListener = () => {
+                    this.abortRequest(pendingRequest);
+                    pendingRequest.onAbort?.();
+                };
+                request.signal.addEventListener('abort', pendingRequest.abortListener, { once: true });
+            }
+            this.pendingRequests.push(pendingRequest);
+        });
+        this.trackEvent({
+            type: 'queued',
+            sourceId: request.sourceId,
+            offset: request.offset,
+            length: request.length,
+            logicalRequestCount: 1,
+            logicalBytes: request.length
+        });
+        this.scheduleFlush();
+        return promise.finally(() => {
+            if (pendingRequest.abortListener)
+                request.signal?.removeEventListener('abort', pendingRequest.abortListener);
+            this.queuedRequests--;
+            this.logicalRequests.delete(pendingRequest);
+        });
+    }
+    /**
+     * Enqueues one HTTP byte-range request and resolves with the exact requested byte slice.
+     */
+    fetch(request) {
+        const fetchFunction = request.fetch || globalThis.fetch;
+        return this.scheduleRequest({
+            sourceId: request.sourceId || request.url,
+            offset: request.offset,
+            length: request.length,
+            signal: request.signal,
+            // Different fetch calls may carry different credentials or transport implementations.
+            // Sharing is therefore opt-in through an explicit common isolation key.
+            isolationKey: request.isolationKey ?? {},
+            fetchRange: (offset, length, signal) => fetchHttpRange({
+                url: request.url,
+                offset,
+                length,
+                signal,
+                fetch: fetchFunction,
+                fetchOptions: request.fetchOptions
+            })
+        });
+    }
+    /** Immediately starts loading the currently queued requests. */
+    flush() {
+        if (this.flushTimer !== null) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        const pendingRequests = this.pendingRequests;
+        this.pendingRequests = [];
+        const activeRequests = pendingRequests.filter(request => {
+            if (request.settled || request.signal?.aborted) {
+                this.abortRequest(request);
+                return false;
+            }
+            return true;
+        });
+        const mergedRequests = this.mergeRequests(activeRequests);
+        if (activeRequests.length > 0) {
+            this.trackBatch(activeRequests, mergedRequests);
+        }
+        this.transportQueue.push(...mergedRequests);
+        this.startQueuedTransports();
+    }
+    /** Cancels owned work and releases queued resources; borrowed users must not finalize shared schedulers. */
+    finalize() {
+        this.finalized = true;
+        if (this.flushTimer !== null)
+            clearTimeout(this.flushTimer);
+        this.flushTimer = null;
+        for (const request of this.logicalRequests) {
+            this.abortRequest(request);
+            if (request.abortListener)
+                request.signal?.removeEventListener('abort', request.abortListener);
+        }
+        for (const controller of this.transportControllers)
+            controller.abort();
+        this.transportQueue = [];
+        this.pendingRequests = [];
+        this.logicalRequests.clear();
+    }
+    /** Starts transports while respecting the configured concurrency bound. */
+    startQueuedTransports() {
+        while (this.activeTransports < this.props.maxConcurrency && this.transportQueue.length) {
+            const request = this.transportQueue.shift();
+            this.activeTransports++;
+            void this.fetchMergedRequest(request).finally(() => {
+                this.activeTransports--;
+                this.startQueuedTransports();
+            });
+        }
+    }
+    /** Starts a fixed batch window only when no flush is already scheduled. */
+    scheduleFlush() {
+        if (this.flushTimer !== null) {
+            return;
+        }
+        this.flushTimer = setTimeout(() => this.flush(), this.props.batchDelayMs);
+    }
+    /** Sorts active requests and combines requests for the same source when thresholds allow. */
+    mergeRequests(requests) {
+        requests.sort((left, right) => {
+            if (left.sourceId !== right.sourceId) {
+                return left.sourceId < right.sourceId ? -1 : 1;
+            }
+            return left.offset - right.offset;
+        });
+        const mergedRequests = [];
+        for (const request of requests) {
+            const requestEndOffset = request.offset + request.length;
+            const lastMergedRequest = mergedRequests[mergedRequests.length - 1];
+            if (lastMergedRequest && canMergeRequests(lastMergedRequest, request, this.props)) {
+                lastMergedRequest.endOffset = Math.max(lastMergedRequest.endOffset, requestEndOffset);
+                lastMergedRequest.requests.push(request);
+            }
+            else {
+                mergedRequests.push({
+                    sourceId: request.sourceId,
+                    isolationKey: request.isolationKey ?? request.sourceId,
+                    offset: request.offset,
+                    endOffset: requestEndOffset,
+                    fetchRange: request.fetchRange,
+                    requests: [request]
+                });
+            }
+        }
+        return mergedRequests;
+    }
+    /** Loads one merged range and resolves each child request with its sliced bytes. */
+    async fetchMergedRequest(mergedRequest) {
+        const { offset, endOffset, fetchRange, requests } = mergedRequest;
+        const abortController = new AbortController();
+        this.transportControllers.add(abortController);
+        const requestStartTime = getTimestamp();
+        const abortTransportIfUnused = () => {
+            if (requests.every(request => request.settled || request.signal?.aborted)) {
+                abortController.abort();
+            }
+        };
+        try {
+            for (const request of requests) {
+                request.onAbort = abortTransportIfUnused;
+            }
+            abortTransportIfUnused();
+            if (requests.every(request => request.settled)) {
+                return;
+            }
+            const logicalBytes = getLogicalRequestBytes(requests);
+            const length = endOffset - offset;
+            if (length > this.props.maxTotalBytes - this.reservedTransportBytes)
+                throw new RangeError('Range request total byte limit exceeded');
+            // Reserve synchronously before awaiting transport so concurrent reads share one budget.
+            this.reservedTransportBytes += length;
+            this.trackEvent({
+                type: 'request',
+                sourceId: mergedRequest.sourceId,
+                offset,
+                length,
+                logicalRequestCount: requests.length,
+                logicalBytes,
+                transportBytes: length,
+                overfetchBytes: Math.max(length - logicalBytes, 0)
+            });
+            const transportResult = normalizeTransportResult(await fetchRange(offset, length, abortController.signal));
+            const { arrayBuffer } = transportResult;
+            const isClampedFullResponse = transportResult.fullResponse && offset === 0 && arrayBuffer.byteLength < length;
+            const isClampedEndOfFile = arrayBuffer.byteLength < length &&
+                Number.isSafeInteger(transportResult.sourceByteLength) &&
+                offset + arrayBuffer.byteLength === transportResult.sourceByteLength;
+            if (arrayBuffer.byteLength !== length && !isClampedFullResponse && !isClampedEndOfFile) {
+                throw new Error(`Byte-range transport returned ${arrayBuffer.byteLength} bytes; expected ${length}`);
+            }
+            const networkTimeMs = transportResult.networkTimeMs ?? getTimestamp() - requestStartTime;
+            this.trackEvent({
+                type: 'response',
+                sourceId: mergedRequest.sourceId,
+                offset,
+                length,
+                logicalRequestCount: requests.length,
+                logicalBytes,
+                transportBytes: length,
+                responseBytes: transportResult.transportBytes ?? arrayBuffer.byteLength,
+                networkTimeMs,
+                overfetchBytes: Math.max(length - logicalBytes, 0),
+                status: transportResult.status,
+                fullResponse: transportResult.fullResponse
+            });
+            for (const request of requests) {
+                if (request.settled) {
+                    continue;
+                }
+                const start = request.offset - offset;
+                request.settled = true;
+                request.resolve(arrayBuffer.slice(start, start + request.length));
+            }
+        }
+        catch (error) {
+            if (!abortController.signal.aborted) {
+                this.trackEvent({
+                    type: 'error',
+                    sourceId: mergedRequest.sourceId,
+                    offset,
+                    length: endOffset - offset,
+                    logicalRequestCount: requests.length,
+                    logicalBytes: getLogicalRequestBytes(requests),
+                    networkTimeMs: getTimestamp() - requestStartTime,
+                    error
+                });
+            }
+            for (const request of requests) {
+                if (request.settled) {
+                    continue;
+                }
+                if (request.signal?.aborted) {
+                    this.abortRequest(request);
+                }
+                else {
+                    request.settled = true;
+                    request.reject(error);
+                }
+            }
+        }
+        finally {
+            this.transportControllers.delete(abortController);
+            for (const request of requests) {
+                if (request.abortListener) {
+                    request.signal?.removeEventListener('abort', request.abortListener);
+                }
+                request.onAbort = undefined;
+            }
+        }
+    }
+    /** Rejects and tracks one logical request exactly once when its caller aborts. */
+    abortRequest(request) {
+        if (request.settled) {
+            return;
+        }
+        request.settled = true;
+        this.pendingRequests = this.pendingRequests.filter(pending => pending !== request);
+        for (const group of this.transportQueue) {
+            group.requests = group.requests.filter(pending => !pending.settled);
+            if (group.requests.length) {
+                group.offset = Math.min(...group.requests.map(pending => pending.offset));
+                group.endOffset = Math.max(...group.requests.map(pending => pending.offset + pending.length));
+            }
+        }
+        this.transportQueue = this.transportQueue.filter(group => group.requests.length > 0);
+        request.reject(request.signal?.reason ?? createAbortError());
+        this.trackEvent({
+            type: 'abort',
+            sourceId: request.sourceId,
+            offset: request.offset,
+            length: request.length,
+            logicalRequestCount: 1,
+            logicalBytes: request.length
+        });
+    }
+    /** Emits one event to Stats and to the optional callback. */
+    trackEvent(event) {
+        trackStatsEvent(this.stats, event);
+        try {
+            this.onEvent?.(event);
+        }
+        catch {
+            // Diagnostics must not change transport behavior or orphan queued requests.
+        }
+    }
+    /** Emits one batch event after logical requests have been merged. */
+    trackBatch(activeRequests, mergedRequests) {
+        const logicalBytes = getLogicalRequestBytes(activeRequests);
+        const transportBytes = mergedRequests.reduce((sum, mergedRequest) => sum + mergedRequest.endOffset - mergedRequest.offset, 0);
+        this.trackEvent({
+            type: 'batch',
+            logicalRequestCount: activeRequests.length,
+            transportRequestCount: mergedRequests.length,
+            logicalBytes,
+            transportBytes,
+            overfetchBytes: Math.max(transportBytes - logicalBytes, 0)
+        });
+    }
+}
+/**
+ * Tracks range batching events in a probe.gl Stats object.
+ */
+export function trackStatsEvent(stats, event) {
+    if ((event.type === 'response' || event.type === 'error') && event.networkTimeMs !== undefined) {
+        stats.get(RANGE_STATS_KEYS.networkTimeMs, 'time').addTime(event.networkTimeMs);
+    }
+    switch (event.type) {
+        case 'queued':
+            stats.get(RANGE_STATS_KEYS.logicalRanges, 'count').incrementCount();
+            stats.get(RANGE_STATS_KEYS.requestedBytes, 'count').addCount(event.logicalBytes || 0);
+            break;
+        case 'batch':
+            stats.get(RANGE_STATS_KEYS.rangeBatches, 'count').incrementCount();
+            stats.get('Logical Ranges Batched', 'count').addCount(event.logicalRequestCount || 0);
+            stats
+                .get(RANGE_STATS_KEYS.transportRanges, 'count')
+                .addCount(event.transportRequestCount || 0);
+            stats
+                .get(RANGE_STATS_KEYS.coalescedRanges, 'count')
+                .addCount(Math.max((event.logicalRequestCount || 0) - (event.transportRequestCount || 0), 0));
+            stats.get(RANGE_STATS_KEYS.transportBytes, 'count').addCount(event.transportBytes || 0);
+            stats.get(RANGE_STATS_KEYS.overfetchBytes, 'count').addCount(event.overfetchBytes || 0);
+            break;
+        case 'response':
+            stats.get(RANGE_STATS_KEYS.completedTransportRanges, 'count').incrementCount();
+            stats.get(RANGE_STATS_KEYS.responseBytes, 'count').addCount(event.responseBytes || 0);
+            if (event.fullResponse) {
+                stats.get(RANGE_STATS_KEYS.fullResponseFallbacks, 'count').incrementCount();
+            }
+            break;
+        case 'error':
+            stats.get(RANGE_STATS_KEYS.failedTransportRanges, 'count').incrementCount();
+            break;
+        case 'abort':
+            stats.get(RANGE_STATS_KEYS.abortedLogicalRanges, 'count').incrementCount();
+            break;
+        default:
+    }
+}
+/** Creates a probe.gl `Stats` object initialized with byte-range scheduler counters. */
+export function createRangeStats(id = 'range-request-scheduler') {
+    const stats = new Stats({ id });
+    initializeStats(stats);
+    return stats;
+}
+/** Reads byte-range scheduler counters from a probe.gl `Stats` object. */
+export function getRangeStats(stats) {
+    return {
+        logicalRanges: stats.get(RANGE_STATS_KEYS.logicalRanges).count,
+        rangeBatches: stats.get(RANGE_STATS_KEYS.rangeBatches).count,
+        transportRanges: stats.get(RANGE_STATS_KEYS.transportRanges).count,
+        completedTransportRanges: stats.get(RANGE_STATS_KEYS.completedTransportRanges).count,
+        coalescedRanges: stats.get(RANGE_STATS_KEYS.coalescedRanges).count,
+        requestedBytes: stats.get(RANGE_STATS_KEYS.requestedBytes).count,
+        transportBytes: stats.get(RANGE_STATS_KEYS.transportBytes).count,
+        responseBytes: stats.get(RANGE_STATS_KEYS.responseBytes).count,
+        networkTimeMs: stats.get(RANGE_STATS_KEYS.networkTimeMs).time,
+        overfetchBytes: stats.get(RANGE_STATS_KEYS.overfetchBytes).count,
+        failedTransportRanges: stats.get(RANGE_STATS_KEYS.failedTransportRanges).count,
+        abortedLogicalRanges: stats.get(RANGE_STATS_KEYS.abortedLogicalRanges).count,
+        fullResponseFallbacks: stats.get(RANGE_STATS_KEYS.fullResponseFallbacks).count
+    };
+}
+/** Issues one HTTP range request and parses range-related status/header behavior. */
+export async function fetchHttpRange(request) {
+    const abortContext = createAbortableFetchContext(request.signal);
+    const requestStartTime = getTimestamp();
+    try {
+        let fullResponse = false;
+        let response = await request.fetch(request.url, createRangeFetchOptions(request.fetchOptions, request.offset, request.length, abortContext.signal));
+        if (response.status === 416 && request.offset === 0) {
+            const actualLength = parseUnsatisfiedContentRange(response.headers.get('Content-Range'));
+            if (!actualLength) {
+                throw new Error('Missing content-length on 416 response');
+            }
+            response = await request.fetch(request.url, createRangeFetchOptions(request.fetchOptions, 0, actualLength, abortContext.signal));
+            fullResponse = true;
+        }
+        if (response.status === 200) {
+            abortContext.abort();
+            await cancelIgnoredRangeResponse(response);
+            throw new Error('Byte-range request failed: server returned 200 instead of 206');
+        }
+        if (response.status !== 206 && !response.ok) {
+            throw new Error(`Bad response code: ${response.status}`);
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        const contentRangeHeader = response.headers.get('Content-Range');
+        const contentRange = parseSatisfiedContentRange(contentRangeHeader);
+        if (contentRangeHeader && !contentRange) {
+            throw new Error(`Invalid Content-Range header: ${contentRangeHeader}`);
+        }
+        if (contentRange) {
+            const responseLength = contentRange.endOffset - contentRange.offset + 1;
+            const requestedEndOffset = request.offset + request.length - 1;
+            if (contentRange.offset !== request.offset ||
+                contentRange.endOffset > requestedEndOffset ||
+                responseLength !== arrayBuffer.byteLength ||
+                (contentRange.sourceByteLength !== undefined &&
+                    contentRange.endOffset >= contentRange.sourceByteLength)) {
+                throw new Error(`Content-Range does not match requested range: ${contentRangeHeader}`);
+            }
+        }
+        return {
+            arrayBuffer,
+            status: response.status,
+            sourceByteLength: contentRange?.sourceByteLength,
+            transportBytes: arrayBuffer.byteLength,
+            networkTimeMs: getTimestamp() - requestStartTime,
+            fullResponse
+        };
+    }
+    finally {
+        abortContext.removeAbortListener();
+    }
+}
+/** Returns true when a new request can be folded into an existing merged request. */
+function canMergeRequests(mergedRequest, request, props) {
+    if (mergedRequest.sourceId !== request.sourceId) {
+        return false;
+    }
+    if (mergedRequest.isolationKey !== (request.isolationKey ?? request.sourceId)) {
+        return false;
+    }
+    const requestEndOffset = request.offset + request.length;
+    const gapBytes = request.offset - mergedRequest.endOffset;
+    const mergedBytes = Math.max(mergedRequest.endOffset, requestEndOffset) - mergedRequest.offset;
+    return gapBytes <= props.rangeExpansionBytes && mergedBytes <= props.maxMergedBytes;
+}
+/** Initializes the Stats keys used by the range scheduler. */
+function initializeStats(stats) {
+    stats.get(RANGE_STATS_KEYS.logicalRanges, 'count');
+    stats.get(RANGE_STATS_KEYS.requestedBytes, 'count');
+    stats.get(RANGE_STATS_KEYS.rangeBatches, 'count');
+    stats.get('Logical Ranges Batched', 'count');
+    stats.get(RANGE_STATS_KEYS.transportRanges, 'count');
+    stats.get(RANGE_STATS_KEYS.coalescedRanges, 'count');
+    stats.get(RANGE_STATS_KEYS.transportBytes, 'count');
+    stats.get(RANGE_STATS_KEYS.completedTransportRanges, 'count');
+    stats.get(RANGE_STATS_KEYS.responseBytes, 'count');
+    stats.get(RANGE_STATS_KEYS.networkTimeMs, 'time');
+    stats.get(RANGE_STATS_KEYS.overfetchBytes, 'count');
+    stats.get(RANGE_STATS_KEYS.fullResponseFallbacks, 'count');
+    stats.get(RANGE_STATS_KEYS.failedTransportRanges, 'count');
+    stats.get(RANGE_STATS_KEYS.abortedLogicalRanges, 'count');
+}
+/** Returns the sum of the caller-requested byte lengths. */
+function getLogicalRequestBytes(requests) {
+    return requests.reduce((sum, request) => sum + request.length, 0);
+}
+/** Normalizes legacy ArrayBuffer fetch results and diagnostic transport results. */
+function normalizeTransportResult(result) {
+    return result instanceof ArrayBuffer ? { arrayBuffer: result } : result;
+}
+/** Creates fetch options for one HTTP byte-range request while preserving caller headers. */
+function createRangeFetchOptions(fetchOptions, offset, length, signal) {
+    return {
+        ...fetchOptions,
+        signal,
+        headers: {
+            ...getHeadersObject(fetchOptions?.headers),
+            Range: `bytes=${offset}-${offset + length - 1}`
+        }
+    };
+}
+/** Copies supported HeadersInit values into a plain object so Range can be merged in. */
+function getHeadersObject(headers) {
+    if (!headers) {
+        return {};
+    }
+    if (headers instanceof Headers) {
+        return Object.fromEntries(headers.entries());
+    }
+    if (Array.isArray(headers)) {
+        return Object.fromEntries(headers);
+    }
+    return headers;
+}
+/** Parses a `Content-Range: bytes *\/<length>` header from an unsatisfied range response. */
+function parseUnsatisfiedContentRange(contentRange) {
+    const match = contentRange?.match(/^bytes \*\/(\d+)$/);
+    return match ? Number(match[1]) : null;
+}
+/** Parses a `Content-Range: bytes <start>-<end>/<length-or-*>` response header. */
+function parseSatisfiedContentRange(contentRange) {
+    const match = contentRange?.match(/^bytes (\d+)-(\d+)\/(\d+|\*)$/);
+    if (!match) {
+        return null;
+    }
+    const offset = Number(match[1]);
+    const endOffset = Number(match[2]);
+    const sourceByteLength = match[3] === '*' ? undefined : Number(match[3]);
+    if (!Number.isSafeInteger(offset) ||
+        !Number.isSafeInteger(endOffset) ||
+        offset > endOffset ||
+        (sourceByteLength !== undefined && !Number.isSafeInteger(sourceByteLength))) {
+        return null;
+    }
+    return { offset, endOffset, sourceByteLength };
+}
+/** Creates an inner abort controller that follows an optional parent signal and can cancel one fetch. */
+function createAbortableFetchContext(parentSignal) {
+    const abortController = new AbortController();
+    const abortListener = () => abortController.abort(parentSignal?.reason);
+    if (parentSignal?.aborted) {
+        abortController.abort(parentSignal?.reason);
+    }
+    else {
+        parentSignal?.addEventListener('abort', abortListener, { once: true });
+    }
+    return {
+        signal: abortController.signal,
+        abort: () => abortController.abort(),
+        removeAbortListener: () => parentSignal?.removeEventListener('abort', abortListener)
+    };
+}
+/** Cancels a response body when a server ignores a `Range` header and starts sending the whole archive. */
+async function cancelIgnoredRangeResponse(response) {
+    await response.body?.cancel().catch(() => { });
+}
+/** Returns a high-resolution timestamp when available. */
+function getTimestamp() {
+    return globalThis.performance?.now() ?? Date.now();
+}
+/** 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=range-request-scheduler.js.map