weifuwu 0.1.0

package/AGENTS.md

@@ -0,0 +1,47 @@
+This is the weifuwu HTTP framework — pure Node.js, no build step.
+
+## Commands
+
+- `node --test` — run all tests
+- `npm install` — install dependencies
+- `npx tsc --noEmit` — type-check without emitting
+
+## TypeScript rules
+
+- All imports must use explicit `.ts` extensions (e.g. `import { x } from './foo.ts'`)
+- Node.js v26+ supports TypeScript natively with `--experimental-strip-types`
+- No `tsc` compiler needed for runtime (native TS via Node.js)
+
+## Code conventions
+
+- Read the full file before editing — context matters
+- Follow existing patterns: `Handler = (req, ctx) => Response | Promise<Response>`
+- All middleware returns a `Middleware` — `(req, ctx, next) => Response | Promise<Response>`
+- Import types from `./types.ts`, source from individual files
+- New modules get their own file, exported from `index.ts`
+- Every module needs tests in `test/`
+- All `ctx` mutations (like `ctx.parsed` or `ctx.user`) should be additive, never overwrite
+
+## Dependencies
+
+- `ws` for WebSocket server
+- `graphql` + `@graphql-tools/schema` for GraphQL
+- `ai` (Vercel AI SDK) for AI streaming
+- `zod` for request validation
+- Node.js built-in `WebSocket` for WebSocket clients
+- Node.js built-in `zlib` for response compression
+
+## Testing
+
+```ts#test/example.test.ts
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+describe('example', () => {
+  it('works', () => {
+    assert.equal(1 + 1, 2)
+  })
+})
+```
+
+Tests live in `test/` and follow the pattern: create a `Router`, call `r.handler()(request, ctx)`, assert on the response. For end-to-end tests, use `serve()`.

package/README.md

