@rlanz/socket 0.0.1-0 → 0.0.1-10

package/README.md

@@ -8,75 +8,169 @@ WebSocket integration for AdonisJS, powered by [`ws`](https://github.com/websock
 yarn add @rlanz/socket
 ```
 
-Register the provider in your AdonisJS application:
+Configure the package in your AdonisJS application:
+
+```sh
+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:
 
 ```ts
 // adonisrc.ts
 export default defineConfig({
-  providers: [() => import('@rlanz/socket/provider')],
+  providers: [
+    {
+      file: () => import('@rlanz/socket/provider'),
+      environment: ['web'],
+    },
+  ],
+  hooks: {
+    init: [() => import('@rlanz/socket/assembler_hook')],
+  },
 })
 ```
 
+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.
+
 ## Configuration
 
 Create a socket config file and tune the WebSocket path or heartbeat.
 
 ```ts
 // config/socket.ts
-import { defineConfig } from '@adonisjs/core/config'
+import { defineConfig } from '@rlanz/socket'
 
 export default defineConfig({
   websocket: {
     path: '/socket',
-    pingInterval: 25_000,
-    pingTimeout: 5_000,
+    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,
+    shutdownTimeout: '5s',
   },
 })
 ```
 
 - `websocket.path` defaults to `/socket`.
-- `websocket.pingInterval` sends a WebSocket ping every configured number of milliseconds.
+- 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.shutdownTimeout` bounds the complete shutdown, including an in-progress boot,
+  in-flight handlers, subscription hooks, and transport teardown; it defaults to `5s`. When it
+  expires, internal socket and subscription state is forcibly released, but JavaScript code that
+  ignores cancellation cannot itself be interrupted.
+
+`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.
 
 ### Authentication
 
-Authenticate sockets during the HTTP upgrade with `websocket.authenticate`. The hook receives the
-upgrade request, the parsed client auth payload, and the AdonisJS HTTP context.
+Authenticate sockets during the HTTP upgrade with `websocket.authenticate`. The hook receives an
+AdonisJS HTTP context and returns the authenticated user.
+
+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.
+
+They are not channel middleware. Channel authorization and per-channel behavior still live on the
+channel itself through `static middlewares`.
 
 ```ts
 // config/socket.ts
-import { defineConfig } from '@adonisjs/core/config'
+import { authenticateWithAdonisAuth, defineConfig } from '@rlanz/socket'
+
+type User = { id: string | number; name: string }
 
 export default defineConfig({
   websocket: {
-    async authenticate({ auth, httpContext }) {
-      const user = await httpContext!.auth.authenticate()
-
-      return {
-        user,
-        auth,
-        data: {
-          connectedAt: new Date(),
-        },
-      }
-    },
+    middleware: [
+      () => import('@adonisjs/session/session_middleware'),
+      () => import('@adonisjs/auth/initialize_auth_middleware'),
+    ],
+
+    authenticate: authenticateWithAdonisAuth<User>(),
   },
 })
 ```
 
-Return `false`, `null`, or throw to reject the upgrade with `401 Unauthorized`. The returned `user`
-is available as `socket.user`, `data` is stored on `socket.raw.data`, and the HTTP context remains
-available as `socket.raw.httpContext`.
+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:
+
+```ts
+async authenticate({ httpContext }) {
+  await httpContext.auth.authenticateUsing()
+  return httpContext.auth.getUserOrFail()
+}
+```
 
 ### Horizontal Sync
 
-Configure an [`@boringnode/bus`](https://github.com/boringnode/bus) transport to synchronize broadcasts across multiple SocketService instances.
+Configure an [`@boringnode/bus`](https://github.com/boringnode/bus) transport to synchronize broadcasts across multiple application instances.
+
+Install the peer dependency required by the selected transport. For Redis:
+
+```sh
+yarn add ioredis
+```
 
 ```ts
 // config/socket.ts
-import { defineConfig } from '@adonisjs/core/config'
 import { redis } from '@boringnode/bus/transports/redis'
+import { defineConfig } from '@rlanz/socket'
 
 export default defineConfig({
   transport: {
@@ -85,14 +179,22 @@ export default defineConfig({
       port: 6379,
     }),
     channel: 'socket::broadcast',
-    presenceTimeout: 100,
+    presenceTimeout: '100ms',
+    retryQueue: {
+      maxSize: 1000,
+    },
   },
 })
 ```
 
-When configured, `socket.to(channel).emit(...)`, `socket.to(channel).except(socketId).emit(...)`, `socket.toUser(userId).emit(...)`, and `socket.broadcast(...)` are delivered locally and published to the bus so other instances can deliver them to their own connected sockets.
+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.
+
+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`.
 
-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 `100` milliseconds.
+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.
 
 ### Health Checks
 
@@ -140,22 +242,19 @@ test.group('Notifications', (group) => {
 
 The fake supports explicit resource management as well, so `using fake = socket.fake()` automatically restores the real socket service when the test scope exits.
 
-Assertion helpers cover global broadcasts, channel events, user events, counts, and negative assertions.
+Five assertion helpers cover global broadcasts, channel events, counts, and negative assertions.
 
 ```ts
 fake.assertBroadcasted('maintenance', { data: { active: true } })
-fake.assertNotBroadcasted('maintenance')
+fake.assertNotBroadcasted('deploy:started')
 
 fake.assertEmittedTo('chat/general', 'chat:message', {
   data: (data) => data.text === 'Hello',
 })
 fake.assertNotEmittedTo('chat/general', 'chat:typing')
 
-fake.assertEmittedToUser(1, 'notification', { data: { unread: 3 } })
-fake.assertNotEmittedToUser(1, 'notification')
-
-fake.assertEmittedCount(2, { target: 'channel', channel: 'chat/general' })
-fake.assertNothingEmitted()
+fake.assertCount(2, { target: 'channel', channel: 'chat/general' })
+fake.assertCount(0)
 ```
 
 ### OpenTelemetry
@@ -164,46 +263,297 @@ fake.assertNothingEmitted()
 
 ```ts
 import { SocketInstrumentation } from '@rlanz/socket/otel'
+import { registerInstrumentations } from '@opentelemetry/instrumentation'
 
-const instrumentation = new SocketInstrumentation()
-
-instrumentation.enable()
-instrumentation.manuallyRegister()
+const unregister = registerInstrumentations({
+  instrumentations: [new SocketInstrumentation()],
+})
 ```
 
+The same instrumentation instance can be passed to the `instrumentations` option of an
+OpenTelemetry `NodeSDK` or an integration such as `@adonisjs/otel`. Registration enables it; no
+additional `enable()` or manual registration call is required. Call `unregister()` only when the
+standalone registration above should be removed.
+
 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.
+
+### Production checklist
+
+- [ ] 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` and define a static `pattern`.
+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.
 
 ```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 }
 
-export default class ChatChannel extends BaseChannel<User> {
+type ServerEvents = {
+  'chat:message': Message
+}
+
+export default class ChatChannel extends BaseChannel<User, ServerEvents> {
   static pattern = 'chat/:roomId'
 
-  async onJoin(socket: AuthenticatedSocket<User>, roomId: string) {
-    this.broadcast('chat:system', {
-      message: `${socket.user?.name ?? 'Someone'} joined ${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
   }
 
-  async onLeave(socket: AuthenticatedSocket<User>, roomId: string) {
-    this.broadcastExcept(socket.id, 'chat:system', {
-      message: `${socket.user?.name ?? 'Someone'} left ${roomId}`,
-    })
+  @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:
+
+```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()
   }
 }
 ```
 
+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.
+
+The Assembler hook generates an explicit `AppSocket` registry. Pass it once to the browser client:
+
+```ts
+import { Socket } from '@rlanz/socket/client'
+import type { AppSocket } from '#generated/socket'
+
+const socket = new Socket<AppSocket>()
+const channel = socket.channel('chat/:roomId', { roomId: 'general' })
+
+channel.listen('chat:message', (message) => console.log(message.id))
+channel.send('chat:ping')
+
+const message = await channel.sendWithAck('chat:send', { text: 'Hello' })
+console.log(message.id)
+```
+
+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.
+
+Client code can also extract event payloads without constructing a channel first:
+
+```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'>
+```
+
+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:
+
+```ts
+// hooks/socket.ts
+import { generateSocketRegistry } from '@rlanz/socket/assembler_hook'
+
+export default generateSocketRegistry({
+  source: './app/realtime',
+  glob: ['**/*.ts'],
+  output: '.adonisjs/client/socket.d.ts',
+})
+```
+
+```ts
+// adonisrc.ts
+export default defineConfig({
+  providers: [
+    {
+      file: () => import('@rlanz/socket/provider'),
+      environment: ['web'],
+    },
+  ],
+  hooks: {
+    init: [() => import('./hooks/socket.js')],
+  },
+})
+```
+
+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.
+
 ### Middleware
 
-Middlewares run before subscription. They may be functions or objects with a `handle` method.
+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.
 
 ```ts
 import { BaseChannel } from '@rlanz/socket'
@@ -212,11 +562,7 @@ import type { MiddlewareContext } from '@rlanz/socket/types'
 type User = { id: string; name: string }
 
 async function auth(ctx: MiddlewareContext<User>, next: () => Promise<void>) {
-  if (!ctx.socket.user) {
-    throw new Error('Unauthorized')
-  }
-
-  await ctx.socket.joinUserRoom(ctx.socket.user.id)
+  ctx.socket.getUserOrFail()
   await next()
 }
 
@@ -226,24 +572,58 @@ export default class ChatChannel extends BaseChannel<User> {
 }
 ```
 
+```ts
+import { inject } from '@adonisjs/core'
+import type { MiddlewareContext } from '@rlanz/socket/types'
+import RoomService from '#services/room_service'
+
+@inject()
+class EnsureRoomAccess {
+  constructor(private rooms: RoomService) {}
+
+  async handle(ctx: MiddlewareContext<User>, next: () => Promise<void>) {
+    await this.rooms.authorize(ctx.socket.getUserOrFail(), ctx.params.roomId)
+    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.
+
 ### Presence
 
 Enable presence with `static options = { presence: true }` and implement `getPresenceInfo`.
 
 ```ts
 import { BaseChannel } from '@rlanz/socket'
-import type { AuthenticatedSocket, PresenceMember } from '@rlanz/socket/types'
+import type { AuthenticatedSocket, PresenceInfo, PresenceMember } from '@rlanz/socket/types'
 
 type User = { id: string; name: string }
+type ServerEvents = {
+  'room:member_joined': PresenceMember
+  'room:member_left': PresenceMember
+}
 
-export default class RoomChannel extends BaseChannel<User> {
+export default class RoomChannel extends BaseChannel<User, ServerEvents> {
   static pattern = 'rooms/:roomId'
   static options = { presence: true }
 
-  getPresenceInfo(socket: AuthenticatedSocket<User>): PresenceMember {
+  getPresenceInfo(socket: AuthenticatedSocket<User>): PresenceInfo {
+    const user = socket.getUserOrFail()
+
     return {
-      id: socket.user!.id,
-      name: socket.user!.name,
+      id: user.id,
+      data: {
+        name: user.name,
+      },
     }
   }
 
@@ -257,9 +637,32 @@ export default class RoomChannel extends BaseChannel<User> {
 }
 ```
 
+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 }`.
+
+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.
+
+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.
+
+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.
+
 ## Channel Messages
 
-Incoming client messages are handled through the `handlers` map, the `@onMessage` decorator, or the `onMessage` fallback.
+Incoming client messages are handled through the `@onMessage` decorator.
+Unknown events receive a negative acknowledgement.
 
 ```ts
 import { BaseChannel } from '@rlanz/socket'
@@ -267,19 +670,15 @@ import { onMessage } from '@rlanz/socket/decorators'
 import type { AuthenticatedSocket } from '@rlanz/socket/types'
 
 type User = { id: string; name: string }
-type Events = {
-  'chat:send': { body: string }
-  'chat:typing': { typing: boolean }
+type ServerEvents = {
+  'chat:message': { user: User | undefined; body: string }
 }
 
-export default class ChatChannel extends BaseChannel<User, Events> {
+export default class ChatChannel extends BaseChannel<User, ServerEvents> {
   static pattern = 'chat/:roomId'
 
-  protected handlers = {
-    'chat:send': this.sendMessage,
-  }
-
-  async sendMessage(socket: AuthenticatedSocket<User>, data: Events['chat:send']) {
+  @onMessage('chat:send')
+  async sendMessage(socket: AuthenticatedSocket<User>, data: { body: string }) {
     this.broadcast('chat:message', {
       user: socket.user,
       body: data.body,
@@ -287,22 +686,32 @@ export default class ChatChannel extends BaseChannel<User, Events> {
 
     return { delivered: true }
   }
+}
+```
 
-  @onMessage('chat:typing')
-  async typing(socket: AuthenticatedSocket<User>, data: Events['chat:typing']) {
-    this.broadcastExcept(socket.id, 'chat:typing', {
-      user: socket.user,
-      typing: data.typing,
-    })
-  }
+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.
 
-  async onMessage(socket: AuthenticatedSocket<User>, event: string, data: unknown) {
-    console.log('Unhandled channel message', event, data)
-  }
-}
+### Client-to-client events
+
+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.
+
+```ts
+channel.listenForWhisper('typing', (payload) => {
+  console.log('typing status', payload)
+})
+
+channel.whisper('typing', {
+  typing: true,
+})
 ```
 
-Returning a value from a handler resolves `sendWithAck()` on the client.
+Whispered events are delivered under an internal `client:` prefix, so they cannot impersonate
+server-emitted channel events.
 
 ## Client
 
@@ -310,11 +719,11 @@ Import the browser client from `@rlanz/socket/client`.
 
 ```ts
 import { Socket } from '@rlanz/socket/client'
+import type { AppSocket } from '#generated/socket'
 
-const socket = new Socket({
+const socket = new Socket<AppSocket>({
   url: 'http://localhost:3333',
   path: '/socket',
-  auth: { token: 'secret' },
   autoReconnect: true,
   reconnectDelay: 250,
   reconnectMaxDelay: 5000,
@@ -334,7 +743,7 @@ await socket.connect()
 ### Subscribe, Listen, Send
 
 ```ts
-const channel = socket.channel('chat/general')
+const channel = socket.channel('chat/:roomId', { roomId: 'general' })
 
 channel
   .here((users) => console.log('present users', users))
@@ -343,10 +752,13 @@ channel
   .listen('chat:message', (message) => {
     console.log('new message', message)
   })
+  .listenForWhisper('typing', (payload) => {
+    console.log('typing', payload)
+  })
 
 await channel.subscribe()
 
-channel.send('chat:typing', { typing: true })
+channel.whisper('typing', { typing: true })
 
 const ack = await channel.sendWithAck('chat:send', {
   body: 'Hello from the client',
@@ -355,8 +767,9 @@ const ack = await channel.sendWithAck('chat:send', {
 console.log(ack)
 
 channel.stopListening('chat:message')
+channel.stopListeningForWhisper('typing')
 await channel.unsubscribe()
-await socket.leave('chat/general')
+await socket.leave(channel.name)
 socket.disconnect()
 ```
 
@@ -364,16 +777,99 @@ socket.disconnect()
 
 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.
+Set `autoReconnect: false` to disable reconnect attempts. A deliberate server disconnect is
+terminal by default; transient transport failures still reconnect. Use
+`shouldReconnect: (closeEvent) => boolean` to override that decision from the WebSocket close code
+and reason.
+
+### React and Vue
+
+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:
+
+```tsx
+// src/socket.ts
+import { Socket } from '@rlanz/socket/client'
+import { createSocketHooks } from '@rlanz/socket/client/react'
+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>
+
+function Chat() {
+  const channel = useChannel('chat/:roomId', { roomId: 'general' })
+  useChannelEvent(
+    'chat/:roomId',
+    { roomId: 'general' },
+    'chat:message',
+    (message) => console.log(message.id)
+  )
+
+  return <button onClick={() => channel?.send('chat:send', { text: 'Hello' })}>Send</button>
+}
+```
+
+Vue:
+
+```ts
+// src/socket.ts
+import { Socket } from '@rlanz/socket/client'
+import { createSocketComposables } from '@rlanz/socket/client/vue'
+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
+provideSocket(socket, { owned: true })
+
+// In a descendant component setup
+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' })
+}
+```
+
+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.
+
+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.
 
 ## Package Exports
 
 ```ts
-import { BaseChannel, ChannelRouter, PresenceManager, SocketService } from '@rlanz/socket'
+import { BaseChannel, SocketResponseError, defineConfig } from '@rlanz/socket'
 import type { AuthenticatedSocket, SocketConfig } from '@rlanz/socket/types'
 import SocketProvider from '@rlanz/socket/provider'
+import socket from '@rlanz/socket/services/main'
 import { onMessage } from '@rlanz/socket/decorators'
-import { Socket, Channel } from '@rlanz/socket/client'
+import { SocketHealthCheck } from '@rlanz/socket/health_check'
+import { SocketInstrumentation } from '@rlanz/socket/otel'
+import { SocketFake } from '@rlanz/socket/testing'
+import { Socket } from '@rlanz/socket/client'
+import { generateSocketRegistry } from '@rlanz/socket/assembler_hook'
+import { createSocketHooks } from '@rlanz/socket/client/react'
+import { createSocketComposables } from '@rlanz/socket/client/vue'
 import type { SocketOptions, PresenceData } from '@rlanz/socket/client/types'
 ```
 
@@ -381,7 +877,15 @@ Available exports:
 
 - `@rlanz/socket`
 - `@rlanz/socket/provider`
+- `@rlanz/socket/assembler_hook`
+- `@rlanz/socket/services/main`
 - `@rlanz/socket/decorators`
+- `@rlanz/socket/health_check`
+- `@rlanz/socket/otel`
+- `@rlanz/socket/testing`
 - `@rlanz/socket/types`
+- `@rlanz/socket/types/tracing_channels`
 - `@rlanz/socket/client`
 - `@rlanz/socket/client/types`
+- `@rlanz/socket/client/react`
+- `@rlanz/socket/client/vue`