mkdnsite 0.0.1 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mkdnsite",
-  "version": "0.0.1",
+  "version": "1.0.1",
   "description": "Markdown for the web. HTML for humans, Markdown for agents.",
   "type": "module",
   "main": "src/index.ts",
@@ -15,7 +15,10 @@
     "./adapters/fly": "./src/adapters/fly.ts"
   },
   "scripts": {
-    "dev": "bun run --watch src/cli.ts ./content",
+    "dev": "bun run --watch src/cli.ts ./content --static ./static --logo /mkdnsite-logo.png --logo-text mkdnsite",
+    "dev:themed": "bun run --watch src/cli.ts --config themed.config.ts",
+    "dev:light": "bun run --watch src/cli.ts --config themed.config.ts --color-scheme light",
+    "dev:dark": "bun run --watch src/cli.ts --config themed.config.ts --color-scheme dark",
     "start": "bun run src/cli.ts",
     "test": "bun test",
     "lint": "ts-standard src/ test/",
@@ -44,6 +47,7 @@
     "src"
   ],
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "gray-matter": "^4.0.3",
     "katex": "^0.16.38",
     "lucide-react": "^0.577.0",
@@ -57,7 +61,8 @@
     "remark-gfm": "^4.0.0",
     "remark-github-blockquote-alert": "^2.0.1",
     "remark-math": "^6.0.0",
