@wooksjs/event-http 0.6.2 → 0.6.3

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

@@ -0,0 +1,220 @@
+# Request Utilities — @wooksjs/event-http
+
+> Covers composables for reading incoming request data: headers, cookies, query params, authorization, IP address, and Accept header.
+
+## `useRequest()`
+
+Primary composable for accessing the raw incoming HTTP request.
+
+```ts
+import { useRequest } from '@wooksjs/event-http'
+
+app.get('/info', () => {
+  const { method, url, headers, rawBody, reqId, getIp } = useRequest()
+
+  return {
+    method,          // 'GET'
+    url,             // '/info?page=1'
+    host: headers.host,
+    ip: getIp(),
+    requestId: reqId(),
+  }
+})
+```
+
+### Properties & methods
+
+| 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 |
+
+### Body size limits
+
+| 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 |
+
+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):
+
+```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
+```
+
+### IP address with proxy support
+
+```ts
+const { getIp } = useRequest()
+
+// Direct connection IP
+const ip = getIp()
+
+// Trust X-Forwarded-For header (behind reverse proxy)
+const clientIp = getIp({ trustProxy: true })
+```
+
+## `useHeaders()`
+
+Returns incoming request headers directly:
+
+```ts
+import { useHeaders } from '@wooksjs/event-http'
+
+app.get('/check', () => {
+  const { host, authorization, 'content-type': contentType } = useHeaders()
+  return { host, hasAuth: !!authorization }
+})
+```
+
+Returns a standard `IncomingHttpHeaders` object (same as `req.headers`).
+
+## `useSearchParams()`
+
+Access URL query parameters (lazy-parsed, cached):
+
+```ts
+import { useSearchParams } from '@wooksjs/event-http'
+
+app.get('/search', () => {
+  const { urlSearchParams, jsonSearchParams, rawSearchParams } = useSearchParams()
+
+  // URLSearchParams-like API
+  const page = urlSearchParams().get('page')    // '1'
+  const tags = urlSearchParams().getAll('tag')   // ['a', 'b']
+
+  // As a plain object (handles repeated keys as arrays)
+  const allParams = jsonSearchParams()  // { page: '1', tag: ['a', 'b'] }
+
+  // Raw query string
+  const raw = rawSearchParams()  // '?page=1&tag=a&tag=b'
+
+  return { page, tags, allParams }
+})
+```
+
+## `useCookies()`
+
+Parse incoming request cookies (lazy per-cookie parsing):
+
+```ts
+import { useCookies } from '@wooksjs/event-http'
+
+app.get('/dashboard', () => {
+  const { getCookie, rawCookies } = useCookies()
+
+  const session = getCookie('session_id')   // 'abc123' or null
+  const theme = getCookie('theme')          // 'dark' or null
+
+  return { session, theme }
+})
+```
+
+Each cookie is parsed individually on first access and cached. If you never call `getCookie('theme')`, the `theme` cookie is never parsed.
+
+## `useAuthorization()`
+
+Parse the `Authorization` header (lazy, cached):
+
+```ts
+import { useAuthorization } from '@wooksjs/event-http'
+
+app.get('/protected', () => {
+  const { isBearer, isBasic, authType, authRawCredentials, basicCredentials } = useAuthorization()
+
+  if (isBearer()) {
+    const token = authRawCredentials()  // 'eyJhbGciOi...'
+    // validate JWT
+  }
+
+  if (isBasic()) {
+    const { username, password } = basicCredentials()!
+    // validate credentials
+  }
+
+  return { authType: authType() }  // 'Bearer', 'Basic', etc.
+})
+```
+
+### Methods
+
+| 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 |
+
+## `useAccept()`
+
+Check the `Accept` header for content negotiation:
+
+```ts
+import { useAccept } from '@wooksjs/event-http'
+
+app.get('/data', () => {
+  const { acceptsJson, acceptsHtml, acceptsXml, acceptsText, accepts } = useAccept()
+
+  if (acceptsJson()) {
+    return { data: 'json response' }
+  }
+  if (acceptsHtml()) {
+    return '<html><body>HTML response</body></html>'
+  }
+  if (accepts('image/png')) {
+    // custom MIME check
+  }
+
+  return 'plain text fallback'
+})
+```
+
+## `useEventId()`
+
+Generate a unique UUID for the current request (lazy, cached):
+
+```ts
+import { useEventId } from '@wooksjs/event-http'
+
+app.get('/track', () => {
+  const { getId } = useEventId()
+  return { requestId: getId() }  // '550e8400-e29b-41d4-a716-446655440000'
+})
+```
+
+The UUID is generated on first call to `getId()` and cached for the request lifetime.
+
+## 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.
+
+## 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()`.

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

