weifuwu 0.19.10 → 0.22.0

package/README.md

@@ -25,6 +25,17 @@ serve(app.handler(), { port: 3000, websocket: app.websocketHandler() })
 npx weifuwu init my-app && cd my-app && npm run dev
 ```
 
+## CLI
+
+```bash
+npx weifuwu init my-app              # Full project (SSR + i18n + theme + WS demo)
+npx weifuwu init my-api --minimal    # Minimal HTTP project (2 files)
+npx weifuwu init my-api --skip-install # Skip npm install
+npx weifuwu dev                       # Start dev server (auto-detect index.ts)
+npx weifuwu generate module my-mod    # Scaffold middleware module + test
+npx weifuwu version                   # Print version
+```
+
 ---
 
 ## Core Concepts
@@ -42,11 +53,14 @@ await server.ready
 | `hostname` | `string` | `'0.0.0.0'` | Listen address |
 | `signal` | `AbortSignal` | — | Shutdown on abort |
 | `websocket` | `WsUpgradeHandler` | — | WebSocket upgrade handler |
-| `maxBodySize` | `number` | — | Max body bytes |
+| `maxBodySize` | `number` | `10MB` | Max body bytes (0 = unlimited) |
+| `timeout` | `number` | `30_000` | Socket inactivity timeout (ms) |
+| `keepAliveTimeout` | `number` | `5_000` | Keep-Alive idle timeout (ms) |
+| `headersTimeout` | `number` | `6_000` | Headers read timeout (ms) |
 | `shutdown` | `boolean` | `true` | Auto SIGTERM/SIGINT |
 
 ```ts