-    "shiki": "^3.0.0"
+    "shiki": "^3.0.0",
+    "zod": "^4.3.6"
   },
   "ts-standard": {
     "project": "./tsconfig.json"

package/src/adapters/cloudflare.ts

@@ -3,12 +3,23 @@ import type { MkdnSiteConfig } from '../config/schema.ts'
 import type { ContentSource } from '../content/types.ts'
 import type { MarkdownRenderer } from '../render/types.ts'
 import { createRenderer } from '../render/types.ts'
+import { GitHubSource } from '../content/github.ts'
+import { R2ContentSource } from '../content/r2.ts'
+import { AssetsSource } from '../content/assets.ts'
+import type { ContentCache } from '../content/cache.ts'
+import { KVContentCache } from '../content/cache.ts'
+import type { ResponseCache } from '../cache/response.ts'
+import { KVResponseCache } from '../cache/kv.ts'
+import type { TrafficAnalytics, TrafficEvent } from '../analytics/types.ts'
 
 /**
  * Cloudflare Workers deployment adapter.
  *
- * Uses R2 for content storage, KV for caching.
- * Wildcard DNS routes (*.mkdn.io) for hosted service.
+ * Auto-detects content source from env bindings:
+ * - CONTENT_SOURCE=github or config.github set → GitHubSource
+ * - CONTENT_SOURCE=r2 or CONTENT_BUCKET present → R2ContentSource
+ * - CONTENT_SOURCE=assets or ASSETS binding present → AssetsSource
+ * - Explicit CONTENT_SOURCE env var overrides auto-detection
  *
  * Usage in a Worker:
  *
@@ -38,48 +49,224 @@ export class CloudflareAdapter implements DeploymentAdapter {
     this.env = env
   }
 
-  createContentSource (_config: MkdnSiteConfig): ContentSource {
-    // TODO: Implement R2ContentSource
-    // return new R2ContentSource(this.env.CONTENT_BUCKET)
+  private createCache (prefix?: string): ContentCache | undefined {
+    if (this.env.CACHE_KV == null) return undefined
+    return new KVContentCache(this.env.CACHE_KV, { prefix })
+  }
+
+  createContentSource (config: MkdnSiteConfig): ContentSource {
+    const sourceType = this.env.CONTENT_SOURCE
+
+    // GitHub source: explicit CONTENT_SOURCE=github or config.github set
+    if (sourceType === 'github' || (sourceType == null && config.github != null)) {
+      const ghConfig = config.github ?? {
+        owner: this.env.GITHUB_OWNER ?? '',
+        repo: this.env.GITHUB_REPO ?? '',
+        ref: this.env.GITHUB_REF,
+        token: this.env.GITHUB_TOKEN
+      }
+      return new GitHubSource(ghConfig)
+    }
+
+    // R2 source: explicit CONTENT_SOURCE=r2 or CONTENT_BUCKET binding present
+    if (sourceType === 'r2' || (sourceType == null && this.env.CONTENT_BUCKET != null)) {
+      if (this.env.CONTENT_BUCKET == null) {
+        throw new Error(
+          'CloudflareAdapter: CONTENT_SOURCE=r2 requires a CONTENT_BUCKET binding in wrangler.toml.'
+        )
+      }
+      return new R2ContentSource({
+        bucket: this.env.CONTENT_BUCKET,
+        basePath: this.env.CONTENT_BASE_PATH,
+        cache: this.createCache(this.env.CONTENT_BASE_PATH)
+      })
+    }
+
+    // Assets source: explicit CONTENT_SOURCE=assets or ASSETS binding present
+    if (sourceType === 'assets' || (sourceType == null && this.env.ASSETS != null)) {
+      if (this.env.ASSETS == null) {
+        throw new Error(
+          'CloudflareAdapter: CONTENT_SOURCE=assets requires an ASSETS binding in wrangler.toml.'
+        )
+      }
+      const manifest = this.env.CONTENT_MANIFEST != null
+        ? JSON.parse(this.env.CONTENT_MANIFEST) as string[]
+        : undefined
+      return new AssetsSource({
+        assets: this.env.ASSETS,
+        manifest,
+        cache: this.createCache('assets:')
+      })
+    }
+
     throw new Error(
-      'CloudflareAdapter.createContentSource() not yet implemented. ' +
-      'Provide an R2-backed ContentSource implementation.'
+      'CloudflareAdapter: No content source configured. ' +
+      'Set CONTENT_SOURCE=github|r2|assets, provide CONTENT_BUCKET (R2), ASSETS binding, or set config.github.'
     )
   }
 
   async createRenderer (_config: MkdnSiteConfig): Promise<MarkdownRenderer> {
-    // CF Workers don't have Bun.markdown, always use portable
+    // CF Workers don't have Bun.markdown — always use portable renderer
     return await createRenderer('portable')
   }
+
+  /**
+   * Create a TrafficAnalytics instance if the ANALYTICS binding is present.
+   *
+   * Returns `undefined` when the binding is absent so callers can skip
+   * passing analytics to createHandler without any change in behaviour.
+   *
+   * Usage:
+   * ```ts
+   * const handler = createHandler({
+   *   source: adapter.createContentSource(config),
+   *   renderer: await adapter.createRenderer(config),
+   *   config,
+   *   analytics: adapter.createTrafficAnalytics()
+   * })
+   * ```
+   */
+  /**
+   * Create a ResponseCache backed by CACHE_KV when available.
+   * Returns undefined when no KV binding is present.
+   */
+  createResponseCache (): ResponseCache | undefined {
+    if (this.env.CACHE_KV == null) return undefined
+    return new KVResponseCache(this.env.CACHE_KV, { prefix: 'resp:' })
+  }
+
+  createTrafficAnalytics (): TrafficAnalytics | undefined {
+    if (this.env.ANALYTICS == null) return undefined
+    return new WorkersAnalyticsEngineAnalytics(this.env.ANALYTICS)
+  }
+}
+
+/**
+ * Cloudflare Workers Analytics Engine implementation of TrafficAnalytics.
+ *
+ * Writes a data point to a CF Analytics Engine dataset binding (`ANALYTICS`).
+ * Each field maps to an index (string "blobs") or double (numeric values).
+ *
+ * Usage: automatically created by `CloudflareAdapter.createTrafficAnalytics()`
+ * when the `ANALYTICS` binding is present.
+ */
+export class WorkersAnalyticsEngineAnalytics implements TrafficAnalytics {
+  private readonly dataset: AnalyticsEngineDataset
+
+  constructor (dataset: AnalyticsEngineDataset) {
+    this.dataset = dataset
+  }
+
+  logRequest (event: TrafficEvent): void {
+    // Field ordering is significant — CF Analytics Engine queries reference
+    // fields by index (blob1, blob2, ..., double1, double2, ...).
+    // Do NOT reorder without updating all downstream queries.
+    this.dataset.writeDataPoint({
+      indexes: [
+        event.siteId ?? '' // index1: site isolation key (empty for single-site)
+      ],
+      blobs: [
+        event.path, // blob1: URL pathname
+        event.method, // blob2: HTTP method
+        event.format, // blob3: response format (html|markdown|mcp|api|other)
+        event.trafficType, // blob4: traffic classification (human|ai_agent|bot|mcp)
+        event.userAgent // blob5: raw User-Agent string
+      ],
+      doubles: [
+        event.statusCode, // double1: HTTP status code
+        event.latencyMs, // double2: handler latency in ms
+        event.contentLength, // double3: response body size in bytes
+        event.cacheHit ? 1 : 0, // double4: cache hit (1) or miss (0)
+        event.timestamp // double5: request timestamp (epoch ms)
+      ]
+    })
+  }
 }
 
 /**
  * Expected Cloudflare Worker environment bindings.
  */
 export interface CloudflareEnv {
-  /** R2 bucket for markdown content */
+  /** Explicit content source selection */
+  CONTENT_SOURCE?: 'github' | 'r2' | 'assets'
+
+  /** R2 bucket binding for markdown content */
   CONTENT_BUCKET?: R2Bucket
-  /** KV namespace for caching */
+  /** Key prefix within the R2 bucket (e.g. 'sites/abc123/') */
+  CONTENT_BASE_PATH?: string
+
+  /** Workers Static Assets binding */
+  ASSETS?: AssetsFetcher
+  /** JSON array of .md file paths (alternative to _manifest.json in assets) */
+  CONTENT_MANIFEST?: string
+
+  /** KV namespace for caching (future use) */
   CACHE_KV?: KVNamespace
-  /** Site title from env var */
+
+  /** GitHub owner (used if config.github not set) */
+  GITHUB_OWNER?: string
+  /** GitHub repo (used if config.github not set) */
+  GITHUB_REPO?: string
+  /** GitHub branch/tag (default: main) */
+  GITHUB_REF?: string
+  /** GitHub token for private repos / higher rate limits */
+  GITHUB_TOKEN?: string
+
+  /** Site title (can override config.site.title) */
   SITE_TITLE?: string
-  /** Site URL from env var */
+  /** Site URL */
   SITE_URL?: string
+
+  /** Secret token for authenticating POST /_refresh requests */
+  REFRESH_TOKEN?: string
+
+  /** Workers Analytics Engine dataset binding for traffic analytics */
+  ANALYTICS?: AnalyticsEngineDataset
 }
 
