@moostjs/event-http 0.5.32 → 0.6.0

package/skills/moostjs-event-http/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: moostjs-event-http
+description: Use this skill when working with @moostjs/event-http — to create an HTTP server with MoostHttp adapter, register route handlers with @Get()/@Post()/@Put()/@Delete()/@Patch()/@All(), extract request data with @Query(), @Header(), @Cookie(), @Body(), @RawBody(), @Authorization(), @Url(), @Method(), @Req(), @Res(), @ReqId(), @Ip(), @IpList(), control responses with @SetHeader(), @SetCookie(), @SetStatus(), @StatusHook(), @HeaderHook(), @CookieHook(), @CookieAttrsHook(), throw HTTP errors with HttpError, enforce body limits with @BodySizeLimit()/@CompressedBodySizeLimit()/@BodyReadTimeoutMs(), define auth guards with defineAuthGuard()/AuthGuard/Authenticate, or handle WebSocket upgrades with @Upgrade().
+---
+
+# @moostjs/event-http
+
+Moost HTTP adapter — decorator-driven HTTP server built on `@wooksjs/event-http`. Provides route decorators, request data extractors, response control, auth guards, and body limits for Moost applications.
+
+## How to use this skill
+
+Read the domain file that matches the task. Do not load all files — only what you need.
+
+| Domain | File | Load when... |
+|--------|------|------------|
+| Core concepts & setup | [core.md](core.md) | Starting a new project, understanding the mental model, configuring MoostHttp adapter |
+| Routing & handlers | [routing.md](routing.md) | Defining routes with @Get/@Post/etc, route parameters, wildcards, path patterns |
+| Request data | [request.md](request.md) | Extracting query params, headers, cookies, body, auth, IP, URL from requests |
+| Response control | [response.md](response.md) | Setting status codes, headers, cookies, error handling, raw response access |
+| Authentication | [auth.md](auth.md) | Auth guards, credential extraction, bearer/basic/apiKey/cookie transports, @Authenticate |
+
+## Quick reference
+
+```ts
+// Imports
+import { MoostHttp, Get, Post, Put, Delete, Patch, All, HttpMethod, Upgrade } from '@moostjs/event-http'
+import { Query, Header, Cookie, Body, RawBody, Authorization, Url, Method, Req, Res, ReqId, Ip, IpList } from '@moostjs/event-http'
+import { SetHeader, SetCookie, SetStatus, StatusHook, HeaderHook, CookieHook, CookieAttrsHook } from '@moostjs/event-http'
+import { BodySizeLimit, CompressedBodySizeLimit, BodyReadTimeoutMs } from '@moostjs/event-http'
+import { Authenticate, AuthGuard, defineAuthGuard, HttpError } from '@moostjs/event-http'
+import { Controller, Param, Params } from 'moost'
+```

package/skills/moostjs-event-http/auth.md