@@ -0,0 +1,316 @@
+# weifuwu
+
+**Web-standard HTTP framework for Node.js.** `(req, ctx) => Response` — no framework-specific objects, just the Web API your browser already speaks.
+
+## Features
+
+- **Web Standard** — `Request` / `Response` / `ReadableStream`, zero abstractions
+- **Trie router** — static > param > wildcard, sub-router mounting, path params
+- **Middleware** — global, path-scoped, route-level — onion model, short-circuit
+- **Built-in middleware** — `auth()`, `cors()`, `logger()`, `rateLimit()`, `compress()`
+- **WebSocket** — `router.ws()` with upgrade middleware (auth before connect)
+- **GraphQL** — `router.graphql()` with GraphiQL IDE
+- **AI streaming** — `router.ai()` via Vercel AI SDK
+- **Static files** — `serveStatic()` with ETag, 304, MIME, directory index
+- **Request validation** — `validate()` with Zod (body / query / params / headers)
+- **File upload** — `upload()` multipart parser with disk save, size & type limits
+- **Cookie** — `getCookies()`, `setCookie()`, `deleteCookie()` — immutable
+- **Error handling** — global `onError()`
+- **Zero build** — native TypeScript in Node.js v24+
+- **Zero deps** (core) — only `node:http` and `node:stream`
+
+## Quick start
+
+```ts
+import { serve } from 'weifuwu'
+
+serve((req, ctx) => new Response('Hello, World!'), { port: 3000 })
+```
+
+## Router
+
+```ts
+import { serve, Router } from 'weifuwu'
+
+const app = new Router()
+  .use((req, ctx, next) => {
+    console.log(`${req.method} ${new URL(req.url).pathname}`)
+    return next(req, ctx)
+  })
+  .get('/hello/:name', (req, ctx) =>
+    Response.json({ message: `Hello, ${ctx.params.name}!` }),
+  )
+  .post('/data', async (req, ctx) => {
+    const body = await req.json()
+    return Response.json(body, { status: 201 })
+  })
+
+serve(app.handler(), { port: 3000 })
+```
+
+## Built-in middleware
+
+### Auth
+
+```ts
+import { auth } from 'weifuwu'
+
+// Static bearer token
+app.use(auth({ token: 'sk-123' }))
+
+// Custom verify (JWT, DB, etc.) — return object to set ctx.user
+app.use(auth({
+  verify: async (token) => {
+    const user = await db.findUserByToken(token)
+    return user ? { sub: user.id, role: user.role } : null
+  },
+}))
+
+// Proxy validation to external auth service
+app.get('/protected', auth({ proxy: 'http://auth:3000/validate' }), handler)
+
+// Custom header
+app.use(auth({ header: 'X-API-Key', token: 'my-key' }))
+```
+
+### CORS
+
+```ts
+import { cors } from 'weifuwu'
+
+app.use(cors())                                          // allow all
+app.use(cors({ origin: ['https://example.com'] }))       // whitelist
+app.use(cors({ origin: (o) => o.endsWith('.trusted.com') ? o : false }))
+app.use(cors({ credentials: true, maxAge: 3600 }))
+```
+
+### Logger
+
+```ts
+import { logger } from 'weifuwu'
+
+app.use(logger())                           // GET /hello 200 5ms
+app.use(logger({ format: 'combined' }))     // with query params
+```
+
+### Rate limit
+
+```ts
+import { rateLimit } from 'weifuwu'
+
+app.use(rateLimit({ max: 100, window: 60_000 }))          // 100 req/min
+app.get('/api', rateLimit({ max: 10 }), handler)          // per-route
+
+// Custom key (by API key, user ID, etc.)
+app.use(rateLimit({
+  max: 1000,
+  key: (req) => req.headers.get('x-api-key') ?? 'anonymous',
+}))
+```
+
+### Compression
+
+```ts
+import { compress } from 'weifuwu'
+
+app.use(compress())                       // brotli > gzip > deflate
+app.use(compress({ threshold: 2048 }))    // only compress > 2KB
+```
+
+## Static files
+
+```ts
+import { serveStatic } from 'weifuwu'
+
+router.get('/static/*', serveStatic('./public'))
+```
+
+Features: MIME type detection (20+ types), ETag + If-None-Match (304), directory index (index.html), path traversal protection, Cache-Control.
+
+## Validation
+
+```ts
+import { z } from 'zod'
+import { validate } from 'weifuwu'
+
+const CreateUser = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+})
+
+router.post('/users',
+  validate({ body: CreateUser }),
+  (req, ctx) => {
+    // ctx.parsed.body — typed & validated
+  },
+)
+
+// Validate multiple dimensions at once
+router.post('/data',
+  validate({
+    body: z.object({ value: z.number() }),
+    query: z.object({ token: z.string() }),
+    params: z.object({ id: z.string().length(24) }),
+  }),
+  handler,
+)
+```
+
+## File upload
+
+```ts
+import { upload } from 'weifuwu'
+
+router.post('/upload',
+  upload({ dir: './uploads', maxFileSize: 10_485_760 }),
+  (req, ctx) => {
+    // ctx.parsed.files.avatar  → { name, type, size, path }
+    // ctx.parsed.fields.title  → 'hello'
+  },
+)
+```
+
+## Cookie
+
+```ts
+import { getCookies, setCookie, deleteCookie } from 'weifuwu'
+
+// Read
+const cookies = getCookies(req)        // { session: 'abc' }
+
+// Set (immutable — returns new Response)
+let res = new Response('ok')
+res = setCookie(res, 'session', 'token', { httpOnly: true, secure: true, maxAge: 3600 })
+
+// Delete
+res = deleteCookie(res, 'session')
+```
+
+## WebSocket
+
+```ts
+const app = new Router()
+  .ws('/chat/:room', {
+    open(ws, ctx) {
+      ws.send(`Connected to room: ${ctx.params.room}`)
+    },
+    message(ws, ctx, data) {
+      ws.send(`echo: ${data}`)
+    },
+    close(ws, ctx) {
+      console.log('disconnected')
+    },
+  })
+
+serve(app.handler(), { port: 3000, websocket: app.websocketHandler() })
+```
+
+Middleware runs **before** WebSocket upgrade — you can reject connections with HTTP status codes:
+
+```ts
+app.ws('/secure',
+  (req, _ctx, next) => {
+    const auth = req.headers.get('Authorization')
+    if (!auth) return Response.json({ error: 'Unauthorized' }, { status: 401 })
+    return next(req, _ctx)
+  },
+  { open(ws) { ws.send('authorized') } },
+)
+```
+
+## GraphQL
+
+```ts
+const app = new Router()
+  .graphql('/graphql', {
+    schema: `
+      type Query { hello: String }
+      type Mutation { setMessage(msg: String!): String }
+    `,
+    resolvers: {
+      Query: { hello: () => 'world' },
+      Mutation: { setMessage: (_, { msg }) => msg },
+    },
+    graphiql: true,
+  })
+
+serve(app.handler(), { port: 3000 })
+```
+
+## AI streaming
+
+```ts
+import { openai } from '@ai-sdk/openai'
+
+const app = new Router()
+  .ai('/chat', async (req) => {
+    const { messages } = await req.json()
+    return {
+      model: openai('gpt-4o'),
+      messages,
+    }
+  })
+
+serve(app.handler(), { port: 3000 })
+```
+
+## Error handling
+
+```ts
+const app = new Router()
+  .onError((err, req, ctx) =>
+    Response.json({ error: err.message }, { status: 500 }),
+  )
+  .get('/crash', () => { throw new Error('boom') })
+```
+
+## API
+
+### `serve(handler, options?)`
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `port` | `0` | Listen port (`0` = random) |
+| `hostname` | `'0.0.0.0'` | Bind address |
+| `signal` | — | `AbortSignal` for graceful shutdown |
+| `websocket` | — | Upgrade handler from `router.websocketHandler()` |
+
+Returns `{ stop, port, hostname, ready }`.
+
+### `Router`
+
+| Method | Description |
+|--------|-------------|
+| `get/post/put/delete/patch/head/options/all(path, ...mws, handler)` | Route registration |
+| `use(mw)` / `use(path, mw)` / `use(path, subRouter)` | Middleware / sub-router |
+| `ws(path, ...mws, handler)` | WebSocket route |
+| `graphql(path, ...mws, options)` | GraphQL endpoint |
+| `ai(path, ...mws, handler)` | AI streaming |
+| `onError(handler)` | Global error handler |
+| `handler()` | Returns `(req, ctx) => Response` for `serve()` |
+| `websocketHandler()` | Returns upgrade handler for `serve({ websocket })` |
+
+### Built-in middleware
+
+| Function | Description |
+|----------|-------------|
+| `auth(options)` | Bearer token / custom header / verify / proxy |
+| `cors(options?)` | CORS with preflight, origin whitelist, credentials |
+| `logger(options?)` | Request logging with duration |
+| `rateLimit(options?)` | In-memory rate limiting with headers |
+| `compress(options?)` | Brotli / Gzip / Deflate compression |
+
+### Utilities
+
+| Function | Description |
+|----------|-------------|
+| `serveStatic(root, options?)` | Static file serving handler |
+| `validate(schemas)` | Zod validation middleware |
+| `upload(options?)` | Multipart file upload middleware |
+| `getCookies(req)` | Parse Cookie header → object |
+| `setCookie(res, name, value, options?)` | Set cookie (returns new Response) |
+| `deleteCookie(res, name)` | Delete cookie (returns new Response) |
+
+## License
+
+MIT