-interface Server { stop: () => void; readonly port: number; readonly hostname: string; ready: Promise<void> }
+interface Server { stop: () => Promise<void>; readonly port: number; readonly hostname: string; ready: Promise<void> }
 const { server, url } = await createTestServer(handler)
 ```
 
@@ -58,9 +72,24 @@ app.get('/hello/:name', (req, ctx) => Response.json({ message: `Hello, ${ctx.par
 app.post('/data', async (req, ctx) => { const body = await req.json(); return Response.json(body, { status: 201 }) })
 app.use('/admin', authMW)                    // path-scoped middleware
 app.use('/admin', adminRouter)               // sub-router (flattened into parent trie)
-app.ws('/echo', { open(ws) { ws.send('connected') }, message(ws, _ctx, data) { ws.send(`echo: ${data}`) } })
+app.ws('/echo', {
+  open(ws, ctx) { ctx.ws.json({ type: 'connected' }) },
+  message(ws, ctx, data) { ctx.ws.json({ echo: data.toString() }) },
+})
+app.ws('/chat', {
+  open(ws, ctx) { ctx.ws.join('room') },
+  message(ws, ctx, data) { ctx.ws.sendRoom('room', JSON.parse(data.toString())) },
+})
 app.onError((err, req, ctx) => Response.json({ error: err.message }, { status: 500 }))
 
+// Debug: list all registered routes
+console.log(app.routes())
+// [ 'GET     /hello/:name', 'POST    /data', 'WS       /echo', 'WS       /chat' ]
+
+// Cross-process WebSocket broadcast (Redis)
+import { createHub } from 'weifuwu'
+app.wsHub(createHub({ redis: redis() }))
+
 const handler = app.handler()
 const wsHandler = app.websocketHandler()
 serve(handler, { port: 3000, websocket: wsHandler })
@@ -112,6 +141,8 @@ The `ctx` object accumulates properties as it passes through the middleware chai
 | `env` | `loadEnv()` | `Record<string, string>` | Public env vars (`WEIFUWU_PUBLIC_*`) |
 | `csrfToken` | `csrf()` | `string` | CSRF token |
 | `requestId` | `requestId()` | `string` | Request ID |
+| `session` | `session()` | `Session` | Session data object |
+| `sessionId` | `session()` | `string` | Session ID |
 | `sql` | `postgres()` | `Sql<{}>` | PostgreSQL tagged-template client |
 | `redis` | `redis()` | `Redis` | Redis client |
 | `queue` | `queue()` | `Queue` | Job queue |
@@ -125,6 +156,27 @@ The `ctx` object accumulates properties as it passes through the middleware chai
 | `setPref` | `preferences()` | `(key, val) => Response` | Set preference cookie + redirect |
 | `compiledTailwindCss` | `ssr()` internal | `string` | Compiled CSS content (internal) |
 | `tailwindCssUrl` | `ssr()` internal | `string` | Compiled CSS route URL (internal) |
+| `session` | `session()` | `Session` | Session data object |
+| `sessionId` | `session()` | `string` | Session ID |
+
+### Type-Safe Context
+
+Middleware-injected properties are **automatically typed** through chained `use()` calls:
+
+```ts
+const app = new Router()
+  .use(csrf())          // → Router<Context & { csrfToken: string }>
+  .use(requestId())     // → Router<Context & { csrfToken, requestId }>
+  .use(postgres())      // → Router<Context & { csrfToken, requestId, sql }>
+
+app.get('/me', (_req, ctx) => {
+  ctx.csrfToken   // ✅ string (IDE autocomplete)
+  ctx.requestId   // ✅ string
+  ctx.sql`SELECT 1` // ✅ Sql<{}>
+})
+```
+
+Each module exports an `XxxInjected` type (e.g. `PostgresInjected`, `UserInjected`) for composing custom context types. `Context` is an interface — modules augment it via `declare module` for ambient compatibility.
 
 ---
 
@@ -165,6 +217,123 @@ app.use('/', a)           // dashboard
 
 ---
 
+## Request Tracing & Logging
+
+Every request gets a **trace ID** via `AsyncLocalStorage`, injected into responses as `X-Trace-Id`. W3C `traceparent` headers are forwarded.
+
+```ts
+import { currentTraceId } from 'weifuwu'
+
+app.get('/api', (req, ctx) => {
+  console.log('Handling request', currentTraceId()) // f240a3f3-60e2-...
+})
+```
+
+**Structured logging** — `logger({ format: 'json' })` outputs JSON to stderr with `traceId`, `timestamp`, `elapsed_ms`:
+
+```json
+{"level":"info","message":"request","method":"GET","path":"/api/users","status":200,"elapsed_ms":42,"traceId":"f240a3f3-...","timestamp":"2025-01-15T10:30:00.000Z"}
+```
+
+Default format is `'short'` (human-readable). `'combined'` includes query strings.
+
+---
+
+## AI Observability
+
+Agent runs are **automatically logged** to `_agent_runs`. Dashboard endpoints provide analytics:
+
+```
+GET /agents/:id/runs?days=7       → [{ input, output, tokens_in, tokens_out, elapsed_ms, status, trace_id, ... }]
+GET /agents/:id/runs/summary?days=7 → { total, success, error, success_rate, tokens_in, tokens_out, avg_elapsed_ms, p95_elapsed_ms }
+GET /opencode/sessions/:id/usage    → { message_count, tokens_in, tokens_out, tokens_total }
+```
+
+Non-streaming runs log full token data; streaming runs log `status: 'stream'`.
+
+---
+
+## Agent ↔ Messager Streaming
+
+Agent replies in messager channels now stream **token-by-token** via WebSocket:
+
+```ts
+// Backend — automatic when agents are attached to messager
+const msg = messager({ pg, agents: agent({ pg, model }) })
+app.ws('/ws', msg.wsHandler())
+// Agent replies stream to: hub.broadcast({ type: 'agent_stream', data: { token, full } })
+```
+
+```tsx
+// Frontend — React hook
+import { useAgentStream } from 'weifuwu/react'
+
+const { getAgentText, isAgentStreaming, stream } = useAgentStream({
+  wsPath: '/ws',
+  channelId: 1,
+})
+```
+
+Multi-round conversation context: the last 10 channel messages are automatically injected into agent calls.
+
+---
+
+## Test Utilities
+
+Chainable test helper for HTTP-level testing without starting a server:
+
+```ts
+import { testApp } from 'weifuwu'
+
+const app = testApp()
+app.use(postgres({ connection: TEST_DB }))
+app.get('/users/:id', (req, ctx) => Response.json({ id: ctx.params.id, user: ctx.user }))
+
+const res = await app
+  .getReq('/users/42?name=Alice')
+  .withUser({ id: 1 })
+  .header('X-Custom', 'val')
+  .body({ data: 'test' })
+  .send()
+
+assert.equal(res.status, 200)
+assert.deepEqual(await res.json(), { id: '42', user: { id: 1 } })
+```
+
+| Method | Description |
+|--------|-------------|
+| `app.getReq(path)` `postReq` `putReq` `patchReq` `deleteReq` | Start building a request |
+| `.withUser(u)` `.withTenant(t)` `.with(ctx)` | Simulate middleware injection |
+| `.header(k,v)` `.body(data)` `.rawBody(str)` | Set request properties |
+| `.send()` → `TestResponse` | Execute and get `{ status, headers, json(), text() }` |
+
+### Database test isolation
+
+```ts
+import { createTestDb, withTestDb } from 'weifuwu'
+
+// Isolated schema — each test gets its own schema, destroyed after
+const db = await createTestDb()
+await db.sql`CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT)`
+await db.sql`INSERT INTO users (name) VALUES ('Alice')`
+await db.destroy()  // DROP SCHEMA ... CASCADE
+
+// Transaction rollback — all changes are rolled back after callback
+await withTestDb(async (sql) => {
+  await sql`INSERT INTO users ...`
+  // Automatically rolled back
+})
+```
+
+| Function | Description |
+|----------|-------------|
+| `createTestDb(opts?)` | Create isolated schema, returns `{ sql, url, schema, destroy }` |
+| `withTestDb(url?, fn)` | Run callback in a transaction, auto-rollback |
+
+Uses `TEST_DATABASE_URL` or `DATABASE_URL`. Automatically skipped in CI if unset.
+
+---
+
 ## Module Reference
 
 ### agent [β]
