weifuwu 0.22.1 → 0.22.3

package/README.md

@@ -60,10 +60,20 @@ await server.ready
 | `shutdown` | `boolean` | `true` | Auto SIGTERM/SIGINT |
 
 ```ts
-interface Server { stop: () => Promise<void>; readonly port: number; readonly hostname: string; ready: Promise<void> }
+interface Server {
+  stop: (timeoutMs?: number) => Promise<void>  // graceful: waits for in-flight, force-closes after timeoutMs (default 10s)
+  readonly port: number
+  readonly hostname: string
+  ready: Promise<void>
+}
 const { server, url } = await createTestServer(handler)
 ```
 
+`server.stop()` performs a graceful shutdown: stops accepting new connections,
+closes idle keep-alive sockets, then waits for in-flight requests to complete.
+If they don't finish within `timeoutMs` (default 10 seconds), remaining connections
+are forcibly closed. SIGTERM/SIGINT use the same graceful pattern.
+
 ### Router
 
 ```ts
@@ -404,6 +414,16 @@ app.use(auth({ token: 'sk-123' }))                              // static token
 app.use(auth({ header: 'X-API-Key', token: 'my-key' }))         // custom header
 app.use(auth({ verify: async (token, req) => ({ sub: 'abc' }) })) // custom verify → sets ctx.user
 app.get('/protected', auth({ proxy: 'http://auth:3000/validate' }), handler)
+
+// Session-based auth (must be placed after session() middleware)
+app.use(session())
+app.use(auth({
+  session: true,
+  resolveUser: async (userId) => {          // load user from DB
+    const [user] = await sql`SELECT * FROM users WHERE id = ${userId}`
+    return user ?? null                      // null → destroy stale session
+  },
+}))
 ```
 
 | Option | Type | Default | Description |
@@ -412,6 +432,13 @@ app.get('/protected', auth({ proxy: 'http://auth:3000/validate' }), handler)
 | `header` | `string` | `'Authorization'` | Header name |
 | `verify` | `(token, req) => object\|null` | — | Verify function, return value sets `ctx.user` |
 | `proxy` | `string` | — | Auth service URL to proxy requests to |
+| `session` | `boolean` | `false` | Enable session-based auth. Checks `ctx.session.userId` first |
+| `resolveUser` | `(userId) => object\|null` | — | Load user from userId (called when `session: true`). Return falsy to reject + auto-destroy stale session |
+
+When `session: true`, auth checks `ctx.session.userId` before the
+Authorization header. This lets logged-in users authenticate via their
+session cookie without sending a token. Falls back to header/token auth
+if no session userId is present.
 
 ### compress [α]
 