-// Type stubs for CF runtime types (not available in non-CF environments)
+// ─── Cloudflare R2 type stubs ─────────────────────────────────────────────────
+// These types are provided by the CF Workers runtime; stubs here for type-checking
+// in non-CF environments.
+
 interface R2Bucket {
   get: (key: string) => Promise<R2Object | null>
-  list: (options?: Record<string, unknown>) => Promise<{ objects: R2Object[] }>
+  list: (options?: R2ListOptions) => Promise<R2ObjectList>
 }
 
 interface R2Object {
   key: string
   uploaded: Date
+  size: number
   text: () => Promise<string>
 }
 
+interface R2ObjectList {
+  objects: R2Object[]
+  truncated: boolean
+  cursor?: string
+}
+
+interface R2ListOptions {
+  prefix?: string
+  cursor?: string
+  limit?: number
+}
+
+interface AssetsFetcher {
+  fetch: (input: Request | string) => Promise<Response>
+}
+
 interface KVNamespace {
   get: (key: string) => Promise<string | null>
-  put: (key: string, value: string, options?: Record<string, unknown>) => Promise<void>
+  put: (key: string, value: string, options?: { expirationTtl?: number }) => Promise<void>
+  delete: (key: string) => Promise<void>
+  list: (options?: { prefix?: string }) => Promise<{ keys: Array<{ name: string }> }>
+}
+
+interface AnalyticsEngineDataset {
+  writeDataPoint: (data: {
+    blobs?: string[]
+    doubles?: number[]
+    indexes?: string[]
+  }) => void
 }

package/src/adapters/local.ts

@@ -1,9 +1,11 @@
+import { Buffer } from 'node:buffer'
 import type { DeploymentAdapter } from './types.ts'
 import { detectRuntime } from './types.ts'
 import type { MkdnSiteConfig } from '../config/schema.ts'
 import type { ContentSource } from '../content/types.ts'
 import type { MarkdownRenderer } from '../render/types.ts'
 import { FilesystemSource } from '../content/filesystem.ts'
