@wooksjs/event-http 0.6.2 → 0.6.3

package/skills/wooksjs-event-http/addons.md

@@ -0,0 +1,307 @@
+# Addons — Body Parser, Static Files, Proxy
+
+> Covers the three official addon packages: `@wooksjs/http-body` for parsing request bodies, `@wooksjs/http-static` for serving static files, and `@wooksjs/http-proxy` for proxying requests.
+
+## Body Parser — `@wooksjs/http-body`
+
+### Installation
+
+```bash
+npm install @wooksjs/http-body
+```
+
+### `useBody()`
+
+Composable that provides content-type detection and body parsing:
+
+```ts
+import { useBody } from '@wooksjs/http-body'
+
+app.post('/api/data', async () => {
+  const { parseBody, isJson, isFormData } = useBody()
+
+  if (isJson()) {
+    const data = await parseBody<{ name: string; age: number }>()
+    return { received: data }
+  }
+
+  if (isFormData()) {
+    const formData = await parseBody<Record<string, string>>()
+    return { fields: formData }
+  }
+
+  return { error: 'Unsupported content type' }
+})
+```
+
+### Content-type checkers
+
+All checkers are lazy-computed and cached:
+
+| Method | Checks for |
+|--------|-----------|
+| `isJson()` | `application/json` |
+| `isHtml()` | `text/html` |
+| `isXml()` | `text/xml` |
+| `isText()` | `text/plain` |
+| `isBinary()` | `application/octet-stream` |
+| `isFormData()` | `multipart/form-data` |
+| `isUrlencoded()` | `application/x-www-form-urlencoded` |
+
+### `parseBody<T>()`
+
+Parses the request body based on content type. Returns a promise. The result is cached — calling `parseBody()` twice returns the same promise.
+
+| Content-Type | Parsed as |
+|-------------|-----------|
+| `application/json` | Parsed JSON object (safe parse with prototype pollution protection) |
+| `multipart/form-data` | Parsed form fields as `Record<string, unknown>` |
+| `application/x-www-form-urlencoded` | Parsed as object using `WooksURLSearchParams` |
+| everything else | Raw text string |
+
+### `rawBody()`
+
+Also re-exports `rawBody()` from `useRequest()` for convenience:
+
+```ts
+const { rawBody } = useBody()
+const buffer = await rawBody()  // Buffer (decompressed if needed)
+```
+
+### Common Pattern: JSON API endpoint
+
+```ts
+app.post('/api/users', async () => {
+  const { parseBody, isJson } = useBody()
+  if (!isJson()) throw new HttpError(415, 'Expected JSON')
+
+  const body = await parseBody<{ name: string; email: string }>()
+  const user = await db.createUser(body)
+
+  const { status } = useResponse()
+  status(201)
+  return user
+})
+```
+
+### Safety
+
+- JSON parsing uses `safeJsonParse` which protects against `__proto__` and `constructor` pollution.
+- Form-data parsing limits: max 255 fields, max 100-byte key names, max 100 KB per field value.
+- Illegal keys (`__proto__`, `constructor`, `prototype`) are rejected with 400.
+
+---
+
+## Static Files — `@wooksjs/http-static`
+
+### Installation
+
+```bash
+npm install @wooksjs/http-static
+```
+
+### `serveFile(filePath, options?)`
+
+Serves a static file with full HTTP caching support (ETags, If-None-Match, If-Modified-Since, Range requests):
+
+```ts
+import { serveFile } from '@wooksjs/http-static'
+
+app.get('/static/*', () => {
+  const { get } = useRouteParams<{ '*': string }>()
+  return serveFile(get('*'), {
+    baseDir: './public',
+    cacheControl: { maxAge: '1h', public: true },
+  })
+})
+```
+
+### Options
+
+```ts
+interface TServeFileOptions {
+  baseDir?: string              // base directory for file resolution
+  headers?: Record<string, string>  // additional response headers
+  cacheControl?: TCacheControl  // Cache-Control directives
+  expires?: Date | string | number  // Expires header
+  pragmaNoCache?: boolean       // set Pragma: no-cache
+  defaultExt?: string           // default extension (e.g. 'html')
+  index?: string                // index file (e.g. 'index.html')
+  listDirectory?: boolean       // serve directory listing
+  allowDotDot?: boolean         // allow ../ traversal (default: false)
+}
+```
+
+### Features
+
+- **ETag & conditional requests**: Automatically generates ETags from inode/size/mtime. Returns 304 Not Modified when appropriate.
+- **Range requests**: Supports `Range` header for partial content (206) and `If-Range` validation.
+- **MIME type detection**: Automatically sets `Content-Type` based on file extension.
+- **Directory listing**: Optional HTML directory listing with file sizes and dates.
+- **Index files**: Serves `index.html` (or configured index) when a directory is requested.
+- **Path traversal protection**: Rejects `../` by default.
+
+### Common Pattern: SPA with fallback
+
+```ts
+app.get('/*', async () => {
+  const { get } = useRouteParams<{ '*': string }>()
+  try {
+    return await serveFile(get('*') || 'index.html', {
+      baseDir: './dist',
+      index: 'index.html',
+      cacheControl: { maxAge: '1d', public: true },
+    })
+  } catch {
+    // Fallback to index.html for SPA client-side routing
+    return await serveFile('index.html', { baseDir: './dist' })
+  }
+})
+```
+
+### Common Pattern: File server with directory listing
+
+```ts
+app.get('/files/*', () => {
+  const { get } = useRouteParams<{ '*': string }>()
+  return serveFile(get('*') || '.', {
+    baseDir: '/var/shared',
+    listDirectory: true,
+    cacheControl: { noCache: true },
+  })
+})
+```
+
+---
+
+## HTTP Proxy — `@wooksjs/http-proxy`
+
+### Installation
+
+```bash
+npm install @wooksjs/http-proxy
+```
+
+### `useProxy()`
+
+Composable that returns a `proxy()` function for forwarding the current request:
+
+```ts
+import { useProxy } from '@wooksjs/http-proxy'
+
+app.get('/api/*', async () => {
+  const proxy = useProxy()
+  return await proxy('https://backend.example.com/api/endpoint', {
+    reqHeaders: { allow: '*' },
+    resHeaders: { allow: '*' },
+  })
+})
+```
+
+### `proxy(target, options?)`
+
+The function returned by `useProxy()`:
+
+```ts
+async function proxy(target: string, opts?: TWooksProxyOptions): Promise<Response>
+```
+
+- `target` — Full URL to proxy to (including path and query string).
+- Returns a `Response` (Fetch API) that the framework sends as the final response.
+
+### Proxy Options
+
+```ts
+interface TWooksProxyOptions {
+  method?: string               // override HTTP method
+  reqHeaders?: TWooksProxyControls   // filter/transform request headers
+  reqCookies?: TWooksProxyControls   // filter/transform request cookies
+  resHeaders?: TWooksProxyControls   // filter/transform response headers
+  resCookies?: TWooksProxyControls   // filter/transform response cookies
+  debug?: boolean               // log proxy details
+}
+```
+
+### Proxy Controls
+
+Each control object (`TWooksProxyControls`) lets you allow, block, or overwrite headers/cookies:
+
+```ts
+interface TWooksProxyControls {
+  allow?: Array<string | RegExp> | '*'   // allowlist (use '*' for all)
+  block?: Array<string | RegExp> | '*'   // blocklist (use '*' for none)
+  overwrite?: Record<string, string> | ((data: Record<string, string>) => Record<string, string>)
+}
+```
+
+### Common Pattern: API Gateway
+
+```ts
+app.all('/api/*', async () => {
+  const proxy = useProxy()
+  const { get } = useRouteParams<{ '*': string }>()
+  const { rawSearchParams } = useSearchParams()
+
+  const targetPath = get('*')
+  const query = rawSearchParams()
+  const target = `https://internal-api.local/${targetPath}${query}`
+
+  return await proxy(target, {
+    reqHeaders: {
+      allow: '*',
+      overwrite: { 'x-gateway': 'wooks' },
+    },
+    resHeaders: { allow: '*' },
+    reqCookies: { allow: ['session_id'] },
+    resCookies: { allow: ['session_id'] },
+  })
+})
+```
+
+### Common Pattern: Selective header forwarding
+
+```ts
+return await proxy('https://api.example.com/data', {
+  reqHeaders: {
+    allow: ['authorization', 'content-type', 'accept'],
+  },
+  resHeaders: {
+    allow: '*',
+    block: ['x-internal-header', 'server'],
+  },
+})
+```
+
+### Blocked headers by default
+
+When using proxy controls, these headers are blocked by default:
+
+**Request**: `connection`, `accept-encoding`, `content-length`, `upgrade-insecure-requests`, `cookie`
+
+**Response**: `transfer-encoding`, `content-encoding`, `set-cookie`
+
+To forward cookies, explicitly configure `reqCookies` / `resCookies`.
+
+### Debug mode
+
+```ts
+return await proxy('https://api.example.com/data', {
+  debug: true,  // logs request/response details to the event logger
+  reqHeaders: { allow: '*' },
+  resHeaders: { allow: '*' },
+})
+```
+
+## Best Practices
+
+- **Always validate and sanitize paths before `serveFile()`** — Don't pass user input directly. Use `baseDir` to restrict the file root.
+- **Use `parseBody()` only once** — It reads and caches the body. Multiple calls return the same cached result.
+- **Use proxy controls to limit header forwarding** — Don't blindly forward all headers between services. Use `allow`/`block` to be explicit.
+- **Set `allow: '*'` explicitly** — Without controls, no headers are forwarded by the proxy.
+
+## Gotchas
+
+- `serveFile()` throws `HttpError(404)` if the file doesn't exist. Catch it if you need fallback behavior.
+- `serveFile()` rejects paths containing `/../` by default. Set `allowDotDot: true` only if you're certain the path is safe.
+- `useProxy()` uses the global `fetch()` API — ensure your Node.js version supports it (18+).
+- The proxy function returns a `Response` object. The framework handles streaming it to the client.

package/skills/wooksjs-event-http/core.md

@@ -0,0 +1,297 @@
+# Core Concepts — @wooksjs/event-http
+
+> Covers HTTP app creation, server setup, how the HTTP adapter integrates with the event context system, testing, and logging.
+
+For the underlying event context store API (`init`, `get`, `set`, `hook`, etc.) and how to create custom composables, see [event-core.md](event-core.md).
+
+## Mental Model
+
+`@wooksjs/event-http` is the HTTP adapter for Wooks. It turns every incoming HTTP request into an event with its own isolated context store. Instead of middleware chains and mutated `req`/`res` objects, you call composable functions (`useRequest()`, `useCookies()`, `useSetHeaders()`, etc.) from anywhere in your handler — values are computed on demand and cached per request.
+
+Key principles:
+1. **Never mutate `req`** — Accumulate request context in the store instead.
+2. **Never parse before needed** — Cookies, body, search params are only parsed when a composable is first called.
+3. **No middleware sprawl** — Composable functions replace middleware. Each one is a focused, importable utility.
+
+## Installation
+
+```bash
+npm install wooks @wooksjs/event-http
+```
+
+## Creating an HTTP App
+
+```ts
+import { createHttpApp } from '@wooksjs/event-http'
+
+const app = createHttpApp()
+
+app.get('/hello', () => 'Hello World!')
+
+app.listen(3000, () => {
+  console.log('Server running on port 3000')
+})
+```
+
+`createHttpApp(opts?, wooks?)` returns a `WooksHttp` instance. Options:
+
+```ts
+interface TWooksHttpOptions {
+  logger?: TConsoleBase          // custom logger
+  eventOptions?: TEventOptions   // event-level logger config
+  onNotFound?: TWooksHandler     // custom 404 handler
+  router?: {
+    ignoreTrailingSlash?: boolean // treat /path and /path/ as the same
+    ignoreCase?: boolean         // case-insensitive matching
+    cacheLimit?: number          // max cached parsed routes
+  }
+  requestLimits?: {              // app-level body limits (overridable per-request)
+    maxCompressed?: number       // default: 1 MB
+    maxInflated?: number         // default: 10 MB
+    maxRatio?: number            // default: 100 (zip-bomb protection)
+    readTimeoutMs?: number       // default: 10 000 ms
+  }
+}
+```
+
+Example — raise body limits for the entire app:
+
+```ts
+const app = createHttpApp({
+  requestLimits: {
+    maxCompressed: 50 * 1024 * 1024,  // 50 MB
+    maxInflated: 100 * 1024 * 1024,   // 100 MB
+    maxRatio: 200,
+  },
+})
+```
+
+These defaults apply to every request but can still be overridden per-request via `useRequest()` (see [request.md](request.md)).
+
+## Using with an Existing Node.js Server
+
+```ts
+import http from 'http'
+import { createHttpApp } from '@wooksjs/event-http'
+
+const app = createHttpApp()
+app.get('/hello', () => 'Hello World!')
+
+const server = http.createServer(app.getServerCb())
+server.listen(3000)
+```
+
+## How HTTP Context Works
+
+When a request arrives, the adapter creates an HTTP-specific event context:
+
+```
+Request arrives (req, res)
+  → createHttpContext({ req, res }, options)
+    → AsyncLocalStorage.run(httpContextStore, handler)
+      → router matches path → handler runs
+        → handler calls useRequest(), useCookies(), etc.
+          → each composable calls useHttpContext()
+            → reads/writes the HTTP context store via init(), get(), set()
+```
+
+### The HTTP Context Store
+
+The HTTP adapter extends the base event context with these sections:
+
+```ts
+interface THttpContextStore {
+  searchParams?: TSearchParamsCache               // cached query params
+  cookies?: Record<string, string | null>          // cached parsed cookies
+  setCookies?: Record<string, TSetCookieData>      // outgoing response cookies
+  accept?: Record<string, boolean>                 // cached Accept header checks
+  authorization?: TAuthCache                       // cached auth header parsing
+  setHeader?: Record<string, string | string[]>    // outgoing response headers
+  request?: TRequestCache                          // cached request data (body, IP, etc.)
+  response?: { responded: boolean }                // response sent flag
+  status?: { code: EHttpStatusCode }               // response status code
+}
+```
+
+Every section is lazily initialized — it only exists when a composable first writes to it. This means zero overhead for unused features.
+
+### Extending the HTTP Store for Custom Composables
+
+When creating custom composables for HTTP, extend the store type via the generic parameter on `useHttpContext`:
+
+```ts
+import { useHttpContext } from '@wooksjs/event-http'
+
+interface TMyStore {
+  myFeature?: {
+    parsedToken?: { userId: string; role: string } | null
+    isAdmin?: boolean
+  }
+}
+
+export function useMyFeature() {
+  const { store } = useHttpContext<TMyStore>()
+  const { init } = store('myFeature')
+
+  const parsedToken = () =>
+    init('parsedToken', () => {
+      const { authRawCredentials, isBearer } = useAuthorization()
+      if (!isBearer()) return null
+      return decodeToken(authRawCredentials()!)
+    })
+
+  const isAdmin = () =>
+    init('isAdmin', () => parsedToken()?.role === 'admin')
+
+  return { parsedToken, isAdmin }
+}
+```
+
+For the full context store API and more composable patterns, see [event-core.md](event-core.md).
+
+## Server Lifecycle
+
+### `listen(...)`
+
+Starts a built-in HTTP server:
+
+```ts
+await app.listen(3000)
+await app.listen(3000, '0.0.0.0')
+await app.listen({ port: 3000, host: '0.0.0.0' })
+```
+
+### `close(server?)`
+
+Stops the server:
+
+```ts
+await app.close()
+```
+
+### `getServer()`
+
+Returns the underlying `http.Server` instance (only available after `listen()`):
+
+```ts
+const server = app.getServer()
+```
+
+### `attachServer(server)`
+
+Attaches an external server so `close()` can stop it:
+
+```ts
+const server = http.createServer(app.getServerCb())
+app.attachServer(server)
+server.listen(3000)
+// later: await app.close()
+```
+
+### `getServerCb()`
+
+Returns the raw `(req, res) => void` callback for use with any Node.js HTTP server:
+
+```ts
+const cb = app.getServerCb()
+http.createServer(cb).listen(3000)
+// or with https:
+https.createServer(sslOpts, cb).listen(443)
+```
+
+## Sharing Router Between Adapters
+
+Multiple adapters can share the same Wooks router:
+
+```ts
+import { Wooks } from 'wooks'
+import { createHttpApp } from '@wooksjs/event-http'
+
+const wooks = new Wooks()
+const app1 = createHttpApp({}, wooks)
+const app2 = createHttpApp({}, wooks)  // shares the same routes
+```
+
+Or share via another adapter instance:
+
+```ts
+const app1 = createHttpApp()
+const app2 = createHttpApp({}, app1)  // shares app1's router
+```
+
+## Logging
+
+Get a scoped logger from the app:
+
+```ts
+const app = createHttpApp()
+const logger = app.getLogger('[my-app]')
+logger.log('App started')
+```
+
+Inside a handler, use the event-scoped logger:
+
+```ts
+import { useEventLogger } from '@wooksjs/event-core'
+
+app.get('/process', () => {
+  const logger = useEventLogger('my-handler')
+  logger.log('Processing request')  // tagged with event ID
+  return 'ok'
+})
+```
+
+## Testing
+
+`@wooksjs/event-http` exports a test utility for running composables outside a real server:
+
+```ts
+import { prepareTestHttpContext } from '@wooksjs/event-http'
+
+const runInContext = prepareTestHttpContext({
+  url: '/users/42',
+  method: 'GET',
+  headers: { authorization: 'Bearer test-token' },
+  params: { id: '42' },
+})
+
+runInContext(() => {
+  const { get } = useRouteParams()
+  console.log(get('id'))  // '42'
+
+  const { isBearer } = useAuthorization()
+  console.log(isBearer())  // true
+})
+```
+
+### `prepareTestHttpContext(options)`
+
+```ts
+interface TTestHttpContext {
+  url: string
+  method?: string              // default: 'GET'
+  headers?: Record<string, string>
+  params?: Record<string, string | string[]>
+  requestLimits?: TRequestLimits  // app-level body limits for testing
+  cachedContext?: {
+    cookies?: Record<string, string | null>
+    authorization?: TAuthCache
+    body?: unknown             // pre-parsed body
+    rawBody?: string | Buffer | Promise<Buffer>
+    raw?: Partial<THttpContextStore>  // raw store sections
+  }
+}
+```
+
+## Best Practices
+
+- **Use `createHttpApp()` factory** — Don't instantiate `WooksHttp` directly unless you need to extend the class.
+- **Use `getServerCb()` for custom servers** — This gives you full control over HTTPS, HTTP/2, or any custom server setup.
+- **One composable per concern** — Split auth, validation, user-fetching into separate composables. Compose them in handlers.
+- **Use `prepareTestHttpContext()` for unit testing composables** — Test composable logic without starting a server.
+
+## Gotchas
+
+- Composables must be called within a request handler (inside the async context). Calling them at module load time throws.
+- `listen()` returns a promise — always `await` it or attach error handling.
+- The framework auto-detects content type from your return value (string -> text/plain, object -> application/json). Override with `useSetHeaders().setContentType()`.