@wooksjs/event-http 0.6.6 → 0.7.1

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

@@ -1,220 +1,204 @@
-# Request Utilities — @wooksjs/event-http
+# Request composables — @wooksjs/event-http
 
-> Covers composables for reading incoming request data: headers, cookies, query params, authorization, IP address, and Accept header.
+> Reading request data: headers, cookies, query params, body, authorization, IP address.
 
-## `useRequest()`
+## Concepts
 
-Primary composable for accessing the raw incoming HTTP request.
+All request data is accessed through composables — functions that resolve context via `AsyncLocalStorage`. They take no arguments (optionally accept `ctx` for performance). Data is parsed lazily on first access and cached for the request lifetime.
 
-```ts
-import { useRequest } from '@wooksjs/event-http'
+All composables are importable from `@wooksjs/event-http`.
 
-app.get('/info', () => {
-  const { method, url, headers, rawBody, reqId, getIp } = useRequest()
+## API Reference
 
-  return {
-    method,          // 'GET'
-    url,             // '/info?page=1'
-    host: headers.host,
-    ip: getIp(),
-    requestId: reqId(),
-  }
-})
-```
+### `useRequest(ctx?)`
+
+The primary request composable. Returns method, URL, headers, raw body, IP, and request limit controls.
 
-### Properties & methods
+```ts
+import { useRequest } from '@wooksjs/event-http'
 
-| Name | Type | Description |
-|------|------|-------------|
-| `rawRequest` | `IncomingMessage` | The raw Node.js request object |
-| `method` | `string` | HTTP method (GET, POST, etc.) |
-| `url` | `string` | Raw request URL including query string |
-| `headers` | `IncomingHttpHeaders` | Request headers object |
-| `rawBody()` | `() => Promise<Buffer>` | Lazily reads and decompresses the request body |
-| `reqId()` | `() => string` | Lazily generates a UUID for this request |
-| `getIp(opts?)` | `(opts?) => string` | Returns client IP (supports `trustProxy`) |
-| `getIpList()` | `() => { remoteIp, forwarded }` | Returns all known IPs |
-| `isCompressed()` | `() => boolean` | Whether the body is compressed |
+const { method, url, headers, rawBody, getIp, reqId } = useRequest()
+```
 
-### Body size limits
+**Returned properties:**
 
-| Limit | Default | Description |
-|-------|---------|-------------|
-| `maxCompressed` | 1 MB (1 048 576) | Max compressed body size in bytes |
-| `maxInflated` | 10 MB (10 485 760) | Max decompressed body size in bytes |
-| `maxRatio` | 100 | Max compression ratio (zip-bomb protection) |
-| `readTimeoutMs` | 10 000 | Body read timeout in milliseconds |
+| Property         | Type                                              | Description                                        |
+| ---------------- | ------------------------------------------------- | -------------------------------------------------- |
+| `raw`            | `IncomingMessage`                                 | Node.js raw request object                         |
+| `url`            | `string`                                          | Request URL                                        |
+| `method`         | `string`                                          | HTTP method                                        |
+| `headers`        | `IncomingHttpHeaders`                             | Request headers                                    |
+| `rawBody`        | `() => Promise<Buffer>`                           | Lazy — reads and decompresses request body on call |
+| `reqId`          | `() => string`                                    | Lazy UUID per request                              |
+| `getIp(opts?)`   | `(opts?: { trustProxy: boolean }) => string`      | Client IP (with optional proxy trust)              |
+| `getIpList()`    | `() => { remoteIp: string; forwarded: string[] }` | All IPs (remote + X-Forwarded-For)                 |
+| `isCompressed()` | `() => boolean`                                   | Whether the request body is compressed             |
 
-Limits can be set **app-wide** via `createHttpApp({ requestLimits: { ... } })` (see [core.md](core.md)) or **per-request** via the setters below (which override app defaults):
+**Request limits (per-request override):**
 
 ```ts
-const {
-  getMaxCompressed, setMaxCompressed,  // default: 1 MB
-  getMaxInflated, setMaxInflated,      // default: 10 MB
-  getMaxRatio, setMaxRatio,            // default: 100× (zip-bomb protection)
-  getReadTimeoutMs, setReadTimeoutMs,  // default: 10s
-} = useRequest()
-
-// Override per-route for file uploads
-setMaxCompressed(50 * 1024 * 1024)  // 50 MB
-setMaxInflated(100 * 1024 * 1024)   // 100 MB
-setMaxRatio(200)                    // allow 200× compression ratio
+const { setMaxCompressed, setMaxInflated, setMaxRatio, setReadTimeoutMs } = useRequest()
+setMaxCompressed(5 * 1024 * 1024) // 5 MB
+setReadTimeoutMs(30_000) // 30 seconds
 ```
 
-### IP address with proxy support
+Default limits: `maxCompressed: 1MB`, `maxInflated: 10MB`, `maxRatio: 100`, `readTimeoutMs: 10s`.
 