+import { GitHubSource } from '../content/github.ts'
 import { createRenderer } from '../render/types.ts'
 
 export class LocalAdapter implements DeploymentAdapter {
@@ -15,6 +17,9 @@ export class LocalAdapter implements DeploymentAdapter {
   }
 
   createContentSource (config: MkdnSiteConfig): ContentSource {
+    if (config.github != null) {
+      return new GitHubSource(config.github)
+    }
     return new FilesystemSource(config.contentDir)
   }
 
@@ -129,25 +134,41 @@ export class LocalAdapter implements DeploymentAdapter {
 
   private printStartup (config: MkdnSiteConfig, port: number): void {
     const url = `http://localhost:${String(port)}`
+    const DIM_CYAN = '\x1b[2;36m'
+    const BOLD_GREEN = '\x1b[1;32m'
+    const DIM = '\x1b[2m'
+    const RESET = '\x1b[0m'
+
+    // ASCII art header
+    console.log('')
+    console.log(`${DIM_CYAN}   ▌  ▌    ▘▗   `)
+    console.log('▛▛▌▙▘▛▌▛▌▛▘▌▜▘█▌')
+    console.log(`▌▌▌▛▖▙▌▌▌▄▌▌▐▖▙▖${RESET}`)
     console.log('')
-    console.log('  ┌──────────────────────────────────────────────┐')
-    console.log('  │                                              │')
-    console.log('  │   mkdnsite is running                       │')
-    console.log(`  │   ${url.padEnd(42)} │`)
-    console.log('  │                                              │')
-    console.log(`  │   Runtime: ${this.name.padEnd(32)} │`)
-    console.log(`  │   Content: ${config.contentDir.padEnd(32)} │`)
-    console.log(`  │   Renderer: ${this.rendererEngine.padEnd(30)} │`)
-    console.log(`  │   Theme mode: ${config.theme.mode.padEnd(28)} │`)
-    console.log(`  │   Client JS: ${(config.client.enabled ? 'on' : 'off').padEnd(29)} │`)
-    console.log(`  │   Content negotiation: ${(config.negotiation.enabled ? 'on' : 'off').padEnd(19)} │`)
-    console.log('  │                                              │')
-    console.log('  └──────────────────────────────────────────────┘')
+    console.log(`  ${BOLD_GREEN}\u2192 ${url}${RESET}`)
+    console.log('')
+
+    const row = (label: string, value: string): void => {
+      console.log(`  ${DIM}${label.padEnd(12)}${RESET}${value}`)
+    }
+
+    row('Runtime', `local (${this.name})`)
+    if (config.github != null) {
+      const ref = config.github.ref ?? 'main'
+      row('GitHub', `${config.github.owner}/${config.github.repo}@${ref}`)
+    } else {
+      row('Content', config.contentDir)
+    }
+    row('Renderer', this.rendererEngine)
+    if (config.mcp.enabled) {
+      row('MCP', config.mcp.endpoint ?? '/mcp')
+    }
+    if (config.client.search) {
+      row('Search', '/api/search')
+    }
+
     console.log('')
-    console.log('  Try:')
-    console.log(`    curl ${url}`)
-    console.log(`    curl -H "Accept: text/markdown" ${url}`)
-    console.log(`    curl ${url}/llms.txt`)
+    console.log(`  ${DIM}Ctrl+C to stop${RESET}`)
     console.log('')
   }
 }

package/src/analytics/classify.ts

@@ -0,0 +1,65 @@
+import type { TrafficType, AnalyticsResponseFormat } from './types.ts'
+
+/**
+ * Known crawler / bot User-Agent patterns.
+ * Checked case-insensitively.
+ *
+ * This list is intentionally extensible — add entries as new crawlers appear.
+ */
+export const BOT_PATTERNS: RegExp[] = [
+  /googlebot/i,
+  /bingbot/i,
+  /slurp/i, // Yahoo
+  /duckduckbot/i,
+  /baiduspider/i,
+  /yandexbot/i,
+  /sogou/i,
+  /exabot/i,
+  /facebot/i,
+  /ia_archiver/i, // Alexa / Internet Archive
+  /semrushbot/i,
+  /ahrefsbot/i,
+  /mj12bot/i,
+  /dotbot/i,
+  /rogerbot/i,
+  /archive\.org_bot/i,
+  /petalbot/i,
+  /bytespider/i, // TikTok
+  /applebot/i,
+  /linkedinbot/i,
+  /twitterbot/i,
+  /facebookexternalhit/i,
+  /whatsapp/i,
+  /telegrambot/i,
+  /discordbot/i,
+  /slackbot/i
+]
+
+/**
+ * Classify a request as human, ai_agent, bot, or mcp traffic.
+ *
+ * Rules (evaluated in order):
+ * 1. MCP format → 'mcp'
+ * 2. markdown format (already resolved by the handler from Accept header / .md URL) → 'ai_agent'
+ * 3. User-Agent matches a known bot pattern → 'bot'
+ * 4. Otherwise → 'human'
+ *
+ * The `format` parameter is pre-resolved by the handler's `resolveAnalyticsFormat()`,
+ * which already checks Content-Type, Accept headers, and .md URL suffix — so we
+ * avoid duplicating that logic here.
+ */
+export function classifyTraffic (request: Request, format: AnalyticsResponseFormat): TrafficType {
+  // MCP traffic
+  if (format === 'mcp') return 'mcp'
+
+  // AI agent: served raw markdown (format resolved from Accept header / .md URL / Content-Type)
+  if (format === 'markdown') return 'ai_agent'
+
+  // Known bot by User-Agent
+  const ua = request.headers.get('User-Agent') ?? ''
+  if (ua !== '' && BOT_PATTERNS.some(pattern => pattern.test(ua))) {
+    return 'bot'
+  }
+
+  return 'human'
+}

package/src/analytics/console.ts

@@ -0,0 +1,39 @@
+import type { TrafficAnalytics, TrafficEvent } from './types.ts'
+
+/**
+ * Console analytics implementation — writes a structured log line to stdout.
+ *
+ * Useful during development and debugging. Output format is a single JSON line
+ * per request so it can be piped to `jq` or similar tools.
+ *
+ * Example output:
+ * {"ts":1710000000000,"method":"GET","path":"/docs","format":"html","type":"human","status":200,"ms":12,"bytes":4321,"cache":false}
+ */
+export class ConsoleAnalytics implements TrafficAnalytics {
+  private readonly output: (line: string) => void
+
+  /**
+   * @param output - Write function (defaults to console.log). Injectable for
+   *   testing without polluting test output.
+   */
+  constructor (output?: (line: string) => void) {
+    this.output = output ?? console.log
+  }
+
+  logRequest (event: TrafficEvent): void {
+    const obj: Record<string, unknown> = {
+      ts: event.timestamp,
+      method: event.method,
+      path: event.path,
+      format: event.format,
+      type: event.trafficType,
+      status: event.statusCode,
+      ms: event.latencyMs,
+      bytes: event.contentLength,
+      cache: event.cacheHit,
+      ua: event.userAgent
+    }
+    if (event.siteId != null) obj.site = event.siteId
+    this.output(JSON.stringify(obj))
+  }
+}

package/src/analytics/noop.ts

@@ -0,0 +1,15 @@
+import type { TrafficAnalytics, TrafficEvent } from './types.ts'
+
+/**
+ * No-op analytics implementation.
+ *
+ * The default when no analytics backend is configured. logRequest() is a
+ * genuine no-op — zero allocations, zero overhead beyond the null check in
+ * the handler.
+ */
+export class NoopAnalytics implements TrafficAnalytics {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  logRequest (_event: TrafficEvent): void {
+    // intentionally empty
+  }
+}

package/src/analytics/types.ts

@@ -0,0 +1,49 @@
+/**
+ * Traffic analytics types for mkdnsite.
+ *
+ * The TrafficAnalytics interface is the core extension point — implement it
+ * to route request events to any analytics backend (console, CF Analytics Engine,
+ * ClickHouse, Plausible, etc.).
+ */
+
+/** Classification of who sent the request */
+export type TrafficType = 'human' | 'ai_agent' | 'bot' | 'mcp'
+
+/** What format was served in the response */
+export type AnalyticsResponseFormat = 'html' | 'markdown' | 'mcp' | 'api' | 'other'
+
+/** A single request event captured by the analytics hook */
+export interface TrafficEvent {
+  /** Unix timestamp (ms) when the request started — Date.now() */
+  timestamp: number
+  /** URL pathname */
+  path: string
+  /** HTTP method (GET, POST, etc.) */
+  method: string
+  /** What was served */
+  format: AnalyticsResponseFormat
+  /** Classified caller type */
+  trafficType: TrafficType
+  /** HTTP status code of the response */
+  statusCode: number
+  /** End-to-end handler latency in milliseconds */
+  latencyMs: number
+  /** Raw User-Agent string */
+  userAgent: string
+  /** Response body size in bytes */
+  contentLength: number
+  /** Whether the response was served from cache */
+  cacheHit: boolean
+  /** Site identifier for multi-tenant deployments (e.g. mkdn.io). Undefined for single-site. */
+  siteId?: string
+}
+
+/**
+ * Pluggable traffic analytics backend.
+ *
+ * `logRequest` is fire-and-forget and must be synchronous (or fire async work
+ * without blocking the response). Implementations must never throw.
+ */
+export interface TrafficAnalytics {
+  logRequest: (event: TrafficEvent) => void
+}

package/src/cache/kv.ts

@@ -0,0 +1,81 @@
+import type { CachedResponse, ResponseCache } from './response.ts'
+import { MemoryResponseCache } from './memory.ts'
+
+const DEFAULT_TTL_SECONDS = 300
+
+/**
+ * Cloudflare KV type stubs (runtime types not available outside CF Workers).
+ * Matches the KVNamespace interface from @cloudflare/workers-types.
+ */
+export interface KVNamespace {
+  get: (key: string) => Promise<string | null>
+  put: (key: string, value: string, options?: { expirationTtl?: number }) => Promise<void>
+  delete: (key: string) => Promise<void>
+  list: (options?: { prefix?: string }) => Promise<{ keys: Array<{ name: string }> }>
+}
+
+/**
+ * Cloudflare KV-backed response cache with L1 in-memory hot path.
+ *
+ * L1 (MemoryResponseCache): fast path for repeated requests within same isolate.
+ * L2 (KV): shared durable storage across isolates / cold starts.
+ *
+ * KV key format: `{prefix}resp:{cacheKey}`
+ */
+export class KVResponseCache implements ResponseCache {
+  private readonly kv: KVNamespace
+  private readonly prefix: string
+  private readonly ttlSeconds: number
+  private readonly memory: MemoryResponseCache
+
+  constructor (kv: KVNamespace, options?: { prefix?: string, ttlSeconds?: number }) {
+    this.kv = kv
+    this.prefix = options?.prefix ?? 'resp:'
+    this.ttlSeconds = options?.ttlSeconds ?? DEFAULT_TTL_SECONDS
+    this.memory = new MemoryResponseCache(this.ttlSeconds)
+  }
+
+  async get (key: string): Promise<CachedResponse | null> {
+    // L1: in-memory
+    const memResult = await this.memory.get(key)
+    if (memResult != null) return memResult
+
+    // L2: KV
+    const raw = await this.kv.get(this.kvKey(key))
+    if (raw != null) {
+      try {
+        const cached = JSON.parse(raw) as CachedResponse
+        await this.memory.set(key, cached, this.ttlSeconds)
+        return cached
+      } catch {
+        return null
+      }
+    }
+    return null
+  }
+
+  async set (key: string, response: CachedResponse, ttlSeconds?: number): Promise<void> {
+    const ttl = ttlSeconds ?? this.ttlSeconds
+    await this.memory.set(key, response, ttl)
+    await this.kv.put(this.kvKey(key), JSON.stringify(response), { expirationTtl: ttl })
+  }
+
+  async delete (key: string): Promise<void> {
+    await this.memory.delete(key)
+    await this.kv.delete(this.kvKey(key))
+  }
+
+  async clear (): Promise<void> {
+    await this.memory.clear()
+    try {
+      const result = await this.kv.list({ prefix: this.prefix })
+      await Promise.all(result.keys.map(async k => await this.kv.delete(k.name)))
+    } catch {
+      // Best-effort — KV TTL handles expiry
+    }
+  }
+
+  private kvKey (key: string): string {
+    return this.prefix + key
+  }
+}

package/src/cache/memory.ts

@@ -0,0 +1,46 @@
+import type { CachedResponse, ResponseCache } from './response.ts'
+
+const DEFAULT_TTL_SECONDS = 300
+
+interface Entry {
+  response: CachedResponse
+  expiresAt: number
+}
+
+/**
+ * In-memory response cache with TTL eviction.
+ *
+ * Suitable for single-process deployments (local dev, Node/Deno/Bun servers).
+ * Does not share state across Worker isolates — use KVResponseCache for that.
+ */
+export class MemoryResponseCache implements ResponseCache {
+  private readonly store = new Map<string, Entry>()
+  private readonly defaultTtlSeconds: number
+
+  constructor (defaultTtlSeconds?: number) {
+    this.defaultTtlSeconds = defaultTtlSeconds ?? DEFAULT_TTL_SECONDS
+  }
+
+  async get (key: string): Promise<CachedResponse | null> {
+    const entry = this.store.get(key)
+    if (entry == null) return null
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key)
+      return null
+    }
+    return entry.response
+  }
+
+  async set (key: string, response: CachedResponse, ttlSeconds?: number): Promise<void> {
+    const ttl = (ttlSeconds ?? this.defaultTtlSeconds) * 1000
+    this.store.set(key, { response, expiresAt: Date.now() + ttl })
+  }
+
+  async delete (key: string): Promise<void> {
+    this.store.delete(key)
+  }
+
+  async clear (): Promise<void> {
+    this.store.clear()
+  }
+}