@wooksjs/event-http 0.6.5 → 0.7.0

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

@@ -1,307 +0,0 @@
-# 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/error-handling.md

@@ -1,253 +0,0 @@
-# Error Handling — @wooksjs/event-http
-
-> Covers throwing HTTP errors, custom error bodies, error rendering, and error flow.
-
-## Concepts
-
-In Wooks, errors are raised by throwing an `HttpError` instance. The framework catches it and renders an appropriate error response based on the client's `Accept` header (JSON, HTML, or plain text).
-
-Any uncaught `Error` thrown in a handler is automatically wrapped as a 500 Internal Server Error.
-
-## `HttpError`
-
-```ts
-import { HttpError } from '@wooksjs/event-http'
-```
-
-### Basic usage
-
-```ts
-app.get('/users/:id', async () => {
-  const user = await db.findUser(id)
-  if (!user) {
-    throw new HttpError(404, 'User not found')
-  }
-  return user
-})
-```
-
-This produces a response like:
-
-```json
-{ "statusCode": 404, "error": "Not Found", "message": "User not found" }
-```
-
-### Status code only
-
-```ts
-throw new HttpError(403)
-// → { "statusCode": 403, "error": "Forbidden", "message": "" }
-```
-
-The `error` field is automatically populated from the standard HTTP status text.
-
-### Custom error body
-
-Pass an object as the second argument for additional fields:
-
-```ts
-throw new HttpError(422, {
-  message: 'Validation failed',
-  statusCode: 422,
-  fields: {
-    email: 'Invalid email format',
-    age: 'Must be positive',
-  },
-})
-```
-
-Response:
-
-```json
-{
-  "statusCode": 422,
-  "error": "Unprocessable Entity",
-  "message": "Validation failed",
-  "fields": {
-    "email": "Invalid email format",
-    "age": "Must be positive"
-  }
-}
-```
-
-### Constructor signature
-
-```ts
-class HttpError<T extends TWooksErrorBody = TWooksErrorBody> extends Error {
-  constructor(
-    code: THttpErrorCodes = 500,  // HTTP status code (4xx, 5xx)
-    body: string | T = '',         // message string or structured body
-  )
-
-  get body(): TWooksErrorBodyExt  // always returns { statusCode, message, error, ...extra }
-}
-```
-
-### Error body shape
-
-```ts
-interface TWooksErrorBody {
-  message: string
-  statusCode: EHttpStatusCode
-  error?: string
-}
-
-// Extended (always has error string)
-interface TWooksErrorBodyExt extends TWooksErrorBody {
-  error: string  // e.g. 'Not Found', 'Internal Server Error'
-}
-```
-
-## Error Flow
-
-1. Handler throws `HttpError` → framework catches it
-2. Error body is constructed via `httpError.body` getter
-3. `HttpErrorRenderer` checks the `Accept` header:
-   - `application/json` → JSON response
-   - `text/html` → styled HTML error page
-   - `text/plain` → plain text
-   - fallback → JSON
-4. Status code from the error is set on the response
-
-### Uncaught errors
-
-Any non-`HttpError` thrown in a handler is wrapped as a 500:
-
-```ts
-app.get('/crash', () => {
-  throw new Error('something broke')
-  // → 500 Internal Server Error: "something broke"
-})
-```
-
-### Error in handler chain
-
-If multiple handlers are registered for a route, an error in a non-last handler falls through to the next handler. Only the last handler's error is sent as the response:
-
-```ts
-// This is the internal behavior — typically you register one handler per route
-```
-
-## Common Patterns
-
-### Pattern: Guard function
-
-```ts
-function requireAuth() {
-  const { isBearer, authRawCredentials } = useAuthorization()
-  if (!isBearer()) {
-    throw new HttpError(401, 'Authentication required')
-  }
-  const token = authRawCredentials()!
-  const user = verifyToken(token)
-  if (!user) {
-    throw new HttpError(401, 'Invalid token')
-  }
-  return user
-}
-
-app.get('/protected', () => {
-  const user = requireAuth()
-  return { message: `Hello ${user.name}` }
-})
-```
-
-### Pattern: Validation with details
-
-```ts
-function validateBody(data: unknown): asserts data is CreateUserDTO {
-  const errors: Record<string, string> = {}
-
-  if (!data || typeof data !== 'object') {
-    throw new HttpError(400, 'Request body must be an object')
-  }
-
-  const body = data as Record<string, unknown>
-  if (!body.email) errors.email = 'Required'
-  if (!body.name) errors.name = 'Required'
-
-  if (Object.keys(errors).length > 0) {
-    throw new HttpError(422, {
-      message: 'Validation failed',
-      statusCode: 422,
-      fields: errors,
-    })
-  }
-}
-```
-
-### Pattern: Not Found with context
-
-```ts
-app.get('/users/:id', async () => {
-  const { get } = useRouteParams<{ id: string }>()
-  const id = get('id')
-  const user = await db.findUser(id)
-  if (!user) {
-    throw new HttpError(404, `User with id "${id}" not found`)
-  }
-  return user
-})
-```
-
-### Pattern: Custom 404 handler
-
-```ts
-const app = createHttpApp({
-  onNotFound: () => {
-    const { url } = useRequest()
-    throw new HttpError(404, `Route ${url} does not exist`)
-  },
-})
-```
-
-## Available Status Codes
-
-`HttpError` accepts any valid HTTP error status code. Common ones:
-
-| Code | Meaning |
-|------|---------|
-| 400 | Bad Request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not Found |
-| 405 | Method Not Allowed |
-| 408 | Request Timeout |
-| 409 | Conflict |
-| 413 | Payload Too Large |
-| 415 | Unsupported Media Type |
-| 416 | Range Not Satisfiable |
-| 422 | Unprocessable Entity |
-| 429 | Too Many Requests |
-| 500 | Internal Server Error |
-| 502 | Bad Gateway |
-| 503 | Service Unavailable |
-
-The `EHttpStatusCode` enum from `@wooksjs/event-http` provides all standard codes.
-
-## Built-in Error Responses
-
-The framework automatically throws `HttpError` in certain situations:
-
-| Situation | Code | Message |
-|-----------|------|---------|
-| No route matched | 404 | (empty) |
-| Body too large (compressed) | 413 | Payload Too Large |
-| Body too large (inflated) | 413 | Inflated body too large |
-| Compression ratio too high | 413 | Compression ratio too high |
-| Unsupported Content-Encoding | 415 | Unsupported Content-Encoding "..." |
-| Body read timeout | 408 | Request body timeout |
-| Malformed JSON body | 400 | (parse error message) |
-| Missing form-data boundary | 400 | form-data boundary not recognized |
-
-## Best Practices
-
-- **Throw `HttpError`, don't return error objects** — The framework detects `HttpError` specially and renders it with correct status and content negotiation.
-- **Use meaningful status codes** — 400 for bad input, 401 for missing auth, 403 for insufficient permissions, 404 for not found, 422 for validation errors.
-- **Include context in error messages** — `"User with id 42 not found"` is more useful than `"Not found"`.
-- **Use guard functions** — Extract auth/validation into reusable functions that throw on failure.
-
-## Gotchas
-
-- Throwing a plain `Error` (not `HttpError`) results in a 500 with the error's message exposed. In production, you may want to catch and wrap errors to avoid leaking internals.
-- `HttpError.body` always includes an `error` field with the standard HTTP status text, even if you didn't provide one.