ddys-api-cache 0.1.0

package/.env.example

@@ -0,0 +1,8 @@
+DDYS_API_CACHE_API_BASE=https://ddys.io/api/v1
+DDYS_API_CACHE_ALLOWED_ENDPOINTS=/latest,/hot,/calendar,/search,/detail
+DDYS_API_CACHE_TTL_SECONDS=300
+DDYS_API_CACHE_STALE_SECONDS=3600
+DDYS_API_CACHE_TIMEOUT_MS=10000
+DDYS_API_CACHE_ADAPTER=memory
+DDYS_API_CACHE_WORKER_CACHE=true
+DDYS_API_CACHE_WARMUP_ENDPOINTS=/latest,/hot,/calendar

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ddysiodev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,76 @@
+# ddys-api-cache
+
+Standalone caching, stale fallback, and edge proxy toolkit for DDYS API integrations. It adds TTL caching, stale fallback, endpoint allowlists, request timeouts, and diagnostic headers for `ddys-feed`, `ddys-sitemap`, `ddys-opml`, `ddys-search-index`, or third-party frontends.
+
+## Features
+
+- Node API with `fetchCached()`, `warmCache()`, and `createMemoryCache()`
+- Cloudflare Workers `/api/*` proxy with `x-ddys-cache`, `x-ddys-upstream-ms`, and ETag support
+- Fresh hit, miss, stale fallback, and force refresh modes
+- Memory adapter and Cache API adapter
+- Endpoint allowlist, query key filtering, query limits, and GET/HEAD method restrictions
+- CLI commands for `fetch`, `warm`, and `diag`
+- GitHub Actions warmup example
+
+## Install
+
+```bash
+npm install ddys-api-cache
+```
+
+## CLI
+
+```bash
+ddys-api-cache diag
+ddys-api-cache fetch --path /latest --query limit=20
+ddys-api-cache warm --endpoints /latest,/hot,/calendar
+```
+
+## Node API
+
+```js
+import { createDdysApiCache } from 'ddys-api-cache';
+
+const cache = createDdysApiCache({
+  ttlSeconds: 300,
+  staleSeconds: 3600
+});
+
+const result = await cache.fetch('/latest', { query: { limit: 20 } });
+console.log(result.cacheStatus, await result.json());
+```
+
+## Cloudflare Workers
+
+```js
+import { createWorkerHandler } from 'ddys-api-cache/worker';
+
+export default {
+  fetch: createWorkerHandler({
+    cacheAdapter: 'cache-api',
+    ttlSeconds: 300,
+    staleSeconds: 3600
+  })
+};
+```
+
+Routes:
+
+- `/api/latest?limit=20`
+- `/api/hot`
+- `/api/calendar`
+- `/api/search?q=keyword`
+- `/health`
+- `/diag`
+
+## Environment
+
+```bash
+DDYS_API_CACHE_API_BASE=https://ddys.io/api/v1
+DDYS_API_CACHE_ALLOWED_ENDPOINTS=/latest,/hot,/calendar,/search,/detail
+DDYS_API_CACHE_TTL_SECONDS=300
+DDYS_API_CACHE_STALE_SECONDS=3600
+DDYS_API_CACHE_TIMEOUT_MS=10000
+DDYS_API_CACHE_ADAPTER=memory
+DDYS_API_CACHE_WORKER_CACHE=true
+```

package/README.md

@@ -0,0 +1,93 @@
+# ddys-api-cache
+
+低端影视 API 的独立缓存、降级和边缘反代工具包。它可以给 DDYS API 请求增加 TTL 缓存、stale fallback、白名单 endpoint、超时控制和诊断 header，适合给 `ddys-feed`、`ddys-sitemap`、`ddys-opml`、`ddys-search-index` 或第三方前端做稳定的 API 入口。
+
+## 功能
+
+- Node API：`fetchCached()`、`warmCache()`、`createMemoryCache()`
+- Cloudflare Workers：`/api/*` 反代 DDYS API，支持 `x-ddys-cache`、`x-ddys-upstream-ms`、ETag
+- 缓存策略：fresh hit、miss、stale fallback、force refresh
+- 缓存适配：Memory adapter、Cache API adapter
+- 安全控制：endpoint 白名单、query key 过滤、query 数量和长度限制、GET/HEAD 方法限制
+- CLI：`fetch` 调试请求、`warm` 预热接口、`diag` 查看配置
+- GitHub Actions 示例：定时预热热门接口
+
+## 安装
+
+```bash
+npm install ddys-api-cache
+```
+
+## CLI
+
+```bash
+ddys-api-cache diag
+ddys-api-cache fetch --path /latest --query limit=20
+ddys-api-cache warm --endpoints /latest,/hot,/calendar
+```
+
+常用参数：
+
+- `--api-base`：DDYS API 根地址
+- `--allowed-endpoints`：允许反代的 endpoint 列表
+- `--ttl-seconds`：新鲜缓存时间
+- `--stale-seconds`：上游失败时允许使用旧缓存的时间
+- `--timeout-ms`：上游请求超时
+- `--adapter`：`memory`、`cache-api` 或 `auto`
+
+## Node API
+
+```js
+import { createDdysApiCache } from 'ddys-api-cache';
+
+const cache = createDdysApiCache({
+  ttlSeconds: 300,
+  staleSeconds: 3600
+});
+
+const result = await cache.fetch('/latest', { query: { limit: 20 } });
+console.log(result.cacheStatus, await result.json());
+```
+
+## Cloudflare Workers
+
+```js
+import { createWorkerHandler } from 'ddys-api-cache/worker';
+
+export default {
+  fetch: createWorkerHandler({
+    cacheAdapter: 'cache-api',
+    ttlSeconds: 300,
+    staleSeconds: 3600
+  })
+};
+```
+
+Worker 路由：
+
+- `/api/latest?limit=20`
+- `/api/hot`
+- `/api/calendar`
+- `/api/search?q=关键词`
+- `/health`
+- `/diag`
+
+## 环境变量
+
+```bash
+DDYS_API_CACHE_API_BASE=https://ddys.io/api/v1
+DDYS_API_CACHE_ALLOWED_ENDPOINTS=/latest,/hot,/calendar,/search,/detail
+DDYS_API_CACHE_TTL_SECONDS=300
+DDYS_API_CACHE_STALE_SECONDS=3600
+DDYS_API_CACHE_TIMEOUT_MS=10000
+DDYS_API_CACHE_ADAPTER=memory
+DDYS_API_CACHE_WORKER_CACHE=true
+```
+
+## 诊断 Header
+
+- `x-ddys-cache`：`HIT`、`MISS`、`STALE`、`BYPASS`
+- `x-ddys-cache-age`：缓存年龄，单位秒
+- `x-ddys-upstream-ms`：上游耗时
+- `x-ddys-cache-key`：短缓存 key
+- `x-ddys-api-cache-version`：包版本

