@effect-native/fetch-hooks 0.0.1-placeholder → 0.0.2

package/src/flat-file-storage.ts

@@ -0,0 +1,170 @@
+/**
+ * Flat file storage - stores cache files in subdirectories named by the key.
+ * Each key gets its own folder with standard cache filenames inside:
+ *   baseDir/001/request.json
+ *   baseDir/001/response.meta.json
+ *   baseDir/001/response.jsonl
+ *   baseDir/002/request.json
+ *   ...
+ *
+ * This is similar to filesystem-storage but the key IS the subdirectory name
+ * (no hashing), making it suitable for conversation turn folders.
+ */
+
+import type { CachedRequest, CachedResponseMeta, CacheKey, CacheStorage, KV, KVStream, TimedChunk } from "./types.js"
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { jsonlToTimedChunks, timedChunksToJsonl } from "./sse-handler.js"
+
+function ensureDir(dir: string): void {
+  if (!existsSync(dir)) {
+    try {
+      mkdirSync(dir, { recursive: true })
+    } catch (error: unknown) {
+      if (!(error instanceof Error && (error as NodeJS.ErrnoException).code === "EEXIST")) {
+        throw error
+      }
+    }
+  }
+}
+
+/** Create a KV store backed by JSON files in subdirectories: baseDir/{key}/{filename} */
+export function createFlatJsonFileKV<T>(baseDir: string, filename: string): KV<CacheKey, T> {
+  return {
+    async get([key]: CacheKey): Promise<T | null> {
+      const filePath = join(baseDir, key, filename)
+      if (!existsSync(filePath)) {
+        return null
+      }
+      const content = readFileSync(filePath, "utf-8")
+      return JSON.parse(content) as T
+    },
+
+    async set([key]: CacheKey, value: T): Promise<void> {
+      const dir = join(baseDir, key)
+      ensureDir(dir)
+      const filePath = join(dir, filename)
+      writeFileSync(filePath, JSON.stringify(value, null, 2), "utf-8")
+    },
+
+    async has([key]: CacheKey): Promise<boolean> {
+      const filePath = join(baseDir, key, filename)
+      return existsSync(filePath)
+    }
+  }
+}
+
+/** Create a KV store backed by plain text files in subdirectories (no JSON serialization) */
+export function createFlatTextFileKV(baseDir: string, filename: string): KV<CacheKey, string> {
+  return {
+    async get([key]: CacheKey): Promise<string | null> {
+      const filePath = join(baseDir, key, filename)
+      if (!existsSync(filePath)) {
+        return null
+      }
+      return readFileSync(filePath, "utf-8")
+    },
+
+    async set([key]: CacheKey, value: string): Promise<void> {
+      const dir = join(baseDir, key)
+      ensureDir(dir)
+      const filePath = join(dir, filename)
+      writeFileSync(filePath, value, "utf-8")
+    },
+
+    async has([key]: CacheKey): Promise<boolean> {
+      const filePath = join(baseDir, key, filename)
+      return existsSync(filePath)
+    }
+  }
+}
+
+/** Create a KV store backed by binary files in subdirectories */
+export function createFlatBinaryFileKV(baseDir: string, filename: string): KV<CacheKey, Uint8Array> {
+  return {
+    async get([key]: CacheKey): Promise<Uint8Array | null> {
+      const filePath = join(baseDir, key, filename)
+      if (!existsSync(filePath)) {
+        return null
+      }
+      const buffer = readFileSync(filePath)
+      return new Uint8Array(buffer)
+    },
+
+    async set([key]: CacheKey, value: Uint8Array): Promise<void> {
+      const dir = join(baseDir, key)
+      ensureDir(dir)
+      const filePath = join(dir, filename)
+      writeFileSync(filePath, value)
+    },
+
+    async has([key]: CacheKey): Promise<boolean> {
+      const filePath = join(baseDir, key, filename)
+      return existsSync(filePath)
+    }
+  }
+}
+
+/** Create a streaming KV store for SSE chunks in subdirectories */
+export function createFlatJsonlFileKVStream(baseDir: string, filename: string): KVStream<CacheKey, TimedChunk> {
+  return {
+    async *get([key]: CacheKey): AsyncIterable<TimedChunk> {
+      const filePath = join(baseDir, key, filename)
+      if (!existsSync(filePath)) {
+        return
+      }
+
+      const content = readFileSync(filePath, "utf-8")
+      const chunks = jsonlToTimedChunks(content)
+      for (const chunk of chunks) {
+        yield chunk
+      }
+    },
+
+    async set([key]: CacheKey, values: Array<TimedChunk> | AsyncIterable<TimedChunk>): Promise<void> {
+      const dir = join(baseDir, key)
+      ensureDir(dir)
+      const filePath = join(dir, filename)
+
+      let chunks: Array<TimedChunk>
+      if (Array.isArray(values)) {
+        chunks = values
+      } else {
+        chunks = []
+        for await (const chunk of values) {
+          chunks.push(chunk)
+        }
+      }
+
+      const jsonl = timedChunksToJsonl(chunks)
+      writeFileSync(filePath, jsonl, "utf-8")
+    },
+
+    async has([key]: CacheKey): Promise<boolean> {
+      const filePath = join(baseDir, key, filename)
+      return existsSync(filePath)
+    }
+  }
+}
+
+/**
+ * Create a CacheStorage that stores files in subdirectories named by the key.
+ *
+ * @example
+ * const storage = createFlatFileStorage("/path/to/conversation")
+ * // With transformCacheKey returning "001", files will be:
+ * //   /path/to/conversation/001/request.json
+ * //   /path/to/conversation/001/response.meta.json
+ * //   /path/to/conversation/001/response.jsonl
+ */
+export function createFlatFileStorage(baseDir: string): CacheStorage {
+  return {
+    requests: createFlatJsonFileKV<CachedRequest>(baseDir, "request.json"),
+    responseMeta: createFlatJsonFileKV<CachedResponseMeta>(baseDir, "response.meta.json"),
+    // Use text storage for responseBody to preserve raw JSON without double-escaping
+    responseBody: createFlatTextFileKV(baseDir, "response.json"),
+    binaryBody: createFlatBinaryFileKV(baseDir, "response.bin"),
+    sseChunks: createFlatJsonlFileKVStream(baseDir, "response.jsonl")
+  }
+}

