weifuwu 0.25.2 → 0.27.1

package/middleware/rate-limit.ts

@@ -0,0 +1,167 @@
+import type { Redis, Context, Handler, Middleware, Closeable } from '../types.ts'
+
+/** Options for {@link rateLimit}. */
+export interface RateLimitOptions {
+  /** Maximum requests within the window (default: 100). */
+  max?: number
+  /** Window duration in ms (default: 60000 = 1 minute). */
+  window?: number
+  /** Custom key function. Default: IP from `x-forwarded-for` or `x-real-ip` or `cf-connecting-ip`. */
+  key?: (req: Request, ctx: Context) => string
+  /** Custom 429 response body." */
+  message?: string
+  /** Store backend. `'memory'` (default) or `'redis'`. */
+  store?: 'memory' | 'redis'
+  /** Redis client (required when `store: 'redis'`). */
+  redis?: Redis
+  /** Redis key prefix (default: `'ratelimit:'`). */
+  prefix?: string
+}
+
+function defaultKey(_req: Request, _ctx: Context): string {
+  const forwarded = _req.headers.get('x-forwarded-for')
+  if (forwarded) return forwarded.split(',')[0]!.trim()
+  const realIp = _req.headers.get('x-real-ip')
+  if (realIp) return realIp
+  const cfIp = _req.headers.get('cf-connecting-ip')
+  if (cfIp) return cfIp
+  return 'global'
+}
+
+/** Rate limit module — middleware + stats. */
+export interface RateLimitModule extends Middleware<Context, Context>, Closeable {
+  stats(): { store: string; entries?: number; maxEntries: number }
+}
+
+/**
+ * Rate limiting middleware (in-memory or Redis-backed).
+ *
+ * Limits requests per key (default: client IP) within a rolling window.
+ * Returns 429 when the limit is exceeded, with `Retry-After` header.
+ *
+ * ```ts
+ * import { rateLimit } from 'weifuwu'
+ *
+ * // In-memory (single process)
+ * app.use(rateLimit({ max: 60, window: 60_000 }))
+ *
+ * // Redis-backed (multi-process)
+ * import { Redis } from 'ioredis'
+ * app.use(rateLimit({ store: 'redis', redis: new Redis(), max: 100 }))
+ * ```
+ */
+export function rateLimit(options?: RateLimitOptions): RateLimitModule {
+  const max = options?.max ?? 100
+  const window = options?.window ?? 60_000
+  const getKey = options?.key ?? defaultKey
+  const message = options?.message ?? 'Too Many Requests'
+  const storeType = options?.store ?? 'memory'
+
+  if (storeType === 'redis' && !options?.redis) {
+    throw new Error('rateLimit: redis client required when store: "redis"')
+  }
+
+  const redis = options?.redis ?? null
+  const keyPrefix = options?.prefix ?? 'ratelimit:'
+
+  // Memory store: in-memory counter map
+  const MAX_ENTRIES = 10000
+  const hits = new Map<string, { count: number; reset: number }>()
+
+  const interval =
+    storeType === 'memory'
+      ? setInterval(
+          () => {
+            const now = Date.now()
+            for (const [key, entry] of hits) {
+              if (entry.reset < now) hits.delete(key)
+            }
+            if (hits.size > MAX_ENTRIES) {
+              const toDelete = hits.size - MAX_ENTRIES
+              let deleted = 0
+              for (const key of hits.keys()) {
+                if (deleted >= toDelete) break
+                hits.delete(key)
+                deleted++
+              }
+            }
+          },
+          Math.min(window, 30000),
+        )
+      : null
+
+  if (interval?.unref) interval.unref()
+
+  // Shared rate check logic — dispatches to memory or redis
+  async function checkAndIncrement(key: string): Promise<{ count: number; reset: number }> {
+    const now = Date.now()
+
+    if (storeType === 'redis' && redis) {
+      const redisKey = `${keyPrefix}${key}`
+      const count = await redis.incr(redisKey)
+      if (count === 1) {
+        await redis.pexpire(redisKey, window)
+      }
+      const pttl = await redis.pttl(redisKey)
+      const reset = pttl > 0 ? now + pttl : now + window
+      return { count, reset }
+    }
+
+    // Memory store
+    const entry = hits.get(key)
+    if (!entry || entry.reset < now) {
+      hits.set(key, { count: 1, reset: now + window })
+      return { count: 1, reset: now + window }
+    }
+    entry.count++
+    return { count: entry.count, reset: entry.reset }
+  }
+
+  const mw = async (req: Request, ctx: Context, next: Handler) => {
+    const key = getKey(req, ctx)
+    const now = Date.now()
+
+    const { count, reset } = await checkAndIncrement(key)
+
+    if (count > max) {
+      return new Response(message, {
+        status: 429,
+        headers: {
+          'Retry-After': String(Math.ceil((reset - now) / 1000)),
+          'X-RateLimit-Limit': String(max),
+          'X-RateLimit-Remaining': '0',
+          'X-RateLimit-Reset': String(Math.ceil(reset / 1000)),
+        },
+      })
+    }
+
+    const remaining = max - count
+    const res = await next(req, ctx)
+    return addRateLimitHeaders(res, max, remaining, reset)
+  }
+
+  mw.__meta = { injects: [], depends: [] }
+  mw.close = async () => {
+    if (interval) clearInterval(interval)
+    hits.clear()
+  }
+  mw.stats = () => ({
+    store: storeType,
+    entries: storeType === 'memory' ? hits.size : undefined,
+    maxEntries: MAX_ENTRIES,
+  })
+  return mw
+}
+
+function addRateLimitHeaders(
+  res: Response,
+  limit: number,
+  remaining: number,
+  reset: number,
+): Response {
+  const headers = new Headers(res.headers)
+  headers.set('X-RateLimit-Limit', String(limit))
+  headers.set('X-RateLimit-Remaining', String(remaining))
+  headers.set('X-RateLimit-Reset', String(Math.ceil(reset / 1000)))
+  return new Response(res.body, { status: res.status, statusText: res.statusText, headers })
+}

