@moostjs/event-ws 0.6.0

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

@@ -0,0 +1,42 @@
+---
+name: moostjs-event-ws
+description: Use this skill when working with @moostjs/event-ws — to build WebSocket servers with Moost using MoostWs adapter or WsApp quick factory, register message handlers with @Message(), handle connections with @Connect()/@Disconnect(), extract data with @MessageData()/@ConnectionId()/@RawMessage()/@MessageId()/@MessageType()/@MessagePath(), use composables like useWsConnection(), useWsMessage(), useWsRooms(), useWsServer(), manage rooms and broadcasting, integrate with @moostjs/event-http via @Upgrade() routes, throw WsError for error replies, or test handlers with prepareTestWsConnectionContext()/prepareTestWsMessageContext(). Covers the wire protocol (WsClientMessage, WsReplyMessage, WsPushMessage), standalone and HTTP-integrated modes, heartbeat, custom serializers, and multi-instance broadcasting with WsBroadcastTransport.
+---
+
+# @moostjs/event-ws
+
+Moost WebSocket adapter — decorator-based routing, DI, interceptors, and pipes for WebSocket handlers, wrapping `@wooksjs/event-ws`.
+
+## 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, choosing standalone vs HTTP-integrated mode, configuring MoostWs or WsApp |
+| Handlers | [handlers.md](handlers.md) | Defining @Message, @Connect, @Disconnect handlers, understanding handler lifecycle |
+| Routing | [routing.md](routing.md) | Event+path routing, controller prefixes, parametric routes, wildcards |
+| Request data | [request-data.md](request-data.md) | Extracting message data, connection info, route params with resolver decorators |
+| Rooms & broadcasting | [rooms.md](rooms.md) | Room management, broadcasting, direct sends, server-wide queries, multi-instance scaling |
+| Wire protocol | [protocol.md](protocol.md) | JSON message format, client/server message types, error codes, heartbeat, custom serialization |
+| Testing | [testing.md](testing.md) | Unit-testing handlers with prepareTestWsMessageContext/prepareTestWsConnectionContext |
+
+## Quick reference
+
+```ts
+import {
+  // Adapter & factory
+  MoostWs, WsApp, WooksWs,
+  // Decorators
+  Message, Connect, Disconnect,
+  MessageData, RawMessage, MessageId, MessageType, MessagePath, ConnectionId,
+  // Composables
+  useWsConnection, useWsMessage, useWsRooms, useWsServer, currentConnection,
+  // Errors
+  WsError,
+  // Testing
+  prepareTestWsMessageContext, prepareTestWsConnectionContext,
+  // Re-exports from moost
+  Controller, Param, Intercept, Description,
+} from '@moostjs/event-ws'
+```

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