@@ -0,0 +1,275 @@
+# Authentication — @moostjs/event-http
+
+> Declarative auth guards with automatic credential extraction and Swagger integration.
+
+## Concepts
+
+The auth guard system has three components:
+
+1. **Transport declaration** — describes *where* credentials come from (bearer token, basic auth, API key, cookie)
+2. **Guard handler** — your verification logic, receives the extracted credentials
+3. **`@Authenticate` decorator** — applies the guard to a controller or handler
+
+Two APIs are provided:
+- **Functional** (`defineAuthGuard`) — stateless, simple guards
+- **Class-based** (`AuthGuard`) — when you need dependency injection
+
+Auth guard transport declarations are stored in metadata, enabling automatic Swagger/OpenAPI security scheme discovery.
+
+## API Reference
+
+### `defineAuthGuard(transports, handler)`
+
+Create a functional auth guard.
+
+```ts
+import { defineAuthGuard, HttpError } from '@moostjs/event-http'
+
+const jwtGuard = defineAuthGuard(
+  { bearer: { format: 'JWT' } },
+  (transports) => {
+    const user = verifyJwt(transports.bearer)
+    if (!user) throw new HttpError(401, 'Invalid token')
+    // return value is optional — if returned, it becomes the handler's response (short-circuit)
+  },
+)
+```
+
+**Parameters:**
+- `transports: TAuthTransportDeclaration` — which credentials to extract
+- `handler: (transports: TAuthTransportValues<T>) => unknown | Promise<unknown>` — verification logic
+
+**Returns:** `TAuthGuardDef` — an interceptor def with transport metadata attached.
+
+### `AuthGuard<T>`
+
+Abstract base class for class-based auth guards. Use when you need DI.
+
+```ts
+import { AuthGuard, HttpError } from '@moostjs/event-http'
+import { Injectable } from 'moost'
+
+@Injectable()
+class JwtGuard extends AuthGuard<{ bearer: { format: 'JWT' } }> {
+  static transports = { bearer: { format: 'JWT' } } as const
+
+  constructor(private userService: UserService) {}
+
+  handle(transports: { bearer: string }) {
+    const user = this.userService.verifyToken(transports.bearer)
+    if (!user) throw new HttpError(401, 'Invalid token')
+  }
+}
+```
+
+Requirements:
+- Extend `AuthGuard<T>` with transport declaration as generic parameter
+- Set `static transports` matching the generic (read at runtime)
+- Implement `handle(transports)` with verification logic
+- Use `@Injectable()` for constructor injection
+
+### `@Authenticate(handler)`
+
+Apply an auth guard to a controller or handler method.
+
+```ts
+import { Authenticate, Get } from '@moostjs/event-http'
+import { Controller } from 'moost'
+
+// Controller-level — all handlers require auth
+@Authenticate(jwtGuard)
+@Controller('users')
+class UsersController {
+  @Get('')
+  list() {}
+
+  @Get(':id')
+  find() {}
+}
+
+// Handler-level — specific endpoints only
+@Controller('products')
+class ProductsController {
+  @Get('')
+  list() { /* public */ }
+
+  @Authenticate(jwtGuard)
+  @Post('')
+  create() { /* requires auth */ }
+}
+```
+
+Accepts both functional (`TAuthGuardDef`) and class-based (`TAuthGuardClass`) guards.
+
+### `extractTransports(declaration)`
+
+Low-level function that extracts credentials from the current request context. Called internally by auth guards — rarely needed directly.
+
+```ts
+import { extractTransports } from '@moostjs/event-http'
+
+const values = extractTransports({ bearer: { format: 'JWT' } })
+// values.bearer = 'eyJ...' (the raw token)
+```
+
+Throws `HttpError(401, 'No authentication credentials provided')` if none of the declared transports are present.
+
+## Transport types
+
+### Bearer token
+
+Extracts from `Authorization: Bearer <token>`:
+
+```ts
+{ bearer: { format?: string, description?: string } }
+// Extracted value: string (raw token without "Bearer " prefix)
+```
+
+### Basic authentication
+
+Extracts from `Authorization: Basic <base64>`:
+
+```ts
+{ basic: { description?: string } }
+// Extracted value: { username: string, password: string }
+```
+
+### API key
+
+Extracts from a header, query parameter, or cookie:
+
+```ts
+{ apiKey: { name: string, in: 'header' | 'query' | 'cookie', description?: string } }
+// Extracted value: string
+```
+
+```ts
+// From header
+defineAuthGuard({ apiKey: { name: 'X-API-Key', in: 'header' } }, (t) => { t.apiKey /* string */ })
+
+// From query param
+defineAuthGuard({ apiKey: { name: 'api_key', in: 'query' } }, (t) => { t.apiKey /* string */ })
+
+// From cookie
+defineAuthGuard({ apiKey: { name: 'api_key', in: 'cookie' } }, (t) => { t.apiKey /* string */ })
+```
+
+### Cookie
+
+Extracts a value from a named cookie:
+
+```ts
+{ cookie: { name: string, description?: string } }
+// Extracted value: string
+```
+
+## Common Patterns
+
+### Pattern: JWT bearer guard
+
+```ts
+const jwtGuard = defineAuthGuard(
+  { bearer: { format: 'JWT', description: 'JWT access token' } },
+  (transports) => {
+    const payload = verifyJwt(transports.bearer)
+    if (!payload) throw new HttpError(401, 'Invalid or expired token')
+  },
+)
+```
+
+### Pattern: API key guard
+
+```ts
+const apiKeyGuard = defineAuthGuard(
+  { apiKey: { name: 'X-API-Key', in: 'header' } },
+  (transports) => {
+    if (!isValidApiKey(transports.apiKey)) {
+      throw new HttpError(401, 'Invalid API key')
+    }
+  },
+)
+```
+
+### Pattern: Auth + authorization stacking
+
+```ts
+@Authenticate(jwtGuard)          // step 1: verify credentials
+@RequireRole('admin')            // step 2: check authorization
+@Controller('admin')
+class AdminController {
+  @Get('dashboard')
+  dashboard() { /* authenticated + admin */ }
+}
+```
+
+### Pattern: Class-based guard with DI
+
+```ts
+@Injectable()
+class SessionGuard extends AuthGuard<{ cookie: { name: 'session' } }> {
+  static transports = { cookie: { name: 'session' } } as const
+
+  constructor(private sessionService: SessionService) {}
+
+  handle(transports: { cookie: string }) {
+    const session = this.sessionService.validate(transports.cookie)
+    if (!session) throw new HttpError(401, 'Invalid session')
+  }
+}
+
+@Authenticate(SessionGuard)
+@Controller('dashboard')
+class DashboardController {}
+```
+
+### Pattern: Handler-level override
+
+```ts
+@Authenticate(apiKeyGuard)
+@Controller('products')
+class ProductsController {
+  @Get('')
+  list() { /* uses apiKeyGuard */ }
+
+  @Authenticate(basicGuard)
+  @Post('')
+  create() { /* uses basicGuard instead */ }
+}
+```
+
+## Integration
+
+- **Swagger**: Transport declarations map directly to OpenAPI security schemes. The `@moostjs/swagger` package auto-discovers `@Authenticate` metadata.
+- **Guards**: Auth guards run at `GUARD` priority. Combine with custom authorization guards (also at `GUARD` priority) — they execute in decorator declaration order.
+
+## Types
+
+```ts
+interface TAuthTransportDeclaration {
+  bearer?: { format?: string; description?: string }
+  basic?: { description?: string }
+  apiKey?: { name: string; in: 'header' | 'query' | 'cookie'; description?: string }
+  cookie?: { name: string; description?: string }
+}
+
+type TAuthTransportValues<T> = {
+  [K in keyof T]: K extends 'basic' ? { username: string; password: string } : string
+}
+
+type TAuthGuardHandler = TAuthGuardDef | TAuthGuardClass
+```
+
+## Best Practices
+
+- Use functional guards (`defineAuthGuard`) for simple, stateless checks
+- Use class-based guards (`AuthGuard`) when you need DI services (e.g., database, token service)
+- Apply `@Authenticate` at the controller level for protected resources, handler level for mixed access
+- Always throw `HttpError` with meaningful messages for auth failures
+- Combine with `@moostjs/swagger` for automatic OpenAPI security documentation
+
+## Gotchas
+
+- If none of the declared transports are present in the request, `extractTransports` throws `HttpError(401)` automatically — your handler won't be called
+- Class-based guards must set `static transports` — it's read at runtime, not from the generic parameter
+- Auth guards run at `GUARD` priority — they execute before `INTERCEPTOR`-priority interceptors
+- The handler's return value (if any) short-circuits the response — use this for redirects or custom auth responses

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