package/bin/ddys-api-cache.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import {
+  createConfig,
+  createDdysApiCache,
+  describeConfig,
+  fetchCached,
+  warmCache
+} from '../src/index.js';
+import { VERSION } from '../src/config.js';
+import { parseQueryString } from '../src/utils.js';
+
+const args = parseArgs(process.argv.slice(2));
+const command = args._[0] || 'diag';
+
+try {
+  if (command === 'version' || args.version) {
+    console.log(VERSION);
+  } else if (command === 'diag') {
+    const config = createConfig(readCliConfig(args));
+    console.log(JSON.stringify({ ok: true, package: 'ddys-api-cache', config: describeConfig(config) }, null, 2));
+  } else if (command === 'fetch') {
+    const path = args.path || args.endpoint || args._[1] || '/latest';
+    const result = await fetchCached(path, {
+      ...readCliConfig(args),
+      query: parseQueryString(args.query || ''),
+      forceRefresh: Boolean(args.refresh)
+    });
+    const body = await readResultBody(result, args);
+    console.log(JSON.stringify({
+      ok: result.ok,
+      status: result.status,
+      cacheStatus: result.cacheStatus,
+      cacheKey: result.cacheKey,
+      upstreamUrl: result.upstreamUrl,
+      ageSeconds: result.ageSeconds,
+      headers: args.headers ? result.headers : undefined,
+      body
+    }, null, 2));
+  } else if (command === 'warm') {
+    const endpoints = args.endpoints || args.endpoint || args.path || '';
+    const result = await warmCache(endpoints, readCliConfig(args));
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.ok) process.exitCode = 1;
+  } else {
+    throw new Error(`Unknown command: ${command}`);
+  }
+} catch (error) {
+  console.error(JSON.stringify({ ok: false, message: error.message }, null, 2));
+  process.exit(1);
+}
+
+function readCliConfig(args) {
+  const out = {};
+  if (args['api-base'] || args.apiBase) out.apiBase = args['api-base'] || args.apiBase;
+  if (args['allowed-endpoints'] || args.allowedEndpoints) out.allowedEndpoints = args['allowed-endpoints'] || args.allowedEndpoints;
+  if (args['blocked-query-keys'] || args.blockedQueryKeys) out.blockedQueryKeys = args['blocked-query-keys'] || args.blockedQueryKeys;
+  if (args['ttl-seconds'] || args.ttlSeconds) out.ttlSeconds = args['ttl-seconds'] || args.ttlSeconds;
+  if (args['stale-seconds'] || args.staleSeconds) out.staleSeconds = args['stale-seconds'] || args.staleSeconds;
+  if (args['timeout-ms'] || args.timeoutMs) out.requestTimeoutMs = args['timeout-ms'] || args.timeoutMs;
+  if (args.adapter) out.cacheAdapter = args.adapter;
+  if (args.namespace) out.cacheNamespace = args.namespace;
+  if (args['max-memory-entries'] || args.maxMemoryEntries) out.maxMemoryEntries = args['max-memory-entries'] || args.maxMemoryEntries;
+  if (args.endpoints) out.warmupEndpoints = args.endpoints;
+  return out;
+}
+
+async function readResultBody(result, args) {
+  const text = await result.text();
+  if (args.raw) return text;
+  try {
+    return text ? JSON.parse(text) : null;
+  } catch {
+    return text;
+  }
+}
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith('--')) {
+      out._.push(arg);
+      continue;
+    }
+    const key = arg.slice(2);
+    const next = argv[index + 1];
+    if (!next || next.startsWith('--')) {
+      out[key] = true;
+      continue;
+    }
+    out[key] = next;
+    index += 1;
+  }
+  return out;
+}

package/examples/cloudflare-worker/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "ddys-api-cache-worker-example",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy"
+  },
+  "dependencies": {
+    "ddys-api-cache": "^0.1.0"
+  },
+  "devDependencies": {
+    "wrangler": "^4.0.0"
+  }
+}

package/examples/cloudflare-worker/src/index.js

@@ -0,0 +1,7 @@
+import { createWorkerHandler } from 'ddys-api-cache/worker';
+
+export default {
+  fetch: createWorkerHandler({
+    cacheAdapter: 'cache-api'
+  })
+};

package/examples/cloudflare-worker/wrangler.jsonc

@@ -0,0 +1,12 @@
+{
+  "name": "ddys-api-cache",
+  "main": "src/index.js",
+  "compatibility_date": "2026-07-11",
+  "vars": {
+    "DDYS_API_CACHE_API_BASE": "https://ddys.io/api/v1",
+    "DDYS_API_CACHE_ALLOWED_ENDPOINTS": "/latest,/hot,/calendar,/search,/detail",
+    "DDYS_API_CACHE_TTL_SECONDS": "300",
+    "DDYS_API_CACHE_STALE_SECONDS": "3600",
+    "DDYS_API_CACHE_ADAPTER": "cache-api"
+  }
+}

package/examples/github-actions/ddys-api-cache-warmup.yml

@@ -0,0 +1,19 @@
+name: Warm DDYS API cache
+
+on:
+  schedule:
+    - cron: "*/15 * * * *"
+  workflow_dispatch:
+
+jobs:
+  warm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npx ddys-api-cache warm --endpoints /latest,/hot,/calendar
+        env:
+          DDYS_API_CACHE_API_BASE: https://ddys.io/api/v1
+          DDYS_API_CACHE_TTL_SECONDS: "300"
+          DDYS_API_CACHE_STALE_SECONDS: "3600"

package/examples/node-cache/cache-latest.mjs