@@ -274,6 +443,46 @@ app.use(cors({ credentials: true, maxAge: 3600 }))
 | `credentials` | `boolean` | `false` | Allow cookies/credentials |
 | `maxAge` | `number` | — | Preflight cache duration (seconds) |
 
+### cache [α]
+
+Response caching middleware with memory and Redis stores. Caches GET/HEAD responses, with tag-based invalidation.
+
+```ts
+app.use(cache())                                                     // in-memory, 5min TTL
+app.use(cache({ ttl: 60_000, store: 'redis', redis: ctx.redis }))    // Redis store
+app.use(cache({
+  ttl: 30_000,
+  tag: (req, ctx) => ctx.user ? `user:${ctx.user.id}` : undefined,   // per-user invalidation
+}))
+
+// Programmatic invalidation
+const c = cache({ store: 'redis', redis: ctx.redis })
+app.use(c)
+await c.invalidate('users')     // invalidate all entries tagged with 'users'
+await c.flush()                 // clear entire cache
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `ttl` | `number` | `300000` (5min) | Cache TTL in ms |
+| `store` | `'memory' \| 'redis' \| CacheStore` | `'memory'` | Cache store backend |
+| `redis` | `Redis` | — | Redis client (required when `store: 'redis'`) |
+| `key` | `(req) => string` | SHA256(method+URL) | Custom cache key |
+| `tag` | `(req, ctx) => string \| string[]` | — | Tag for grouped invalidation |
+| `cacheCookies` | `boolean` | `false` | Cache responses with Set-Cookie |
+| `cacheStatus` | `number[]` | `[200]` | Status codes to cache |
+| `maxBodySize` | `number` | `1048576` (1MB) | Max body bytes to cache |
+
+Cached responses include `X-Cache: HIT` and `Age` headers. Requests with `Authorization` or `Cookie` headers are never cached. Binary content types (image, audio, video) are skipped.
+
+```ts
+import { MemoryCache, RedisCache } from 'weifuwu'
+
+const mem = new MemoryCache()
+await mem.set('key', { status: 200, statusText: 'OK', headers: {}, body: '...', createdAt: Date.now(), tags: [] }, 300_000)
+mem.close()
+```
+
 ### csrf [α]
 
 ```ts