package/src/index.ts

@@ -0,0 +1,249 @@
+import type { CacheOptions, CacheStorage } from "./types.js"
+
+import {
+  getCachedResponse,
+  getCacheKeyFromUrl,
+  setInternalFetchForCache,
+  storeRequest,
+  storeResponse
+} from "./cache-manager.js"
+import { getCacheDir, isCacheEnabled, isProduction, isReplayOnly } from "./environment.js"
+import { createFilesystemStorage } from "./filesystem-storage.js"
+import { hashRequest, headersToRecord } from "./request-hasher.js"
+
+// Only export the public API - internal implementation details are not exported
+export type {
+  CacheKey,
+  CacheOptions,
+  CacheStorage,
+  GeneratorTransformHook,
+  HashableRequest,
+  KV,
+  KVStream,
+  StorableResponse,
+  TimedChunk,
+  TransformHook
+} from "./types.js"
+
+// Export storage factories for custom implementations
+export { createFilesystemStorage } from "./filesystem-storage.js"
+export { createFlatFileStorage } from "./flat-file-storage.js"
+
+const CACHE_ENABLED_BANNER = `
+╔══════════════════════════════════════════════════════════════╗
+║  DEV-FETCH-CACHE ENABLED                                     ║
+║  Responses are being cached/replayed from .cache/fetch/      ║
+║  To disable: DEV_FETCH_CACHE=0 or --no-fetch-cache           ║
+╚══════════════════════════════════════════════════════════════╝
+`
+
+let originalFetch: typeof globalThis.fetch | null = null
+
+function getUrlFromInput(input: Request | string | URL): string {
+  if (typeof input === "string") {
+    return input
+  }
+  if (input instanceof URL) {
+    return input.href
+  }
+  return input.url
+}
+
+function normalizeHeadersInit(headersInit: unknown): Record<string, string> {
+  if (!headersInit) {
+    return {}
+  }
+  if (headersInit instanceof Headers) {
+    return headersToRecord(headersInit)
+  }
+  if (Array.isArray(headersInit)) {
+    return Object.fromEntries(headersInit)
+  }
+  return headersInit as Record<string, string>
+}
+
+async function extractBodyInit(bodyInit: RequestInit["body"]): Promise<string | undefined> {
+  if (!bodyInit) {
+    return undefined
+  }
+  if (typeof bodyInit === "string") {
+    return bodyInit
+  }
+  if (bodyInit instanceof URLSearchParams) {
+    return bodyInit.toString()
+  }
+  if (bodyInit instanceof Blob) {
+    return bodyInit.text()
+  }
+  if (bodyInit instanceof FormData) {
+    const pairs: Array<string> = []
+    for (const [key, value] of bodyInit.entries()) {
+      // FormDataEntryValue can be File or string; File needs to be converted to string
+      const stringValue = typeof value === "string" ? value : value.name
+      pairs.push(`${encodeURIComponent(key)}=${encodeURIComponent(stringValue)}`)
+    }
+    return pairs.join("&")
+  }
+  if (bodyInit instanceof ArrayBuffer) {
+    return new TextDecoder().decode(bodyInit)
+  }
+  if (ArrayBuffer.isView(bodyInit)) {
+    return new TextDecoder().decode(new Uint8Array(bodyInit.buffer, bodyInit.byteOffset, bodyInit.byteLength))
+  }
+  if (bodyInit instanceof ReadableStream) {
+    const reader = bodyInit.getReader()
+    const chunks: Array<Uint8Array> = []
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      if (value) chunks.push(value)
+    }
+    const totalLength = chunks.reduce((acc, chunk) => acc + chunk.length, 0)
+    const combined = new Uint8Array(totalLength)
+    let offset = 0
+    for (const chunk of chunks) {
+      combined.set(chunk, offset)
+      offset += chunk.length
+    }
+    return new TextDecoder().decode(combined)
+  }
+  return undefined
+}
+
+/** Default identity transform hook */
+const identity = <T>(value: T): T => value
+
+export function createCachedFetch(baseFetch: typeof globalThis.fetch, options?: CacheOptions) {
+  const replayOnly = options?.replayOnly ?? isReplayOnly()
+  const beforeHash = options?.beforeHash ?? identity
+  const beforeStoreRequest = options?.beforeStoreRequest ?? identity
+  const transformCacheKey = options?.transformCacheKey ?? ((key: string) => key)
+
+  // Create or use provided storage
+  const storage: CacheStorage = options?.storage ?? createFilesystemStorage(getCacheDir())
+
+  // Set internal fetch for dev-fs-logs communication (defaults to baseFetch)
+  setInternalFetchForCache(options?.internalFetch ?? baseFetch)
+
+  return async function cachedFetch(input: Request | string | URL, init?: RequestInit): Promise<Response> {
+    if (isProduction()) {
+      return baseFetch(input, init)
+    }
+
+    const url = getUrlFromInput(input)
+
+    // Skip caching for localhost requests (including dev-fs-logs on port 1090)
+    if (url.includes("localhost") || url.includes("127.0.0.1")) {
+      return baseFetch(input, init)
+    }
+
+    const method = init?.method ?? (typeof input === "object" && "method" in input ? input.method : "GET")
+
+    const cacheKeyFromUrl = getCacheKeyFromUrl(url)
+    if (cacheKeyFromUrl) {
+      const cached = await getCachedResponse(
+        cacheKeyFromUrl,
+        options?.afterLoadResponse,
+        options?.transformSSEChunk,
+        storage
+      )
+      if (cached) {
+        return cached
+      }
+      return new Response("Cache entry not found", {
+        status: 404
+      })
+    }
+
+    const headersInit = init?.headers ?? (typeof input === "object" && "headers" in input ? input.headers : undefined)
+    const headers = normalizeHeadersInit(headersInit)
+
+    let body: string | undefined
+
+    // Extract body from Request object or init
+    if (input instanceof Request && input.body) {
+      // Clone the request so we can read the body without consuming the original
+      const clonedRequest = input.clone()
+      body = await extractBodyInit(clonedRequest.body!)
+    } else if (init?.body !== null && init?.body !== undefined) {
+      body = await extractBodyInit(init.body)
+    }
+
+    // Apply beforeHash transform to affect cache key generation, then transformCacheKey for custom prefixes/suffixes
+    const hashableRequest = await beforeHash({ url, method, headers, body })
+    const cacheKey = transformCacheKey(hashRequest(hashableRequest), hashableRequest)
+
+    const cached = await getCachedResponse(
+      cacheKey,
+      options?.afterLoadResponse,
+      options?.transformSSEChunk,
+      storage
+    )
+    if (cached) {
+      return cached
+    }
+
+    if (replayOnly) {
+      return new Response("Cache miss in replay-only mode", {
+        status: 503
+      })
+    }
+
+    const requestToStore = await beforeStoreRequest({ url, method, headers, body })
+    await storeRequest(
+      {
+        url: requestToStore.url,
+        method: requestToStore.method,
+        headers: requestToStore.headers,
+        body: requestToStore.body
+      },
+      cacheKey,
+      options?.beforeStoreRequest !== undefined, // skip header filtering if hook provided
+      storage,
+      hashableRequest
+    )
+
+    const response = await baseFetch(input, init)
+
+    return storeResponse(cacheKey, response, options?.beforeStoreResponse, storage, hashableRequest)
+  }
+}
+
+export function enableDevFetchCache(options?: CacheOptions): void {
+  if (isProduction()) {
+    return
+  }
+
+  if (!isCacheEnabled()) {
+    return
+  }
+
+  if (originalFetch !== null) {
+    return
+  }
+
+  originalFetch = globalThis.fetch
+  const cachedFetch = createCachedFetch(originalFetch, {
+    ...options,
+    internalFetch: options?.internalFetch ?? originalFetch
+  })
+
+  // Cast to typeof fetch to include preconnect method
+  globalThis.fetch = cachedFetch as typeof globalThis.fetch
+
+  // biome-ignore lint/suspicious/noConsole: Banner display is intentional for dev tooling
+  console.info(CACHE_ENABLED_BANNER)
+}
+
+export function disableDevFetchCache(): void {
+  if (originalFetch === null) {
+    return
+  }
+
+  globalThis.fetch = originalFetch
+  originalFetch = null
+}
+
+export function isDevFetchCacheEnabled(): boolean {
+  return originalFetch !== null
+}