@@ -0,0 +1,336 @@
+# Response & Status — @wooksjs/event-http
+
+> Covers setting status codes, response headers, outgoing cookies, cache control, and content type.
+
+## Concepts
+
+In Wooks, the response is built through composables rather than mutating the `res` object directly. You call `useResponse()`, `useSetHeaders()`, `useSetCookies()`, etc. to configure the response. All settings are collected in the context store and applied when the framework sends the response.
+
+The framework automatically handles content type detection, serialization, and status code defaults. You only need to explicitly set these when you want non-default behavior.
+
+## `useResponse()`
+
+Core response composable for status codes and raw response access:
+
+```ts
+import { useResponse } from '@wooksjs/event-http'
+
+app.post('/users', () => {
+  const { status } = useResponse()
+  status(201)  // Set status to 201 Created
+  return { id: 1, name: 'Alice' }
+})
+```
+
+### Properties & methods
+
+| Name | Type | Description |
+|------|------|-------------|
+| `status(code?)` | `(code?) => EHttpStatusCode` | Get/set the response status code |
+| `rawResponse(opts?)` | `(opts?) => ServerResponse` | Access the raw Node.js response |
+| `hasResponded()` | `() => boolean` | True if response already sent |
+
+### `status()` as a hookable function
+
+The `status` function doubles as a hookable accessor:
+
+```ts
+const { status } = useResponse()
+
+// Set status
+status(404)
+
+// Read status (call without args)
+const currentStatus = status()
+
+// Or use .value (hooked property)
+status.value = 200
+console.log(status.value)  // 200
+```
+
+### Raw response access
+
+```ts
+const { rawResponse } = useResponse()
+
+// Passthrough mode: lets you write directly but still uses framework headers
+const res = rawResponse({ passthrough: true })
+res.write('chunk 1')
+
+// Default mode: marks response as "handled", framework won't write again
+const res2 = rawResponse()
+res2.writeHead(200)
+res2.end('done')
+```
+
+## `useStatus()`
+
+Standalone status hook — returns a hookable accessor for the status code:
+
+```ts
+import { useStatus } from '@wooksjs/event-http'
+
+app.get('/check', () => {
+  const statusHook = useStatus()
+  statusHook.value = 202
+  return 'Accepted'
+})
+```
+
+This is useful when a utility function needs to set the status without pulling in the full `useResponse()`.
+
+### Type: `TStatusHook`
+
+```ts
+import type { TStatusHook } from '@wooksjs/event-http'
+
+function myMiddleware(status: TStatusHook) {
+  status.value = 403
+}
+```
+
+## `useSetHeaders()`
+
+Set outgoing response headers:
+
+```ts
+import { useSetHeaders } from '@wooksjs/event-http'
+
+app.get('/data', () => {
+  const { setHeader, setContentType, enableCors } = useSetHeaders()
+
+  setHeader('x-request-id', '12345')
+  setContentType('application/xml')
+  enableCors('https://example.com')
+
+  return '<data>hello</data>'
+})
+```
+
+### Methods
+
+| Name | Signature | Description |
+|------|-----------|-------------|
+| `setHeader` | `(name, value) => void` | Set a response header |
+| `getHeader` | `(name) => string \| undefined` | Read a previously set header |
+| `removeHeader` | `(name) => void` | Remove a set header |
+| `setContentType` | `(value) => void` | Shortcut for `setHeader('content-type', value)` |
+| `headers` | `() => Record<string, string>` | Get all set headers as an object |
+| `enableCors` | `(origin?) => void` | Set `Access-Control-Allow-Origin` (default `*`) |
+
+## `useSetHeader(name)`
+
+Returns a hookable accessor for a single response header:
+
+```ts
+import { useSetHeader } from '@wooksjs/event-http'
+
+const xRequestId = useSetHeader('x-request-id')
+xRequestId.value = '12345'
+console.log(xRequestId.value)     // '12345'
+console.log(xRequestId.isDefined) // true
+```
+
+### Type: `THeaderHook`
+
+```ts
+import type { THeaderHook } from '@wooksjs/event-http'
+
+function setCorrelationId(header: THeaderHook) {
+  if (!header.isDefined) {
+    header.value = generateId()
+  }
+}
+```
+
+## `useSetCookies()`
+
+Set outgoing response cookies:
+
+```ts
+import { useSetCookies } from '@wooksjs/event-http'
+
+app.post('/login', () => {
+  const { setCookie, removeCookie, clearCookies } = useSetCookies()
+
+  setCookie('session_id', 'abc123', {
+    httpOnly: true,
+    secure: true,
+    sameSite: 'Strict',
+    maxAge: '7d',  // supports time strings like '1h', '30m', '7d'
+    path: '/',
+  })
+
+  return { success: true }
+})
+```
+
+### Methods
+
+| Name | Signature | Description |
+|------|-----------|-------------|
+| `setCookie` | `(name, value, attrs?) => void` | Set a response cookie |
+| `getCookie` | `(name) => TSetCookieData \| undefined` | Read a previously set cookie |
+| `removeCookie` | `(name) => void` | Remove a set cookie |
+| `clearCookies` | `() => void` | Remove all set cookies |
+| `cookies` | `() => string[]` | Render all cookies as Set-Cookie header strings |
+
+### Cookie Attributes
+
+```ts
+interface TCookieAttributes {
+  expires: Date | string | number       // expiration date
+  maxAge: number | TTimeMultiString     // max age (seconds or time string)
+  domain: string                        // cookie domain
+  path: string                          // cookie path
+  secure: boolean                       // HTTPS only
+  httpOnly: boolean                     // no JS access
+  sameSite: boolean | 'Lax' | 'None' | 'Strict'
+}
+```
+
+Time strings (`TTimeMultiString`) support formats like `'1h'`, `'30m'`, `'7d'`, `'1y'`.
+
+## `useSetCookie(name)`
+
+Hookable accessor for a single outgoing cookie:
+
+```ts
+import { useSetCookie } from '@wooksjs/event-http'
+
+const sessionCookie = useSetCookie('session_id')
+
+// Set value
+sessionCookie.value = 'abc123'
+
+// Set attributes
+sessionCookie.attrs = { httpOnly: true, secure: true }
+
+// Read
+console.log(sessionCookie.value)  // 'abc123'
+console.log(sessionCookie.attrs)  // { httpOnly: true, secure: true }
+```
+
+### Type: `TCookieHook`
+
+```ts
+import type { TCookieHook } from '@wooksjs/event-http'
+
+function enforceSecureCookie(cookie: TCookieHook) {
+  cookie.attrs = { ...cookie.attrs, secure: true, httpOnly: true }
+}
+```
+
+## `useSetCacheControl()`
+
+Set cache-related response headers:
+
+```ts
+import { useSetCacheControl } from '@wooksjs/event-http'
+
+app.get('/assets/:file', () => {
+  const { setCacheControl, setExpires, setAge, setPragmaNoCache } = useSetCacheControl()
+
+  setCacheControl({
+    maxAge: 3600,
+    public: true,
+    noTransform: true,
+  })
+
+  // Or set individual cache headers
+  setAge(300)                   // Age: 300
+  setExpires(new Date('2025-12-31'))  // Expires: Wed, 31 Dec 2025 ...
+  setPragmaNoCache()            // Pragma: no-cache
+
+  return serveFile(...)
+})
+```
+
+### Cache-Control Directives
+
+```ts
+interface TCacheControl {
+  maxAge?: number | TTimeMultiString
+  sMaxage?: number | TTimeMultiString
+  noCache?: boolean
+  noStore?: boolean
+  noTransform?: boolean
+  mustRevalidate?: boolean
+  proxyRevalidate?: boolean
+  public?: boolean
+  private?: boolean
+  immutable?: boolean
+  staleWhileRevalidate?: number | TTimeMultiString
+  staleIfError?: number | TTimeMultiString
+}
+```
+
+## Content Type Auto-Detection
+
+The framework automatically sets the content type based on the handler return value:
+
+| Return type | Content-Type |
+|-------------|-------------|
+| `string` | `text/plain` |
+| `number` | `text/plain` |
+| `boolean` | `text/plain` |
+| `object` / `array` | `application/json` |
+| `Readable` stream | (must set manually) |
+| `undefined` | (no body, 204) |
+
+Override by calling `setContentType()` before returning:
+
+```ts
+app.get('/html', () => {
+  const { setContentType } = useSetHeaders()
+  setContentType('text/html')
+  return '<h1>Hello</h1>'
+})
+```
+
+## Common Patterns
+
+### Pattern: JSON API Response
+
+```ts
+app.get('/api/users/:id', async () => {
+  const { get } = useRouteParams<{ id: string }>()
+  const user = await db.findUser(get('id'))
+  if (!user) throw new HttpError(404, 'User not found')
+  return user  // auto-serialized as JSON with 200
+})
+```
+
+### Pattern: File Download
+
+```ts
+app.get('/download/:file', () => {
+  const { setHeader } = useSetHeaders()
+  const { get } = useRouteParams<{ file: string }>()
+  setHeader('content-disposition', `attachment; filename="${get('file')}"`)
+  return createReadStream(`/uploads/${get('file')}`)
+})
+```
+
+### Pattern: Redirect
+
+```ts
+import { BaseHttpResponse } from '@wooksjs/event-http'
+
+app.get('/old-page', () => {
+  return new BaseHttpResponse().setStatus(302).setHeader('location', '/new-page')
+})
+```
+
+## Best Practices
+
+- **Let the framework auto-detect content type** — Only call `setContentType()` when you need a non-default type.
+- **Use `useSetCookies()` for multiple cookies, `useSetCookie(name)` for hookable access to a single cookie**.
+- **Set status before returning** — If you need a custom status, call `status(code)` before the handler returns.
+- **Use time strings for maxAge** — `'7d'` is clearer than `604800`.
+
+## Gotchas
+
+- If you call `rawResponse()` without `{ passthrough: true }`, the framework marks the response as sent and won't write anything else.
+- Headers set via `useSetHeaders()` are merged with any `BaseHttpResponse` headers. The `BaseHttpResponse` headers take precedence on collision.
+- Cookies set via `useSetCookies()` are merged with `BaseHttpResponse.setCookie()` cookies.