@@ -398,6 +607,29 @@ Restart=always
 
 
 
+### graphql [β]
+
+```ts
+const handler: GraphQLHandler = () => ({
+  schema: `type Query { hello: String }`,
+  resolvers: { Query: { hello: () => 'world' } },
+  graphiql: true,         // GET / returns GraphiQL IDE
+  maxDepth: 10,            // max query nesting (default 10, 0 = disable)
+  timeout: 30_000,         // execution timeout in ms
+})
+app.use('/graphql', graphql(handler))
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `schema` | `string \| GraphQLSchema` | — | SDL string or pre-built schema |
+| `resolvers` | `object` | — | Resolver map |
+| `rootValue` | `any` | — | Root value for queries |
+| `context` | `(req, ctx) => object` | — | Per-request context factory |
+| `graphiql` | `boolean` | `false` | Serve GraphiQL IDE at GET / |
+| `maxDepth` | `number` | `10` | Max query nesting depth |
+| `timeout` | `number` | `30_000` | Execution timeout (ms) |
+
 ### health [β]
 
 ```ts
@@ -584,52 +816,70 @@ app.use(pg)                    // injects ctx.sql
 | `ssl` | `boolean\|object` | — | SSL options |
 | `idle_timeout` | `number` | `30` | Idle timeout (seconds) |
 | `connect_timeout` | `number` | `30` | Connection timeout |
+| `statementTimeout` | `number` | `30_000` | Per-statement timeout (ms, 0 = disable) |
+| `onQuery` | `(query, ms, rows) => void` | — | Query logging callback |
 
 ```ts
 // Raw SQL via tagged template
 await pg.sql`SELECT * FROM users WHERE email = ${email}`
 
-// Type-safe DDL
-import { pgTable, serial, text, boolean, timestamps } from 'weifuwu'
+// Define a table — one API, sql pre-bound
+import { serial, text, boolean, timestamps } from 'weifuwu'
 
-const users = pgTable('_users', {
+const users = pg.table('_users', {
   id: serial('id').primaryKey(),
   name: text('name').notNull(),
   email: text('email').unique().notNull(),
   active: boolean('active').default(true),
   ...timestamps(),
 })
-await users.create(pg.sql)
-await users.createIndex(pg.sql, 'email')
-
-// BoundTable — sql bound once, no need to pass sql to every call
-const t = pg.table('_users', { id: serial('id'), name: text('name'), email: text('email'), ...timestamps() })
-await t.insert({ name: 'Alice' })
-// vs unbound Table — sql passed as first argument each time
-// const t = pgTable('_users', { ... })
-// await t.insert(pg.sql, { name: 'Alice' })
-const { count, data } = await t.readMany({ role: 'admin' }, { orderBy: { name: 'asc' }, limit: 10 })
-await t.upsert({ email: 'alice@test.com' }, 'email')
-
-// Transactions
+await users.create()           // DDL — no need to pass sql
+await users.createIndex('email')
+
+// CRUD — sql already bound
+await users.insert({ name: 'Alice' })
+const { count, data } = await users.readMany({ role: 'admin' }, { orderBy: { name: 'asc' }, limit: 10 })
+await users.upsert({ email: 'alice@test.com' }, 'email')
+
+// Reuse schema without redefining fields
+import { pgTable } from 'weifuwu'
+const usersSchema = pgTable('_users', { id: serial('id'), name: text('name') })  // define once
+const users = pg.table(usersSchema)  // bind — no field duplication
+
+// Transactions — with auto-retry on deadlock/serialization failure
 await pg.transaction(async (sql) => {
-  const users = pg.table('_users', {}).withSql(sql)
-  return users.insert({ name: 'Bob' })
-})
+  const txUsers = users.withSql(sql)
+  return txUsers.insert({ name: 'Bob' })
+}, { maxRetries: 3 })
 
 // Soft delete — automatic if deleted_at column exists
-await t.delete(1)       // SET deleted_at = NOW()
-await t.hardDelete(1)   // DELETE FROM
-await t.readMany()      // WHERE deleted_at IS NULL (use withDeleted: true to include)
+await users.delete(1)       // SET deleted_at = NOW()
+await users.hardDelete(1)   // DELETE FROM
+await users.read(1)         // auto-filters deleted_at IS NULL (use withDeleted: true to include)
 
 // JSONB queries
 const logs = pg.table('logs', { meta: jsonb<{ service: string }>('meta') })
 await logs.readMany(contains('meta', { service: 'auth' }))
 
+// Connection pool visibility
+console.log(pg.poolStats())  // { active: 3, idle: 7, waiting: 0, max: 10 }
+
+// Migration tracking
+await pg.migrate()           // creates _weifuwu_migrations
+await pg.markMigrated('myModule')  // idempotent
+const done = await pg.isMigrated('myModule')
+
 // Partitioned tables
 await logs.create({ partitionBy: partitionBy('range', 'created_at') })
 ```
 