package/src/request-hasher.ts

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto"
+import type { RawCachedRequest } from "./types.js"
+
+const BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+
+function toBase62(n: bigint): string {
+  if (n === 0n) return "0"
+  let result = ""
+  while (n > 0n) {
+    result = BASE62[Number(n % 62n)] + result
+    n = n / 62n
+  }
+  return result
+}
+
+const SENSITIVE_HEADERS = new Set([
+  "authorization",
+  "x-api-key",
+  "api-key",
+  "x-openrouter-api-key",
+  "cookie",
+  "set-cookie",
+  "x-auth-token",
+  "x-access-token",
+  "bearer"
+])
+
+function normalizeUrl(url: string): string {
+  const parsed = new URL(url)
+  parsed.searchParams.sort()
+  const pathname = parsed.pathname.replace(/\/+$/, "") || "/"
+  return `${parsed.protocol}//${parsed.host}${pathname}${parsed.search}`
+}
+
+function filterHeaders(
+  headers: Record<string, string>,
+  getOutputKey: (originalKey: string, lowerKey: string) => string
+): Record<string, string> {
+  const result: Record<string, string> = {}
+  for (const [key, value] of Object.entries(headers)) {
+    const lowerKey = key.toLowerCase()
+    if (SENSITIVE_HEADERS.has(lowerKey)) {
+      continue
+    }
+    const outputKey = getOutputKey(key, lowerKey)
+    result[outputKey] = value
+  }
+  return result
+}
+
+function normalizeHeaders(headers: Record<string, string>): Record<string, string> {
+  return filterHeaders(headers, (_originalKey, lowerKey) => lowerKey)
+}
+
+function filterSensitiveHeaders(headers: Record<string, string>): Record<string, string> {
+  return filterHeaders(headers, (originalKey) => originalKey)
+}
+
+export function hashRequest({ body, headers, method, url }: RawCachedRequest): string {
+  // Build content string for hashing
+  let content = normalizeUrl(url) + "\n" + method.toUpperCase()
+  const normalizedHeaders = normalizeHeaders(headers)
+  const sortedHeaderKeys = Object.keys(normalizedHeaders).sort()
+  for (const key of sortedHeaderKeys) {
+    content += `\n${key}:${normalizedHeaders[key]}`
+  }
+  if (body) {
+    content += `\n${body}`
+  }
+  // Create a SHA256 hash and convert to base62 for a short string
+  const hash = createHash("sha256").update(content).digest()
+  const hashBigInt = BigInt("0x" + hash.toString("hex"))
+  return toBase62(hashBigInt % 62n ** 11n) // Limit to base62 with ~11 chars max
+}
+
+export function getStorableHeaders(headers: Record<string, string>): Record<string, string> {
+  return filterSensitiveHeaders(headers)
+}
+
+export function headersToRecord(headers: Headers): Record<string, string> {
+  const record: Record<string, string> = {}
+  headers.forEach((value, key) => {
+    record[key] = value
+  })
+  return record
+}