package/middleware/request-id.ts

@@ -0,0 +1,60 @@
+import crypto from 'node:crypto'
+import type { Context, Middleware } from '../types.ts'
+
+// Augment Context with requestId property
+declare module '../types.ts' {
+  interface Context {
+    requestId: string
+  }
+}
+
+/** Options for {@link requestId}. */
+/** Request ID module — a {@link Middleware} that injects `ctx.requestId`. */
+export type RequestIdModule = Middleware<Context, Context & { requestId: string }>
+
+export interface RequestIdOptions {
+  /** Header name for request ID (default: `'X-Request-ID'`). */
+  header?: string
+  /** Custom ID generator (default: `crypto.randomUUID`). */
+  generator?: () => string
+}
+
+/**
+ * Request ID middleware.
+ *
+ * @deprecated Use `trace()` from 'weifuwu' instead — it injects `ctx.trace.requestId`
+ * along with `traceId` and `elapsed()` in a single middleware.
+ *
+ * ```ts
+ * // Old:
+ * app.use(requestId())
+ * ctx.requestId
+ *
+ * // New:
+ * app.use(trace())
+ * ctx.trace.requestId
+ * ```
+ *
+ * Reads an incoming `X-Request-ID` header (or custom header name) from the
+ * request. If absent, generates a new UUID. Sets the response header and
+ * injects `ctx.requestId`.
+ */
+export function requestId(
+  options?: RequestIdOptions,
+): Middleware<Context, Context & { requestId: string }> {
+  const header = options?.header ?? 'X-Request-ID'
+  const gen = options?.generator ?? (() => crypto.randomUUID())
+
+  const mw: Middleware<Context, Context & { requestId: string }> = async (req, ctx, next) => {
+    const existing = req.headers.get(header)
+    const id = existing ?? gen()
+    ;(ctx as unknown as { requestId: string }).requestId = id
+    const res = await next(req, ctx as Context & { requestId: string })
+    if (res.headers.has(header)) return res
+    const h = new Headers(res.headers)
+    h.set(header, id)
+    return new Response(res.body, { status: res.status, statusText: res.statusText, headers: h })
+  }
+  mw.__meta = { injects: ['requestId'], depends: [] }
+  return mw
+}

package/middleware/static.ts