+**When to use pgTable vs pg.table:**
+| API | Use when |
+|-----|---------|
+| `pg.table('t', cols)` | You have `pg` available (factory, handler, migrate) |
+| `pg.table(schema)` | Reusing a schema without duplicating field definitions |
+| `pgTable('t', cols)` | No `pg` reference (utility modules, standalone schema files) |
+
 | Column builder | Type | Notes |
 |---------------|------|-------|
 | `serial(name)` | `number` | Auto-increment |
@@ -644,27 +894,27 @@ await logs.create({ partitionBy: partitionBy('range', 'created_at') })
 
 **Column modifiers:** `.primaryKey()`, `.notNull()`, `.nullable()`, `.default(val)`, `.unique()`, `.references(table, column?, onDelete?)`.
 
-**BoundTable CRUD methods:**
+**CRUD methods:**
 
 | Method | Description |
 |--------|-------------|
 | `insert(data)` | INSERT + RETURNING \*, returns the inserted row |
 | `insertMany(data)` | Bulk INSERT + RETURNING \*, returns rows |
-| `read(id, opts?)` | SELECT by primary key, returns row or undefined |
+| `read(id, opts?)` | SELECT by detected primary key + auto soft-delete filter |
 | `readMany(where?, opts?)` | Filtered query with `{ count, data }` — auto-filters soft-deleted |
-| `update(id, data)` | UPDATE by id + RETURNING \*, returns updated row |
+| `update(id, data)` | UPDATE by primary key + RETURNING \*, returns updated row |
 | `updateMany(where, data)` | Bulk UPDATE, returns affected row count |
 | `delete(id)` | Soft delete if `deleted_at` exists, else hard delete |
 | `hardDelete(id)` | Always DELETE FROM |
 | `deleteMany(where)` | Soft bulk delete if `deleted_at` exists |
 | `hardDeleteMany(where)` | Always DELETE FROM |
 | `upsert(data, conflict)` | INSERT ON CONFLICT DO UPDATE, returns row |
-| `count(where?)` | SELECT COUNT(\*) |
+| `count(where?)` | SELECT COUNT(\*) — auto-filters soft-deleted |
 | `create(opts?)` | CREATE TABLE IF NOT EXISTS |
 | `drop(opts?)` | DROP TABLE IF EXISTS |
 | `createIndex(columns, opts?)` | CREATE INDEX |
 | `createUniqueIndex(columns)` | CREATE UNIQUE INDEX |
-| `withSql(sql)` | Returns a new BoundTable bound to a different sql (for transactions) |
+| `withSql(sql)` | Returns copy bound to a different sql (for transactions) |
 
 **Where helpers** — composable query conditions:
 