package/compress.ts

@@ -0,0 +1,69 @@
+import { gzipSync, brotliCompressSync, constants } from 'node:zlib'
+import type { Middleware } from './types.ts'
+
+export interface CompressOptions {
+  level?: number
+  threshold?: number
+}
+
+export function compress(options?: CompressOptions): Middleware {
+  const level = options?.level ?? 6
+  const threshold = options?.threshold ?? 1024
+
+  return async (req, ctx, next) => {
+    const accept = req.headers.get('accept-encoding') ?? ''
+
+    const useBrotli = accept.includes('br')
+    const useGzip = !useBrotli && accept.includes('gzip')
+    const useDeflate = !useBrotli && !useGzip && accept.includes('deflate')
+
+    if (!useBrotli && !useGzip && !useDeflate) {
+      return next(req, ctx)
+    }
+
+    const res = await next(req, ctx)
+
+    if (res.status === 304 || res.status === 204 || res.status < 200 || res.status >= 300) {
+      return res
+    }
+
+    const ce = res.headers.get('content-encoding')
+    if (ce) return res
+
+    const ct = res.headers.get('content-type') ?? ''
+    if (!ct || ct.startsWith('audio/') || ct.startsWith('video/') || ct.startsWith('image/') || ct === 'application/zip') {
+      return res
+    }
+
+    const body = await res.bytes()
+    if (body.byteLength < threshold) return res
+
+    let compressed: Buffer
+    let encoding: string
+
+    if (useBrotli) {
+      compressed = brotliCompressSync(body, {
+        params: { [constants.BROTLI_PARAM_QUALITY]: Math.min(level, 11) },
+      })
+      encoding = 'br'
+    } else if (useGzip) {
+      compressed = gzipSync(body, { level: Math.min(level, 9) })
+      encoding = 'gzip'
+    } else {
+      compressed = gzipSync(body, { level: Math.min(level, 9) })
+      encoding = 'deflate'
+    }
+
+    const headers = new Headers(res.headers)
+    headers.set('Content-Encoding', encoding)
+    headers.set('Content-Length', String(compressed.byteLength))
+    headers.delete('Content-Range')
+    headers.set('Vary', 'Accept-Encoding')
+
+    return new Response(compressed, {
+      status: res.status,
+      statusText: res.statusText,
+      headers,
+    })
+  }
+}

