@ar.io/wayfinder-core 1.7.2 → 1.8.0

package/README.md

@@ -345,6 +345,128 @@ const wayfinder = createWayfinderClient({
 });
 ```
 
+## Data Retrieval Strategies
+
+Wayfinder supports multiple data retrieval strategies to fetch transaction data from AR.IO gateways. These strategies determine how data is requested and assembled from the underlying storage layer.
+
+| Strategy                          | Default | Performance | Use Case                                    | Requirements                           |
+| --------------------------------- | ------- | ----------- | ------------------------------------------- | -------------------------------------- |
+| `ContiguousDataRetrievalStrategy` | ✅      | High        | Standard data fetching via direct GET      | Gateway has the data available         |
+| `ChunkDataRetrievalStrategy`      | ❌      | Medium      | Chunk-based data assembly for large files  | Gateway supports `/chunk/<offset>/data` endpoint and has requested transaction indexed as offsets are needed |
+
+#### ContiguousDataRetrievalStrategy
+
+The default strategy that fetches data using a direct GET request to the gateway. This is the most straightforward approach and works for most use cases.
+
+```javascript
+import { Wayfinder, ContiguousDataRetrievalStrategy } from '@ar.io/wayfinder-core';
+
+const wayfinder = new Wayfinder({
+  dataRetrievalStrategy: new ContiguousDataRetrievalStrategy(),
+});
+```
+
+#### ChunkDataRetrievalStrategy
+
+An advanced strategy that provides the easiest way to load chunks stored on Arweave nodes via the robust chunk API provided by AR.IO gateways. This approach is particularly useful for:
+
+- **Direct chunk access**: Efficiently retrieves data directly from the underlying chunk storage layer
+- **Bundled data items**: Seamlessly fetches data items from within ANS-104 bundles using calculated offsets
+- **x402 payment compatibility**: Both strategies support custom fetch clients for payment-enabled requests
+- **Large file handling**: More reliable for large transactions that may time out with direct requests
+
+**Requirements:**
+
+- Gateway must support the `/chunk/<offset>/data` endpoint (added in [r58](https://github.com/ar-io/ar-io-node/releases/tag/r58))
+- Gateway must have the requested transaction indexed (offsets are needed to fetch directly from chunks)
+
+```javascript
+import { Wayfinder, ChunkDataRetrievalStrategy } from '@ar.io/wayfinder-core';
+
+const wayfinder = new Wayfinder({
+  dataRetrievalStrategy: new ChunkDataRetrievalStrategy(),
+});
+```
+
+**How it works:**
+
+1. Makes a HEAD request to get transaction metadata (root transaction ID, data offset, content length)
+2. Queries `/tx/{root-tx-id}/offset` to get the root transaction's absolute offset in the weave
+3. Calculates the absolute offset for the requested data item
+4. Fetches data in chunks using `/chunk/<offset>/data` and assembles the complete data stream
+5. Validates that chunks belong to the expected root transaction for security
+
+**Sequence Diagram:**
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Wayfinder
+    participant Gateway as AR.IO Gateway
+    participant Arweave as Arweave Nodes
+
+    Client->>Wayfinder: request('ar://data-item-id')
+    activate Wayfinder
+
+    Wayfinder->>Gateway: HEAD /tx/{data-item-id}
+    Note over Gateway: Lookup data item metadata<br/>from indexed bundles
+    Gateway-->>Wayfinder: Headers:<br/>- x-root-tx-id (bundle ID)<br/>- x-data-offset<br/>- content-length
+
+    Wayfinder->>Gateway: GET /tx/{root-tx-id}/offset
+    Gateway->>Arweave: GET /tx/{root-tx-id}/offset
+    Note over Arweave: Lookup transaction offset<br/>in the weave
+    Arweave-->>Gateway: Root transaction offset
+    Gateway-->>Wayfinder: Root transaction offset in weave
+
+    Note over Wayfinder: Calculate absolute offset:<br/>absolute = root_offset + data_offset
+
+    loop For each chunk needed
+        Wayfinder->>Gateway: GET /chunk/{absolute-offset}/data
+        
+        Note over Gateway: Serve chunk data from<br/>indexed storage using<br/>root transaction ID
+        
+        Gateway-->>Wayfinder: Chunk data + validation headers<br/>(x-root-tx-id for security)
+        
+        Note over Wayfinder: Validate chunk belongs<br/>to expected root TX
+        
+        Wayfinder-->>Client: Stream chunk data
+    end
+
+    Wayfinder-->>Client: Complete response
+    deactivate Wayfinder
+```
+
+**Example with createWayfinderClient:**
+
+```javascript
+import { createWayfinderClient, ChunkDataRetrievalStrategy } from '@ar.io/wayfinder-core';
+
+const wayfinder = createWayfinderClient({
+  dataRetrievalStrategy: new ChunkDataRetrievalStrategy(),
+});
+
+// Fetch a data item from within an ANS-104 bundle
+const response = await wayfinder.request('ar://data-item-id');
+```
+
+#### x402 Support
+
+Both data retrieval strategies support custom fetch implementations, allowing you to use x402-enabled fetch clients for paid gateway requests.
+
+```javascript
+import { createWayfinderClient, ChunkDataRetrievalStrategy } from '@ar.io/wayfinder-core';
+import { createX402Fetch } from '@ar.io/wayfinder-x402-fetch';
+
+const x402Fetch = createX402Fetch({ /* payment config */ });
+
+const wayfinder = createWayfinderClient({
+  fetch: x402Fetch,
+  dataRetrievalStrategy: new ChunkDataRetrievalStrategy({
+    fetch: x402Fetch,
+  }),
+});
+```
+
 ## Verification Strategies
 
 Wayfinder includes verification mechanisms to ensure the integrity of retrieved data. Verification strategies offer different trade-offs between complexity, performance, and security.