@@ -0,0 +1,15 @@
+import { createDdysApiCache } from 'ddys-api-cache';
+
+const cache = createDdysApiCache({
+  ttlSeconds: 300,
+  staleSeconds: 3600
+});
+
+const first = await cache.fetch('/latest', { query: { limit: 20 } });
+const second = await cache.fetch('/latest', { query: { limit: 20 } });
+
+console.log(JSON.stringify({
+  first: first.cacheStatus,
+  second: second.cacheStatus,
+  stats: cache.stats()
+}, null, 2));

package/index.d.ts

@@ -0,0 +1,110 @@
+export interface DdysApiCacheConfig {
+  version: string;
+  apiBase: string;
+  userAgent: string;
+  allowedEndpoints: string[];
+  blockedQueryKeys: string[];
+  allowedMethods: string[];
+  warmupEndpoints: string[];
+  ttlSeconds: number;
+  staleSeconds: number;
+  requestTimeoutMs: number;
+  maxQueryParams: number;
+  maxQueryLength: number;
+  cacheAdapter: 'memory' | 'cache-api' | 'auto' | 'none';
+  cacheNamespace: string;
+  maxMemoryEntries: number;
+  workerCache: boolean;
+}
+
+export interface CacheEntry {
+  cacheKey: string;
+  upstreamUrl: string;
+  canonicalUrl: string;
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  body: string;
+  createdAt: number;
+  expiresAt: number;
+  staleUntil: number;
+  ttlSeconds: number;
+  staleSeconds: number;
+  etag: string;
+}
+
+export interface CacheAdapter {
+  name: string;
+  get(key: string): Promise<CacheEntry | null>;
+  set(key: string, entry: CacheEntry): Promise<void>;
+  delete?(key: string): Promise<void>;
+  clear?(): Promise<void>;
+  stats?(): Record<string, unknown>;
+}
+
+export interface CachedFetchResult {
+  ok: boolean;
+  status: number;
+  statusText: string;
+  cacheStatus: 'HIT' | 'MISS' | 'STALE' | 'BYPASS';
+  cacheKey: string;
+  upstreamUrl: string;
+  canonicalUrl: string;
+  ageSeconds: number;
+  stale: boolean;
+  durationMs: number;
+  method: string;
+  headers: Record<string, string>;
+  body: string;
+  error?: string;
+  text(): Promise<string>;
+  json(): Promise<unknown>;
+}
+
+export interface DdysApiCache {
+  config: DdysApiCacheConfig;
+  adapter: CacheAdapter;
+  fetch(pathname: string, options?: Record<string, unknown>): Promise<CachedFetchResult>;
+  warm(endpoints?: string[] | string, options?: Record<string, unknown>): Promise<WarmCacheResult>;
+  stats(): Record<string, unknown>;
+  describe(): Record<string, unknown>;
+}
+
+export interface WarmCacheResult {
+  ok: boolean;
+  total: number;
+  results: Array<{
+    ok: boolean;
+    path: string;
+    cacheStatus?: string;
+    status?: number;
+    cacheKey?: string;
+    upstreamUrl?: string;
+    message?: string;
+  }>;
+}
+
+export function createConfig(input?: Partial<DdysApiCacheConfig> | Record<string, unknown>, env?: Record<string, string | undefined>): DdysApiCacheConfig;
+export function loadConfigFromEnv(env?: Record<string, string | undefined>): DdysApiCacheConfig;
+export function describeConfig(config: DdysApiCacheConfig): Record<string, unknown>;
+export function normalizeEndpointList(value: string[] | string): string[];
+export function normalizeWarmupEndpoints(value: string[] | string): string[];
+export function createMemoryCache(options?: { maxEntries?: number }): CacheAdapter;
+export function createCacheApiAdapter(cacheApi: unknown, options?: { namespace?: string }): CacheAdapter;
+export function createNullCache(): CacheAdapter;
+export function createCacheAdapter(config: DdysApiCacheConfig, runtime?: Record<string, unknown>): CacheAdapter;
+export function assertAllowedEndpoint(pathname: string, config: DdysApiCacheConfig): string;
+export function assertAllowedMethod(method: string, config: DdysApiCacheConfig): string;
+export function sanitizeQuery(query: string | URLSearchParams | Record<string, unknown>, config: DdysApiCacheConfig): URLSearchParams;
+export function buildUpstreamRequest(pathname: string, query: string | URLSearchParams | Record<string, unknown>, config: DdysApiCacheConfig): { path: string; query: URLSearchParams; upstreamUrl: string; canonicalUrl: string };
+export function createDdysApiCache(input?: Partial<DdysApiCacheConfig> | Record<string, unknown>, runtime?: Record<string, unknown>): DdysApiCache;
+export function fetchCached(pathname: string, input?: Record<string, unknown>, runtime?: Record<string, unknown>): Promise<CachedFetchResult>;
+export function warmCache(endpoints: string[] | string, input?: Record<string, unknown>, runtime?: Record<string, unknown>): Promise<WarmCacheResult>;
+export function fetchUpstream(url: string, config: DdysApiCacheConfig, runtime?: { fetch?: typeof fetch; now?: () => number }): Promise<Record<string, unknown>>;
+export function buildCacheKey(request: { canonicalUrl: string }, config: DdysApiCacheConfig): string;
+export function buildResultHeaders(entry: CacheEntry, meta?: Record<string, unknown>): Record<string, string>;
+export function createCacheEntry(input: Record<string, unknown>): CacheEntry;
+export function createCachedResult(entry: CacheEntry, meta?: Record<string, unknown>): CachedFetchResult;
+export function createWorkerHandler(input?: Record<string, unknown>): (request: Request, env?: Record<string, string | undefined>, ctx?: unknown) => Promise<Response>;
+export function handleWorkerRequest(request: Request, runtime?: Record<string, unknown>): Promise<Response>;
+export function routeForPath(pathname: string): 'health' | 'diag' | 'warm' | 'api' | 'not-found';

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "ddys-api-cache",
+  "version": "0.1.0",
+  "description": "Caching, stale fallback, and edge proxy toolkit for DDYS API integrations.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/ddysiodev/ddys-api-cache",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ddysiodev/ddys-api-cache.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ddysiodev/ddys-api-cache/issues"
+  },
+  "keywords": [
+    "ddys",
+    "api-cache",
+    "edge-cache",
+    "stale-while-revalidate",
+    "cloudflare-workers",
+    "github-actions",
+    "proxy",
+    "api"
+  ],
+  "bin": {
+    "ddys-api-cache": "./bin/ddys-api-cache.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./config": {
+      "types": "./index.d.ts",
+      "import": "./src/config.js"
+    },
+    "./cache": {
+      "types": "./index.d.ts",
+      "import": "./src/cache.js"
+    },
+    "./adapters": {
+      "types": "./index.d.ts",
+      "import": "./src/adapters.js"
+    },
+    "./worker": {
+      "types": "./index.d.ts",
+      "import": "./src/worker.js"
+    }
+  },
+  "main": "./src/index.js",
+  "types": "./index.d.ts",
+  "files": [
+    "bin",
+    "src",
+    "examples",
+    "index.d.ts",
+    "README.md",
+    "README.en.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "scripts": {
+    "check": "node tools/check.mjs",
+    "test": "node tools/check.mjs && node --test tests/*.test.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/adapters.js

@@ -0,0 +1,105 @@
+import { hashString, nowMs } from './utils.js';
+
+export function createMemoryCache(options = {}) {
+  const maxEntries = options.maxEntries || 500;
+  const entries = new Map();
+  const stats = {
+    gets: 0,
+    sets: 0,
+    deletes: 0,
+    clears: 0
+  };
+
+  return {
+    name: 'memory',
+    async get(key) {
+      stats.gets += 1;
+      const entry = entries.get(key);
+      if (!entry) return null;
+      entries.delete(key);
+      entries.set(key, entry);
+      return structuredCloneSafe(entry);
+    },
+    async set(key, entry) {
+      stats.sets += 1;
+      entries.set(key, structuredCloneSafe(entry));
+      while (entries.size > maxEntries) {
+        const oldest = entries.keys().next().value;
+        entries.delete(oldest);
+      }
+    },
+    async delete(key) {
+      stats.deletes += 1;
+      entries.delete(key);
+    },
+    async clear() {
+      stats.clears += 1;
+      entries.clear();
+    },
+    stats() {
+      return { ...stats, entries: entries.size, maxEntries };
+    }
+  };
+}
+
+export function createCacheApiAdapter(cacheApi, options = {}) {
+  const namespace = options.namespace || 'ddys-api-cache';
+  const cache = cacheApi?.default || cacheApi;
+  if (!cache?.match || !cache?.put) throw new Error('Cache API adapter requires a cache with match() and put().');
+  return {
+    name: 'cache-api',
+    async get(key) {
+      const response = await cache.match(cacheRequest(namespace, key));
+      if (!response) return null;
+      return response.json();
+    },
+    async set(key, entry) {
+      await cache.put(cacheRequest(namespace, key), new Response(JSON.stringify(entry), {
+        headers: {
+          'content-type': 'application/json; charset=utf-8',
+          'cache-control': `public, max-age=${Math.max(1, Math.ceil((entry.staleUntil - nowMs()) / 1000))}`
+        }
+      }));
+    },
+    async delete(key) {
+      if (cache.delete) await cache.delete(cacheRequest(namespace, key));
+    },
+    stats() {
+      return { adapter: 'cache-api', namespace };
+    }
+  };
+}
+
+export function createNullCache() {
+  return {
+    name: 'none',
+    async get() {
+      return null;
+    },
+    async set() {},
+    async delete() {},
+    async clear() {},
+    stats() {
+      return { adapter: 'none' };
+    }
+  };
+}
+
+export function createCacheAdapter(config, runtime = {}) {
+  if (runtime.adapter) return runtime.adapter;
+  if (config.cacheAdapter === 'none') return createNullCache();
+  if (config.cacheAdapter === 'cache-api') return createCacheApiAdapter(runtime.caches || globalThis.caches, { namespace: config.cacheNamespace });
+  if (config.cacheAdapter === 'auto' && (runtime.caches || globalThis.caches)) {
+    return createCacheApiAdapter(runtime.caches || globalThis.caches, { namespace: config.cacheNamespace });
+  }
+  return runtime.memoryCache || createMemoryCache({ maxEntries: config.maxMemoryEntries });
+}
+
+function cacheRequest(namespace, key) {
+  return new Request(`https://ddys-api-cache.local/${encodeURIComponent(namespace)}/${hashString(key, 32)}`);
+}
+
+function structuredCloneSafe(value) {
+  if (typeof structuredClone === 'function') return structuredClone(value);
+  return JSON.parse(JSON.stringify(value));
+}

package/src/cache.js

@@ -0,0 +1,237 @@
+import { createConfig, describeConfig } from './config.js';
+import { createCacheAdapter, createMemoryCache } from './adapters.js';
+import { assertAllowedMethod, buildUpstreamRequest } from './security.js';
+import {
+  createEtag,
+  createTimeoutSignal,
+  hashString,
+  normalizeHeaderObject,
+  nowMs,
+  parseQueryString,
+  sanitizeResponseHeaders
+} from './utils.js';
+
+export function createDdysApiCache(input = {}, runtime = {}) {
+  const config = createConfig(input, input.env || runtime.env);
+  const memoryCache = runtime.memoryCache || createMemoryCache({ maxEntries: config.maxMemoryEntries });
+  const adapter = runtime.adapter || createCacheAdapter(config, { ...runtime, memoryCache });
+
+  return {
+    config,
+    adapter,
+    fetch: (pathname, options = {}) => fetchCached(pathname, { ...config, ...options, adapter }, { ...runtime, memoryCache }),
+    warm: (endpoints = config.warmupEndpoints, options = {}) => warmCache(endpoints, { ...config, ...options, adapter }, { ...runtime, memoryCache }),
+    stats: () => adapter.stats?.() || {},
+    describe: () => describeConfig(config)
+  };
+}
+
+export async function fetchCached(pathname, input = {}, runtime = {}) {
+  const startedAt = nowMs(runtime);
+  const config = createConfig(input, input.env || runtime.env);
+  const adapter = input.adapter || runtime.adapter || createCacheAdapter(config, runtime);
+  const method = assertAllowedMethod(input.method || runtime.method || 'GET', config);
+  const query = input.query || parseQueryString(String(pathname || '').split('?')[1] || '');
+  const request = buildUpstreamRequest(pathname, query, config);
+  const cacheKey = buildCacheKey(request, config);
+  const now = nowMs(runtime);
+  const forceRefresh = Boolean(input.forceRefresh || runtime.forceRefresh);
+  const cached = forceRefresh ? null : await adapter.get(cacheKey);
+
+  if (cached && cached.expiresAt > now) {
+    return createCachedResult(cached, {
+      cacheStatus: 'HIT',
+      cacheKey,
+      request,
+      now,
+      startedAt,
+      method
+    });
+  }
+
+  let stale = null;
+  if (cached && cached.staleUntil > now) stale = cached;
+
+  try {
+    const upstream = await fetchUpstream(request.upstreamUrl, config, runtime);
+    const entry = createCacheEntry({
+      cacheKey,
+      request,
+      upstream,
+      config,
+      now: nowMs(runtime)
+    });
+    if (upstream.ok) await adapter.set(cacheKey, entry);
+    return createCachedResult(entry, {
+      cacheStatus: forceRefresh ? 'BYPASS' : 'MISS',
+      cacheKey,
+      request,
+      now: nowMs(runtime),
+      startedAt,
+      method,
+      upstreamMs: upstream.durationMs
+    });
+  } catch (error) {
+    if (stale) {
+      return createCachedResult(stale, {
+        cacheStatus: 'STALE',
+        cacheKey,
+        request,
+        now,
+        startedAt,
+        method,
+        error
+      });
+    }
+    throw error;
+  }
+}
+
+export async function warmCache(endpoints, input = {}, runtime = {}) {
+  const config = createConfig(input, input.env || runtime.env);
+  const adapter = input.adapter || runtime.adapter || createCacheAdapter(config, runtime);
+  const list = normalizeWarmupList(endpoints || config.warmupEndpoints);
+  const results = [];
+  for (const endpoint of list) {
+    try {
+      const result = await fetchCached(endpoint.path, {
+        ...config,
+        query: endpoint.query,
+        adapter,
+        forceRefresh: true
+      }, runtime);
+      results.push({
+        ok: true,
+        path: endpoint.path,
+        cacheStatus: result.cacheStatus,
+        status: result.status,
+        cacheKey: result.cacheKey,
+        upstreamUrl: result.upstreamUrl
+      });
+    } catch (error) {
+      results.push({
+        ok: false,
+        path: endpoint.path,
+        message: error.message
+      });
+    }
+  }
+  return {
+    ok: results.every((item) => item.ok),
+    total: results.length,
+    results
+  };
+}
+
+export async function fetchUpstream(url, config, runtime = {}) {
+  const fetchImpl = runtime.fetch || globalThis.fetch;
+  if (typeof fetchImpl !== 'function') throw new Error('A fetch implementation is required.');
+  const timeout = createTimeoutSignal(config.requestTimeoutMs);
+  const startedAt = nowMs(runtime);
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: 'GET',
+      headers: {
+        accept: 'application/json, text/plain;q=0.9, */*;q=0.8',
+        'user-agent': config.userAgent
+      },
+      signal: timeout.signal
+    });
+  } catch (error) {
+    if (timeout.timedOut()) throw new Error(`DDYS upstream timed out after ${config.requestTimeoutMs}ms.`);
+    throw error;
+  } finally {
+    timeout.cancel();
+  }
+
+  const body = await response.text();
+  const headers = sanitizeResponseHeaders(response.headers);
+  return {
+    ok: response.ok,
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+    body,
+    durationMs: Math.max(0, nowMs(runtime) - startedAt)
+  };
+}
+
+export function buildCacheKey(request, config) {
+  return `${config.cacheNamespace}:${hashString(`${request.canonicalUrl}`, 32)}`;
+}
+
+export function createCacheEntry({ cacheKey, request, upstream, config, now }) {
+  return {
+    cacheKey,
+    upstreamUrl: request.upstreamUrl,
+    canonicalUrl: request.canonicalUrl,
+    status: upstream.status,
+    statusText: upstream.statusText,
+    headers: upstream.headers,
+    body: upstream.body,
+    createdAt: now,
+    expiresAt: now + config.ttlSeconds * 1000,
+    staleUntil: now + (config.ttlSeconds + config.staleSeconds) * 1000,
+    ttlSeconds: config.ttlSeconds,
+    staleSeconds: config.staleSeconds,
+    etag: createEtag(upstream.body)
+  };
+}
+
+export function createCachedResult(entry, meta = {}) {
+  const ageSeconds = Math.max(0, Math.floor(((meta.now ?? Date.now()) - entry.createdAt) / 1000));
+  const headers = buildResultHeaders(entry, {
+    cacheStatus: meta.cacheStatus,
+    ageSeconds,
+    upstreamMs: meta.upstreamMs ?? 0,
+    cacheKey: meta.cacheKey,
+    error: meta.error
+  });
+  const result = {
+    ok: entry.status >= 200 && entry.status < 300,
+    status: entry.status,
+    statusText: entry.statusText,
+    cacheStatus: meta.cacheStatus,
+    cacheKey: meta.cacheKey || entry.cacheKey,
+    upstreamUrl: entry.upstreamUrl,
+    canonicalUrl: entry.canonicalUrl,
+    ageSeconds,
+    stale: meta.cacheStatus === 'STALE',
+    durationMs: Math.max(0, (meta.now ?? Date.now()) - (meta.startedAt ?? Date.now())),
+    method: meta.method || 'GET',
+    headers,
+    body: entry.body,
+    error: meta.error ? meta.error.message : undefined,
+    async text() {
+      return entry.body;
+    },
+    async json() {
+      return entry.body ? JSON.parse(entry.body) : null;
+    }
+  };
+  return result;
+}
+
+export function buildResultHeaders(entry, meta = {}) {
+  return {
+    ...normalizeHeaderObject(entry.headers),
+    'cache-control': `public, max-age=${entry.ttlSeconds}, stale-while-revalidate=${entry.staleSeconds}`,
+    etag: entry.etag,
+    'x-ddys-cache': meta.cacheStatus || 'MISS',
+    'x-ddys-cache-age': String(meta.ageSeconds || 0),
+    'x-ddys-cache-key': hashString(meta.cacheKey || entry.cacheKey, 12),
+    'x-ddys-upstream-ms': String(meta.upstreamMs || 0),
+    'x-ddys-api-cache-version': '0.1.0',
+    ...(meta.error ? { 'x-ddys-cache-error': String(meta.error.message || meta.error).slice(0, 160) } : {})
+  };
+}
+
+function normalizeWarmupList(value) {
+  const list = Array.isArray(value) ? value : String(value || '').split(/[,\n;]/).map((item) => item.trim()).filter(Boolean);
+  return list.map((item) => {
+    if (typeof item === 'object') return { path: item.path || item.endpoint || '/', query: item.query || {} };
+    const [path, query = ''] = String(item).split('?');
+    return { path, query: parseQueryString(query) };
+  });
+}