package/cookie.ts

@@ -0,0 +1,58 @@
+export interface CookieOptions {
+  domain?: string
+  path?: string
+  maxAge?: number
+  expires?: Date
+  httpOnly?: boolean
+  secure?: boolean
+  sameSite?: 'strict' | 'lax' | 'none'
+}
+
+export function getCookies(req: Request): Record<string, string> {
+  const header = req.headers.get('cookie')
+  if (!header) return {}
+
+  const cookies: Record<string, string> = {}
+  for (const pair of header.split(';')) {
+    const idx = pair.indexOf('=')
+    if (idx === -1) continue
+    const name = pair.slice(0, idx).trim()
+    const value = pair.slice(idx + 1).trim()
+    if (name) {
+      cookies[name] = decodeURIComponent(value)
+    }
+  }
+  return cookies
+}
+
+function serializeCookie(name: string, value: string, options?: CookieOptions): string {
+  const parts = [`${encodeURIComponent(name)}=${encodeURIComponent(value)}`]
+  if (options?.maxAge != null) parts.push(`Max-Age=${options.maxAge}`)
+  if (options?.expires) parts.push(`Expires=${options.expires.toUTCString()}`)
+  if (options?.domain) parts.push(`Domain=${options.domain}`)
+  if (options?.path) parts.push(`Path=${options.path}`)
+  if (options?.httpOnly) parts.push('HttpOnly')
+  if (options?.secure) parts.push('Secure')
+  if (options?.sameSite) parts.push(`SameSite=${options.sameSite}`)
+  return parts.join('; ')
+}
+
+export function setCookie(res: Response, name: string, value: string, options?: CookieOptions): Response {
+  const headers = new Headers(res.headers)
+  headers.append('Set-Cookie', serializeCookie(name, value, options))
+  return new Response(res.body, {
+    status: res.status,
+    statusText: res.statusText,
+    headers,
+  })
+}
+
+export function deleteCookie(res: Response, name: string, options?: Omit<CookieOptions, 'maxAge'>): Response {
+  const headers = new Headers(res.headers)
+  headers.append('Set-Cookie', serializeCookie(name, '', { ...options, maxAge: 0 }))
+  return new Response(res.body, {
+    status: res.status,
+    statusText: res.statusText,
+    headers,
+  })
+}