package/dist/{fetch.d.ts → fetch/base-fetch.d.ts}

@@ -20,4 +20,4 @@
  * @returns The native fetch function
  */
 export declare const createBaseFetch: () => typeof globalThis.fetch;
-//# sourceMappingURL=fetch.d.ts.map
+//# sourceMappingURL=base-fetch.d.ts.map

package/dist/fetch/base-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-fetch.d.ts","sourceRoot":"","sources":["../../src/fetch/base-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;GAIG;AACH,eAAO,MAAM,eAAe,QAAO,OAAO,UAAU,CAAC,KAEpD,CAAC"}

package/dist/fetch/wayfinder-fetch.d.ts

@@ -0,0 +1,45 @@
+/**
+ * WayFinder
+ * Copyright (C) 2022-2025 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type Tracer } from '@opentelemetry/api';
+import { WayfinderEmitter } from '../emitter.js';
+import type { DataRetrievalStrategy, Logger, RoutingStrategy, VerificationStrategy, WayfinderEvents, WayfinderRequestInit } from '../types.js';
+/**
+ * Creates a wrapped fetch function that supports ar:// protocol
+ 
+ * @param logger - Optional logger for logging fetch operations
+ * @param strict - Whether to enforce strict verification
+ * @param fetch - Base fetch function to use for HTTP requests
+ * @param routingStrategy - Strategy for selecting gateways
+ * @param dataRetrievalStrategy - Strategy for retrieving data
+ * @param verificationStrategy - Strategy for verifying data integrity
+ * @param emitter - Optional event emitter for wayfinder events
+ * @param tracer - Optional OpenTelemetry tracer for tracing fetch operations
+ * @param events - Optional event handlers for wayfinder events
+ * @returns a wrapped fetch function that supports ar:// protocol and always returns Response
+ */
+export declare const createWayfinderFetch: ({ logger, strict, fetch, routingStrategy, dataRetrievalStrategy, verificationStrategy, emitter, tracer, events, }: {
+    logger?: Logger;
+    verificationStrategy?: VerificationStrategy;
+    strict?: boolean;
+    routingStrategy?: RoutingStrategy;
+    dataRetrievalStrategy?: DataRetrievalStrategy;
+    emitter?: WayfinderEmitter;
+    tracer?: Tracer;
+    fetch?: typeof globalThis.fetch;
+    events?: WayfinderEvents;
+}) => ((input: URL | RequestInfo, init?: WayfinderRequestInit) => Promise<Response>);
+//# sourceMappingURL=wayfinder-fetch.d.ts.map