package/src/config.js

@@ -0,0 +1,129 @@
+import {
+  normalizeApiPath,
+  normalizeBaseUrl,
+  parseBoolean,
+  parseNonNegativeInteger,
+  parsePositiveInteger,
+  splitList
+} from './utils.js';
+
+export const VERSION = '0.1.0';
+
+export const DEFAULT_CONFIG = {
+  version: VERSION,
+  apiBase: 'https://ddys.io/api/v1',
+  userAgent: `ddys-api-cache/${VERSION}`,
+  allowedEndpoints: ['/latest', '/hot', '/calendar', '/search', '/detail'],
+  blockedQueryKeys: ['token', 'access_token', 'api_key', 'apikey', 'key', 'secret', 'password'],
+  allowedMethods: ['GET', 'HEAD'],
+  warmupEndpoints: ['/latest', '/hot', '/calendar'],
+  ttlSeconds: 300,
+  staleSeconds: 3600,
+  requestTimeoutMs: 10000,
+  maxQueryParams: 24,
+  maxQueryLength: 2048,
+  cacheAdapter: 'memory',
+  cacheNamespace: 'ddys-api-cache',
+  maxMemoryEntries: 500,
+  workerCache: true
+};
+
+export function loadConfigFromEnv(env = getProcessEnv()) {
+  return createConfig({}, env);
+}
+
+export function createConfig(input = {}, env = input.env || getProcessEnv()) {
+  const envConfig = readEnvConfig(env || {});
+  const merged = {
+    ...DEFAULT_CONFIG,
+    ...envConfig,
+    ...input
+  };
+
+  merged.apiBase = normalizeBaseUrl(merged.apiBase, 'apiBase');
+  merged.allowedEndpoints = normalizeEndpointList(merged.allowedEndpoints);
+  merged.blockedQueryKeys = normalizeNameList(merged.blockedQueryKeys).map((item) => item.toLowerCase());
+  merged.allowedMethods = normalizeNameList(merged.allowedMethods).map((item) => item.toUpperCase());
+  merged.warmupEndpoints = normalizeWarmupEndpoints(merged.warmupEndpoints);
+  merged.ttlSeconds = parsePositiveInteger(merged.ttlSeconds, DEFAULT_CONFIG.ttlSeconds, 'ttlSeconds');
+  merged.staleSeconds = parseNonNegativeInteger(merged.staleSeconds, DEFAULT_CONFIG.staleSeconds, 'staleSeconds');
+  merged.requestTimeoutMs = parsePositiveInteger(merged.requestTimeoutMs, DEFAULT_CONFIG.requestTimeoutMs, 'requestTimeoutMs');
+  merged.maxQueryParams = parsePositiveInteger(merged.maxQueryParams, DEFAULT_CONFIG.maxQueryParams, 'maxQueryParams');
+  merged.maxQueryLength = parsePositiveInteger(merged.maxQueryLength, DEFAULT_CONFIG.maxQueryLength, 'maxQueryLength');
+  merged.maxMemoryEntries = parsePositiveInteger(merged.maxMemoryEntries, DEFAULT_CONFIG.maxMemoryEntries, 'maxMemoryEntries');
+  merged.cacheAdapter = normalizeCacheAdapter(merged.cacheAdapter);
+  merged.cacheNamespace = String(merged.cacheNamespace || DEFAULT_CONFIG.cacheNamespace).trim();
+  merged.workerCache = parseBoolean(merged.workerCache, DEFAULT_CONFIG.workerCache);
+  return merged;
+}
+
+export function readEnvConfig(env = {}) {
+  const out = {};
+  if (env.DDYS_API_CACHE_API_BASE) out.apiBase = env.DDYS_API_CACHE_API_BASE;
+  if (env.DDYS_API_CACHE_USER_AGENT) out.userAgent = env.DDYS_API_CACHE_USER_AGENT;
+  if (env.DDYS_API_CACHE_ALLOWED_ENDPOINTS) out.allowedEndpoints = env.DDYS_API_CACHE_ALLOWED_ENDPOINTS;
+  if (env.DDYS_API_CACHE_BLOCKED_QUERY_KEYS) out.blockedQueryKeys = env.DDYS_API_CACHE_BLOCKED_QUERY_KEYS;
+  if (env.DDYS_API_CACHE_ALLOWED_METHODS) out.allowedMethods = env.DDYS_API_CACHE_ALLOWED_METHODS;
+  if (env.DDYS_API_CACHE_WARMUP_ENDPOINTS) out.warmupEndpoints = env.DDYS_API_CACHE_WARMUP_ENDPOINTS;
+  if (env.DDYS_API_CACHE_TTL_SECONDS) out.ttlSeconds = env.DDYS_API_CACHE_TTL_SECONDS;
+  if (env.DDYS_API_CACHE_STALE_SECONDS) out.staleSeconds = env.DDYS_API_CACHE_STALE_SECONDS;
+  if (env.DDYS_API_CACHE_TIMEOUT_MS) out.requestTimeoutMs = env.DDYS_API_CACHE_TIMEOUT_MS;
+  if (env.DDYS_API_CACHE_MAX_QUERY_PARAMS) out.maxQueryParams = env.DDYS_API_CACHE_MAX_QUERY_PARAMS;
+  if (env.DDYS_API_CACHE_MAX_QUERY_LENGTH) out.maxQueryLength = env.DDYS_API_CACHE_MAX_QUERY_LENGTH;
+  if (env.DDYS_API_CACHE_ADAPTER) out.cacheAdapter = env.DDYS_API_CACHE_ADAPTER;
+  if (env.DDYS_API_CACHE_NAMESPACE) out.cacheNamespace = env.DDYS_API_CACHE_NAMESPACE;
+  if (env.DDYS_API_CACHE_MAX_MEMORY_ENTRIES) out.maxMemoryEntries = env.DDYS_API_CACHE_MAX_MEMORY_ENTRIES;
+  if (env.DDYS_API_CACHE_WORKER_CACHE) out.workerCache = env.DDYS_API_CACHE_WORKER_CACHE;
+  return out;
+}
+
+export function describeConfig(config) {
+  return {
+    version: config.version,
+    apiBase: config.apiBase,
+    allowedEndpoints: config.allowedEndpoints,
+    blockedQueryKeys: config.blockedQueryKeys,
+    allowedMethods: config.allowedMethods,
+    warmupEndpoints: config.warmupEndpoints,
+    ttlSeconds: config.ttlSeconds,
+    staleSeconds: config.staleSeconds,
+    requestTimeoutMs: config.requestTimeoutMs,
+    maxQueryParams: config.maxQueryParams,
+    maxQueryLength: config.maxQueryLength,
+    cacheAdapter: config.cacheAdapter,
+    cacheNamespace: config.cacheNamespace,
+    maxMemoryEntries: config.maxMemoryEntries,
+    workerCache: config.workerCache
+  };
+}
+
+export function normalizeEndpointList(value) {
+  const endpoints = (Array.isArray(value) ? value : splitList(value))
+    .map((item) => normalizeApiPath(item))
+    .filter((item) => item !== '/');
+  return endpoints.length ? [...new Set(endpoints)] : DEFAULT_CONFIG.allowedEndpoints;
+}
+
+export function normalizeWarmupEndpoints(value) {
+  const endpoints = (Array.isArray(value) ? value : splitList(value))
+    .map((item) => String(item || '').trim())
+    .filter(Boolean);
+  return endpoints.length ? [...new Set(endpoints)] : [];
+}
+
+function normalizeNameList(value) {
+  const names = (Array.isArray(value) ? value : splitList(value))
+    .map((item) => String(item || '').trim())
+    .filter(Boolean);
+  return names.length ? [...new Set(names)] : [];
+}
+
+function normalizeCacheAdapter(value) {
+  const adapter = String(value || 'memory').trim().toLowerCase();
+  if (!['memory', 'cache-api', 'auto', 'none'].includes(adapter)) throw new Error(`Unsupported cache adapter: ${value}`);
+  return adapter;
+}
+
+function getProcessEnv() {
+  return globalThis.process?.env || {};
+}