@@ -690,6 +940,42 @@ class MyModule extends PgModule {
 
 Where helpers + `and`/`or`/`not` can be imported from `'weifuwu'` alongside `postgres`. Full column builders and table helpers are in the same barrel.
 
+### fts — Full-Text Search (PostgreSQL)
+
+Utilities for PostgreSQL full-text search: create GIN indexes, search with ranking, and generate highlighted snippets.
+
+```ts
+import { fts } from 'weifuwu'
+
+const articles = pg.table('articles', {
+  id: serial('id').primaryKey(),
+  title: text('title'),
+  body: text('body'),
+})
+
+// Create search index
+await fts.createIndex(pg.sql, articles, ['title', 'body'], { language: 'english' })
+
+// Search with ranking
+const results = await fts.search(pg.sql, articles, 'node.js framework', {
+  fields: ['title', 'body'],
+  limit: 20,
+  headline: true, // highlighted snippets via ts_headline
+})
+// → [{ id, rank: 0.8, row: { title, body, ... }, headline: '...<b>Node.js</b> framework...' }]
+
+// Drop index
+await fts.dropIndex(pg.sql, articles)
+```
+
+| Function | Description |
+|----------|-------------|
+| `createIndex(sql, table, fields, opts?)` | Create GIN/GiST tsvector index |
+| `search(sql, table, query, opts?)` | Search with ts_rank ordering |
+| `dropIndex(sql, table, opts?)` | Drop the index |
+
+Search options: `fields`, `limit` (20), `offset` (0), `headline` (false), `language` ('english'), `minRank`.
+
 ### preferences [α]
 
 Locale detection + theme + translations. `/__lang/:locale` and `/__theme/:theme` auto-routed.
@@ -742,16 +1028,34 @@ await q.add('send-email', { to: 'user@test.com' }, { cron: '0 8 * * *' })
 | `.process(handler)` | Register job processor |
 | `.run()` | Start processing |
 | `.stop()` | Stop processing |
+| `.jobs(limit?)` | List pending jobs |
+| `.failedJobs(limit?)` | List failed jobs with error messages |
+| `.retryFailed(jobId)` | Retry a specific failed job |
+| `.retryAllFailed(type?)` | Retry all failed jobs (optionally by type) |
+| `.dashboard()` | Returns a Router with management endpoints |
 | `.close()` | Cleanup |
 
+**Dashboard endpoints** (mount via `app.use('/__queue', q.dashboard())`):
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/` | Queue stats + pending/failed counts by type |
+| GET | `/:type/failed` | List failed jobs for a type |
+| POST | `/:type/retry` | Retry all failed jobs of a type |
+| POST | `/retry/:id` | Retry a specific failed job by ID |
+
 ### rateLimit [α]
 
 ```ts
-app.use(rateLimit({ max: 100, window: 60_000 }))            // 100 req/min
+app.use(rateLimit({ max: 100, window: 60_000 }))            // 100 req/min, in-memory
 app.get('/api', rateLimit({ max: 10 }), handler)            // per-route
 app.use(rateLimit({ key: (req) => req.headers.get('x-api-key') ?? 'anonymous' }))
+
+// Multi-process: Redis-backed rate limiting
+app.use(rateLimit({ max: 100, store: 'redis', redis: ctx.redis }))
+
 // Sets X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After headers
-// m.stop() — clear interval
+// m.stop() — clear interval (memory) or Redis cleanup
 ```
 
 | Option | Type | Default | Description |
@@ -760,6 +1064,11 @@ app.use(rateLimit({ key: (req) => req.headers.get('x-api-key') ?? 'anonymous' })
 | `window` | `number` | `60_000` | Window duration (ms) |
 | `key` | `(req) => string` | IP-based | Key function |
 | `message` | `string` | `'Too Many Requests'` | 429 response body |
+| `store` | `'memory' \| 'redis'` | `'memory'` | Backend store |
+| `redis` | `Redis` | — | Redis client (required when `store: 'redis'`) |
+| `prefix` | `string` | `'ratelimit:'` | Redis key prefix |
+
+Redis mode uses `INCR` + `EXPIRE` for atomic counting, enabling accurate rate limiting across multiple server processes. Memory mode is ideal for single-process deployments.
 
 ### redis [α]
 
@@ -808,6 +1117,58 @@ Also exports `seoTags(config)` for generating meta/og/twitter tags as an HTML st
 | `sitemap` | `SitemapConfig` | — | Sitemap configuration (urls, resolve, cacheTTL) |
 | `headers` | `SeoHeadersConfig` | — | Response headers (e.g. `X-Robots-Tag`) |
 
+### session [α]
+
+Cookie-based server-side session management with memory and Redis stores.
+
+```ts
+app.use(session())                                          // in-memory store (default)
+app.use(session({ store: 'redis', redis: ctx.redis }))       // Redis store
+app.use(session({ store: 'redis', redis, ttl: 30 * 60_000, cookieName: 'sid' }))
+
+app.get('/login', async (req, ctx) => {
+  ctx.session.userId = 42
+  ctx.session.role = 'admin'
+  // Auto-saved on response — cookie set automatically
+  return Response.json({ ok: true })
+})
+
+app.get('/logout', async (req, ctx) => {
+  ctx.session.destroy()     // or ctx.session = null
+  return Response.json({ ok: true })
+})
+
+// ctx.session.id — readonly session ID
+// ctx.session.save() — explicit dirty mark (for deep mutations)
+// ctx.session.destroy() — clear session + remove cookie
+// Session mutations are auto-detected on property set/delete
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `store` | `'memory' \| 'redis' \| SessionStore` | `'memory'` | Session store backend |
+| `redis` | `Redis` | — | Redis client (required when `store: 'redis'`) |
+| `ttl` | `number` | `86400000` (24h) | Session TTL in ms |
+| `cookieName` | `string` | `'__session'` | Cookie name |
+| `cookie.httpOnly` | `boolean` | `true` | Cookie httpOnly flag |
+| `cookie.secure` | `boolean` | `auto` | Cookie Secure flag (true in production) |
+| `cookie.sameSite` | `string` | `'lax'` | SameSite policy |
+| `cookie.path` | `string` | `'/'` | Cookie path |
+| `cookie.domain` | `string` | — | Cookie domain |
+
+**Stores** are also exported for standalone use:
+
+```ts
+import { MemoryStore, RedisStore } from 'weifuwu'
+
+const mem = new MemoryStore()  // auto-cleanup every 60s
+await mem.set('sid', { userId: 1 }, 86400000)
+mem.close()
+
+const redis = new RedisStore(redisClient, 'myapp:session:')
+await redis.destroy('sid')
+```
+
 ### ssr({ dir }) [β]
 
 One-stop Server-Side Rendering. Accepts a directory and returns a Router that handles all SSR routes, tailwind CSS, hydration bundles, and livereload — using Next.js-style file conventions.
@@ -938,7 +1299,67 @@ app.post('/users', validate({ body: CreateUser, query: z.object({ ref: z.string(
   // ctx.parsed.headers — typed & validated
 })
 // Validation failure: returns 400 with { error: 'Validation failed', issues: [...] }
+
+**Form body auto-parsing** — `application/x-www-form-urlencoded` bodies are automatically parsed into `Record<string, string>` via `URLSearchParams`, even without a Zod schema:
+
+```ts
+// No schema needed — just parse the form
+app.post('/contact', validate(), (req, ctx) => {
+  const email = ctx.parsed.body.email  // string
+  const msg = ctx.parsed.body.message  // string
+  return Response.json({ received: true })
+})
+
+// Or validate with Zod
+app.post('/contact', validate({ body: z.object({ email: z.string().email() }) }), handler)
 ```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `body` | `ZodSchema` | — | Body validation schema (omit to skip) |
+| `query` | `ZodSchema` | — | Query validation schema |
+| `params` | `ZodSchema` | — | URL params validation schema |
+| `headers` | `ZodSchema` | — | Header validation schema |
+
+### webhook [β]
+
+Webhook receiver with built-in signature verification for Stripe, GitHub, and Slack. Event-based dispatch with replay protection.
+
+```ts
+import { webhook } from 'weifuwu'
+
+const wh = webhook({
+  stripe: { secret: process.env.STRIPE_WEBHOOK_SECRET! },
+  github: { secret: process.env.GITHUB_WEBHOOK_SECRET! },
+  slack: { secret: process.env.SLACK_WEBHOOK_SECRET! },
+})
+
+app.use('/webhooks', wh)
+
+wh.on('checkout.session.completed', async (event, ctx) => {
+  await fulfillOrder(event.payload.data.object)
+})
+
+wh.on('push', async (event, ctx) => {
+  await triggerCI(event.payload)
+})
+
+wh.on('*', (event) => {
+  console.log(`Received ${event.provider}.${event.event}`)
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `stripe` | `PlatformConfig` | — | Stripe webhook config with `secret` |
+| `github` | `PlatformConfig` | — | GitHub webhook config |
+| `slack` | `PlatformConfig` | — | Slack webhook config |
+| `custom` | `CustomVerifierConfig[]` | — | Custom signature verifiers |
+| `replayProtection` | `boolean` | `true` | Deduplicate by event ID |
+| `idempotencyTTL` | `number` | `3600000` | Dedup TTL (ms) |
+
+Built-in verifiers handle HMAC-SHA256, timestamp validation (Slack's 5-min window), and Stripe's `t=` / `v1=` signature format. Slack URL verification challenges are auto-responded.
+
 ### Client-side navigation
 
 ```tsx
@@ -1120,14 +1541,16 @@ Every public symbol can be imported from `'weifuwu'`:
 ```ts
 serve, createTestServer, Router, ssr,
 Context, Handler, Middleware, ErrorHandler, ServeOptions, Server,
-loadEnv
+loadEnv, testApp, TestApp, TestRequest, TestResponse,
+currentTraceId, currentTrace, runWithTrace, traceElapsed, TraceContext,
 ```
 
 ### Middleware modules
 
 ```ts
 auth, cors, csrf, compress, helmet, logger, rateLimit, requestId, validate, upload,
-preferences, serveStatic
+preferences, serveStatic, session, MemoryStore, RedisStore, SessionStore,
+cache, MemoryCache, RedisCache, CacheStore
 ```
 
 ### Database
@@ -1136,6 +1559,7 @@ preferences, serveStatic
 postgres, PostgresOptions, PostgresClient,
 redis, RedisOptions, RedisClient,
 queue, QueueOptions, QueueJob, Queue,
+PostgresInjected, RedisInjected, QueueInjected,
 // Schema helpers — importable alongside postgres:
 pgTable, SQL, sql,
 ColumnBuilder, serial, uuid, text, integer, boolean, boolean_, timestamptz, jsonb, textArray, vector,
@@ -1151,8 +1575,10 @@ TsxContext, useLoaderData,
 useWebsocket, useAction, useFetch, useQueryState, createStore,
 Link, useNavigate, useNavigating, addInterceptor,
 useLocale, useTheme, applyTheme, useFlashMessage,
+useAgentStream,
 Head
 ```
+export type { UseAgentStreamOptions, UseAgentStreamReturn, AgentStreamState } from 'weifuwu/react'
 
 ### AI SDK (re-exported from `ai`)
 
@@ -1168,9 +1594,15 @@ openai, createOpenAI
 preferences, health, analytics, seo, seoMiddleware, seoTags,
 user, mailer, graphql, aiStream, runWorkflow,
 logdb, messager, agent, iii, createWorker, registerWorker,
-opencode, deploy, defineConfig,
+opencode, deploy, defineConfig, webhook,
+testApp, TestApp, TestRequest, TestResponse,
+createTestDb, withTestDb,
 getCookies, setCookie, deleteCookie,
-createSSEStream, formatSSE, formatSSEData
+createSSEStream, formatSSE, formatSSEData,
+currentTraceId, currentTrace, runWithTrace, traceElapsed,
+createHub, Hub, HubOptions,
+DEFAULT_MAX_BODY, MIGRATIONS_TABLE,
+fts,
 ```
 
 ---