package/dist/fetch/wayfinder-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wayfinder-fetch.d.ts","sourceRoot":"","sources":["../../src/fetch/wayfinder-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,KAAK,MAAM,EAAkB,MAAM,oBAAoB,CAAC;AAEjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAIjD,OAAO,KAAK,EACV,qBAAqB,EACrB,MAAM,EACN,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,oBAAoB,EACrB,MAAM,aAAa,CAAC;AASrB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,GAAI,mHAYlC;IACD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAC9C,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B,KAAG,CAAC,CACH,KAAK,EAAE,GAAG,GAAG,WAAW,EACxB,IAAI,CAAC,EAAE,oBAAoB,KACxB,OAAO,CAAC,QAAQ,CAAC,CA0LrB,CAAC"}

package/dist/fetch/wayfinder-fetch.js

@@ -0,0 +1,192 @@
+/**
+ * WayFinder
+ * Copyright (C) 2022-2025 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { context, trace } from '@opentelemetry/api';
+import { arioHeaderNames } from '../constants.js';
+import { WayfinderEmitter } from '../emitter.js';
+import { defaultLogger } from '../logger.js';
+import { ContiguousDataRetrievalStrategy } from '../retrieval/contiguous.js';
+import { RandomRoutingStrategy } from '../routing/random.js';
+import { tapAndVerifyReadableStream } from '../utils/verify-stream.js';
+import { constructGatewayUrl, createWayfinderRequestHeaders, extractRoutingInfo, } from '../wayfinder.js';
+import { createBaseFetch } from './base-fetch.js';
+/**
+ * Creates a wrapped fetch function that supports ar:// protocol
+ 
+ * @param logger - Optional logger for logging fetch operations
+ * @param strict - Whether to enforce strict verification
+ * @param fetch - Base fetch function to use for HTTP requests
+ * @param routingStrategy - Strategy for selecting gateways
+ * @param dataRetrievalStrategy - Strategy for retrieving data
+ * @param verificationStrategy - Strategy for verifying data integrity
+ * @param emitter - Optional event emitter for wayfinder events
+ * @param tracer - Optional OpenTelemetry tracer for tracing fetch operations
+ * @param events - Optional event handlers for wayfinder events
+ * @returns a wrapped fetch function that supports ar:// protocol and always returns Response
+ */
+export const createWayfinderFetch = ({ logger = defaultLogger, strict = false, fetch = createBaseFetch(), routingStrategy = new RandomRoutingStrategy(), dataRetrievalStrategy = new ContiguousDataRetrievalStrategy({
+    fetch,
+}), verificationStrategy, emitter, tracer, events, }) => {
+    return async (input, init) => {
+        /**
+         * Summary:
+         *
+         * 1. Check if URL is ar:// - if not, call fetch directly
+         * 2. Extract routing info (subdomain, path, txId, arnsName)
+         * 3. Use routing strategy to select gateway
+         * 4. Construct gateway URL given the requested resource
+         * 5. If no txId or arnsName, perform direct fetch to gateway URL
+         * 6. If txId or arnsName present, use data retrieval strategy to fetch data
+         * 7. If verification strategy present, verify data stream
+         * 8. Return a Response object with the (optionally verified) data stream
+         */
+        const requestUri = input instanceof URL ? input.toString() : input.toString();
+        if (!requestUri.startsWith('ar://')) {
+            logger?.debug('URL is not a wayfinder url, skipping routing', {
+                input,
+            });
+            emitter?.emit('routing-skipped', {
+                originalUrl: JSON.stringify(input),
+            });
+            return fetch(input, init);
+        }
+        const { subdomain, path, txId, arnsName } = extractRoutingInfo(requestUri);
+        // Create request-specific emitter
+        const requestEmitter = new WayfinderEmitter({
+            verification: {
+                ...events,
+                ...init?.verificationSettings?.events,
+            },
+            routing: {
+                ...events,
+                ...init?.routingSettings?.events,
+            },
+            parentEmitter: emitter,
+        });
+        // Create parent span for the entire fetch operation
+        const parentSpan = tracer?.startSpan('wayfinder.fetch');
+        // Create request span
+        const requestSpan = parentSpan
+            ? tracer?.startSpan('wayfinder.fetch.wayfinderDataFetcher', undefined, trace.setSpan(context.active(), parentSpan))
+            : undefined;
+        // Add request attributes to span
+        requestSpan?.setAttribute('request.url', requestUri);
+        requestSpan?.setAttribute('request.method', 'GET');
+        // Emit routing started event
+        requestEmitter.emit('routing-started', {
+            originalUrl: requestUri,
+        });
+        try {
+            logger.debug('Fetching data', {
+                uri: requestUri,
+                subdomain,
+                path,
+            });
+            // Select gateway using routing strategy
+            const selectedGateway = await routingStrategy.selectGateway({
+                path,
+                subdomain,
+            });
+            // it's just a non data specific request, construct the gateway URL and fetch directly
+            const redirectUrl = constructGatewayUrl({
+                selectedGateway,
+                subdomain,
+                path,
+            });
+            // Emit routing succeeded event
+            requestEmitter.emit('routing-succeeded', {
+                originalUrl: requestUri,
+                selectedGateway: selectedGateway.toString(),
+                redirectUrl: redirectUrl.toString(),
+            });
+            // if its a txId or arnsName use the dataRetrievalStrategy to fetch the data; otherwise just call internal fetch
+            if (!txId && !arnsName) {
+                logger.debug('No transaction ID or ARNS name found, performing direct fetch', {
+                    uri: requestUri,
+                });
+                return fetch(redirectUrl.toString(), init);
+            }
+            const requestHeaders = {
+                ...Object.fromEntries(new Headers(init?.headers || {})),
+                ...createWayfinderRequestHeaders({
+                    traceId: requestSpan?.spanContext().traceId,
+                }),
+            };
+            // Use data retrieval strategy to fetch the actual data
+            const dataResponse = await dataRetrievalStrategy.getData({
+                gateway: selectedGateway,
+                requestUrl: redirectUrl,
+                headers: requestHeaders,
+            });
+            // If the response is not successful (e.g., 404, 500), return it directly
+            if (!dataResponse.ok) {
+                logger.debug('Gateway returned error response', {
+                    uri: requestUri,
+                    status: dataResponse.status,
+                    statusText: dataResponse.statusText,
+                });
+                return dataResponse;
+            }
+            logger.debug('Successfully fetched data', {
+                uri: requestUri,
+            });
+            // Extract data ID from headers for verification
+            const resolvedDataId = dataResponse.headers.get(arioHeaderNames.dataId.toLowerCase()) || txId;
+            const contentLength = dataResponse.headers.has('content-length')
+                ? parseInt(dataResponse.headers.get('content-length'), 10)
+                : 0;
+            const finalVerificationStrategy = init?.verificationSettings?.enabled
+                ? init.verificationSettings.strategy
+                : verificationStrategy;
+            let finalStream = dataResponse.body;
+            // Apply verification if strategy is provided
+            if (resolvedDataId && dataResponse.body && finalVerificationStrategy) {
+                logger.debug('Applying verification to data stream', {
+                    dataId: resolvedDataId,
+                });
+                // Determine strict mode - check init first, then fall back to instance settings
+                const isStrictMode = init?.verificationSettings?.strict ?? strict;
+                finalStream = tapAndVerifyReadableStream({
+                    originalStream: dataResponse.body,
+                    contentLength: contentLength,
+                    verifyData: finalVerificationStrategy.verifyData.bind(finalVerificationStrategy),
+                    txId: resolvedDataId,
+                    headers: Object.fromEntries(dataResponse.headers),
+                    emitter: requestEmitter,
+                    strict: isStrictMode,
+                });
+            }
+            return new Response(finalStream, {
+                headers: dataResponse.headers,
+                status: dataResponse.status,
+                statusText: dataResponse.statusText,
+            });
+        }
+        catch (error) {
+            requestEmitter.emit('routing-failed', error);
+            logger.error('Failed to fetch data', {
+                error: error.message,
+                stack: error.stack,
+                uri: requestUri,
+            });
+            throw error;
+        }
+        finally {
+            requestSpan?.end();
+            parentSpan?.end();
+        }
+    };
+};