-```ts
-const { getIp } = useRequest()
+### `useHeaders(ctx?): IncomingHttpHeaders`
 
-// Direct connection IP
-const ip = getIp()
+Returns request headers directly. Shorthand for `useRequest().headers`.
 
-// Trust X-Forwarded-For header (behind reverse proxy)
-const clientIp = getIp({ trustProxy: true })
+```ts
+import { useHeaders } from '@wooksjs/event-http'
+
+const { host, authorization, 'content-type': contentType } = useHeaders()
 ```
 
-## `useHeaders()`
+### `useCookies(ctx?)`
 
-Returns incoming request headers directly:
+Parses incoming request cookies lazily (per cookie name, via `cachedBy`).
 
 ```ts
-import { useHeaders } from '@wooksjs/event-http'
+import { useCookies } from '@wooksjs/event-http'
 
-app.get('/check', () => {
-  const { host, authorization, 'content-type': contentType } = useHeaders()
-  return { host, hasAuth: !!authorization }
-})
+const { getCookie, raw } = useCookies()
+const session = getCookie('session_id') // parsed + cached
+const theme = getCookie('theme') // parsed + cached (different key)
+// raw = raw Cookie header string
 ```
 
-Returns a standard `IncomingHttpHeaders` object (same as `req.headers`).
+### `useUrlParams(ctx?)`
 
-## `useSearchParams()`
-
-Access URL query parameters (lazy-parsed, cached):
+Provides access to URL query parameters.
 
 ```ts
-import { useSearchParams } from '@wooksjs/event-http'
-
-app.get('/search', () => {
-  const { urlSearchParams, jsonSearchParams, rawSearchParams } = useSearchParams()
+import { useUrlParams } from '@wooksjs/event-http'
 
-  // URLSearchParams-like API
-  const page = urlSearchParams().get('page')    // '1'
-  const tags = urlSearchParams().getAll('tag')   // ['a', 'b']
+const { params, toJson, raw } = useUrlParams()
 
-  // As a plain object (handles repeated keys as arrays)
-  const allParams = jsonSearchParams()  // { page: '1', tag: ['a', 'b'] }
+// URLSearchParams API
+const page = params().get('page')
+const tags = params().getAll('tag')
 
-  // Raw query string
-  const raw = rawSearchParams()  // '?page=1&tag=a&tag=b'
+// As a plain object
+const query = toJson() // { page: '1', tag: ['a', 'b'] }
 
-  return { page, tags, allParams }
-})
+// Raw query string
+const rawQuery = raw() // '?page=1&tag=a&tag=b'
 ```
 
-## `useCookies()`
+### `useAuthorization(ctx?)`
 
-Parse incoming request cookies (lazy per-cookie parsing):
+Parses the Authorization header (supports Basic and Bearer).
 
 ```ts
-import { useCookies } from '@wooksjs/event-http'
+import { useAuthorization } from '@wooksjs/event-http'
 
-app.get('/dashboard', () => {
-  const { getCookie, rawCookies } = useCookies()
+const { authorization, type, credentials, is, basicCredentials } = useAuthorization()
 
-  const session = getCookie('session_id')   // 'abc123' or null
-  const theme = getCookie('theme')          // 'dark' or null
+if (is('bearer')) {
+  const token = credentials() // the raw token string
+}
 
-  return { session, theme }
-})
+if (is('basic')) {
+  const { username, password } = basicCredentials()!
+}
 ```
 
-Each cookie is parsed individually on first access and cached. If you never call `getCookie('theme')`, the `theme` cookie is never parsed.
-
-## `useAuthorization()`
+**Returned properties:**
 
-Parse the `Authorization` header (lazy, cached):
+| Property               | Type                             | Description                                                    |
+| ---------------------- | -------------------------------- | -------------------------------------------------------------- |
+| `authorization`        | `string \| undefined`            | Raw Authorization header value                                 |
+| `type()`               | `string \| null`                 | Auth scheme: `'Basic'`, `'Bearer'`, etc.                       |
+| `credentials()`        | `string \| null`                 | Everything after the scheme                                    |
+| `is(type)`             | `boolean`                        | Check auth scheme: `'basic'`, `'bearer'`, or any custom scheme |
+| `basicCredentials()`   | `{ username, password } \| null` | Decoded Basic credentials                                      |
 
-```ts
-import { useAuthorization } from '@wooksjs/event-http'
+### `useAccept(ctx?)`
 