@@ -0,0 +1,149 @@
+import { open, realpath, type FileHandle } from 'node:fs/promises'
+import { extname, resolve, normalize, sep } from 'node:path'
+import { Readable } from 'node:stream'
+import type { Handler } from '../types.ts'
+
+/** Options for {@link serveStatic}. */
+export interface ServeStaticOptions {
+  /** Directory index filename (default: `'index.html'`). */
+  index?: string
+  /** `Cache-Control max-age` in seconds. */
+  maxAge?: number
+  /** Add `immutable` to `Cache-Control` (requires `maxAge`). */
+  immutable?: boolean
+}
+
+/**
+ * Static file serving handler.
+ *
+ * Serves files from a root directory. Supports ETag/304, directory index,
+ * Content-Type detection by extension, and directory traversal protection.
+ *
+ * ```ts
+ * import { serveStatic, Router } from 'weifuwu'
+ * const app = new Router()
+ * app.get('/static/*', serveStatic('./public'))
+ * ```
+ */
+export function serveStatic(root: string, options?: ServeStaticOptions): Handler {
+  const rootDir = resolve(root)
+
+  const opts = options ?? {}
+
+  return async (req, ctx) => {
+    const relativePath = ctx.params['*'] ?? new URL(req.url).pathname.slice(1)
+    const decoded = decodeURIComponent(relativePath)
+
+    if (decoded.includes('..') || decoded.includes('\0')) {
+      return new Response('Forbidden', { status: 403 })
+    }
+
+    let filePath = normalize(resolve(rootDir, decoded))
+    if (!filePath.startsWith(rootDir + sep) && filePath !== rootDir) {
+      return new Response('Forbidden', { status: 403 })
+    }
+
+    let fileHandle: FileHandle | undefined
+    try {
+      fileHandle = await open(filePath, 'r')
+      let stat = await fileHandle.stat()
+
+      // Resolve symlinks and verify within root
+      const realPath = await realpath(filePath)
+      if (!realPath.startsWith(rootDir + sep) && realPath !== rootDir) {
+        await fileHandle.close()
+        return new Response('Forbidden', { status: 403 })
+      }
+
+      if (stat.isDirectory()) {
+        await fileHandle.close()
+        const indexFile = opts.index ?? 'index.html'
+        filePath = resolve(filePath, indexFile)
+        if (!filePath.startsWith(rootDir + sep)) {
+          return new Response('Forbidden', { status: 403 })
+        }
+        fileHandle = await open(filePath, 'r')
+        stat = await fileHandle.stat()
+        if (!stat.isFile()) {
+          await fileHandle.close()
+          return new Response('Not Found', { status: 404 })
+        }
+      }
+
+      const mimeType = MIME_TYPES[extname(filePath).toLowerCase()] ?? 'application/octet-stream'
+
+      const etag = `"${stat.ino}-${stat.size}-${stat.mtimeMs}"`
+      const ifNoneMatch = req.headers.get('if-none-match')
+      if (ifNoneMatch === etag) {
+        await fileHandle.close()
+        return new Response(null, { status: 304 })
+      }
+
+      const ifModifiedSince = req.headers.get('if-modified-since')
+      if (ifModifiedSince && stat.mtimeMs <= new Date(ifModifiedSince).getTime()) {
+        await fileHandle.close()
+        return new Response(null, { status: 304 })
+      }
+
+      const headers: Record<string, string> = {
+        'Content-Type': mimeType,
+        'Content-Length': String(stat.size),
+        ETag: etag,
+        'Last-Modified': stat.mtime.toUTCString(),
+        'Cache-Control': opts.immutable
+          ? `public, max-age=${opts.maxAge ?? 31536000}, immutable`
+          : `public, max-age=${opts.maxAge ?? 0}`,
+      }
+
+      const readStream = fileHandle!.createReadStream()
+      const cleanup = () => fileHandle!.close().catch(() => {})
+      readStream.on('close', cleanup)
+      readStream.on('error', cleanup)
+      const webStream = Readable.toWeb(readStream)
+      return new Response(webStream as unknown as ReadableStream, { headers })
+    } catch (err) {
+      if (fileHandle) await fileHandle.close().catch(() => {})
+      if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') {
+        return new Response('Not Found', { status: 404 })
+      }
+      return new Response('Internal Server Error', { status: 500 })
+    }
+  }
+}
+
+const MIME_TYPES: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.htm': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.eot': 'application/vnd.ms-fontobject',
+  '.txt': 'text/plain; charset=utf-8',
+  '.xml': 'application/xml',
+  '.pdf': 'application/pdf',
+  '.zip': 'application/zip',
+  '.wasm': 'application/wasm',
+  '.map': 'application/json',
+  '.ts': 'application/x-typescript',
+  '.tsx': 'application/x-typescript',
+  '.md': 'text/markdown; charset=utf-8',
+  '.yaml': 'application/x-yaml',
+  '.yml': 'application/x-yaml',
+  '.csv': 'text/csv; charset=utf-8',
+  '.mp4': 'video/mp4',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+}