package/dist/retrieval/chunk.d.ts

@@ -0,0 +1,36 @@
+/**
+ * WayFinder
+ * Copyright (C) 2022-2025 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { DataRetrievalStrategy, Logger } from '../types.js';
+/**
+ * Chunk data retrieval strategy that fetches transaction data in chunks
+ * by first getting metadata from HEAD request, then streaming individual
+ * chunks from /chunk/{offset}/data endpoint.
+ */
+export declare class ChunkDataRetrievalStrategy implements DataRetrievalStrategy {
+    private logger;
+    private fetch;
+    constructor({ logger, fetch, }?: {
+        logger?: Logger;
+        fetch?: typeof globalThis.fetch;
+    });
+    getData({ gateway, requestUrl, headers, }: {
+        gateway: URL;
+        requestUrl: URL;
+        headers?: Record<string, string>;
+    }): Promise<Response>;
+}
+//# sourceMappingURL=chunk.d.ts.map

package/dist/retrieval/chunk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../../src/retrieval/chunk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAEjE;;;;GAIG;AACH,qBAAa,0BAA2B,YAAW,qBAAqB;IACtE,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAA0B;gBAE3B,EACV,MAAsB,EACtB,KAAwB,GACzB,GAAE;QACD,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;KAC5B;IAKA,OAAO,CAAC,EACZ,OAAO,EACP,UAAU,EACV,OAAO,GACR,EAAE;QACD,OAAO,EAAE,GAAG,CAAC;QACb,UAAU,EAAE,GAAG,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAClC,GAAG,OAAO,CAAC,QAAQ,CAAC;CAwOtB"}