@@ -0,0 +1,157 @@
+# Core concepts & setup — @moostjs/event-ws
+
+> Installation, mental model, standalone vs HTTP-integrated modes, and adapter configuration.
+
+## Concepts
+
+`@moostjs/event-ws` is a Moost adapter for WebSocket events. It wraps `@wooksjs/event-ws` and adds decorator-based routing, dependency injection, interceptors, and pipes to WebSocket handlers.
+
+**Two modes:**
+- **Standalone** — dedicated WebSocket server, no HTTP. Use `WsApp` for quick setup or `MoostWs` with `listen()`.
+- **HTTP-integrated** (recommended for production) — shares the HTTP port, requires explicit `@Upgrade()` route from `@moostjs/event-http`.
+
+**Wire protocol:** JSON-over-WebSocket with `event` + `path` routing. Clients send `{ event, path, data?, id? }`. Server replies with `{ id, data?, error? }` or pushes `{ event, path, data? }`.
+
+## Installation
+
+```bash
+npm install @moostjs/event-ws
+```
+
+For HTTP-integrated mode, also install:
+```bash
+npm install @moostjs/event-ws @moostjs/event-http
+```
+
+## Standalone Mode — WsApp
+
+`WsApp` extends `Moost` and sets up a standalone `MoostWs` adapter automatically:
+
+```ts
+import { WsApp, Message, MessageData, Connect, ConnectionId } from '@moostjs/event-ws'
+import { Controller } from 'moost'
+
+@Controller()
+class ChatController {
+  @Connect()
+  onConnect(@ConnectionId() id: string) {
+    console.log(`Connected: ${id}`)
+  }
+
+  @Message('echo', '/echo')
+  echo(@MessageData() data: unknown) {
+    return data
+  }
+}
+
+new WsApp()
+  .controllers(ChatController)
+  .start(3000)
+```
+
+### WsApp API
+
+```ts
+class WsApp extends Moost {
+  controllers(...controllers: (object | Function | [string, object | Function])[]): this
+  useWsOptions(opts: { ws?: TWooksWsOptions }): this
+  getWsAdapter(): MoostWs | undefined
+  start(port: number, hostname?: string): Promise<void>
+}
+```
+
+## HTTP-Integrated Mode — MoostWs
+
+Pass the HTTP app to share the port. Requires an `@Upgrade()` route:
+
+```ts
+import { MoostHttp } from '@moostjs/event-http'
+import { MoostWs } from '@moostjs/event-ws'
+import { Moost } from 'moost'
+
+const app = new Moost()
+const http = new MoostHttp()
+const ws = new MoostWs({ httpApp: http.getHttpApp() })
+
+app.adapter(http)
+app.adapter(ws)
+app.registerControllers(AppController, ChatController)
+
+await http.listen(3000)
+await app.init()
+```
+
+The upgrade controller:
+
+```ts
+import { Upgrade } from '@moostjs/event-http'
+import type { WooksWs } from '@moostjs/event-ws'
+import { Controller, Inject } from 'moost'
+
+@Controller()
+export class AppController {
+  constructor(@Inject('WooksWs') private ws: WooksWs) {}
+
+  @Upgrade('ws')
+  upgrade() {
+    return this.ws.upgrade()
+  }
+}
+```
+
+### MoostWs API
+
+```ts
+interface TMoostWsOpts {
+  wooksWs?: WooksWs | TWooksWsOptions
+}
+
+class MoostWs {
+  constructor(opts?: TMoostWsOpts & { httpApp?: { getHttpApp(): unknown } | object })
+  getWsApp(): WooksWs
+  listen(port: number, hostname?: string): Promise<void>  // standalone only
+  close(): void
+}
+```
+
+### TWooksWsOptions
+
+```ts
+interface TWooksWsOptions {
+  heartbeatInterval?: number       // ping interval ms (default: 30000, 0 = disabled)
+  heartbeatTimeout?: number        // pong timeout ms (default: 5000)
+  messageParser?: (raw: Buffer | string) => WsClientMessage
+  messageSerializer?: (msg: WsReplyMessage | WsPushMessage) => string | Buffer
+  logger?: TConsoleBase
+  maxMessageSize?: number          // bytes (default: 1MB)
+  wsServerAdapter?: WsServerAdapter
+  broadcastTransport?: WsBroadcastTransport
+}
+```
+
+## DI: Injecting Adapter Instances
+
+The adapter registers both class and string keys:
+
+| Key | Resolves To |
+|-----|-------------|
+| `MoostWs` / `'MoostWs'` | The `MoostWs` adapter instance |
+| `WooksWs` / `'WooksWs'` | The underlying `WooksWs` instance |
+
+Use string keys for reliability (avoids esbuild/tsx metadata issues):
+
+```ts
+constructor(@Inject('WooksWs') private ws: WooksWs) {}
+```
+
+## Best Practices
+
+- Use HTTP-integrated mode for production — single port, explicit upgrade control, easier auth
+- Use `WsApp` for quick prototyping or standalone WebSocket services
+- Use `@Inject('WooksWs')` (string key) rather than class reference to avoid module init order issues
+
+## Gotchas
+
+- `WsApp.start()` must be awaited — it calls `this.init()` and `listen()` internally
+- In HTTP-integrated mode, `ws.listen()` is NOT called — the HTTP server handles the port
+- The package is marked experimental — the API may change without semver until stable

package/skills/moostjs-event-ws/handlers.md