package/middleware/theme.ts

@@ -0,0 +1,84 @@
+import type { Context, Middleware } from '../types.ts'
+import { getCookies } from '../core/cookie.ts'
+import { Router } from '../core/router.ts'
+
+// Augment Context with theme property
+declare module '../types.ts' {
+  interface Context {
+    theme: ThemeInjected
+  }
+}
+
+export interface ThemeInjected {
+  value: string
+  set: (value: string, loc?: string) => Response
+}
+
+export interface ThemeOptions {
+  /** Default theme value (default: 'system'). */
+  default?: string
+  /** Cookie name (default: 'theme'). Set to empty string to disable cookie. */
+  cookie?: string
+}
+
+function makeSetTheme(cookie: string, location: string) {
+  return (value: string, loc?: string) => {
+    const finalLoc = loc ?? location
+    const c = `${cookie}=${encodeURIComponent(value)}; Path=/; SameSite=Lax`
+    return new Response(null, { status: 302, headers: { Location: finalLoc, 'Set-Cookie': c } })
+  }
+}
+
+/**
+ * Theme module. Returns a Router with an attached `.middleware()` method.
+ *
+ * ```ts
+ * const t = theme()
+ * app.use(t.middleware())  // → ctx.theme = { value, set }
+ * app.use('/', t)          // → GET /__theme/dark (switch route)
+ * ```
+ */
+export interface ThemeModule extends Router {
+  /** Middleware that injects `ctx.theme = { value, set }`. */
+  middleware: () => Middleware<Context, Context & ThemeInjected>
+}
+
+export function theme(options?: ThemeOptions): ThemeModule {
+  const opts = { default: 'system', cookie: 'theme', ...options }
+
+  const mw: Middleware<Context, Context & ThemeInjected> = async (req, ctx, next) => {
+    let themeValue = opts.default
+    if (opts.cookie) {
+      const fromCookie = getCookies(req)[opts.cookie]
+      if (fromCookie) themeValue = fromCookie
+    }
+
+    ;(ctx as Context & ThemeInjected).theme = {
+      value: themeValue,
+      set: makeSetTheme(opts.cookie, req.headers.get('referer') || '/'),
+    }
+    return next(req, ctx as Context & ThemeInjected)
+  }
+  mw.__meta = { injects: ['theme'], depends: [] }
+
+  class ThemeRouter extends Router {
+    middleware() {
+      return mw
+    }
+  }
+
+  const router = new ThemeRouter()
+  router.get('/__theme/:value', (req) => {
+    const url = new URL(req.url)
+    const value = url.pathname.split('/__theme/')[1] ?? ''
+    const cookie = `${opts.cookie}=${encodeURIComponent(value)}; Path=/; SameSite=Lax`
+    const accept = req.headers.get('accept') ?? ''
+    if (accept.includes('application/json')) {
+      return Response.json({ ok: true, theme: value }, { headers: { 'Set-Cookie': cookie } })
+    }
+    const referer = req.headers.get('referer') || '/'
+    return new Response(null, { status: 302, headers: { Location: referer, 'Set-Cookie': cookie } })
+  })
+
+  return router
+}

package/middleware/upload.ts

