@rlanz/socket 0.0.1-9 → 0.1.1

package/README.md

@@ -1,21 +1,31 @@
 # @rlanz/socket
 
-WebSocket integration for AdonisJS, powered by [`ws`](https://github.com/websockets/ws).
+A WebSocket server and typed client for AdonisJS, powered by
+[`ws`](https://github.com/websockets/ws).
 
-## Installation
+> [!WARNING]
+> This package is available for testing and early production use. It will move to
+> `@adonisjs/socket` before its official release. Expect breaking changes and a migration.
 
-```sh
-yarn add @rlanz/socket
-```
+`@rlanz/socket` provides:
+
+- AdonisJS channels with middleware, lifecycle hooks, and dependency injection
+- end-to-end types generated from server channel classes
+- presence channels and client-to-client events
+- automatic client reconnection and re-subscription
+- cross-instance broadcasts through `@boringnode/bus`
+- React and Vue adapters
+- health checks, OpenTelemetry instrumentation, and test fakes
 
-Configure the package in your AdonisJS application:
+## Install
 
 ```sh
+yarn add @rlanz/socket
 node ace configure @rlanz/socket
 ```
 
-This registers the provider for the `web` environment only, so Ace commands do not boot the
-WebSocket integration, and installs the Assembler hook:
+The configure command registers the provider in the `web` environment and adds the Assembler hook
+that discovers channels and generates client types.
 
 ```ts
 // adonisrc.ts
@@ -32,478 +42,234 @@ export default defineConfig({
 })
 ```
 
-The Assembler hook generates both the application registry used for end-to-end client types and the
-server manifest consumed by the provider from the same channel file list. The client registry is a
-typed subset: channels whose inheritance, pattern, or handlers cannot be represented statically are
-still registered at runtime but are omitted from generated client types with a diagnostic. Keep the
-standard AdonisJS package import mapping `#generated/*` pointed at `./.adonisjs/server/*.js`; the
-provider loads `#generated/socket_channels` through that convention.
+The package requires Node.js 24 or newer and AdonisJS 7.
 
-## Configuration
+## Quick start
 
-Create a socket config file and tune the WebSocket path or heartbeat.
+Create a channel in `app/channels`.
 
 ```ts
-// config/socket.ts
-import { defineConfig } from '@rlanz/socket'
+// app/channels/chat_channel.ts
+import { BaseChannel } from '@rlanz/socket'
+import { onMessage } from '@rlanz/socket/decorators'
+import type { AuthenticatedSocket } from '@rlanz/socket/types'
 
-export default defineConfig({
-  websocket: {
-    path: '/socket',
-    origin: (origin, ctx) => {
-      return ['https://app.example.com', 'https://admin.example.com'].includes(origin)
-    },
-    pingInterval: '25s',
-    pingTimeout: '5s',
-    maxBufferedAmount: 16 * 1024 * 1024,
-    maxOutboundPayload: 1024 * 1024,
-    maxSubscriptionsPerSocket: 100,
-    maxChannelNameLength: 255,
-  },
-})
-```
+type User = { id: string; name: string }
+type Message = { id: string; text: string }
 
-- `websocket.path` defaults to `/socket`.
-- Browser upgrades are restricted to the request's own origin by default. `websocket.origin`
-  accepts the same values as AdonisJS CORS `origin`: a boolean, a string (including `'*'` or a
-  comma-separated list), an array of strings, or `(origin, httpContext) => value`. Matching is
-  case-sensitive and, like `@adonisjs/cors`, comma-separated entries are not whitespace-trimmed. A
-  configured policy replaces the same-origin default. Clients without an `Origin` header remain
-  supported.
-- `websocket.middleware` runs AdonisJS HTTP middleware for the WebSocket upgrade request.
-- `websocket.pingInterval` sends a WebSocket ping every configured duration.
-- `websocket.pingTimeout` closes connections that do not answer in time.
-- If only one heartbeat value is configured, the other one uses the default shown above.
-- `websocket.maxPayload` limits inbound message payloads; it defaults to 1 MiB.
-- `websocket.maxQueuedMessages` limits unresolved non-ping protocol messages per socket; it defaults
-  to `100`.
-- `websocket.maxMessagesPerInterval` limits inbound protocol messages per
-  `websocket.messageRateInterval`; they default to `1000` messages per `1s`.
-- `websocket.maxBufferedAmount` closes slow outbound sockets when the buffered bytes plus the next
-  protocol message would exceed the configured limit; it defaults to 16 MiB.
-- `websocket.maxOutboundPayload` limits every serialized outbound event, ACK, pong, and protocol
-  error; it defaults to 1 MiB.
-- `websocket.maxSubscriptionsPerSocket` limits active channel subscriptions retained by one socket;
-  it defaults to `100`.
-- `websocket.maxChannelNameLength` limits channel names before routing; it defaults to `255`
-  characters.
-
-`websocket.middleware` is different from channel middleware. Use it to prepare request-scoped
-services such as sessions or auth during the initial HTTP upgrade; use `static middlewares` on a
-channel class to authorize or enrich individual channel subscriptions.
-
-AdonisJS CORS middleware does not authorize the Node.js `upgrade` event and browsers do not apply
-Fetch CORS response checks to WebSockets. The origin check therefore runs before upgrade middleware
-and authentication, which protects cookie- or session-authenticated sockets from cross-site
-WebSocket hijacking. A reverse proxy must preserve the public `Host` and overwrite
-`X-Forwarded-Proto` with the trusted public protocol. If it rewrites either value, add the public
-origin explicitly with `websocket.origin` instead of relying on implicit same-origin
-detection.
+type ServerEvents = {
+  'chat:message': Message
+}
 
-### Authentication
+export default class ChatChannel extends BaseChannel<User, ServerEvents> {
+  static pattern = 'chat/:roomId'
 
-Authenticate sockets during the HTTP upgrade with `websocket.authenticate`. The hook receives an
-AdonisJS HTTP context and returns the authenticated user.
+  @onMessage('chat:send')
+  async sendMessage(
+    socket: AuthenticatedSocket<User>,
+    payload: { text: string }
+  ): Promise<Message> {
+    const message = { id: crypto.randomUUID(), text: payload.text }
 
-Define `websocket.middleware` when your WebSocket upgrade authentication depends on AdonisJS
-middleware such as sessions or auth initialization. These middleware run only for the HTTP upgrade
-request, before `websocket.authenticate`, so they are the right place to prepare `httpContext.auth`,
-`httpContext.session`, and other request-scoped services used during the handshake.
+    this.broadcastExcept(socket.id, 'chat:message', message)
+    return message
+  }
+}
+```
 
-They are not channel middleware. Channel authorization and per-channel behavior still live on the
-channel itself through `static middlewares`.
+The Assembler hook generates an `AppSocket` type from this class. Give it to the browser client to
+type channel parameters, event names, payloads, and acknowledgements.
 
 ```ts
-// config/socket.ts
-import { authenticateWithAdonisAuth, defineConfig } from '@rlanz/socket'
-
-type User = { id: string | number; name: string }
+import { Socket } from '@rlanz/socket/client'
+import type { AppSocket } from '#generated/socket'
 
-export default defineConfig({
-  websocket: {
-    middleware: [
-      () => import('@adonisjs/session/session_middleware'),
-      () => import('@adonisjs/auth/initialize_auth_middleware'),
-    ],
+const socket = new Socket<AppSocket>()
+const channel = socket.channel('chat/:roomId', { roomId: 'general' })
 
-    authenticate: authenticateWithAdonisAuth<User>(),
-  },
+channel.listen('chat:message', (message) => {
+  console.log(message.id)
 })
-```
 
-Return `false`, `null`, or throw to reject the upgrade with `401 Unauthorized`. The returned user is
-available as `socket.user`.
-
-Every connected socket retains the initial Adonis HTTP context at `socket.raw.httpContext`; use
-`socket.raw.data` for mutable socket-lifetime state.
-
-The retained HTTP context describes the initial upgrade handshake. After the `101` response, it is
-not an active HTTP request: do not write through `httpContext.response` or expect it to remain
-available through AdonisJS async-local storage. The upgrade pipeline receives the context explicitly
-and does not install it in async-local storage during the handshake either. Copy durable values into
-`socket.user` or `socket.raw.data` instead of keeping response-bound resources alive.
-
-Override `websocket.authenticate` when you need custom behavior:
+await socket.connect()
+await channel.subscribe()
 
-```ts
-async authenticate({ httpContext }) {
-  await httpContext.auth.authenticateUsing()
-  return httpContext.auth.getUserOrFail()
-}
+const message = await channel.sendWithAck('chat:send', { text: 'Hello' })
+console.log(message.id)
 ```
 
-### Horizontal Sync
+TypeScript rejects unknown channels, missing channel parameters, unknown events, invalid payloads,
+and invalid server broadcasts.
 
-Configure an [`@boringnode/bus`](https://github.com/boringnode/bus) transport to synchronize broadcasts across multiple application instances.
+## Configure the server
 
-Install the peer dependency required by the selected transport. For Redis:
-
-```sh
-yarn add ioredis
-```
+Create `config/socket.ts` when you need to change the defaults.
 
 ```ts
 // config/socket.ts
-import { redis } from '@boringnode/bus/transports/redis'
 import { defineConfig } from '@rlanz/socket'
 
 export default defineConfig({
-  transport: {
-    driver: redis({
-      host: '127.0.0.1',
-      port: 6379,
-    }),
-    channel: 'socket::broadcast',
-    presenceTimeout: '100ms',
-    retryQueue: {
-      maxSize: 1000,
-    },
+  websocket: {
+    path: '/socket',
+    origin: ['https://app.example.com', 'https://admin.example.com'],
+    pingInterval: '25s',
+    pingTimeout: '5s',
   },
 })
 ```
 
-When configured, `socket.to(channel).emit(...)`, `socket.to(channel).except(socketId).emit(...)`, and `socket.broadcast(...)` are delivered locally and published to the bus so other instances can deliver them to their own connected sockets.
+### WebSocket options
 
-The default bus channel is `socket::broadcast`. Presence channels also use the bus to build distributed snapshots during subscribe, duplicate subscribe, join, and leave updates. `presenceTimeout` controls how long an instance waits for other instances to answer a presence snapshot request; it defaults to `100ms`.
+| Option                      | Default     | Purpose                                                  |
+| --------------------------- | ----------- | -------------------------------------------------------- |
+| `path`                      | `/socket`   | WebSocket endpoint                                       |
+| `origin`                    | Same origin | Browser origin policy                                    |
+| `middleware`                | `[]`        | AdonisJS HTTP middleware run during upgrade              |
+| `authenticate`              | None        | Resolves the user attached to the socket                 |
+| `pingInterval`              | Disabled    | Interval between WebSocket pings                         |
+| `pingTimeout`               | Disabled    | Time allowed for a pong response                         |
+| `maxPayload`                | 1 MiB       | Maximum inbound WebSocket message size                   |
+| `maxQueuedMessages`         | `100`       | Pending non-ping messages allowed per socket             |
+| `maxMessagesPerInterval`    | `1000`      | Messages accepted per rate limit window                  |
+| `messageRateInterval`       | `1s`        | Per-socket rate limit window                             |
+| `maxBufferedAmount`         | 16 MiB      | Outbound buffer limit before disconnecting a slow socket |
+| `maxOutboundPayload`        | 1 MiB       | Maximum serialized outbound message size                 |
+| `maxSubscriptionsPerSocket` | `100`       | Active subscriptions allowed per socket                  |
+| `maxChannelNameLength`      | `255`       | Maximum channel name length                              |
+| `shutdownTimeout`           | `5s`        | Time allowed for handlers and hooks during shutdown      |
 
-Failed publications enter an in-memory retry queue. It is enabled by default, deduplicates identical
-messages, and retains at most `1000` entries; when full, the oldest entry is discarded. Configure
-`transport.retryQueue` to change the limit, retry interval, deduplication, or to disable retries.
-Setting `maxSize: null` explicitly opts into an unbounded queue.
+Heartbeat is disabled when neither `pingInterval` nor `pingTimeout` is set. If you set only one,
+the other defaults to `25s` or `5s` respectively.
 
-### Health Checks
+The message rate and queue limits protect individual connections. They do not replace connection
+limits or abuse protection at the proxy.
 
-Register `SocketHealthCheck` inside your AdonisJS readiness checks to report whether the WebSocket service is ready to accept traffic.
+### Origin checks
 
-```ts
-// start/health.ts
-import { HealthChecks, DiskSpaceCheck, MemoryHeapCheck } from '@adonisjs/core/health'
-import socket from '@rlanz/socket/services/main'
-import { SocketHealthCheck } from '@rlanz/socket/health_check'
+Browser upgrades are restricted to the request's origin by default. The `origin` option accepts the
+same values as the AdonisJS CORS `origin` option:
 
-export const healthChecks = new HealthChecks().register([
-  new DiskSpaceCheck(),
-  new MemoryHeapCheck(),
-  new SocketHealthCheck(socket),
-])
-```
+- a boolean
+- a string, including `'*'` or a comma-separated list
+- an array of strings
+- `(origin, httpContext) => value`
 
-The check returns `ok` only after the provider has successfully booted the WebSocket server. It reports `error` while the service is stopped, stopping, or failed, so readiness probes can remove the instance from traffic during shutdown or startup failures.
+Matching is case-sensitive. Comma-separated entries are not trimmed. A configured policy replaces
+the same-origin default. Clients without an `Origin` header remain supported.
 
-### Testing
+AdonisJS CORS middleware does not authorize WebSocket upgrades. The package checks the origin before
+upgrade middleware and authentication. This protects cookie-authenticated sockets from cross-site
+WebSocket hijacking.
 
-Use `socket.fake()` to intercept outgoing events and store them in memory without touching any connected WebSocket client or distributed transport.
+Your reverse proxy must preserve the public `Host` and replace `X-Forwarded-Proto` with the trusted
+public protocol. If the proxy rewrites the host, configure the public origin explicitly.
 
-```ts
-import { test } from '@japa/runner'
-import socket from '@rlanz/socket/services/main'
+### Authentication
 
-test.group('Notifications', (group) => {
-  group.each.teardown(() => {
-    socket.restore()
-  })
+Use `websocket.middleware` to prepare request services such as sessions and auth. Then resolve the
+user with `websocket.authenticate`.
 
-  test('broadcasts the notification', async ({ client }) => {
-    const fake = socket.fake()
+```ts
+// config/socket.ts
+import { authenticateWithAdonisAuth, defineConfig } from '@rlanz/socket'
 
-    await client.post('/notifications').json({ message: 'Hello' })
+type User = { id: string; name: string }
 
-    fake.assertBroadcasted('notification:created', {
-      data: { message: 'Hello' },
-    })
-  })
+export default defineConfig({
+  websocket: {
+    middleware: [
+      () => import('@adonisjs/session/session_middleware'),
+      () => import('@adonisjs/auth/initialize_auth_middleware'),
+    ],
+    authenticate: authenticateWithAdonisAuth<User>(),
+  },
 })
 ```
 
-The fake supports explicit resource management as well, so `using fake = socket.fake()` automatically restores the real socket service when the test scope exits.
+Return `false`, `null`, or throw to reject the upgrade with `401 Unauthorized`. A successful result
+becomes `socket.user`.
 
-Five assertion helpers cover global broadcasts, channel events, counts, and negative assertions.
+You can provide a custom handler instead.
 
 ```ts
-fake.assertBroadcasted('maintenance', { data: { active: true } })
-fake.assertNotBroadcasted('deploy:started')
-
-fake.assertEmittedTo('chat/general', 'chat:message', {
-  data: (data) => data.text === 'Hello',
+export default defineConfig({
+  websocket: {
+    async authenticate({ httpContext }) {
+      await httpContext.auth.authenticateUsing()
+      return httpContext.auth.getUserOrFail()
+    },
+  },
 })
-fake.assertNotEmittedTo('chat/general', 'chat:typing')
-
-fake.assertCount(2, { target: 'channel', channel: 'chat/general' })
-fake.assertCount(0)
 ```
 
-### OpenTelemetry
-
-`@rlanz/socket` emits `diagnostics_channel` tracing events and ships an optional OpenTelemetry instrumentation. This lets an AdonisJS integration such as `@adonisjs/otel` register the instrumentation without coupling the socket provider to a telemetry runtime.
-
-```ts
-import { SocketInstrumentation } from '@rlanz/socket/otel'
+Upgrade middleware and channel middleware have different jobs. Upgrade middleware prepares the HTTP
+handshake. Channel middleware authorizes one subscription.
 
-const instrumentation = new SocketInstrumentation()
-
-instrumentation.enable()
-instrumentation.manuallyRegister()
-```
-
-The instrumentation creates spans for socket connect/disconnect, subscribe/unsubscribe, incoming channel messages, and broadcast delivery. It also records counters for active connections, active subscriptions, received channel messages, broadcast operations, and broadcast deliveries.
-
-## Production and scaling
-
-### Process and reverse proxy
-
-The provider attaches its WebSocket `upgrade` handler to the AdonisJS Node HTTP server after that
-server is ready. WebSockets therefore use the same process, listener, event loop, memory, and failure
-domain as HTTP; there is no separate socket process or port. Size each application instance for its
-combined HTTP and long-lived WebSocket workload, and remember that a process failure drops every
-socket connected to that instance.
-
-At the reverse proxy or load balancer:
-
-- route `websocket.path` to the AdonisJS HTTP listener and forward WebSocket upgrade requests using
-  HTTP/1.1 with the `Upgrade` and `Connection: upgrade` headers;
-- terminate TLS there if desired, use `wss://` publicly, preserve a validated public `Host`, and
-  **overwrite** `X-Forwarded-Proto` with the trusted public protocol (`http` or `https`);
-- allow long-lived upgraded connections and set the proxy idle timeout above the configured
-  heartbeat cadence; and
-- restrict direct access to the upstream. Same-origin validation trusts `Host` and the first
-  `X-Forwarded-Proto` value, so client-supplied versions of those headers must not reach the app.
-
-Browser origins are not authorized by AdonisJS CORS middleware. Configure exact public origins in
-[`websocket.origin`](#configuration) when the browser origin differs from the public socket
-origin or when the proxy rewrites `Host`. Clients without an `Origin` header are accepted, so use
-upgrade authentication for non-browser clients rather than treating the origin check as
-authentication.
-
-### Multiple instances and reconnects
-
-A load balancer may route each new upgrade to any ready instance and must keep that upgraded TCP
-connection attached to that instance. The package neither implements nor guarantees sticky
-sessions. Without a [transport](#horizontal-sync), subscriptions, broadcasts, and
-presence are local to one instance; affinity is not a replacement for configuring the transport.
-All instances in one logical deployment must use a compatible shared transport and the same bus
-channel.
-
-The bundled client reconnects by default with exponential backoff from `250ms` to `5s` and
-re-subscribes desired channels after establishing a new connection, which may be on another
-instance. A reconnect is a new session: pending acknowledgements are rejected, authentication and
-channel middleware run again, and events sent while disconnected are not replayed. The built-in
-backoff has no jitter; stagger deployments or add reconnect staggering in the application when a
-large fleet could reconnect simultaneously.
-
-### Transport, presence, and delivery semantics
-
-Local broadcasts are sent to currently connected local recipients and are also published to the
-configured `@boringnode/bus` transport. Publication is fire-and-forget from the socket API. Failed
-publications may be retried from the bounded, in-memory retry queue after the transport reconnects,
-so stale events remain possible. The package does not persist bus messages, wait for remote
-delivery, acknowledge recipients, or recover events after a process restart; the guarantees of a
-particular transport do not turn socket delivery into a durable application queue.
-
-Distributed presence is also best-effort and non-durable. A snapshot contains the replies received
-before `transport.presenceTimeout`; partitions, slow instances, concurrent changes, and restarts can
-produce incomplete snapshots or duplicate/omitted member transitions. Presence hooks must be
-idempotent and presence must not be used as an authoritative online-user or membership store.
-
-`sendWithAck()` only confirms that the receiving server-side handler completed and returned a
-result. It does not confirm that a broadcast reached any client. Applications that need durable
-notifications, recovery after reconnect, or at-least-once processing must persist events or state
-outside this package and define their own event IDs, cursors, deduplication, acknowledgement, and
-replay protocol.
-
-### Restarts and resource limits
-
-On AdonisJS shutdown, the service becomes unready, stops accepting upgrades, terminates existing
-WebSockets, runs their subscription/disconnect finalizers, and then disconnects the bus. It does
-**not** gracefully drain established sockets or wait for in-flight client acknowledgements. For a
-rolling restart, remove the instance from new HTTP/upgrade traffic first when the platform permits,
-expect connected clients to reconnect, and give the process enough termination grace to finish its
-socket finalizers and bus shutdown before sending a forced kill.
-
-Review the limits under [Configuration](#configuration) against real payloads and fan-out:
-
-- enable heartbeat explicitly; it is disabled when neither `pingInterval` nor `pingTimeout` is set;
-- tune inbound/outbound payload sizes, the per-socket fixed-window message rate, serialized message
-  queue depth, subscriptions per socket, channel-name length, and the transport retry queue;
-- treat rate and queue limits as per-connection safeguards, not perimeter abuse prevention; enforce
-  aggregate connection and request limits at the proxy or application boundary; and
-- tune `maxBufferedAmount` for available memory. Slow consumers and oversized outbound frames are
-  disconnected rather than buffered without bound or retried.
-
-There is no built-in total connection limit. Each connection consumes a file descriptor plus
-application, subscription, queue, heartbeat, and `ws` memory. Set process/container memory limits,
-raise and monitor file-descriptor limits where appropriate, cap connections at the edge, and load
-test representative connection counts, message rates, payloads, and broadcast fan-out before
-production.
-
-### Health and monitoring
-
-Expose the application-owned readiness endpoint containing [`SocketHealthCheck`](#health-checks)
-and route new upgrades only to ready instances. The check reports local service startup/shutdown
-state and local connection/channel counts; it does not probe the transport backend, remote
-instances, or end-to-end publish delivery. Monitor those dependencies separately and keep a normal
-process liveness check so readiness failures do not automatically cause restart loops.
-
-Enable the optional [OpenTelemetry instrumentation](#opentelemetry) and alert on connection and
-disconnection changes, active connections/subscriptions, message errors, and broadcast volume and
-local delivery counts. Also collect process event-loop delay, memory, CPU, open file descriptors,
-proxy upgrade/rejection metrics, reconnect rates, logs, and transport health. Broadcast delivery
-counters count immediate sends to local `ws` objects, not application-level receipt.
+Every socket retains the initial HTTP context at `socket.raw.httpContext`. This context describes the
+handshake. It is not an active request after the `101` response and is not installed in AdonisJS
+async-local storage. Put mutable socket-lifetime state in `socket.raw.data`. Copy durable identity
+into `socket.user` instead of retaining response-bound resources.
 
-### Production checklist
+## Define channels
 
-- [ ] Proxy upgrades on the configured path with HTTP/1.1 `Upgrade`/`Connection` headers.
-- [ ] Terminate TLS safely; preserve a validated public `Host` and overwrite `X-Forwarded-Proto`.
-- [ ] Configure an exact `origin` policy and upgrade authentication; protect the upstream from direct
-      access.
-- [ ] Set proxy idle timeouts and explicitly configure/test heartbeat behavior.
-- [ ] Configure a shared transport and bus channel for every instance that must exchange broadcasts
-      or presence.
-- [ ] Make clients tolerate reconnect, re-authentication, re-subscription, duplicate handling, and
-      gaps during deploys or failures.
-- [ ] Persist and replay application-critical events outside the socket bus.
-- [ ] Tune payload, rate, queue, subscription, backpressure, connection, memory, and file-descriptor
-      limits using load tests.
-- [ ] Wire readiness, liveness, OpenTelemetry, logs, proxy metrics, and transport monitoring.
-- [ ] Give rolling shutdown enough grace for finalizers and bus disconnect; do not expect socket
-      draining.
-
-## Channels
-
-Channels are discovered from `app/channels/**/*_channel.{ts,js}`. Export a default class extending
-`BaseChannel`. Client-to-server payloads and acknowledgements are inferred from public handler
-methods. The optional second generic declares server-to-client events. When omitted, the channel
-cannot broadcast server events.
+The default Assembler hook discovers `app/channels/**/*_channel.{ts,js}`. Each file must export a
+default class that extends `BaseChannel`.
 
 ```ts
-// app/channels/chat_channel.ts
 import { BaseChannel } from '@rlanz/socket'
-import { onMessage } from '@rlanz/socket/decorators'
-import type { AuthenticatedSocket } from '@rlanz/socket/types'
-
-type User = { id: string; name: string }
-type Message = { id: string; text: string }
 
-type ServerEvents = {
-  'chat:message': Message
-}
-
-export default class ChatChannel extends BaseChannel<User, ServerEvents> {
+export default class ChatChannel extends BaseChannel {
   static pattern = 'chat/:roomId'
-
-  @onMessage('chat:send')
-  async sendMessage(
-    socket: AuthenticatedSocket<User>,
-    payload: { text: string }
-  ): Promise<Message> {
-    const message = { id: crypto.randomUUID(), text: payload.text }
-    this.broadcastExcept(socket.id, 'chat:message', message)
-    return message
-  }
-
-  @onMessage('chat:ping')
-  ping(_socket: AuthenticatedSocket<User>, _payload: undefined): void {}
 }
 ```
 
-Channel instances are resolved through the AdonisJS container for every new subscription, so
-constructor injection works as it does for other AdonisJS classes:
+Patterns support:
 
-```ts
-import { inject } from '@adonisjs/core'
-import { BaseChannel } from '@rlanz/socket'
-import MessageService from '#services/message_service'
+- literal segments such as `announcements`
+- required parameters such as `chat/:roomId`
+- one final optional parameter such as `threads/:threadId?`
+- one final wildcard such as `files/*`
 
-@inject()
-export default class ChatChannel extends BaseChannel {
-  static pattern = 'chat/:roomId'
+Generated clients use the declared pattern and a separate parameter object.
 
-  constructor(private messages: MessageService) {
-    super()
-  }
-}
+```ts
+socket.channel('announcements')
+socket.channel('chat/:roomId', { roomId: 'general' })
+socket.channel('threads/:threadId?', {})
+socket.channel('files/*', { wildcard: 'docs/guides/start' })
 ```
 
-The event name comes from `@onMessage('event')`, the handler's second parameter becomes the client
-payload, and `Awaited<ReturnType<handler>>` becomes its acknowledgement. No duplicate client event
-map is required. `ServerEvents` remains explicit because generation does not scan
-`broadcast()` calls; it checks `broadcast()` and `broadcastExcept()`. Omitting it makes both methods
-reject every event at compile time.
+An untyped `new Socket()` accepts concrete channel names instead.
 
-The Assembler hook generates an explicit `AppSocket` registry. Pass it once to the browser client:
+### Generated client contracts
 
-```ts
-import { Socket } from '@rlanz/socket/client'
-import type { AppSocket } from '#generated/socket'
+The Assembler hook writes:
 
-const socket = new Socket<AppSocket>()
-const channel = socket.channel('chat/:roomId', { roomId: 'general' })
+- `.adonisjs/client/socket.ts` for browser types
+- `.adonisjs/server/socket_channels.ts` for runtime channel discovery
 
-channel.listen('chat:message', (message) => console.log(message.id))
-channel.send('chat:ping')
+Configure the frontend project to resolve an alias such as `#generated/socket` to the client file.
+This alias is separate from the AdonisJS server mapping for `#generated/*`.
 
-const message = await channel.sendWithAck('chat:send', { text: 'Hello' })
-console.log(message.id)
-```
+Keep the standard AdonisJS `#generated/*` mapping pointed at `./.adonisjs/server/*.js`. The provider
+uses it to load the generated channel manifest.
 
-The generated registry is a map keyed by each declared channel pattern. The client selects that
-pattern explicitly and constructs the concrete name from typed parameters, so its types never need
-to reproduce runtime route ordering or specificity. Every registry entry carries its generated
-parameter shape; static channels use `undefined`, while dynamic channels expose their required,
-optional, or wildcard parameters.
+The generator recognizes:
 
-Client code can also extract event payloads without constructing a channel first:
+- default-exported classes that directly extend `BaseChannel`
+- direct string values assigned to `static pattern`
+- named public methods decorated with `@onMessage('event')`
+- required, optional, or absent handler payloads
 
-```ts
-import type { ChannelBroadcastPayload, ChannelClientEventPayload } from '@rlanz/socket/client'
-import type { AppSocket } from '#generated/socket'
+Runtime inheritance remains valid, but channels that use intermediate inheritance or patterns that
+cannot be read statically are omitted from client types. The generator reports why it omitted them.
+Abstract channels, private or static handlers, rest parameters, and required parameters after the
+payload fail generation.
 
-type IncomingMessage = ChannelBroadcastPayload<AppSocket, 'chat/:roomId', 'chat:message'>
-type OutgoingMessage = ChannelClientEventPayload<AppSocket, 'chat/:roomId', 'chat:send'>
-```
+Generated types validate TypeScript calls. They do not validate runtime payloads.
 
-The scanner recognizes default-exported classes that directly extend `BaseChannel`, direct
-string-literal `static pattern` values, and `@onMessage('event')` imported from
-`@rlanz/socket/decorators`. Handler methods must be
-named, public instance methods so the generated registry can reference their parameter and return
-types. Abstract channels, private/protected/static handlers, rest parameters, and required parameters
-after the payload fail generation with a diagnostic. A handler may accept no
-parameters, only the socket, a required payload, or an optional payload. Intermediate channel
-inheritance is deliberately omitted from generated contracts; runtime channel inheritance remains
-valid.
-
-Generated patterns support literal segments, required parameters, one final optional parameter, and
-one final wildcard. Dynamic patterns always receive a parameter object; pass `{}` to omit a final
-optional parameter. Wildcards use the explicit `wildcard` parameter and may contain slashes. Static
-channels need no parameter object. An untyped `new Socket()` continues to accept raw concrete channel
-names.
-
-The default Assembler hook discovers `app/channels/**/*_channel.{ts,js}` and generates both
-`.adonisjs/client/socket.ts` and `.adonisjs/server/socket_channels.ts`. Configure the frontend
-project to resolve an alias such as `#generated/socket` to the client file; this frontend mapping is
-separate from the AdonisJS server `#generated/*` mapping. Channels are discovered in `app/channels`
-by default. Any source inside `app` is supported, and generated imports use the corresponding
-AdonisJS `#app` alias without TypeScript extensions. To customize discovery or client output, replace
-the package hook in `adonisrc.ts` with a local hook:
+To change channel discovery or the generated client path, replace the package hook with a local one.
 
 ```ts
 // hooks/socket.ts
@@ -531,19 +297,33 @@ export default defineConfig({
 })
 ```
 
-Generated matching supports literals, required parameters, a final optional parameter, and a final
-wildcard. Dynamic or unsupported patterns are omitted. Plain dynamic channel names, ambiguous
-matches, and unmatched literals are rejected at compile time; the browser client must receive the
-generated registry as `Socket<AppSocket>`. Generation provides compile-time types only and does not
-validate runtime payloads. Whispers intentionally remain caller-generic because they are
-peer-to-peer. Runtime channel files always come from the generated server manifest.
+Any source directory inside `app` is supported. Generated imports use the matching AdonisJS `#app`
+alias without TypeScript extensions.
+
+### Dependency injection
+
+The AdonisJS container creates a channel instance for every subscription. Constructor injection
+works like it does in controllers and other container-managed classes.
+
+```ts
+import { inject } from '@adonisjs/core'
+import { BaseChannel } from '@rlanz/socket'
+import MessageService from '#services/message_service'
+
+@inject()
+export default class ChatChannel extends BaseChannel {
+  static pattern = 'chat/:roomId'
+
+  constructor(private messages: MessageService) {
+    super()
+  }
+}
+```
 
 ### Middleware
 
-Middlewares run before subscription. They may be functions, objects with a `handle` method, or
-classes. Middleware classes are resolved through the AdonisJS container for every subscription, so
-constructor injection works with `@inject()`. Classes in the same middleware chain share one
-container resolver, matching AdonisJS HTTP middleware scoping.
+Channel middleware runs before subscription. A middleware can be a function, an object with a
+`handle` method, or a class.
 
 ```ts
 import { BaseChannel } from '@rlanz/socket'
@@ -562,11 +342,16 @@ export default class ChatChannel extends BaseChannel<User> {
 }
 ```
 
+The container resolves middleware classes for every subscription, so they support constructor
+injection too.
+
 ```ts
 import { inject } from '@adonisjs/core'
 import type { MiddlewareContext } from '@rlanz/socket/types'
 import RoomService from '#services/room_service'
 
+type User = { id: string; name: string }
+
 @inject()
 class EnsureRoomAccess {
   constructor(private rooms: RoomService) {}
@@ -576,147 +361,173 @@ class EnsureRoomAccess {
     await next()
   }
 }
-
-export default class ChatChannel extends BaseChannel<User> {
-  static pattern = 'chat/:roomId'
-  static middlewares = [EnsureRoomAccess]
-}
 ```
 
-Only `SocketResponseError` messages are intentionally exposed to clients. Unexpected middleware,
-join, and message-handler errors are logged server-side and replaced with a generic protocol error,
-so internal exception details do not leak. Use `SocketResponseError` only for safe, user-facing
-messages.
+Only `SocketResponseError` messages are sent to clients. The server logs unexpected middleware,
+join, and message-handler errors and returns a generic protocol error. Use `SocketResponseError`
+only for messages that are safe to expose.
 
-### Presence
+## Exchange messages
 
-Enable presence with `static options = { presence: true }` and implement `getPresenceInfo`.
+Decorate a channel method with `@onMessage` to handle a client event.
 
 ```ts
 import { BaseChannel } from '@rlanz/socket'
-import type { AuthenticatedSocket, PresenceInfo, PresenceMember } from '@rlanz/socket/types'
+import { onMessage } from '@rlanz/socket/decorators'
+import type { AuthenticatedSocket } from '@rlanz/socket/types'
 
 type User = { id: string; name: string }
+
 type ServerEvents = {
-  'room:member_joined': PresenceMember
-  'room:member_left': PresenceMember
+  'chat:message': { user: User | undefined; body: string }
 }
 
-export default class RoomChannel extends BaseChannel<User, ServerEvents> {
-  static pattern = 'rooms/:roomId'
-  static options = { presence: true }
+export default class ChatChannel extends BaseChannel<User, ServerEvents> {
+  static pattern = 'chat/:roomId'
 
-  getPresenceInfo(socket: AuthenticatedSocket<User>): PresenceInfo {
-    const user = socket.getUserOrFail()
+  @onMessage('chat:send')
+  async sendMessage(socket: AuthenticatedSocket<User>, payload: { body: string }) {
+    this.broadcast('chat:message', {
+      user: socket.user,
+      body: payload.body,
+    })
 
-    return {
-      id: user.id,
-      data: {
-        name: user.name,
-      },
-    }
+    return { delivered: true }
   }
+}
+```
 
-  async onMemberJoin(socket: AuthenticatedSocket<User>, member: PresenceMember) {
-    this.broadcastExcept(socket.id, 'room:member_joined', member)
-  }
+The handler's second parameter defines the client payload. Its awaited return value defines the
+acknowledgement returned by `sendWithAck()`.
 
-  async onMemberLeave(socket: AuthenticatedSocket<User>, member: PresenceMember) {
-    this.broadcast('room:member_left', member)
+```ts
+const result = await channel.sendWithAck('chat:send', { body: 'Hello' })
+console.log(result.delivered)
+```
+
+Unknown events receive a negative acknowledgement. Handler results must be JSON-serializable. The
+server rejects a non-serializable result instead of sending a broken acknowledgement.
+
+The second `BaseChannel` generic declares server events. `broadcast()` and `broadcastExcept()` use
+this map to check event names and payloads. A channel without this generic cannot broadcast.
+
+```ts
+type ServerEvents = {
+  'chat:message': { id: string; body: string }
+}
+
+export default class ChatChannel extends BaseChannel<User, ServerEvents> {
+  publish(message: ServerEvents['chat:message'], socket: AuthenticatedSocket<User>) {
+    this.broadcast('chat:message', message)
+    this.broadcastExcept(socket.id, 'chat:message', message)
   }
 }
 ```
 
-The `id` identifies one member across multiple sockets or browser tabs. The optional `data` object
-defines the channel-specific public fields exposed on that member. Snapshots and member hooks flatten
-these values into `{ id, ...data, joinedAt }`.
+Use the socket service to broadcast outside a channel instance.
+
+```ts
+import socket from '@rlanz/socket/services/main'
+
+socket.broadcast('maintenance', { active: true })
+socket.to('chat/general').emit('chat:message', message)
+socket.to('chat/general').except(socketId).emit('chat:message', message)
+```
+
+You can extract payload types from a generated registry without creating a channel.
+
+```ts
+import type { ChannelBroadcastPayload, ChannelClientEventPayload } from '@rlanz/socket/client'
+import type { AppSocket } from '#generated/socket'
+
+type IncomingMessage = ChannelBroadcastPayload<AppSocket, 'chat/:roomId', 'chat:message'>
+type OutgoingMessage = ChannelClientEventPayload<AppSocket, 'chat/:roomId', 'chat:send'>
+```
+
+### Client-to-client events
+
+Use `whisper()` for temporary events such as typing indicators. The server accepts whispers only
+from subscribed sockets and forwards them to the other channel members.
 
-Custom presence fields are not normalized or recursively validated. WebSocket and distributed
-transport serialization may transform them, so use JSON-compatible values when local and distributed
-snapshots must have the same shape.
+```ts
+channel.listenForWhisper<{ typing: boolean }>('typing', ({ typing }) => {
+  console.log('typing:', typing)
+})
 
-Presence is exposed per user ID: multiple sockets or browser tabs for the same ID remain separate
-broadcast destinations but produce one `users` entry and contribute one to `count`. `onMemberJoin`
-runs for the first locally observed connection and `onMemberLeave` for the last; `onJoin` and
-`onLeave` still run for every socket. Across multiple application instances, member hooks are
-best-effort and must be idempotent because concurrent joins, leaves, timeouts, or partitions can
-duplicate or omit a transition. When two connections provide different metadata, the earliest
-connection is the representative. Distributed snapshots are deduplicated across the responses
-received before `transport.presenceTimeout` and therefore remain a best-effort, non-durable view
-during network partitions.
+channel.whisper('typing', { typing: true })
+```
 
-Presence snapshots are validated for JSON serialization before join hooks run. Hooks can still
-perform arbitrary external side effects and are not database transactions; keep them idempotent so
-an exception from a later hook can be retried safely.
+Whispers use an internal `client:` prefix and cannot impersonate server events. Their types remain
+caller-defined because they do not come from a server handler.
 
-## Channel Messages
+## Presence
 
-Incoming client messages are handled through the `@onMessage` decorator.
-Unknown events receive a negative acknowledgement.
+Enable presence on a channel and return the public data for each member.
 
 ```ts
 import { BaseChannel } from '@rlanz/socket'
-import { onMessage } from '@rlanz/socket/decorators'
-import type { AuthenticatedSocket } from '@rlanz/socket/types'
+import type { AuthenticatedSocket, PresenceInfo, PresenceMember } from '@rlanz/socket/types'
 
 type User = { id: string; name: string }
+
 type ServerEvents = {
-  'chat:message': { user: User | undefined; body: string }
+  'room:member_joined': PresenceMember
+  'room:member_left': PresenceMember
 }
 
-export default class ChatChannel extends BaseChannel<User, ServerEvents> {
-  static pattern = 'chat/:roomId'
+export default class RoomChannel extends BaseChannel<User, ServerEvents> {
+  static pattern = 'rooms/:roomId'
+  static options = { presence: true }
 
-  @onMessage('chat:send')
-  async sendMessage(socket: AuthenticatedSocket<User>, data: { body: string }) {
-    this.broadcast('chat:message', {
-      user: socket.user,
-      body: data.body,
-    })
+  getPresenceInfo(socket: AuthenticatedSocket<User>): PresenceInfo {
+    const user = socket.getUserOrFail()
 
-    return { delivered: true }
+    return {
+      id: user.id,
+      data: { name: user.name },
+    }
   }
-}
-```
 
-Returning a value from a handler resolves `sendWithAck()` on the client. Handler results and
-presence snapshots must be JSON-serializable. A non-serializable handler result receives an
-immediate negative acknowledgement; a non-serializable initial presence snapshot rolls back the
-subscription instead of leaving client and server state out of sync.
-
-### Client-to-client events
+  async onMemberJoin(socket: AuthenticatedSocket<User>, member: PresenceMember) {
+    this.broadcastExcept(socket.id, 'room:member_joined', member)
+  }
 
-Use `whisper()` for ephemeral events that should be relayed to the other members of the same
-channel without writing a channel message handler. Whispers are only accepted from subscribed
-sockets and are delivered to everyone else on the channel.
+  async onMemberLeave(_socket: AuthenticatedSocket<User>, member: PresenceMember) {
+    this.broadcast('room:member_left', member)
+  }
+}
+```
 
-```ts
-channel.listenForWhisper('typing', (payload) => {
-  console.log('typing status', payload)
-})
+The member `id` groups multiple sockets or browser tabs for the same person. These sockets remain
+separate broadcast targets but produce one entry in the presence snapshot. `onMemberJoin` runs for
+the first locally observed socket. `onMemberLeave` runs after the last one leaves. `onJoin` and
+`onLeave` still run for every socket.
 
-channel.whisper('typing', {
-  typing: true,
-})
-```
+Snapshots flatten `data` into `{ id, ...data, joinedAt }`. Use JSON-compatible values. The package
+checks snapshot serialization before running join hooks.
 
-Whispered events are delivered under an internal `client:` prefix, so they cannot impersonate
-server-emitted channel events.
+Distributed presence is a best-effort view, not an authoritative membership store. Timeouts,
+partitions, restarts, and concurrent changes can produce incomplete snapshots or repeated or missing
+member hooks. Keep presence hooks idempotent.
 
-## Client
+## Use the browser client
 
-Import the browser client from `@rlanz/socket/client`.
+The client uses the current browser origin and `/socket` by default.
 
 ```ts
 import { Socket } from '@rlanz/socket/client'
 import type { AppSocket } from '#generated/socket'
 
 const socket = new Socket<AppSocket>({
-  url: 'http://localhost:3333',
+  url: 'https://app.example.com',
   path: '/socket',
   autoReconnect: true,
   reconnectDelay: 250,
   reconnectMaxDelay: 5000,
+  onResubscribeError({ channel, error }) {
+    if (error.message === 'Session expired') return
+    console.error(`Could not resubscribe to ${channel}`, error)
+  },
 })
 
 socket.onStateChange((state) => {
@@ -730,7 +541,7 @@ socket.on('connect', () => {
 await socket.connect()
 ```
 
-### Subscribe, Listen, Send
+Subscribe before sending channel events.
 
 ```ts
 const channel = socket.channel('chat/:roomId', { roomId: 'general' })
@@ -739,22 +550,13 @@ channel
   .here((users) => console.log('present users', users))
   .joining((user) => console.log('joined', user))
   .leaving((user) => console.log('left', user))
-  .listen('chat:message', (message) => {
-    console.log('new message', message)
-  })
-  .listenForWhisper('typing', (payload) => {
-    console.log('typing', payload)
-  })
+  .listen('chat:message', (message) => console.log(message))
+  .listenForWhisper('typing', (payload) => console.log(payload))
 
 await channel.subscribe()
 
-channel.whisper('typing', { typing: true })
-
-const ack = await channel.sendWithAck('chat:send', {
-  body: 'Hello from the client',
-})
-
-console.log(ack)
+channel.send('chat:send', { body: 'No acknowledgement needed' })
+const ack = await channel.sendWithAck('chat:send', { body: 'Wait for the server' })
 
 channel.stopListening('chat:message')
 channel.stopListeningForWhisper('typing')
@@ -763,19 +565,20 @@ await socket.leave(channel.name)
 socket.disconnect()
 ```
 
-`subscribe()` and `unsubscribe()` accept an optional `{ timeout }` in milliseconds.
+`subscribe()` and `unsubscribe()` accept `{ timeout }` in milliseconds. The default is `5000`.
 
-The client reconnects automatically by default. `reconnectDelay` is the initial delay in
-milliseconds, and each failed retry doubles the delay until `reconnectMaxDelay` is reached.
-Set `autoReconnect: false` to disable reconnect attempts.
+Automatic reconnection starts at `250ms` and doubles up to `5s`. After reconnecting, the client
+subscribes again to desired channels. Pending acknowledgements fail and authentication and channel
+middleware run again. Events sent while disconnected are not replayed. A rejected automatic
+subscription calls `onResubscribeError` with the channel name and error. The client does not report
+this protocol outcome as a global JavaScript error.
 
-### React and Vue
+Set `autoReconnect: false` to disable retries. A deliberate server disconnect is terminal by
+default. Use `shouldReconnect(closeEvent)` to override the decision for any close code or reason.
 
-Framework adapters keep the generated `AppSocket` type at one application-level factory. Channel
-names, client methods, server events, and payloads then remain inferred without repeating the
-generic in every component.
+### React
 
-React:
+Create one typed set of hooks for the application.
 
 ```tsx
 // src/socket.ts
@@ -786,26 +589,31 @@ import type { AppSocket } from '#generated/socket'
 export const socket = new Socket<AppSocket>()
 export const { SocketProvider, useChannel, useChannelEvent, useSocketState } =
   createSocketHooks<AppSocket>()
+```
 
-// app.tsx
-<SocketProvider socket={socket} owned>
-  <Chat />
-</SocketProvider>
+```tsx
+function App() {
+  return (
+    <SocketProvider socket={socket} owned>
+      <Chat />
+    </SocketProvider>
+  )
+}
 
 function Chat() {
   const channel = useChannel('chat/:roomId', { roomId: 'general' })
-  useChannelEvent(
-    'chat/:roomId',
-    { roomId: 'general' },
-    'chat:message',
-    (message) => console.log(message.id)
+
+  useChannelEvent('chat/:roomId', { roomId: 'general' }, 'chat:message', (message) =>
+    console.log(message.id)
   )
 
   return <button onClick={() => channel?.send('chat:send', { text: 'Hello' })}>Send</button>
 }
 ```
 
-Vue:
+### Vue
+
+Create one typed set of composables for the application.
 
 ```ts
 // src/socket.ts
@@ -816,51 +624,249 @@ import type { AppSocket } from '#generated/socket'
 export const socket = new Socket<AppSocket>()
 export const { provideSocket, useChannel, useChannelEvent, useSocketState } =
   createSocketComposables<AppSocket>()
+```
 
-// In the root component setup
+```ts
+// Root component
 provideSocket(socket, { owned: true })
 
-// In a descendant component setup
+// Descendant component
 const channel = useChannel('chat/:roomId', { roomId: 'general' })
-useChannelEvent('chat/:roomId', { roomId: 'general' }, 'chat:message', (message) =>
-  console.log(message.id)
-)
 
-function send() {
-  channel.value?.send('chat:send', { text: 'Hello' })
-}
+useChannelEvent('chat/:roomId', { roomId: 'general' }, 'chat:message', (message) => {
+  console.log(message.id)
+})
 ```
 
-Adapters acquire and share channel subscriptions, attach listeners before subscribing, and release
-them when the component or scope is disposed. React returns `null` until its passive effect acquires
-the channel; Vue exposes a nullable shallow ref. Multiple consumers of the same channel share one
-subscription, including across development
-remounts, without removing listeners registered through the direct client API.
+The adapters share one subscription between consumers of the same channel and release it after the
+last consumer unmounts. React returns `null` until its effect acquires the channel. Vue returns a
+nullable shallow ref.
 
-Sockets are borrowed by default: the adapter neither connects nor disconnects them. Pass `owned` to
-`SocketProvider` or `{ owned: true }` to `provideSocket` only when that framework root exclusively
-owns the socket lifecycle. Otherwise call `socket.connect()` and `socket.disconnect()` in
-application-owned lifecycle code.
+Adapters borrow the socket by default and do not connect or disconnect it. Pass `owned` to
+`SocketProvider` or `{ owned: true }` to `provideSocket` only when that framework root owns the
+socket lifecycle.
 
-## Package Exports
+## Test broadcasts
+
+`socket.fake()` captures outgoing events without writing to WebSocket clients or the distributed
+transport.
 
 ```ts
-import { BaseChannel, SocketResponseError, defineConfig } from '@rlanz/socket'
-import type { AuthenticatedSocket, SocketConfig } from '@rlanz/socket/types'
-import SocketProvider from '@rlanz/socket/provider'
+import { test } from '@japa/runner'
 import socket from '@rlanz/socket/services/main'
-import { onMessage } from '@rlanz/socket/decorators'
+
+test.group('Notifications', (group) => {
+  group.each.teardown(() => socket.restore())
+
+  test('broadcasts a notification', async ({ client }) => {
+    const fake = socket.fake()
+
+    await client.post('/notifications').json({ message: 'Hello' })
+
+    fake.assertBroadcasted('notification:created', {
+      data: { message: 'Hello' },
+    })
+  })
+})
+```
+
+Use `using fake = socket.fake()` to restore the real service when the scope exits.
+
+```ts
+fake.assertBroadcasted('maintenance', { data: { active: true } })
+fake.assertNotBroadcasted('deploy:started')
+
+fake.assertEmittedTo('chat/general', 'chat:message', {
+  data: (data) => data.text === 'Hello',
+})
+fake.assertNotEmittedTo('chat/general', 'chat:typing')
+
+fake.assertCount(2, { target: 'channel', channel: 'chat/general' })
+fake.assertCount(0)
+```
+
+## Run multiple instances
+
+Without a transport, subscriptions, broadcasts, and presence stay inside one application instance.
+Configure an `@boringnode/bus` transport when multiple instances must exchange events.
+
+Install the dependency required by your transport. For Redis:
+
+```sh
+yarn add ioredis
+```
+
+```ts
+// config/socket.ts
+import { redis } from '@boringnode/bus/transports/redis'
+import { defineConfig } from '@rlanz/socket'
+
+export default defineConfig({
+  transport: {
+    driver: redis({
+      host: '127.0.0.1',
+      port: 6379,
+    }),
+    channel: 'socket::broadcast',
+    presenceTimeout: '100ms',
+    retryQueue: {
+      maxSize: 1000,
+    },
+  },
+})
+```
+
+All instances in one deployment must use a compatible transport and the same bus channel. The
+default channel is `socket::broadcast`.
+
+Broadcasts are delivered locally and published to the transport. Publication does not wait for
+remote delivery. Failed publications enter a bounded in-memory retry queue. The queue holds `1000`
+entries by default, removes duplicate messages, and drops the oldest entry when full. Configure
+`transport.retryQueue` to change these rules or disable retries. Setting `maxSize: null` creates an
+unbounded queue. A transport reconnect can deliver queued events after newer events.
+
+Presence uses the transport to collect snapshots. `presenceTimeout`, which defaults to `100ms`, sets
+how long an instance waits for replies.
+
+The transport does not make events durable. The package does not persist messages, acknowledge
+recipients, or recover events after a process restart. Persist application state separately when a
+client must recover missed events.
+
+## Production
+
+The package attaches to the AdonisJS HTTP server. HTTP and WebSocket traffic share the same process,
+listener, event loop, memory, and failure domain. A process failure disconnects every socket on that
+instance.
+
+### Reverse proxy
+
+Configure the proxy or load balancer to:
+
+- route `websocket.path` to the AdonisJS HTTP listener
+- forward HTTP/1.1 upgrades with `Upgrade` and `Connection: upgrade`
+- use `wss://` publicly and terminate TLS safely
+- preserve a validated public `Host`
+- replace `X-Forwarded-Proto` with the trusted public protocol
+- keep upgraded connections attached to their original instance
+- set the idle timeout above the heartbeat cadence
+- prevent direct access to the upstream
+
+Sticky sessions are not required and do not replace a shared transport.
+
+### Delivery guarantees
+
+Socket delivery is temporary and best-effort:
+
+- reconnecting creates a new socket session
+- pending acknowledgements fail on disconnect
+- events sent while disconnected are not replayed
+- `sendWithAck()` confirms that the server handler returned, not that a broadcast reached a client
+- transport publication does not confirm remote delivery
+- distributed presence can be incomplete during failures or concurrent changes
+
+Applications that need durable notifications or at-least-once processing must store events or state
+outside this package. Define application-level event IDs, cursors, deduplication, acknowledgements,
+and replay where needed.
+
+### Shutdown and resource limits
+
+During shutdown, the service becomes unready, rejects new upgrades, closes existing sockets, runs
+subscription and disconnect hooks, and then disconnects the bus. It does not drain established
+sockets or wait for pending client acknowledgements.
+
+After `shutdownTimeout`, the service releases its internal socket and subscription state. JavaScript
+handlers that ignore cancellation can continue running.
+
+Remove an instance from new traffic before a rolling restart when your platform allows it. Give the
+process enough termination time to run hooks and close the bus.
+
+There is no built-in total connection limit. Each connection consumes a file descriptor, memory,
+heartbeat state, message queues, and channel subscriptions. Set memory and file descriptor limits,
+cap connections at the edge, and load test realistic connection counts, payloads, message rates, and
+broadcast fan-out.
+
+Slow consumers are disconnected when `maxBufferedAmount` is exceeded. Oversized outbound messages
+are rejected rather than buffered or retried.
+
+### Production checklist
+
+- [ ] Forward WebSocket upgrades on the configured path.
+- [ ] Preserve `Host` and replace `X-Forwarded-Proto` at the proxy.
+- [ ] Configure exact browser origins and upgrade authentication.
+- [ ] Set and test the heartbeat and proxy idle timeout.
+- [ ] Configure one shared transport for every related instance.
+- [ ] Make clients tolerate reconnects, repeated subscriptions, duplicates, and missed events.
+- [ ] Store and replay application-critical events outside the socket transport.
+- [ ] Tune payload, rate, queue, subscription, connection, memory, and file descriptor limits.
+- [ ] Add readiness, liveness, logs, metrics, and transport monitoring.
+- [ ] Allow enough shutdown time for hooks and bus disconnection.
+
+## Health checks
+
+Add `SocketHealthCheck` to the application readiness checks.
+
+```ts
+// start/health.ts
+import { DiskSpaceCheck, HealthChecks, MemoryHeapCheck } from '@adonisjs/core/health'
 import { SocketHealthCheck } from '@rlanz/socket/health_check'
+import socket from '@rlanz/socket/services/main'
+
+export const healthChecks = new HealthChecks().register([
+  new DiskSpaceCheck(),
+  new MemoryHeapCheck(),
+  new SocketHealthCheck(socket),
+])
+```
+
+The check reports `ok` after the WebSocket service boots. It reports `error` while the service is
+starting, stopping, stopped, or failed. Metadata includes local connection and channel counts.
+
+This check does not probe the transport, remote instances, or end-to-end delivery. Monitor those
+separately and keep a process liveness check so a readiness failure does not cause a restart loop.
+
+## OpenTelemetry
+
+The package emits `diagnostics_channel` events and provides optional OpenTelemetry instrumentation.
+
+```ts
+import { registerInstrumentations } from '@opentelemetry/instrumentation'
 import { SocketInstrumentation } from '@rlanz/socket/otel'
-import { SocketFake } from '@rlanz/socket/testing'
-import { Socket } from '@rlanz/socket/client'
+
+const unregister = registerInstrumentations({
+  instrumentations: [new SocketInstrumentation()],
+})
+```
+
+You can pass the same instrumentation to an OpenTelemetry `NodeSDK` or an integration such as
+`@adonisjs/otel`. Registration enables it. Call `unregister()` only when removing a standalone
+registration.
+
+The instrumentation creates spans for connections, disconnections, subscriptions,
+unsubscriptions, incoming channel messages, and broadcast delivery. It records counters for active
+connections, active subscriptions, received messages, broadcasts, and local deliveries.
+
+Also monitor event-loop delay, memory, CPU, open file descriptors, proxy upgrade failures, reconnect
+rates, and transport health. A broadcast delivery counter records a write to a local `ws` object. It
+does not confirm that the application received the event.
+
+## Package exports
+
+```ts
+import { BaseChannel, SocketResponseError, defineConfig } from '@rlanz/socket'
 import { generateSocketRegistry } from '@rlanz/socket/assembler_hook'
+import { Socket } from '@rlanz/socket/client'
 import { createSocketHooks } from '@rlanz/socket/client/react'
 import { createSocketComposables } from '@rlanz/socket/client/vue'
-import type { SocketOptions, PresenceData } from '@rlanz/socket/client/types'
+import { onMessage } from '@rlanz/socket/decorators'
+import { SocketHealthCheck } from '@rlanz/socket/health_check'
+import { SocketInstrumentation } from '@rlanz/socket/otel'
+import socket from '@rlanz/socket/services/main'
+import { SocketFake } from '@rlanz/socket/testing'
+import type { AuthenticatedSocket, SocketConfig } from '@rlanz/socket/types'
+import type { PresenceData, SocketOptions } from '@rlanz/socket/client/types'
 ```
 
-Available exports:
+Available entry points:
 
 - `@rlanz/socket`
 - `@rlanz/socket/provider`