-app.get('/protected', () => {
-  const { isBearer, isBasic, authType, authRawCredentials, basicCredentials } = useAuthorization()
+Checks the request's `Accept` header for MIME type support. Uses short names (`'json'`, `'html'`, `'xml'`, `'text'`) or full MIME types.
 
-  if (isBearer()) {
-    const token = authRawCredentials()  // 'eyJhbGciOi...'
-    // validate JWT
-  }
+```ts
+import { useAccept } from '@wooksjs/event-http'
 
-  if (isBasic()) {
-    const { username, password } = basicCredentials()!
-    // validate credentials
-  }
+const { accept, has } = useAccept()
 
-  return { authType: authType() }  // 'Bearer', 'Basic', etc.
-})
+if (has('json')) {
+  /* ... */
+}
+if (has('image/png')) {
+  /* ... */
+}
 ```
 
-### Methods
+### `useRouteParams<T>(ctx?)`
 
-| Name | Returns | Description |
-|------|---------|-------------|
-| `authorization` | `string \| undefined` | Raw header value |
-| `authType()` | `string \| null` | Auth scheme (Bearer, Basic, etc.) |
-| `authRawCredentials()` | `string \| null` | Everything after the scheme |
-| `isBearer()` | `boolean` | True if Bearer auth |
-| `isBasic()` | `boolean` | True if Basic auth |
-| `basicCredentials()` | `{ username, password } \| null` | Decoded Basic credentials |
+Route parameters from the URL. Re-exported from `@wooksjs/event-core`.
 
-## `useAccept()`
+```ts
+import { useRouteParams } from '@wooksjs/event-http'
 
-Check the `Accept` header for content negotiation:
+// Given route: /users/:id/posts/:postId
+const { params, get } = useRouteParams<{ id: string; postId: string }>()
+params.id // '42'
+get('postId') // '7'
+```
 
-```ts
-import { useAccept } from '@wooksjs/event-http'
+### `useLogger(ctx?): Logger`
 
-app.get('/data', () => {
-  const { acceptsJson, acceptsHtml, acceptsXml, acceptsText, accepts } = useAccept()
+Logger from the current event context. Re-exported from `@wooksjs/event-core`.
 
-  if (acceptsJson()) {
-    return { data: 'json response' }
-  }
-  if (acceptsHtml()) {
-    return '<html><body>HTML response</body></html>'
-  }
-  if (accepts('image/png')) {
-    // custom MIME check
-  }
+```ts
+import { useLogger } from '@wooksjs/event-http'
 
-  return 'plain text fallback'
-})
+const log = useLogger()
+log.info('handling request')
 ```
 
-## `useEventId()`
+## Common Patterns
 
-Generate a unique UUID for the current request (lazy, cached):
+### Pattern: Auth guard with early return
 
 ```ts
-import { useEventId } from '@wooksjs/event-http'
+app.post('/admin/action', async () => {
+  const { is, credentials } = useAuthorization()
+  if (!is('bearer')) throw new HttpError(401)
+
+  const token = credentials()!
+  const user = await verifyToken(token)
+  if (!user.isAdmin) throw new HttpError(403)
 
-app.get('/track', () => {
-  const { getId } = useEventId()
-  return { requestId: getId() }  // '550e8400-e29b-41d4-a716-446655440000'
+  // Body is never parsed if auth fails
+  const { parseBody } = useBody() // from @wooksjs/http-body
+  return parseBody()
 })
 ```
 
-The UUID is generated on first call to `getId()` and cached for the request lifetime.
+### Pattern: Performance — resolve context once
+
+```ts
+import { current } from '@wooksjs/event-core'
+
+app.get('/hot-path', () => {
+  const ctx = current()
+  const { method } = useRequest(ctx)
+  const { getCookie } = useCookies(ctx)
+  const { params } = useUrlParams(ctx)
+  // 1 ALS lookup instead of 3
+})
+```
 
 ## Best Practices
 
-- **Use `useHeaders()` for raw header access**, `useAuthorization()` / `useCookies()` / `useAccept()` for parsed access. Don't manually parse headers when a composable exists.
-- **Call `rawBody()` only once per request** — it reads the stream and returns a Buffer. The result is cached, so subsequent calls return the same promise.
-- **Set limits before reading the body** — Call `setMaxCompressed()` etc. before `rawBody()` if you need non-default limits.
-- **Use `getIp({ trustProxy: true })` only behind a trusted reverse proxy** — otherwise clients can spoof the `X-Forwarded-For` header.
+- Composables are lazy — call them only when you need the data
+- Pass `ctx` explicitly in hot paths with multiple composable calls
+- Use `getCookie(name)` over parsing all cookies when you need only a few
+- `rawBody()` handles decompression (gzip, deflate, brotli) automatically with limits enforcement
 
 ## Gotchas
 
-- `useHeaders()` returns the raw Node.js `IncomingHttpHeaders` where all header names are lowercase.
-- `getCookie()` returns `null` (not `undefined`) when a cookie doesn't exist.
-- `rawBody()` returns a `Promise<Buffer>`. If the body is compressed (gzip/deflate/br), it is automatically decompressed.
-- Body reading has a 10-second timeout by default. If the client sends data slowly, you may need to increase it with `setReadTimeoutMs()`.
+- `rawBody()` returns a `Promise<Buffer>` — always `await` it
+- `rawBody()` consumes the stream — it's cached, so second call returns the same buffer
+- `getCookie()` returns `null` (not `undefined`) when a cookie doesn't exist
+- `useRequest()` limits setters use copy-on-write — they don't affect other requests