@@ -0,0 +1,168 @@
+/* eslint-disable no-console */
+import { writeFile, mkdir } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import { join, extname } from 'node:path'
+import type { Context, Middleware } from '../types.ts'
+
+// Augment Context with parsed property (shared with validate)
+declare module '../types.ts' {
+  interface Context {
+    parsed: Record<string, unknown>
+  }
+}
+
+/** Upload middleware — a {@link Middleware} that injects `ctx.parsed` with file fields. */
+export type UploadModule = Middleware<Context, Context & { parsed: Record<string, unknown> }>
+
+/** A parsed file from a multipart upload. */
+export interface UploadedFile {
+  /** Original filename from the client. */
+  name: string
+  /** MIME type from the `Content-Type` part header. */
+  type: string
+  /** File size in bytes. */
+  size: number
+  /** Path where the file was saved (when `dir` option is set). */
+  path?: string
+  /** File content as Buffer (when `dir` option is not set). */
+  buffer?: Buffer
+}
+
+/** Options for {@link upload}. */
+export interface UploadOptions {
+  /** Directory to save uploaded files. If not set, files stay in memory via `.buffer`. */
+  dir?: string
+  /** Maximum file size in bytes. Default: 10 MB. Set `0` to allow unlimited. */
+  maxFileSize?: number
+  /** Allowed MIME types (e.g. `['image/jpeg', 'image/png']`). Empty array allows all. */
+  allowedTypes?: string[]
+}
+
+const extensionMimeMap: Record<string, string> = {
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.png': 'image/png',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml',
+  '.pdf': 'application/pdf',
+  '.doc': 'application/msword',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.xls': 'application/vnd.ms-excel',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  '.zip': 'application/zip',
+  '.gz': 'application/gzip',
+  '.mp4': 'video/mp4',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+  '.json': 'application/json',
+  '.csv': 'text/csv',
+  '.txt': 'text/plain',
+  '.html': 'text/html',
+  '.css': 'text/css',
+  '.js': 'text/javascript',
+  '.ts': 'application/x-typescript',
+  '.tsx': 'application/x-typescript',
+}
+
+function detectMimeFromExtension(filename: string): string | undefined {
+  return extensionMimeMap[extname(filename).toLowerCase()]
+}
+
+/**
+ * Multipart file upload middleware.
+ *
+ * Parses `multipart/form-data` requests, extracting files and fields.
+ * Files can be saved to disk (`dir` option) or kept in memory as Buffers.
+ * Parsed fields are available in `ctx.parsed`.
+ *
+ * ```ts
+ * import { upload } from 'weifuwu'
+ *
+ * // Save to disk
+ * app.use(upload({ dir: './uploads', maxFileSize: 5_000_000 }))
+ *
+ * // In-memory
+ * app.post('/upload', async (req, ctx) => {
+ *   const file = ctx.parsed?.file as UploadedFile
+ *   console.log(file.name, file.type, file.buffer!.length)
+ * })
+ * ```
+ */
+export function upload(
+  options?: UploadOptions,
+): Middleware<Context, Context & { parsed: Record<string, unknown> }> {
+  const saveDir = options?.dir
+
+  const mw: Middleware<Context, Context & { parsed: Record<string, unknown> }> = async (
+    req,
+    ctx,
+    next,
+  ) => {
+    const ct = req.headers.get('content-type') ?? ''
+    if (!ct.includes('multipart/form-data')) return next(req, ctx)
+    try {
+      if (saveDir) await mkdir(saveDir, { recursive: true })
+    } catch (e) {
+      console.error('upload: failed to create directory', saveDir, e)
+      return Response.json({ error: 'Server configuration error' }, { status: 500 })
+    }
+
+    let formData: FormData
+    try {
+      formData = await req.formData()
+    } catch {
+      return Response.json({ error: 'Invalid multipart data' }, { status: 400 })
+    }
+
+    const files: Record<string, UploadedFile | UploadedFile[]> = {}
+    const fields: Record<string, string> = {}
+
+    for (const [key, value] of formData) {
+      if (value instanceof File) {
+        // Validate: check client-declared type AND extension-based type
+        if (options?.allowedTypes) {
+          const clientOk = options.allowedTypes.includes(value.type)
+          const extType = detectMimeFromExtension(value.name)
+          const extOk = extType ? options.allowedTypes.includes(extType) : false
+          if (!clientOk && !extOk) {
+            return Response.json({ error: `File type not allowed: ${value.type}` }, { status: 415 })
+          }
+        }
+        if (options?.maxFileSize && value.size > options.maxFileSize) {
+          return Response.json({ error: `File too large: ${value.name}` }, { status: 413 })
+        }
+
+        const buf = Buffer.from(await value.arrayBuffer())
+
+        const uf: UploadedFile = {
+          name: value.name,
+          type: value.type,
+          size: buf.byteLength,
+          buffer: saveDir ? undefined : buf,
+        }
+
+        if (saveDir) {
+          const safeName = value.name.replace(/[/\\\0]/g, '_').replace(/\.\./g, '_')
+          const filePath = join(saveDir, `${randomUUID()}-${safeName}`)
+          await writeFile(filePath, buf)
+          uf.path = filePath
+        }
+
+        if (files[key]) {
+          const existing = files[key]
+          files[key] = Array.isArray(existing) ? [...existing, uf] : [existing, uf]
+        } else {
+          files[key] = uf
+        }
+      } else {
+        fields[key] = value
+      }
+    }
+
+    ctx.parsed = { ...ctx.parsed, files, fields }
+    return next(req, ctx)
+  }
+  mw.__meta = { injects: ['parsed'], depends: [] }
+  return mw
+}