@rlanz/socket 0.0.1-0

package/LICENSE.md

@@ -0,0 +1,9 @@
+# The MIT License
+
+Copyright (c) 2026 Romain Lanz, AdonisJS Core Team, contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,387 @@
+# @rlanz/socket
+
+WebSocket integration for AdonisJS, powered by [`ws`](https://github.com/websockets/ws).
+
+## Installation
+
+```sh
+yarn add @rlanz/socket
+```
+
+Register the provider in your AdonisJS application:
+
+```ts
+// adonisrc.ts
+export default defineConfig({
+  providers: [() => import('@rlanz/socket/provider')],
+})
+```
+
+## Configuration
+
+Create a socket config file and tune the WebSocket path or heartbeat.
+
+```ts
+// config/socket.ts
+import { defineConfig } from '@adonisjs/core/config'
+
+export default defineConfig({
+  websocket: {
+    path: '/socket',
+    pingInterval: 25_000,
+    pingTimeout: 5_000,
+  },
+})
+```
+
+- `websocket.path` defaults to `/socket`.
+- `websocket.pingInterval` sends a WebSocket ping every configured number of milliseconds.
+- `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.
+
+### 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.
+
+```ts
+// config/socket.ts
+import { defineConfig } from '@adonisjs/core/config'
+
+export default defineConfig({
+  websocket: {
+    async authenticate({ auth, httpContext }) {
+      const user = await httpContext!.auth.authenticate()
+
+      return {
+        user,
+        auth,
+        data: {
+          connectedAt: new Date(),
+        },
+      }
+    },
+  },
+})
+```
+
+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`.
+
+### Horizontal Sync
+
+Configure an [`@boringnode/bus`](https://github.com/boringnode/bus) transport to synchronize broadcasts across multiple SocketService instances.
+
+```ts
+// config/socket.ts
+import { defineConfig } from '@adonisjs/core/config'
+import { redis } from '@boringnode/bus/transports/redis'
+
+export default defineConfig({
+  transport: {
+    driver: redis({
+      host: '127.0.0.1',
+      port: 6379,
+    }),
+    channel: 'socket::broadcast',
+    presenceTimeout: 100,
+  },
+})
+```
+
+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.
+
+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.
+
+### Health Checks
+
+Register `SocketHealthCheck` inside your AdonisJS readiness checks to report whether the WebSocket service is ready to accept traffic.
+
+```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'
+
+export const healthChecks = new HealthChecks().register([
+  new DiskSpaceCheck(),
+  new MemoryHeapCheck(),
+  new SocketHealthCheck(socket),
+])
+```
+
+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.
+
+### Testing
+
+Use `socket.fake()` to intercept outgoing events and store them in memory without touching any connected WebSocket client or distributed transport.
+
+```ts
+import { test } from '@japa/runner'
+import socket from '@rlanz/socket/services/main'
+
+test.group('Notifications', (group) => {
+  group.each.teardown(() => {
+    socket.restore()
+  })
+
+  test('broadcasts the notification', async ({ client }) => {
+    const fake = socket.fake()
+
+    await client.post('/notifications').json({ message: 'Hello' })
+
+    fake.assertBroadcasted('notification:created', {
+      data: { message: 'Hello' },
+    })
+  })
+})
+```
+
+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.
+
+```ts
+fake.assertBroadcasted('maintenance', { data: { active: true } })
+fake.assertNotBroadcasted('maintenance')
+
+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()
+```
+
+### 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'
+
+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.
+
+## Channels
+
+Channels are discovered from `app/channels/**/*_channel.{ts,js}`. Export a default class extending `BaseChannel` and define a static `pattern`.
+
+```ts
+// app/channels/chat_channel.ts
+import { BaseChannel } from '@rlanz/socket'
+import type { AuthenticatedSocket } from '@rlanz/socket/types'
+
+type User = { id: string; name: string }
+
+export default class ChatChannel extends BaseChannel<User> {
+  static pattern = 'chat/:roomId'
+
+  async onJoin(socket: AuthenticatedSocket<User>, roomId: string) {
+    this.broadcast('chat:system', {
+      message: `${socket.user?.name ?? 'Someone'} joined ${roomId}`,
+    })
+  }
+
+  async onLeave(socket: AuthenticatedSocket<User>, roomId: string) {
+    this.broadcastExcept(socket.id, 'chat:system', {
+      message: `${socket.user?.name ?? 'Someone'} left ${roomId}`,
+    })
+  }
+}
+```
+
+### Middleware
+
+Middlewares run before subscription. They may be functions or objects with a `handle` method.
+
+```ts
+import { BaseChannel } from '@rlanz/socket'
+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)
+  await next()
+}
+
+export default class ChatChannel extends BaseChannel<User> {
+  static pattern = 'chat/:roomId'
+  static middlewares = [auth]
+}
+```
+
+### 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'
+
+type User = { id: string; name: string }
+
+export default class RoomChannel extends BaseChannel<User> {
+  static pattern = 'rooms/:roomId'
+  static options = { presence: true }
+
+  getPresenceInfo(socket: AuthenticatedSocket<User>): PresenceMember {
+    return {
+      id: socket.user!.id,
+      name: socket.user!.name,
+    }
+  }
+
+  async onMemberJoin(socket: AuthenticatedSocket<User>, member: PresenceMember) {
+    this.broadcastExcept(socket.id, 'room:member_joined', member)
+  }
+
+  async onMemberLeave(socket: AuthenticatedSocket<User>, member: PresenceMember) {
+    this.broadcast('room:member_left', member)
+  }
+}
+```
+
+## Channel Messages
+
+Incoming client messages are handled through the `handlers` map, the `@onMessage` decorator, or the `onMessage` fallback.
+
+```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 Events = {
+  'chat:send': { body: string }
+  'chat:typing': { typing: boolean }
+}
+
+export default class ChatChannel extends BaseChannel<User, Events> {
+  static pattern = 'chat/:roomId'
+
+  protected handlers = {
+    'chat:send': this.sendMessage,
+  }
+
+  async sendMessage(socket: AuthenticatedSocket<User>, data: Events['chat:send']) {
+    this.broadcast('chat:message', {
+      user: socket.user,
+      body: data.body,
+    })
+
+    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,
+    })
+  }
+
+  async onMessage(socket: AuthenticatedSocket<User>, event: string, data: unknown) {
+    console.log('Unhandled channel message', event, data)
+  }
+}
+```
+
+Returning a value from a handler resolves `sendWithAck()` on the client.
+
+## Client
+
+Import the browser client from `@rlanz/socket/client`.
+
+```ts
+import { Socket } from '@rlanz/socket/client'
+
+const socket = new Socket({
+  url: 'http://localhost:3333',
+  path: '/socket',
+  auth: { token: 'secret' },
+  autoReconnect: true,
+  reconnectDelay: 250,
+  reconnectMaxDelay: 5000,
+})
+
+socket.onStateChange((state) => {
+  console.log('socket state:', state)
+})
+
+socket.on('connect', () => {
+  console.log('connected')
+})
+
+await socket.connect()
+```
+
+### Subscribe, Listen, Send
+
+```ts
+const channel = socket.channel('chat/general')
+
+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)
+  })
+
+await channel.subscribe()
+
+channel.send('chat:typing', { typing: true })
+
+const ack = await channel.sendWithAck('chat:send', {
+  body: 'Hello from the client',
+})
+
+console.log(ack)
+
+channel.stopListening('chat:message')
+await channel.unsubscribe()
+await socket.leave('chat/general')
+socket.disconnect()
+```
+
+`subscribe()` and `unsubscribe()` accept an optional `{ timeout }` in milliseconds.
+
+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.
+
+## Package Exports
+
+```ts
+import { BaseChannel, ChannelRouter, PresenceManager, SocketService } from '@rlanz/socket'
+import type { AuthenticatedSocket, SocketConfig } from '@rlanz/socket/types'
+import SocketProvider from '@rlanz/socket/provider'
+import { onMessage } from '@rlanz/socket/decorators'
+import { Socket, Channel } from '@rlanz/socket/client'
+import type { SocketOptions, PresenceData } from '@rlanz/socket/client/types'
+```
+
+Available exports:
+
+- `@rlanz/socket`
+- `@rlanz/socket/provider`
+- `@rlanz/socket/decorators`
+- `@rlanz/socket/types`
+- `@rlanz/socket/client`
+- `@rlanz/socket/client/types`