package/dist/retrieval/chunk.js

@@ -0,0 +1,178 @@
+/**
+ * WayFinder
+ * Copyright (C) 2022-2025 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { arioHeaderNames } from '../constants.js';
+import { defaultLogger } from '../logger.js';
+/**
+ * Chunk data retrieval strategy that fetches transaction data in chunks
+ * by first getting metadata from HEAD request, then streaming individual
+ * chunks from /chunk/{offset}/data endpoint.
+ */
+export class ChunkDataRetrievalStrategy {
+    logger;
+    fetch;
+    constructor({ logger = defaultLogger, fetch = globalThis.fetch, } = {}) {
+        this.logger = logger;
+        this.fetch = fetch;
+    }
+    async getData({ gateway, requestUrl, headers, }) {
+        this.logger.debug('Fetching data via ChunkDataRetrievalStrategy from gateway', {
+            gateway: gateway.toString(),
+            requestUrl: requestUrl.toString(),
+        });
+        const headResponse = await this.fetch(requestUrl.toString(), {
+            method: 'HEAD',
+            headers,
+        });
+        if (!headResponse.ok) {
+            throw new Error(`HEAD request failed: ${headResponse.status}`);
+        }
+        const rootTransactionId = headResponse.headers.get(arioHeaderNames.rootTransactionId);
+        if (!rootTransactionId) {
+            this.logger.warn('Missing root transaction ID header, cannot use chunk API');
+            throw new Error('No root transaction ID header present - cannot use chunk API');
+        }
+        const relativeRootOffsetHeader = headResponse.headers.get(arioHeaderNames.rootDataOffset);
+        if (!relativeRootOffsetHeader) {
+            this.logger.warn('Missing root data offset header, cannot use chunk API');
+            throw new Error('No root data offset header present - cannot use chunk API');
+        }
+        const relativeRootOffset = parseInt(relativeRootOffsetHeader, 10);
+        // get the absolute offset of the root transaction id from the gateway via /offset path
+        const offsetForRootTransactionIdUrl = new URL(`/tx/${rootTransactionId}/offset`, gateway);
+        const offsetResponse = await this.fetch(offsetForRootTransactionIdUrl.toString(), {
+            method: 'GET',
+            redirect: 'follow',
+            headers,
+        });
+        if (!offsetResponse.ok) {
+            throw new Error(`Failed to fetch offset for root transaction ID: ${offsetResponse.status}`);
+        }
+        const { offset: offsetForRootTransactionIdString, size: rootTransactionSizeString, } = (await offsetResponse.json());
+        const rootTransactionEndOffset = parseInt(offsetForRootTransactionIdString, 10);
+        const rootTransactionSize = parseInt(rootTransactionSizeString, 10);
+        // The /tx/{id}/offset endpoint returns the END offset of the transaction
+        // We need to calculate the START offset: endOffset - size + 1
+        const absoluteOffsetForRootTransaction = rootTransactionEndOffset - rootTransactionSize + 1;
+        const absoluteOffsetForDataItem = absoluteOffsetForRootTransaction + relativeRootOffset;
+        const contentLength = headResponse.headers.get('content-length');
+        if (!contentLength) {
+            throw new Error('Missing content-length header from HEAD response');
+        }
+        const totalSize = parseInt(contentLength, 10);
+        this.logger.debug('Successfully retrieved necessary offset information', {
+            rootTransactionId,
+            relativeRootOffset,
+            rootTransactionEndOffset,
+            rootTransactionSize,
+            absoluteOffsetForRootTransaction,
+            absoluteOffsetForDataItem,
+            totalSize,
+        });
+        // Store references for use inside the stream
+        const logger = this.logger;
+        const fetchFn = this.fetch;
+        const chunkGateway = gateway;
+        // Create a readable stream that fetches chunks on demand
+        const stream = new ReadableStream({
+            async start(controller) {
+                let currentOffset = absoluteOffsetForDataItem; // Start from where our data item actually is
+                let bytesRead = 0;
+                while (bytesRead < totalSize) {
+                    try {
+                        const chunkUrl = new URL(`/chunk/${currentOffset}/data`, chunkGateway);
+                        logger.debug('Fetching chunk', {
+                            url: chunkUrl.toString(),
+                            currentOffset,
+                            bytesRead,
+                            totalSize,
+                        });
+                        const chunkResponse = await fetchFn(chunkUrl.toString(), {
+                            method: 'GET',
+                            redirect: 'follow',
+                            headers,
+                        });
+                        if (!chunkResponse.ok) {
+                            throw new Error(`Chunk request failed at offset ${currentOffset}: ${chunkResponse.status} ${chunkResponse.statusText}`);
+                        }
+                        // Get chunk metadata headers
+                        const chunkReadOffsetHeader = chunkResponse.headers.get(arioHeaderNames.chunkReadOffset);
+                        const chunkStartOffsetHeader = chunkResponse.headers.get(arioHeaderNames.chunkStartOffset);
+                        const chunkTxId = chunkResponse.headers.get(arioHeaderNames.chunkTxId);
+                        if (!chunkReadOffsetHeader) {
+                            throw new Error('Missing chunk read offset header from chunk response');
+                        }
+                        // Assert that the chunk belongs to our root transaction
+                        if (chunkTxId !== rootTransactionId) {
+                            logger.error('Chunk belongs to wrong transaction', {
+                                currentOffset,
+                                expectedTxId: rootTransactionId,
+                                actualTxId: chunkTxId,
+                                chunkStartOffset: chunkStartOffsetHeader,
+                                chunkReadOffset: chunkReadOffsetHeader,
+                            });
+                            throw new Error(`Chunk transaction ID mismatch at offset ${currentOffset}. Expected: ${rootTransactionId}, Got: ${chunkTxId}`);
+                        }
+                        logger.debug('Chunk belongs to correct root transaction', {
+                            chunkTxId,
+                            rootTransactionId,
+                            offset: currentOffset,
+                        });
+                        const chunkData = await chunkResponse.arrayBuffer();
+                        const fullChunkArray = new Uint8Array(chunkData);
+                        const chunkReadOffset = parseInt(chunkReadOffsetHeader, 10);
+                        // Extract data starting from chunk read offset
+                        let dataToEnqueue = fullChunkArray.slice(chunkReadOffset);
+                        // Limit data to only what we need (don't exceed totalSize)
+                        const remainingBytes = totalSize - bytesRead;
+                        if (dataToEnqueue.length > remainingBytes) {
+                            dataToEnqueue = dataToEnqueue.slice(0, remainingBytes);
+                        }
+                        // Enqueue the extracted data
+                        controller.enqueue(dataToEnqueue);
+                        // Update counters
+                        bytesRead += dataToEnqueue.length;
+                        // Calculate next offset for multi-chunk files
+                        const chunkStartOffset = parseInt(chunkStartOffsetHeader || currentOffset.toString(), 10);
+                        currentOffset = chunkStartOffset + fullChunkArray.length;
+                        // If we've read all the data, close the stream
+                        if (bytesRead >= totalSize) {
+                            logger.info('Successfully retrieved all data', {
+                                totalBytesRead: bytesRead,
+                                totalSize,
+                            });
+                            controller.close();
+                            break;
+                        }
+                    }
+                    catch (error) {
+                        controller.error(error);
+                        break;
+                    }
+                }
+            },
+        });
+        const response = new Response(stream, {
+            status: 200,
+            headers: {
+                // all the original ario headers from the HEAD request
+                ...Object.fromEntries(headResponse.headers),
+                'x-wayfinder-data-retrieval-strategy': 'chunk',
+            },
+        });
+        return response;
+    }
+}