package/src/index.js

@@ -0,0 +1,14 @@
+export { createConfig, describeConfig, loadConfigFromEnv, normalizeEndpointList, normalizeWarmupEndpoints } from './config.js';
+export { createMemoryCache, createCacheApiAdapter, createNullCache, createCacheAdapter } from './adapters.js';
+export { assertAllowedEndpoint, assertAllowedMethod, buildUpstreamRequest, sanitizeQuery } from './security.js';
+export {
+  buildCacheKey,
+  buildResultHeaders,
+  createCacheEntry,
+  createCachedResult,
+  createDdysApiCache,
+  fetchCached,
+  fetchUpstream,
+  warmCache
+} from './cache.js';
+export { createWorkerHandler, handleWorkerRequest, routeForPath } from './worker.js';

package/src/security.js

@@ -0,0 +1,45 @@
+import { joinUrl, normalizeApiPath, queryToSearchParams, stableSearch } from './utils.js';
+
+export function assertAllowedMethod(method, config) {
+  const normalized = String(method || 'GET').toUpperCase();
+  if (!config.allowedMethods.includes(normalized)) throw new Error(`HTTP method is not allowed: ${normalized}`);
+  return normalized;
+}
+
+export function assertAllowedEndpoint(pathname, config) {
+  const path = normalizeApiPath(pathname);
+  const allowed = config.allowedEndpoints.some((endpoint) => path === endpoint || path.startsWith(`${endpoint}/`));
+  if (!allowed) throw new Error(`DDYS API endpoint is not allowed: ${path}`);
+  return path;
+}
+
+export function sanitizeQuery(query, config) {
+  const input = queryToSearchParams(query);
+  const out = new URLSearchParams();
+  let count = 0;
+  for (const [key, value] of input.entries()) {
+    const normalizedKey = String(key || '').trim();
+    if (!normalizedKey) continue;
+    if (config.blockedQueryKeys.includes(normalizedKey.toLowerCase())) continue;
+    count += 1;
+    if (count > config.maxQueryParams) throw new Error(`Too many query parameters. Max: ${config.maxQueryParams}`);
+    out.append(normalizedKey, String(value));
+  }
+  const serialized = stableSearch(out);
+  if (serialized.length > config.maxQueryLength) throw new Error(`Query string is too long. Max: ${config.maxQueryLength}`);
+  return out;
+}
+
+export function buildUpstreamRequest(pathname, query, config) {
+  const path = assertAllowedEndpoint(pathname, config);
+  const params = sanitizeQuery(query, config);
+  const url = new URL(joinUrl(config.apiBase, path));
+  const serialized = stableSearch(params);
+  for (const [key, value] of new URLSearchParams(serialized).entries()) url.searchParams.append(key, value);
+  return {
+    path,
+    query: params,
+    upstreamUrl: url.toString(),
+    canonicalUrl: `${path}${serialized ? `?${serialized}` : ''}`
+  };
+}