package/index.ts

@@ -0,0 +1,19 @@
+export type { Context, Handler, Middleware, ErrorHandler } from './types.ts'
+export { serve } from './serve.ts'
+export type { ServeOptions, Server } from './serve.ts'
+export { Router } from './router.ts'
+export type { WebSocketHandler, GraphQLOptions, AIHandler } from './router.ts'
+export { auth, cors, logger } from './middleware.ts'
+export type { AuthOptions, CORSOptions, LoggerOptions } from './middleware.ts'
+export { serveStatic } from './static.ts'
+export type { ServeStaticOptions } from './static.ts'
+export { validate } from './validate.ts'
+export type { ValidationSchemas } from './validate.ts'
+export { getCookies, setCookie, deleteCookie } from './cookie.ts'
+export type { CookieOptions } from './cookie.ts'
+export { upload } from './upload.ts'
+export type { UploadOptions, UploadedFile } from './upload.ts'
+export { rateLimit } from './rate-limit.ts'
+export type { RateLimitOptions } from './rate-limit.ts'
+export { compress } from './compress.ts'
+export type { CompressOptions } from './compress.ts'

package/middleware.ts

@@ -0,0 +1,178 @@
+import type { Middleware } from './types.ts'
+
+// ── Logger ────────────────────────────────────────────────────────────────────
+
+export interface LoggerOptions {
+  format?: 'short' | 'combined'
+}
+
+export function logger(options?: LoggerOptions): Middleware {
+  return async (req, ctx, next) => {
+    const start = Date.now()
+    const url = new URL(req.url)
+    const res = await next(req, ctx)
+    const ms = Date.now() - start
+
+    if (options?.format === 'combined') {
+      console.log(`${req.method} ${url.pathname}${url.search} ${res.status} ${ms}ms`)
+    } else {
+      console.log(`${req.method} ${url.pathname} ${res.status} ${ms}ms`)
+    }
+
+    return res
+  }
+}
+
+// ── CORS ──────────────────────────────────────────────────────────────────────
+
+export interface CORSOptions {
+  origin?: string | string[] | ((origin: string) => string | boolean | undefined)
+  methods?: string[]
+  allowedHeaders?: string[]
+  exposedHeaders?: string[]
+  credentials?: boolean
+  maxAge?: number
+}
+
+export function cors(options?: CORSOptions): Middleware {
+  const opts: Required<Pick<CORSOptions, 'origin' | 'methods' | 'allowedHeaders'>> & CORSOptions = {
+    origin: '*',
+    methods: ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE'],
+    allowedHeaders: ['Content-Type', 'Authorization'],
+    ...options,
+  }
+
+  function resolveOrigin(requestOrigin: string): string {
+    if (typeof opts.origin === 'string') return opts.origin === '*' ? '*' : opts.origin
+    if (Array.isArray(opts.origin)) {
+      return opts.origin.includes(requestOrigin) ? requestOrigin : ''
+    }
+    const result = opts.origin(requestOrigin)
+    if (typeof result === 'boolean') return result ? requestOrigin : ''
+    if (typeof result === 'string') return result
+    return ''
+  }
+
+  function setCORSHeaders(res: Response, acao: string): Response {
+    if (!acao) return res
+    const headers = new Headers(res.headers)
+    headers.set('Access-Control-Allow-Origin', acao)
+    if (opts.credentials) headers.set('Access-Control-Allow-Credentials', 'true')
+    if (opts.exposedHeaders?.length) headers.set('Access-Control-Expose-Headers', opts.exposedHeaders.join(', '))
+    headers.set('Vary', 'Origin')
+    return new Response(res.body, { status: res.status, statusText: res.statusText, headers })
+  }
+
+  return (req, ctx, next) => {
+    const requestOrigin = req.headers.get('origin') ?? ''
+    const acao = resolveOrigin(requestOrigin)
+
+    if (req.method === 'OPTIONS' && acao) {
+      const headers = new Headers()
+      headers.set('Access-Control-Allow-Origin', acao)
+      headers.set('Access-Control-Allow-Methods', opts.methods.join(', '))
+      headers.set('Access-Control-Allow-Headers', opts.allowedHeaders.join(', '))
+      if (opts.credentials) headers.set('Access-Control-Allow-Credentials', 'true')
+      if (opts.maxAge != null) headers.set('Access-Control-Max-Age', String(opts.maxAge))
+      headers.set('Vary', 'Origin')
+      return new Response(null, { status: 204, headers })
+    }
+
+    if (!acao) return next(req, ctx)
+
+    return Promise.resolve(next(req, ctx)).then((res) => setCORSHeaders(res, acao))
+  }
+}
+
+// ── Auth ───────────────────────────────────────────────────────────────────────
+
+export interface AuthOptions {
+  token?: string
+  verify?: (token: string, req: Request) => unknown | Promise<unknown>
+  proxy?: string | URL
+  header?: string
+}
+
+export function auth(options: AuthOptions): Middleware {
+  return async (req, ctx, next) => {
+    const headerName = options.header ?? 'Authorization'
+    const header = req.headers.get(headerName)
+
+    if (!header) {
+      return new Response('Unauthorized', {
+        status: 401,
+        headers: headerName.toLowerCase() === 'authorization'
+          ? { 'WWW-Authenticate': 'Bearer' }
+          : undefined,
+      })
+    }
+
+    let token = header
+    if (headerName.toLowerCase() === 'authorization') {
+      const parts = header.split(' ')
+      if (parts[0]?.toLowerCase() === 'bearer') {
+        token = parts.slice(1).join(' ')
+      }
+    }
+
+    // ── Proxy mode ──────────────────────────────────────────────────────────
+    if (options.proxy) {
+      const proxyUrl = typeof options.proxy === 'string'
+        ? new URL(options.proxy)
+        : options.proxy
+
+      const proxyHeaders: Record<string, string> = {}
+
+      if (headerName.toLowerCase() === 'authorization') {
+        proxyHeaders['Authorization'] = header
+      } else {
+        proxyUrl.searchParams.set('access_token', token)
+      }
+
+      for (const name of ['x-forwarded-for', 'x-real-ip', 'user-agent', 'content-type']) {
+        const v = req.headers.get(name)
+        if (v) proxyHeaders[name] = v
+      }
+
+      const proxyRes = await fetch(proxyUrl.href, { headers: proxyHeaders })
+
+      if (proxyRes.status >= 400) {
+        return new Response(await proxyRes.text() || 'Forbidden', { status: proxyRes.status })
+      }
+
+      let userData: unknown = undefined
+      if (proxyRes.status === 200) {
+        const ct = proxyRes.headers.get('content-type')
+        if (ct?.includes('application/json')) {
+          try { userData = await proxyRes.json() } catch {}
+        }
+      }
+
+      ctx.user = userData
+      return next(req, ctx)
+    }
+
+    // ── Static token mode ───────────────────────────────────────────────────
+    if (options.token) {
+      if (token !== options.token) {
+        return new Response('Forbidden', { status: 403 })
+      }
+      return next(req, ctx)
+    }
+
+    // ── Verify mode ─────────────────────────────────────────────────────────
+    if (options.verify) {
+      const result = await options.verify(token, req)
+      if (!result) {
+        return new Response('Forbidden', { status: 403 })
+      }
+      if (typeof result === 'object' && result !== null) {
+        ctx.user = result
+      }
+      return next(req, ctx)
+    }
+
+    // ── Trust any token (no validation configured) ─────────────────────────
+    return next(req, ctx)
+  }
+}