@@ -699,6 +726,64 @@ await engine.trigger({ function_id: 'orders::create', payload: { items: ['apple'
 
 
 
+### knowledgeBase [β] — RAG with pgvector
+
+```ts
+import { knowledgeBase } from 'weifuwu'
+import { embed } from 'ai'
+
+const kb = knowledgeBase({
+  sql: ctx.sql,
+  embedding: (text) =>
+    embed({ model: openai.embedding('text-embedding-3-small'), value: text })
+      .then(r => r.embedding),
+  dimensions: 1536,
+})
+
+// Create table + HNSW index (safe to call multiple times)
+await kb.migrate()
+
+// Ingest a document (auto chunk → embed → store)
+await kb.ingest('docs/intro.md', `# Welcome\n\nThis is the introduction...`, {
+  title: 'Introduction',
+  metadata: { source: 'docs', author: 'alice' },
+})
+
+// Semantic search
+const results = await kb.search('how to get started?', { limit: 5 })
+// → [{ key, title, content, score: 0.92, metadata }, ...]
+
+// Delete
+await kb.delete('docs/outdated.md')
+
+// List all documents
+const entries = await kb.list()
+// → [{ key, title, chunks: 3 }, ...]
+
+// Use as middleware (injects ctx.kb.search)
+app.use(kb.middleware())
+app.get('/search', async (req, ctx) => {
+  const results = await ctx.kb.search(ctx.query.q)
+  return Response.json(results)
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `sql` | `Sql<{}>` | — | **Required.** Postgres client with pgvector |
+| `embedding` | `(text) => Promise<number[]>` | — | **Required.** Embedding function |
+| `dimensions` | `number` | `1536` | Vector dimensions |
+| `table` | `string` | `'_kb_docs'` | Database table name |
+| `chunkSize` | `number` | `512` | Max characters per chunk |
+| `chunkOverlap` | `number` | `64` | Overlap between chunks |
+| `searchLimit` | `number` | `5` | Default search result count |
+| `searchThreshold` | `number` | `0` | Minimum similarity (0–1) |
+
+Documents are split on paragraph boundaries (`\n\n`). Re-ingesting the same key
+replaces old chunks. The HNSW index enables fast approximate nearest-neighbor
+search (cosine distance).
+
+
 ### logdb [β]
 
 PostgreSQL structured event logging with monthly partitioning.
@@ -746,6 +831,72 @@ await mail.send({ to: 'user@test.com', subject: 'Hello', text: 'Body', html: '<p
 | `from` | `string` | — | Default sender address |
 | `send` | `function` | — | Custom send function (alternative to transport) |
 
+
+
+### oauthClient [β] — Social login (OAuth 2.0 client)
+
+```ts
+import { oauthClient } from 'weifuwu'
+
+app.use(session())                       // required — stores OAuth state
+app.use(user({ pg, jwtSecret }))         // required — user management
+app.use('/auth', oauthClient({           // mounts /auth/google, /auth/google/callback
+  pg,
+  jwtSecret,
+  redirectUrl: '/dashboard',
+  providers: {
+    google: {
+      clientId: process.env.GOOGLE_CLIENT_ID,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+    },
+    github: {
+      clientId: process.env.GITHUB_CLIENT_ID,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET,
+    },
+  },
+}))
+```
+
+**Flow:** User clicks "Login with Google" → redirected to Google → back to app → user created/linked in database → JWT signed → session created → redirected to `redirectUrl` with `?token=` (or JSON response for API clients).
+
+Supports custom providers via `authUrl`, `tokenUrl`, `userUrl`, and `parseUser`:
+
+```ts
+app.use('/auth', oauthClient({
+  pg,
+  jwtSecret,
+  providers: {
+    discord: {
+      clientId: process.env.DISCORD_CLIENT_ID,
+      clientSecret: process.env.DISCORD_CLIENT_SECRET,
+      authUrl: 'https://discord.com/api/oauth2/authorize',
+      tokenUrl: 'https://discord.com/api/oauth2/token',
+      userUrl: 'https://discord.com/api/users/@me',
+      parseUser: (data) => ({
+        id: data.id,
+        email: data.email ?? '',
+        name: data.global_name ?? data.username,
+        avatarUrl: data.avatar
+          ? `https://cdn.discordapp.com/avatars/${data.id}/${data.avatar}.png`
+          : '',
+      }),
+    },
+  },
+}))
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `pg` | `PostgresClient` | — | **Required.** Database connection |
+| `jwtSecret` | `string` | — | **Required.** Must match `user()` module's secret |
+| `providers` | `Record<string, OAuthProviderConfig>` | — | **Required.** Provider configs (Google/GitHub built-in, any custom) |
+| `redirectUrl` | `string` | `'/'` | Post-login redirect destination |
+| `expiresIn` | `string \| number` | `'24h'` | JWT expiry |
+| `table` | `string` | `'_auth_providers'` | Provider-user link table name |
+
+The module auto-creates a `_auth_providers` table (`user_id`, `provider`, `provider_id`, `email`, `name`, `avatar_url`) on first request. Built-in providers (Google, GitHub) have preset URLs — you only need to provide `clientId` and `clientSecret`.
+
+
 ### messager [β]
 
 Real-time chat with channels, WebSocket, agent routing.