package/dist/retrieval/contiguous.d.ts

@@ -0,0 +1,35 @@
+/**
+ * WayFinder
+ * Copyright (C) 2022-2025 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { DataRetrievalStrategy, Logger } from '../types.js';
+/**
+ * Contiguous data retrieval strategy that fetches the entire transaction
+ * data in a single streaming request
+ */
+export declare class ContiguousDataRetrievalStrategy implements DataRetrievalStrategy {
+    private logger;
+    private fetch;
+    constructor({ logger, fetch, }?: {
+        logger?: Logger;
+        fetch?: typeof globalThis.fetch;
+    });
+    getData({ requestUrl, headers, }: {
+        gateway: URL;
+        requestUrl: URL;
+        headers?: Record<string, string>;
+    }): Promise<Response>;
+}
+//# sourceMappingURL=contiguous.d.ts.map

package/dist/retrieval/contiguous.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contiguous.d.ts","sourceRoot":"","sources":["../../src/retrieval/contiguous.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAEjE;;;GAGG;AACH,qBAAa,+BAAgC,YAAW,qBAAqB;IAC3E,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAA0B;gBAE3B,EACV,MAAsB,EACtB,KAAwB,GACzB,GAAE;QACD,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;KAC5B;IAKA,OAAO,CAAC,EACZ,UAAU,EACV,OAAO,GACR,EAAE;QACD,OAAO,EAAE,GAAG,CAAC;QACb,UAAU,EAAE,GAAG,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAClC,GAAG,OAAO,CAAC,QAAQ,CAAC;CAatB"}