package/src/utils.js

@@ -0,0 +1,150 @@
+import { createHash } from 'node:crypto';
+
+export function normalizeBaseUrl(value, name = 'url') {
+  const raw = String(value || '').trim();
+  if (!raw) throw new Error(`${name} is required.`);
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(`${name} must be a valid URL.`);
+  }
+  if (!['http:', 'https:'].includes(url.protocol)) throw new Error(`${name} must use http or https.`);
+  return url.toString().replace(/\/+$/, '');
+}
+
+export function joinUrl(base, pathname = '') {
+  const left = String(base || '').replace(/\/+$/, '');
+  const right = String(pathname || '').replace(/^\/+/, '');
+  return right ? `${left}/${right}` : left;
+}
+
+export function splitList(value) {
+  if (Array.isArray(value)) return value.flatMap((item) => splitList(item));
+  return String(value || '')
+    .split(/[,\n;]/)
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+export function parseBoolean(value, fallback = false) {
+  if (value === undefined || value === null || value === '') return fallback;
+  if (typeof value === 'boolean') return value;
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'y', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'n', 'off'].includes(normalized)) return false;
+  return fallback;
+}
+
+export function parsePositiveInteger(value, fallback, name = 'value') {
+  const number = Number(value);
+  if (Number.isInteger(number) && number > 0) return number;
+  if (fallback !== undefined) return fallback;
+  throw new Error(`${name} must be a positive integer.`);
+}
+
+export function parseNonNegativeInteger(value, fallback, name = 'value') {
+  const number = Number(value);
+  if (Number.isInteger(number) && number >= 0) return number;
+  if (fallback !== undefined) return fallback;
+  throw new Error(`${name} must be a non-negative integer.`);
+}
+
+export function hashString(value, length = 16) {
+  return createHash('sha1').update(String(value || '')).digest('hex').slice(0, length);
+}
+
+export function createEtag(value) {
+  return `"${hashString(value, 24)}"`;
+}
+
+export function normalizeApiPath(pathname) {
+  const raw = String(pathname || '/').trim();
+  if (/^https?:\/\//i.test(raw)) throw new Error('API path must be relative, not absolute.');
+  const withoutQuery = raw.split('?')[0];
+  const path = `/${withoutQuery.replace(/^\/+/, '')}`.replace(/\/{2,}/g, '/');
+  return path === '/' ? '/' : path.replace(/\/+$/, '');
+}
+
+export function normalizeHeaderObject(headers = {}) {
+  const out = {};
+  if (headers?.forEach) {
+    headers.forEach((value, key) => {
+      out[String(key).toLowerCase()] = String(value);
+    });
+    return out;
+  }
+  for (const [key, value] of Object.entries(headers || {})) {
+    if (value === undefined || value === null) continue;
+    out[String(key).toLowerCase()] = String(value);
+  }
+  return out;
+}
+
+export function sanitizeResponseHeaders(headers = {}) {
+  const input = normalizeHeaderObject(headers);
+  const blocked = new Set(['set-cookie', 'set-cookie2', 'connection', 'transfer-encoding', 'content-length']);
+  const out = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (blocked.has(key)) continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+export function createTimeoutSignal(ms) {
+  const controller = new AbortController();
+  let didTimeout = false;
+  const timer = setTimeout(() => {
+    didTimeout = true;
+    controller.abort();
+  }, ms);
+  return {
+    signal: controller.signal,
+    timedOut: () => didTimeout,
+    cancel: () => clearTimeout(timer)
+  };
+}
+
+export function parseQueryString(value) {
+  const out = {};
+  const params = new URLSearchParams(String(value || '').replace(/^\?/, ''));
+  for (const [key, item] of params.entries()) {
+    if (key in out) {
+      if (!Array.isArray(out[key])) out[key] = [out[key]];
+      out[key].push(item);
+    } else {
+      out[key] = item;
+    }
+  }
+  return out;
+}
+
+export function queryToSearchParams(query = {}) {
+  if (query instanceof URLSearchParams) return new URLSearchParams(query);
+  if (typeof query === 'string') return new URLSearchParams(query.replace(/^\?/, ''));
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query || {})) {
+    if (value === undefined || value === null || value === '') continue;
+    if (Array.isArray(value)) {
+      for (const item of value) params.append(key, String(item));
+      continue;
+    }
+    params.set(key, String(value));
+  }
+  return params;
+}
+
+export function stableSearch(params) {
+  const entries = [...params.entries()].sort(([aKey, aValue], [bKey, bValue]) => {
+    const keyCompare = aKey.localeCompare(bKey);
+    return keyCompare || aValue.localeCompare(bValue);
+  });
+  const out = new URLSearchParams();
+  for (const [key, value] of entries) out.append(key, value);
+  return out.toString();
+}
+
+export function nowMs(runtime = {}) {
+  return Number(runtime.now?.() ?? Date.now());
+}