@@ -1099,6 +1250,85 @@ app.use(requestId({ header: 'X-Request-Id', generator: () => crypto.randomUUID()
 
 
 
+### s3 [α] — S3-compatible object storage
+
+```ts
+import { s3 } from 'weifuwu'
+
+app.use(s3({
+  bucket: 'my-app',
+  region: 'us-east-1',
+  endpoint: process.env.S3_URL,              // MinIO / R2 / AWS
+  forcePathStyle: true,                       // required for MinIO
+  credentials: {
+    accessKeyId: process.env.S3_ACCESS_KEY,
+    secretAccessKey: process.env.S3_SECRET_KEY,
+  },
+  publicUrl: 'https://cdn.example.com',       // for unsigned public URLs
+}))
+```
+
+Injects `ctx.s3` with methods for S3-compatible object storage.
+
+```ts
+// Upload
+await ctx.s3.put('images/logo.png', buffer, { contentType: 'image/png' })
+
+// Download
+const buf = await ctx.s3.get('images/logo.png')  // Buffer | null
+
+// Delete
+await ctx.s3.delete('images/logo.png')
+
+// Check existence
+if (await ctx.s3.exists('images/logo.png')) { ... }
+
+// Signed URL (expires in 1 hour by default)
+const url = await ctx.s3.url('images/logo.png')
+const shortUrl = await ctx.s3.url('images/logo.png', { expiresIn: 60 })
+
+// Public URL (requires publicUrl in options)
+const publicUrl = await ctx.s3.url('images/logo.png', { expiresIn: 0 })
+
+// List objects under a prefix
+const keys = await ctx.s3.list('images/')
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `bucket` | `string` | — | **Required.** S3 bucket name |
+| `region` | `string` | `'us-east-1'` | AWS region |
+| `endpoint` | `string` | — | Custom endpoint (MinIO, R2, B2) |
+| `forcePathStyle` | `boolean` | `false` | Path-style addressing (required for MinIO) |
+| `credentials` | `{ accessKeyId, secretAccessKey }` | — | Falls back to AWS env vars / IAM role |
+| `publicUrl` | `string` | — | Base URL for unsigned public URLs via `url(key, { expiresIn: 0 })` |
+
+Credentials can be omitted to use AWS environment variables (`AWS_ACCESS_KEY_ID`,
+`AWS_SECRET_ACCESS_KEY`) or IAM roles (EC2, ECS, Lambda).
+
+The module can also be used standalone without the middleware:
+
+```ts
+const storage = s3({ bucket: 'my-app', endpoint: '...' })
+await storage.put('key', body)
+const data = await storage.get('key')
+```
+
+Requires MinIO or another S3-compatible service for local development.
+Add to `docker-compose.yml`:
+
+```yml
+minio:
+  image: minio/minio
+  ports:
+    - '9000:9000'
+  environment:
+    MINIO_ROOT_USER: minioadmin
+    MINIO_ROOT_PASSWORD: minioadmin
+  command: server /data
+```
+
+
 ### seo [β] + seoMiddleware [α]
 
 ```ts
@@ -1155,6 +1385,16 @@ app.get('/logout', async (req, ctx) => {
 | `cookie.sameSite` | `string` | `'lax'` | SameSite policy |
 | `cookie.path` | `string` | `'/'` | Cookie path |
 | `cookie.domain` | `string` | — | Cookie domain |
+| `secret` | `string` | — | HMAC-SHA256 sign the session cookie (`uuid.signature`). Prevents tampering **strongly recommended in production** |
+| `rotateInterval` | `number` | `900000` (15min) | Auto-rotate session ID to prevent fixation attacks. Set `0` to disable |
+
+When `secret` is set, the cookie value is signed with HMAC-SHA256:
+`uuid.base64url(hmac)`. Tampered cookies are rejected and treated as new
+sessions (no error message, no data leak).
+
+Session ID auto-rotation copies data to a new ID and deletes the old one
+from the store. Rotation happens transparently on the next request after
+`rotateInterval` has elapsed.
 
 **Stores** are also exported for standalone use:
 

package/dist/auth.d.ts

@@ -4,5 +4,19 @@ export interface AuthOptions {
     verify?: (token: string, req: Request) => unknown | Promise<unknown>;
     proxy?: string | URL;
     header?: string;
+    /**
+     * Enable session-based authentication.
+     * When true, auth() checks `ctx.session.userId` first.
+     * If found, the user is authenticated via session (no token required).
+     * Falls back to header-based auth if no session userId is present.
+     */
+    session?: boolean;
+    /**
+     * Function to load user data from a user ID stored in the session.
+     * Called when `session: true` and `ctx.session.userId` is present.
+     * Return a falsy value to reject (e.g. if the user was deleted).
+     * If not provided, `ctx.user` is set to `{ id: ctx.session.userId }`.
+     */
+    resolveUser?: (userId: unknown) => unknown | Promise<unknown>;
 }
 export declare function auth(options: AuthOptions): Middleware;

package/dist/index.d.ts

@@ -13,6 +13,8 @@ export { cors } from './cors.ts';
 export type { CORSOptions } from './cors.ts';
 export { auth } from './auth.ts';
 export type { AuthOptions } from './auth.ts';
+export { oauthClient } from './oauth-client.ts';
+export type { OAuthClientOptions, OAuthProviderConfig } from './oauth-client.ts';
 export { serveStatic } from './static.ts';
 export type { ServeStaticOptions } from './static.ts';
 export { validate } from './validate.ts';
@@ -84,3 +86,7 @@ export type { CacheOptions, CacheStore, CacheMiddleware, CachedResponse } from '
 export { webhook } from './webhook.ts';
 export type { WebhookOptions, WebhookModule, WebhookEvent, WebhookHandler, PlatformConfig, CustomVerifierConfig } from './webhook.ts';
 export * as fts from './fts.ts';
+export { s3 } from './s3.ts';
+export type { S3Options, S3PutOptions, S3UrlOptions, S3Module, S3Body } from './s3.ts';
+export { knowledgeBase } from './kb.ts';
+export type { KBOptions, KBIngestOptions, KBSearchResult, KBSearchOptions, KBListEntry, KBModule } from './kb.ts';