Merge branch 'main' into ash/feat/add-did-document

Author: alanshaw

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [2.34.0](https://github.com/storacha/freeway/compare/v2.33.0...v2.34.0) (2025-11-25)
+
+
+### Features
+
+* add a stripped down server for debugging ([#196](https://github.com/storacha/freeway/issues/196)) ([bd7adb2](https://github.com/storacha/freeway/commit/bd7adb2fbe2a0780aeff8c6ed80dfd84552ce004))
+* bump egress tracking traffic to 5% ([#200](https://github.com/storacha/freeway/issues/200)) ([5b97f6f](https://github.com/storacha/freeway/commit/5b97f6f4945daf177daf73f2d2a7ada5598fc5a1))
+
+
+### Bug Fixes
+
+* disable FF_TELEMETRY_ENABLED in wrangler.toml ([#197](https://github.com/storacha/freeway/issues/197)) ([b63d3c3](https://github.com/storacha/freeway/commit/b63d3c3bfdc24badce41b6f5f2517755ba98a153))
+* skip egress tracking if content found in multiple spaces ([#199](https://github.com/storacha/freeway/issues/199)) ([9a8089f](https://github.com/storacha/freeway/commit/9a8089f82214778a53de1f5891f25ebc51eca289))
+
 ## [2.33.0](https://github.com/storacha/freeway/compare/v2.32.0...v2.33.0) (2025-11-20)
 
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "freeway",
-  "version": "2.33.0",
+  "version": "2.34.0",
   "description": "An IPFS gateway for accessing UnixFS data via CAR CIDs",
   "keywords": [
     "IPFS",
@@ -85,7 +85,8 @@
   },
   "standard": {
     "ignore": [
-      "*.ts"
+      "*.ts",
+      "src/middleware/withVersionHeader.js"
     ]
   },
   "packageManager": "pnpm@10.14.0+sha512.ad27a79641b49c3e481a16a805baa71817a04bbe06a38d17e60e2eaee83f6a146c6a688125f5792e48dd5ba30e7da52a5cda4c3992b9ccf333f9ce223af84748"

package.json

@@ -0,0 +1,3 @@
+# freeway-debug
+
+A stripped down freeway for debugging. Just run `npx wrangler dev` from this directory to start a freeway server that points to production on `http://localhost:8787`.

scripts/debug/README.md

@@ -0,0 +1,19 @@
+{
+  "name": "freeway-debug",
+  "version": "0.0.0",
+  "description": "An IPFS gateway for accessing UnixFS data via CAR CIDs",
+  "license": "Apache-2.0 OR MIT",
+  "author": "Alan Shaw",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./dist/src/index.d.ts"
+    }
+  },
+  "main": "src/index.js",
+  "scripts": {
+    "build": "esbuild --bundle src/index.js --format=esm --outfile=dist/worker.mjs",
+    "build:tsc": "tsc --build"
+  }
+}

scripts/debug/package.json

@@ -0,0 +1,71 @@
+/* eslint-env worker */
+
+// Stripped down freeway for debugging. It points at the production network.
+
+import {
+  withCdnCache,
+  withContext,
+  withCorsHeaders,
+  withContentDispositionHeader,
+  withErrorHandler,
+  createWithHttpMethod as withHttpMethods,
+  withParsedIpfsUrl,
+  composeMiddleware
+} from '@web3-storage/gateway-lib/middleware'
+import { handleUnixfs } from '@web3-storage/gateway-lib/handlers'
+import {
+  withContentClaimsDagula,
+  withVersionHeader,
+  withCarBlockHandler,
+  withLocator,
+  withOptionsRequest,
+  withFormatRawHandler,
+  withFormatCarHandler
+} from '../../../src/middleware/index.js'
+
+/**
+ * @import { Handler, Context } from '@web3-storage/gateway-lib'
+ * @import { Environment } from '../../../src/bindings.js'
+ */
+
+const middleware = composeMiddleware(
+  withCdnCache,
+  withContext,
+  withOptionsRequest,
+  withCorsHeaders,
+  withVersionHeader,
+  withErrorHandler,
+  withHttpMethods('GET', 'HEAD'),
+  withParsedIpfsUrl,
+  withLocator,
+  withCarBlockHandler,
+  withContentClaimsDagula,
+  withFormatRawHandler,
+  withFormatCarHandler,
+  withContentDispositionHeader
+)
+
+const handler = {
+  /** @type {Handler<Context, Environment>} */
+  async fetch (request, env, ctx) {
+    let status = 500
+    let headers = new Headers()
+    try {
+      const handler = middleware(handleUnixfs)
+      const response = await handler(request, env, ctx)
+      status = response.status
+      headers = response.headers
+      return response
+    } catch (/** @type {any} */ err) {
+      console.error(err)
+      return new Response(err.stack, { status })
+    } finally {
+      console.log(request.method, request.url, '→', status)
+      for (const [k, v] of headers) {
+        console.log(`\t${k}:`, v)
+      }
+    }
+  }
+}
+
+export default handler

scripts/debug/src/index.js

@@ -0,0 +1,10 @@
+name = "freeway-debug"
+main = "./dist/worker.mjs"
+compatibility_flags = [ "nodejs_compat" ]
+compatibility_date = "2025-09-01"
+
+[vars]
+FF_RAMP_UP_PROBABILITY = "100"
+
+[build]
+command = "npm run build"

scripts/debug/wrangler.toml

@@ -10,11 +10,7 @@ import {
   withFixedLengthStream,
   composeMiddleware
 } from '@web3-storage/gateway-lib/middleware'
-import {
-  handleUnixfs,
-  handleBlock,
-  handleCar
-} from '@web3-storage/gateway-lib/handlers'
+import { handleUnixfs } from '@web3-storage/gateway-lib/handlers'
 import {
   withContentClaimsDagula,
   withVersionHeader,
@@ -31,21 +27,15 @@ import {
   withDelegationStubs,
   withOptionsRequest,
   withCarParkFetch,
-  withDidDocumentHandler
+  withDidDocumentHandler,
+  withFormatRawHandler,
+  withFormatCarHandler
 } from './middleware/index.js'
 import { instrument } from '@microlabs/otel-cf-workers'
 import { NoopSpanProcessor, TraceIdRatioBasedSampler } from '@opentelemetry/sdk-trace-base'
 
 /**
- * @import {
- *   Handler,
- *   Middleware,
- *   Context,
- *   IpfsUrlContext,
- *   BlockContext,
- *   DagContext,
- *   UnixfsContext
- * } from '@web3-storage/gateway-lib'
+ * @import { Handler, Context } from '@web3-storage/gateway-lib'
  * @import { Environment } from './bindings.js'
  */
 
@@ -181,39 +171,3 @@ const handler = {
 }
 
 export default handler
-
-/**
- * @type {Middleware<BlockContext & UnixfsContext & IpfsUrlContext, BlockContext & UnixfsContext & IpfsUrlContext, Environment>}
- */
-export function withFormatRawHandler (handler) {
-  return async (request, env, ctx) => {
-    const { headers } = request
-    const { searchParams } = ctx
-    if (!searchParams) throw new Error('missing URL search params')
-    if (
-      searchParams.get('format') === 'raw' ||
-      headers.get('Accept')?.includes('application/vnd.ipld.raw')
-    ) {
-      return await handleBlock(request, env, ctx)
-    }
-    return handler(request, env, ctx) // pass to other handlers
-  }
-}
-
-/**
- * @type {Middleware<DagContext & IpfsUrlContext, DagContext & IpfsUrlContext, Environment>}
- */
-export function withFormatCarHandler (handler) {
-  return async (request, env, ctx) => {
-    const { headers } = request
-    const { searchParams } = ctx
-    if (!searchParams) throw new Error('missing URL search params')
-    if (
-      searchParams.get('format') === 'car' ||
-      headers.get('Accept')?.includes('application/vnd.ipld.car')
-    ) {
-      return await handleCar(request, env, ctx)
-    }
-    return handler(request, env, ctx) // pass to other handlers
-  }
-}

src/index.js

@@ -6,8 +6,10 @@ export { withVersionHeader } from './withVersionHeader.js'
 export { withAuthorizedSpace } from './withAuthorizedSpace.js'
 export { withLocator } from './withLocator.js'
 export { withCarParkFetch } from './withCarParkFetch.js'
-export { withEgressTracker } from './withEgressTracker.js'
 export { withEgressClient } from './withEgressClient.js'
+export { withEgressTracker } from './withEgressTracker.js'
+export { withFormatCarHandler } from './withFormatCarHandler.js'
+export { withFormatRawHandler } from './withFormatRawHandler.js'
 export { withDelegationStubs } from './withDelegationStubs.js'
 export { withDidDocumentHandler } from './withDidDocumentHandler.js'
 export { withGatewayIdentity } from './withGatewayIdentity.js'

src/middleware/index.js

@@ -104,6 +104,15 @@ export function withAuthorizedSpace (handler) {
       .map((site) => extractSpaceDID(site.space))
       .filter((space) => space !== undefined)
 
+    // If content is found in multiple DIFFERENT spaces, skip egress tracking
+    // by not setting ctx.space (security/billing concern - ambiguous ownership)
+    const uniqueSpaces = [...new Set(spaces.map(s => s.toString()))]
+    const skipEgressTracking = uniqueSpaces.length > 1
+    if (skipEgressTracking && env.DEBUG === 'true') {
+      console.log(`Content found in ${uniqueSpaces.length} different spaces - egress tracking will be skipped`)
+      console.log(`Spaces: ${uniqueSpaces.join(', ')}`)
+    }
+
     try {
       // First space to successfully authorize is the one we'll use.
       const { space: selectedSpace, delegationProofs } = await Promise.any(
@@ -117,7 +126,8 @@ export function withAuthorizedSpace (handler) {
       )
       return handler(request, env, {
         ...ctx,
-        space: SpaceDID.from(selectedSpace.toString()),
+        // Only set space if we're not skipping egress tracking
+        space: skipEgressTracking ? undefined : SpaceDID.from(selectedSpace.toString()),
         delegationProofs,
         locator: locator.scopeToSpaces([selectedSpace])
       })