@@ -0,0 +1,193 @@
+# Core concepts & setup — @moostjs/event-http
+
+> How to create and configure an HTTP server with the Moost HTTP adapter.
+
+## Concepts
+
+`@moostjs/event-http` is the HTTP adapter for the Moost framework. It bridges Moost's decorator-driven controller system with `@wooksjs/event-http` (the underlying HTTP engine). The adapter handles:
+
+- Binding decorated handler methods to HTTP routes
+- Managing request scoping and cleanup
+- Providing dependency injection for the underlying WooksHttp instance
+
+**Key classes:**
+- `MoostHttp` — the adapter class you instantiate and attach to your Moost app
+- `WooksHttp` — the underlying Wooks HTTP engine (available via DI if needed)
+
+## Installation
+
+```bash
+npm install @moostjs/event-http moost
+# or
+pnpm add @moostjs/event-http moost
+```
+
+Peer dependencies (installed automatically with moost):
+- `@wooksjs/event-core` — async event context
+- `@prostojs/infact` — dependency injection
+- `@prostojs/router` — route matching
+
+## Setup
+
+### Minimal HTTP server
+
+```ts
+import { MoostHttp, Get } from '@moostjs/event-http'
+import { Moost, Controller, Param } from 'moost'
+
+@Controller()
+class AppController {
+  @Get('hello/:name')
+  greet(@Param('name') name: string) {
+    return `Hello, ${name}!`
+  }
+}
+
+const app = new Moost()
+void app.adapter(new MoostHttp()).listen(3000, () => {
+  app.getLogger('app').info('Up on port 3000')
+})
+void app.registerControllers(AppController).init()
+```
+
+### Scaffold a project
+
+```bash
+npm create moost -- --http
+# or with a name:
+npm create moost my-web-app -- --http
+```
+
+## API Reference
+
+### `MoostHttp`
+
+The HTTP adapter class implementing `TMoostAdapter`.
+
+```ts
+import { MoostHttp } from '@moostjs/event-http'
+
+// Default — creates a new WooksHttp internally
+const http = new MoostHttp()
+
+// With options passed to WooksHttp
+const http = new MoostHttp({ onNotFound: customHandler })
+
+// With an existing WooksHttp instance
+const http = new MoostHttp(existingWooksHttp)
+```
+
+**Methods:**
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `listen(port?, ...)` | `Promise<void>` | Start the HTTP server (same overloads as `net.Server.listen`) |
+| `getHttpApp()` | `WooksHttp` | Access the underlying Wooks HTTP engine |
+| `getServerCb()` | `RequestListener` | Get the request handler callback for use with existing Node.js servers |
+
+### `getServerCb()` — Custom server integration
+
+Use `getServerCb()` to integrate with an existing Node.js HTTP/HTTPS server:
+
+```ts
+import { createServer } from 'https'
+import { MoostHttp } from '@moostjs/event-http'
+import { Moost } from 'moost'
+
+const http = new MoostHttp()
+const app = new Moost()
+app.adapter(http)
+
+const server = createServer(tlsOptions, http.getServerCb())
+server.listen(443)
+await app.init()
+```
+
+### `HttpError`
+
+Re-exported from `@wooksjs/event-http`. Throw to produce an HTTP error response with a specific status code.
+
+```ts
+import { HttpError } from '@moostjs/event-http'
+
+throw new HttpError(404, 'Not Found')
+throw new HttpError(422, { message: 'Validation failed', errors: [...] })
+```
+
+### `httpKind`
+
+Re-exported from `@wooksjs/event-http`. The event kind identifier for HTTP events.
+
+### `useHttpContext()`
+
+Re-exported from `@wooksjs/event-http`. Access the raw Wooks HTTP context from within a handler (advanced use only — prefer decorators).
+
+## Common Patterns
+
+### Pattern: Class extending Moost
+
+Instead of creating a separate `Moost` instance and registering controllers, extend `Moost` directly:
+
+```ts
+import { MoostHttp, Get } from '@moostjs/event-http'
+import { Moost, Param } from 'moost'
+
+class MyServer extends Moost {
+  @Get('test/:name')
+  test(@Param('name') name: string) {
+    return { message: `Hello ${name}!` }
+  }
+}
+
+const app = new MyServer()
+app.adapter(new MoostHttp()).listen(3000)
+void app.init()
+```
+
+### Pattern: Multiple controllers
+
+```ts
+import { Moost } from 'moost'
+import { MoostHttp } from '@moostjs/event-http'
+
+const app = new Moost()
+app.adapter(new MoostHttp()).listen(3000)
+void app
+  .registerControllers(UserController, ProductController, OrderController)
+  .init()
+```
+
+## DI-available services
+
+When MoostHttp is attached, these are available via constructor injection:
+
+| Token | Type | Description |
+|-------|------|-------------|
+| `WooksHttp` | class | The underlying Wooks HTTP app |
+| `'WooksHttp'` | string | Same, by string token |
+| `HttpServer` | `http.Server` | The Node.js HTTP server instance |
+| `HttpsServer` | `https.Server` | The Node.js HTTPS server instance |
+
+```ts
+import { Injectable } from 'moost'
+import { WooksHttp } from '@wooksjs/event-http'
+
+@Injectable()
+class MyService {
+  constructor(private wooks: WooksHttp) {}
+}
+```
+
+## Best Practices
+
+- Call `app.adapter(http).listen(port)` before `app.init()` — the adapter must be attached before initialization
+- Use `registerControllers()` to add controller classes, not instances
+- Prefer the decorator-based API (`@Get`, `@Body`, etc.) over accessing wooks composables directly
+- Use `getServerCb()` when integrating with existing HTTP/HTTPS servers instead of calling `listen()`
+
+## Gotchas
+
+- The `path` argument in route decorators is optional — when omitted, the method name is used as the path segment
+- `@Get('')` (empty string) maps to the controller root, while `@Get()` (no argument) uses the method name
+- `app.init()` must be called after `registerControllers()` — routes are bound during initialization
+- MoostHttp registers a default 404 handler that runs through the global interceptor chain