package/src/worker.js

@@ -0,0 +1,77 @@
+import { createConfig, describeConfig } from './config.js';
+import { createMemoryCache } from './adapters.js';
+import { fetchCached, warmCache } from './cache.js';
+import { normalizeApiPath, parseQueryString } from './utils.js';
+
+export function createWorkerHandler(input = {}) {
+  const memoryCache = createMemoryCache({ maxEntries: input.maxMemoryEntries || 500 });
+  return async function fetch(request, env = {}, ctx = {}) {
+    return handleWorkerRequest(request, {
+      ...input,
+      env,
+      ctx,
+      memoryCache,
+      caches: globalThis.caches
+    });
+  };
+}
+
+export async function handleWorkerRequest(request, runtime = {}) {
+  const url = new URL(request.url);
+  const route = routeForPath(url.pathname);
+  const config = createConfig(runtime, runtime.env || {});
+
+  if (route === 'health') {
+    return jsonResponse({ ok: true, service: 'ddys-api-cache', version: config.version }, 200, { 'cache-control': 'no-store' });
+  }
+
+  if (route === 'diag') {
+    return jsonResponse({ ok: true, config: describeConfig(config) }, 200, { 'cache-control': 'no-store' });
+  }
+
+  if (route === 'warm') {
+    const warmed = await warmCache(config.warmupEndpoints, config, runtime);
+    return jsonResponse(warmed, warmed.ok ? 200 : 207, { 'cache-control': 'no-store' });
+  }
+
+  if (route !== 'api') {
+    return jsonResponse({ ok: false, message: 'Not found' }, 404, { 'cache-control': 'no-store' });
+  }
+
+  const apiPath = normalizeApiPath(url.pathname.replace(/^\/api(?=\/|$)/, '') || '/');
+  const result = await fetchCached(apiPath, {
+    ...config,
+    method: request.method,
+    query: parseQueryString(url.search),
+    adapter: runtime.adapter
+  }, runtime);
+
+  if (request.headers.get('if-none-match') && request.headers.get('if-none-match') === result.headers.etag) {
+    return new Response(null, { status: 304, headers: result.headers });
+  }
+
+  return new Response(request.method === 'HEAD' ? null : result.body, {
+    status: result.status,
+    statusText: result.statusText,
+    headers: result.headers
+  });
+}
+
+export function routeForPath(pathname) {
+  const path = String(pathname || '/').replace(/\/+$/, '') || '/';
+  if (path === '/health') return 'health';
+  if (path === '/diag') return 'diag';
+  if (path === '/warm') return 'warm';
+  if (path === '/api' || path.startsWith('/api/')) return 'api';
+  return 'not-found';
+}
+
+function jsonResponse(body, status = 200, headers = {}) {
+  return new Response(`${JSON.stringify(body, null, 2)}\n`, {
+    status,
+    headers: {
+      'content-type': 'application/json; charset=utf-8',
+      ...headers
+    }
+  });
+}