@wooksjs/event-http 0.6.1 → 0.6.3

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()`.

package/skills/wooksjs-event-http/error-handling.md

@@ -0,0 +1,253 @@
+# 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.