@@ -0,0 +1,162 @@
+# Handlers — @moostjs/event-ws
+
+> Defining WebSocket event handlers with @Message, @Connect, and @Disconnect decorators.
+
+## Concepts
+
+Moost WS provides three handler decorators:
+- `@Message(event, path?)` — handles routed WebSocket messages
+- `@Connect()` — runs when a new connection is established
+- `@Disconnect()` — runs when a connection closes
+
+All handlers participate in the full Moost event lifecycle (scope registration, interceptor init, argument resolution, handler execution, interceptor after/onError, scope cleanup).
+
+## API Reference
+
+### `@Message(event: string, path?: string)`
+
+Registers a handler for routed WebSocket messages. Matches on both the `event` field and `path` from the client message.
+
+```ts
+import { Message, MessageData } from '@moostjs/event-ws'
+import { Controller } from 'moost'
+
+@Controller()
+export class EchoController {
+  @Message('echo', '/echo')
+  echo(@MessageData() data: unknown) {
+    return data // sent back as reply if client included an id
+  }
+}
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `event` | `string` | Message event type to match (e.g. `"message"`, `"join"`, `"rpc"`) |
+| `path` | `string` (optional) | Route path with optional params. When omitted, the method name is used. |
+
+**Return values:** The return value is sent as a reply only when the client included a correlation `id` (RPC). Fire-and-forget messages (no `id`) ignore the return value.
+
+### `@Connect()`
+
+Runs when a new WebSocket connection is established. Executes inside the connection context.
+
+```ts
+import { Connect, ConnectionId } from '@moostjs/event-ws'
+import { Controller } from 'moost'
+
+@Controller()
+export class LifecycleController {
+  @Connect()
+  onConnect(@ConnectionId() id: string) {
+    console.log(`New connection: ${id}`)
+  }
+}
+```
+
+If the handler throws or returns a rejected promise, the connection is closed immediately.
+
+### `@Disconnect()`
+
+Runs when a WebSocket connection closes. Use for cleanup.
+
+```ts
+import { Disconnect, ConnectionId } from '@moostjs/event-ws'
+import { Controller } from 'moost'
+
+@Controller()
+export class LifecycleController {
+  @Disconnect()
+  onDisconnect(@ConnectionId() id: string) {
+    console.log(`Connection ${id} closed`)
+  }
+}
+```
+
+Room membership is automatically cleaned up on disconnect — no need to manually leave rooms.
+
+## Common Patterns
+
+### Pattern: Multiple events on the same path
+
+```ts
+@Controller('chat')
+export class ChatController {
+  @Message('join', ':room')
+  join(@Param('room') room: string) { /* ... */ }
+
+  @Message('leave', ':room')
+  leave(@Param('room') room: string) { /* ... */ }
+
+  @Message('message', ':room')
+  message(@Param('room') room: string) { /* ... */ }
+}
+```
+
+### Pattern: Mixed HTTP and WS handlers in one controller
+
+A single controller can contain both HTTP and WebSocket handlers when both adapters are registered:
+
+```ts
+import { Get } from '@moostjs/event-http'
+import { Message, MessageData } from '@moostjs/event-ws'
+import { Controller } from 'moost'
+
+@Controller('api')
+export class ApiController {
+  @Get('status')
+  getStatus() { return { online: true } }
+
+  @Message('query', '/status')
+  wsStatus() { return { online: true } }
+}
+```
+
+### Pattern: Protected handlers with interceptors
+
+```ts
+import { Message, MessageData } from '@moostjs/event-ws'
+import { Controller, Intercept, Validate } from 'moost'
+import { AuthGuard } from './auth.guard'
+
+@Controller('admin')
+@Intercept(AuthGuard)
+export class AdminController {
+  @Message('broadcast', '/announce')
+  announce(@MessageData() @Validate() data: AnnounceDto) {
+    // protected by AuthGuard and validated
+  }
+}
+```
+
+### Pattern: Full lifecycle controller
+
+```ts
+@Controller('chat')
+export class ChatController {
+  @Connect()
+  onConnect(@ConnectionId() id: string) { /* ... */ }
+
+  @Disconnect()
+  onDisconnect(@ConnectionId() id: string) { /* ... */ }
+
+  @Message('join', ':room')
+  join(@Param('room') room: string) { /* ... */ }
+
+  @Message('message', ':room')
+  message(@Param('room') room: string) { /* ... */ }
+}
+```
+
+## Best Practices
+
+- Keep `@Connect` handlers lightweight — they block the connection establishment
+- Use `@Disconnect` for cleanup, but don't rely on it for room management (rooms auto-clean)
+- One controller can have at most one `@Connect` and one `@Disconnect` handler
+- Use interceptors (`@Intercept`) for cross-cutting concerns like auth and logging
+
+## Gotchas
+
+- Throwing in `@Connect` closes the connection immediately — use `WsError` for meaningful error codes
+- Fire-and-forget messages (no `id`) silently discard handler return values
+- `@Message` path is relative to the controller prefix, not absolute

package/skills/moostjs-event-ws/protocol.md

@@ -0,0 +1,181 @@
+# Wire protocol — @moostjs/event-ws
+
+> JSON message format, message types, error codes, heartbeat, and custom serialization.
+
+## Concepts
+
+Moost WS uses a simple JSON-over-WebSocket protocol. Messages are plain JSON objects sent as text frames. There are three message types:
+
+1. **Client → Server** (`WsClientMessage`) — routed by event + path
+2. **Server → Client: Reply** (`WsReplyMessage`) — response to an RPC call
+3. **Server → Client: Push** (`WsPushMessage`) — server-initiated message
+
+## Message Types
+
+### WsClientMessage (Client → Server)
+
+```ts
+interface WsClientMessage {
+  event: string            // Router method (e.g. "message", "join", "query")
+  path: string             // Route path (e.g. "/chat/general")
+  data?: unknown           // Payload
+  id?: string | number     // Correlation ID — present for RPC, absent for fire-and-forget
+}
+```
+
+**Fire-and-forget** (no reply expected):
+```json
+{ "event": "message", "path": "/chat/general", "data": { "text": "Hello!" } }
+```
+
+**RPC** (reply expected):
+```json
+{ "event": "join", "path": "/chat/general", "data": { "name": "Alice" }, "id": 1 }
+```
+
+### WsReplyMessage (Server → Client)
+
+Sent in response to a client message that included an `id`. Exactly one reply per request.
+
+```ts
+interface WsReplyMessage {
+  id: string | number                          // Matches client's correlation ID
+  data?: unknown                                // Handler return value
+  error?: { code: number; message: string }     // Error details (if handler threw)
+}
+```
+
+**Success:**
+```json
+{ "id": 1, "data": { "joined": true, "room": "general" } }
+```
+
+**Error:**
+```json
+{ "id": 1, "error": { "code": 400, "message": "Name is required" } }
+```
+
+### WsPushMessage (Server → Client)
+
+Server-initiated messages from broadcasts, subscriptions, or direct sends.
+
+```ts
+interface WsPushMessage {
+  event: string                        // Event type
+  path: string                         // Concrete path
+  params?: Record<string, string>      // Route params extracted by router
+  data?: unknown                       // Payload
+}
+```
+
+```json
+{ "event": "message", "path": "/chat/general", "data": { "from": "Alice", "text": "Hello!" } }
+```
+
+## Error Codes
+
+| Code | Meaning |
+|------|---------|
+| 400 | Bad request / validation error |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+| 404 | Not found (auto-sent for unmatched routes) |
+| 409 | Conflict |
+| 429 | Too many requests |
+| 500 | Internal server error (auto-sent for unhandled exceptions) |
+| 503 | Service unavailable |
+
+### WsError
+
+Throw `WsError` for structured error responses:
+
+```ts
+import { WsError } from '@moostjs/event-ws'
+
+throw new WsError(400, 'Name is required')
+throw new WsError(401, 'Unauthorized')
+```
+
+```ts
+class WsError extends Error {
+  readonly code: number
+  constructor(code: number, message?: string)
+}
+```
+
+`WsError` works in:
+- `@Message` handlers — sends error reply to client (if RPC)
+- `@Upgrade` handlers — rejects the WebSocket connection
+- `@Connect` handlers — closes the connection
+
+Unhandled (non-`WsError`) exceptions send a generic `{ code: 500, message: "Internal Error" }` without leaking details.
+
+## Heartbeat
+
+The server sends periodic WebSocket `ping` frames to detect stale connections. Configure via `TWooksWsOptions`:
+
+```ts
+const ws = new MoostWs({
+  wooksWs: {
+    heartbeatInterval: 30000, // ms (default: 30000)
+    heartbeatTimeout: 5000,   // ms (default: 5000)
+  },
+})
+```
+
+Set `heartbeatInterval: 0` to disable.
+
+## Custom Serialization
+
+Both server and client support pluggable serialization (e.g. MessagePack, CBOR):
+
+```ts
+const ws = new MoostWs({
+  wooksWs: {
+    messageParser: (raw: string) => myCustomParse(raw),
+    messageSerializer: (msg: unknown) => myCustomSerialize(msg),
+  },
+})
+```
+
+Both sides must use the same serialization format.
+
+## Client Library
+
+Use `@wooksjs/ws-client` for a type-safe client:
+
+```bash
+npm install @wooksjs/ws-client
+```
+
+```ts
+import { createWsClient } from '@wooksjs/ws-client'
+
+const client = createWsClient('ws://localhost:3000/ws', {
+  reconnect: true,
+  rpcTimeout: 5000,
+})
+
+// RPC
+const result = await client.call('join', '/chat/general', { name: 'Alice' })
+
+// Listen for pushes
+client.on('message', '/chat/general', ({ data }) => {
+  console.log(`${data.from}: ${data.text}`)
+})
+
+// Fire-and-forget
+client.send('message', '/chat/general', { from: 'Alice', text: 'Hello!' })
+```
+
+## Best Practices
+
+- Use `id` (RPC) when the client needs a response, omit for fire-and-forget
+- Use HTTP-style numeric codes for errors (400, 401, 404, etc.)
+- Keep payloads small — default `maxMessageSize` is 1MB
+
+## Gotchas
+
+- Fire-and-forget messages that hit unmatched routes are logged but no error is sent to the client
+- Oversized messages (exceeding `maxMessageSize`) are silently dropped
+- Reply is only sent when client message includes `id` — handler return values are discarded otherwise