@rlanz/socket 0.0.1-0

package/build/src/types.d.ts

@@ -0,0 +1,5 @@
+export { A as AuthenticatedSocket, C as ChannelEventMap, h as ChannelHandlerFn, a as ChannelHandlerMap, b as ChannelMatch, d as ChannelOptions, M as Middleware, i as MiddlewareClass, j as MiddlewareContext, k as MiddlewareFn, l as PresenceMember, R as RawSocket, m as SocketAuthenticationDetails, n as SocketAuthenticationHandler, o as SocketAuthenticationResult, e as SocketConfig, S as SocketEvents, g as SocketHealthSnapshot, p as SocketHttpContextFactory, f as SocketServiceStatus, q as SocketUpgradeContext } from '../types-C0rDwbry.js';
+import 'ws';
+import 'node:http';
+export { C as ChannelAck, a as ChannelMessage } from '../shared_types-Dw9AphfO.js';
+import '@boringnode/bus/types/main';

package/build/src/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/build/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/build/types-C0rDwbry.d.ts

@@ -0,0 +1,393 @@
+import { WebSocket } from 'ws';
+import { IncomingMessage } from 'node:http';
+import { TransportFactory } from '@boringnode/bus/types/main';
+import './shared_types-Dw9AphfO.js';
+
+declare const PRESENCE_DATA_KEY = "__rlanzSocketPresence";
+type PresenceSocketData = Record<string, unknown> & {
+    [PRESENCE_DATA_KEY]?: Record<string, PresenceUser>;
+};
+interface PresenceUser {
+    id: string;
+    name: string;
+    joinedAt: Date;
+    [key: string]: unknown;
+}
+interface PresenceData {
+    channel: string;
+    users: PresenceUser[];
+    count: number;
+}
+interface PresenceSocket {
+    id: string;
+    data: PresenceSocketData;
+}
+/**
+ * Tracks user presence in channels.
+ *
+ * channel -> socketId -> PresenceUser
+ */
+declare class PresenceManager {
+    #private;
+    /**
+     * Sets the socket fetcher used to build distributed snapshots.
+     */
+    setSocketFetcher(fetchSockets: (channel: string) => Promise<PresenceSocket[]>): void;
+    /**
+     * Adds a user to a channel.
+     */
+    join(channel: string, socket: PresenceSocket, member: string | PresenceMember): void;
+    /**
+     * Removes a user from a channel.
+     */
+    leave(channel: string, socket: PresenceSocket): void;
+    /**
+     * Removes a user from every channel.
+     * Returns the list of channels the user left.
+     */
+    leaveAll(socket: PresenceSocket): string[];
+    /**
+     * Gets presence data for a channel.
+     */
+    snapshot(channel: string): Promise<PresenceData>;
+    /**
+     * Gets the number of users in a channel.
+     */
+    count(channel: string): Promise<number>;
+    /**
+     * Checks whether a socket is locally present in a channel.
+     */
+    hasLocal(channel: string, socketId: string): boolean;
+    /**
+     * Lists every local channel where a socket is present.
+     */
+    getLocalChannelsForSocket(socketId: string): string[];
+    /**
+     * Lists sockets that are locally present in a channel.
+     */
+    getLocalSockets(channel: string): PresenceSocket[];
+}
+
+interface ChannelBroadcaster {
+    to(channel: string): {
+        emit(event: string, data: unknown): void;
+        except(socketId: string): {
+            emit(event: string, data: unknown): void;
+        };
+    };
+}
+/**
+ * Abstract class used to define a channel.
+ *
+ * @example
+ * ```ts
+ * export default class ChatChannel extends BaseChannel {
+ *   static pattern = 'chat/:roomId'
+ *   static middlewares = [
+ *     async (ctx, next) => {
+ *       // Authorize access to the channel through middleware.
+ *       // if (!Room.isMember(ctx.params.roomId, ctx.socket.user.id)) throw new Error('Forbidden')
+ *       await next()
+ *     },
+ *   ]
+ * }
+ * ```
+ *
+ * @example With presence and decorated handlers
+ * ```ts
+ * import { onMessage } from '@rlanz/socket/decorators'
+ *
+ * export default class ChatChannel extends BaseChannel {
+ *   static pattern = 'chat/:roomId'
+ *   static options = { presence: true }
+ *
+ *   static middlewares = [
+ *     async (ctx, next) => {
+ *       if (!ctx.socket.user.isVerified) throw new Error('Not verified')
+ *       await next()
+ *     }
+ *   ]
+ *
+ *   @onMessage('chat:send')
+ *   async handleSend(socket: AuthenticatedSocket<User>, data: unknown) {
+ *     // Handle chat:send event
+ *   }
+ *
+ *   @onMessage('chat:typing')
+ *   async handleTyping(socket: AuthenticatedSocket<User>, data: unknown) {
+ *     // Handle chat:typing event
+ *   }
+ * }
+ * ```
+ */
+declare class BaseChannel<User = unknown, Events extends ChannelEventMap = ChannelEventMap, HttpContext = unknown> {
+    /**
+     * URL-like channel pattern, for example: 'chat/:roomId'.
+     */
+    static pattern: string;
+    /**
+     * Channel options.
+     */
+    static options?: ChannelOptions;
+    /**
+     * Middlewares to run before subscription.
+     */
+    static middlewares?: Middleware<any, any>[];
+    /**
+     * Event handler map.
+     * Ex: { 'chat:send': 'handleSend' }
+     */
+    protected handlers: ChannelHandlerMap<User, Events, HttpContext>;
+    /**
+     * Injected socket service.
+     */
+    protected socket: ChannelBroadcaster;
+    /**
+     * Full channel name, for example: 'chat/general'.
+     */
+    protected channelName: string;
+    /**
+     * Parameters extracted from the pattern, for example: { roomId: 'general' }.
+     */
+    protected params: Record<string, string>;
+    /**
+     * Injected presence manager when presence is enabled.
+     */
+    protected presence: PresenceManager;
+    /**
+     * Injects dependencies.
+     */
+    $setContext(socket: ChannelBroadcaster, channelName: string, params: Record<string, string>, presence?: PresenceManager): void;
+    /**
+     * Emits to every channel member.
+     */
+    protected broadcast(event: string, data: unknown): void;
+    /**
+     * Emits to every channel member except one socket.
+     */
+    protected broadcastExcept(socketId: string, event: string, data: unknown): void;
+    /**
+     * Runs the middleware chain.
+     *
+     * middleware[0] -> middleware[1] -> ... -> subscribe
+     */
+    $runMiddlewares(ctx: MiddlewareContext<User, HttpContext>): Promise<void>;
+    /**
+     * Returns member information for presence.
+     * Implement when options.presence = true.
+     */
+    getPresenceInfo?(socket: AuthenticatedSocket<User, HttpContext>): PresenceMember;
+    /**
+     * Hook called when a socket joins the channel.
+     */
+    onJoin?(socket: AuthenticatedSocket<User, HttpContext>, ...params: string[]): Promise<void>;
+    /**
+     * Hook called when a socket leaves the channel.
+     */
+    onLeave?(socket: AuthenticatedSocket<User, HttpContext>, ...params: string[]): Promise<void>;
+    /**
+     * Hook called when a message is received on the channel.
+     * Used as fallback when no event handler matches.
+     */
+    onMessage?(socket: AuthenticatedSocket<User, HttpContext>, event: string, data: unknown): Promise<void>;
+    /**
+     * Hook called when a member joins a presence channel.
+     */
+    onMemberJoin?(socket: AuthenticatedSocket<User, HttpContext>, member: PresenceMember, ...params: string[]): Promise<void>;
+    /**
+     * Hook called when a member leaves a presence channel.
+     */
+    onMemberLeave?(socket: AuthenticatedSocket<User, HttpContext>, member: PresenceMember, ...params: string[]): Promise<void>;
+    /**
+     * Dispatches a message to the matching handler.
+     * Called by SocketService. Do not override.
+     */
+    $handleMessage(socket: AuthenticatedSocket<User, HttpContext>, event: string, data: unknown): Promise<unknown>;
+    /**
+     * Runs the generic join hook. ChannelSubscriptions owns subscription lifecycle.
+     */
+    $handleJoin(socket: AuthenticatedSocket<User, HttpContext>, ...params: string[]): Promise<void>;
+    /**
+     * Runs the generic leave hook. ChannelSubscriptions owns subscription lifecycle.
+     */
+    $handleLeave(socket: AuthenticatedSocket<User, HttpContext>, ...params: string[]): Promise<void>;
+    $getPresenceInfo(socket: AuthenticatedSocket<User, HttpContext>): PresenceMember;
+}
+
+interface SocketTransportConfig {
+    driver: TransportFactory;
+    channel?: string;
+    presenceTimeout?: number;
+}
+
+interface RawSocket<HttpContext = unknown> {
+    id: string;
+    data: Record<string, unknown>;
+    auth?: Record<string, unknown>;
+    connection: WebSocket;
+    request: IncomingMessage;
+    httpContext?: HttpContext;
+}
+/**
+ * Socket exposed to channels after the HTTP upgrade.
+ */
+interface AuthenticatedSocket<User = unknown, HttpContext = unknown> {
+    /**
+     * Unique socket ID.
+     */
+    id: string;
+    /**
+     * Authenticated user resolved during the HTTP upgrade.
+     */
+    user: User | undefined;
+    /**
+     * Channels this socket is subscribed to.
+     */
+    channels: Set<string>;
+    /**
+     * Emits an event to this socket.
+     */
+    emit(event: string, data: unknown): void;
+    /**
+     * Joins the user target used by SocketService.toUser().
+     */
+    joinUserRoom(userId: string | number): Promise<void>;
+    /**
+     * Leaves the current SocketService.toUser() target.
+     */
+    leaveUserRoom(): Promise<void>;
+    /**
+     * Disconnects the socket.
+     */
+    disconnect(): void;
+    /**
+     * Raw WebSocket connection metadata.
+     */
+    raw: RawSocket<HttpContext>;
+}
+interface SocketUpgradeContext<HttpContext = unknown> {
+    request: IncomingMessage;
+    auth?: Record<string, unknown>;
+    httpContext?: HttpContext;
+}
+interface SocketAuthenticationDetails<User = unknown> {
+    user?: User;
+    auth?: Record<string, unknown>;
+    data?: Record<string, unknown>;
+}
+type SocketAuthenticationResult<User = unknown> = SocketAuthenticationDetails<User> | false | null;
+type SocketAuthenticationHandler<User = unknown, HttpContext = unknown> = (ctx: SocketUpgradeContext<HttpContext>) => SocketAuthenticationResult<User> | Promise<SocketAuthenticationResult<User>>;
+type SocketHttpContextFactory<HttpContext = unknown> = (request: IncomingMessage) => HttpContext | Promise<HttpContext>;
+/**
+ * Result of matching a channel.
+ */
+interface ChannelMatch {
+    channel: typeof BaseChannel;
+    pattern: string;
+    params: Record<string, string>;
+}
+/**
+ * Channel options.
+ */
+interface ChannelOptions {
+    presence?: boolean;
+}
+/**
+ * Presence member information.
+ */
+interface PresenceMember {
+    id: string;
+    name: string;
+    [key: string]: unknown;
+}
+/**
+ * Context passed to middlewares.
+ */
+interface MiddlewareContext<User = unknown, HttpContext = unknown> {
+    socket: AuthenticatedSocket<User, HttpContext>;
+    channel: string;
+    params: Record<string, string>;
+    presenceData?: Record<string, unknown> | PresenceData;
+    setPresenceData(data: Record<string, unknown> | PresenceData): void;
+}
+/**
+ * Middleware function.
+ */
+type MiddlewareFn<User = unknown, HttpContext = unknown> = (ctx: MiddlewareContext<User, HttpContext>, next: () => Promise<void>) => Promise<void>;
+/**
+ * Middleware class.
+ */
+interface MiddlewareClass<User = unknown, HttpContext = unknown> {
+    handle: MiddlewareFn<User, HttpContext>;
+}
+/**
+ * Middleware, either a function or a class.
+ */
+type Middleware<User = unknown, HttpContext = unknown> = MiddlewareFn<User, HttpContext> | MiddlewareClass<User, HttpContext>;
+/**
+ * Event handler map.
+ */
+type ChannelEventMap = Record<string, unknown>;
+type ChannelHandlerFn<User = unknown, Events extends ChannelEventMap = ChannelEventMap, HttpContext = unknown, K extends keyof Events = keyof Events> = (socket: AuthenticatedSocket<User, HttpContext>, data: Events[K]) => unknown | Promise<unknown>;
+type ChannelHandlerMap<User = unknown, Events extends ChannelEventMap = ChannelEventMap, HttpContext = unknown> = {
+    [K in keyof Events]?: ChannelHandlerFn<User, Events, HttpContext, K>;
+};
+/**
+ * Package configuration.
+ */
+interface SocketConfig<User = unknown, HttpContext = unknown> {
+    channels?: {
+        patterns?: string[];
+    };
+    websocket?: {
+        path?: string;
+        createContext?: SocketHttpContextFactory<HttpContext>;
+        authenticate?: SocketAuthenticationHandler<User, HttpContext>;
+        /**
+         * Sends a WebSocket ping every configured number of milliseconds.
+         *
+         * When only pingTimeout is configured, the service uses a default 25s interval.
+         */
+        pingInterval?: number;
+        /**
+         * Terminates connections that do not answer a ping within the configured milliseconds.
+         *
+         * When only pingInterval is configured, the service uses a default 5s timeout.
+         */
+        pingTimeout?: number;
+    };
+    /**
+     * Optional transport used to synchronize broadcasts between SocketService instances.
+     */
+    transport?: SocketTransportConfig | null;
+}
+type SocketServiceStatus = 'starting' | 'ready' | 'stopping' | 'stopped' | 'failed';
+interface SocketHealthSnapshot {
+    status: SocketServiceStatus;
+    ready: boolean;
+    connections: number;
+    channels: number;
+    lastError?: string;
+}
+/**
+ * Events emitted by the service.
+ */
+interface SocketEvents<User = unknown, HttpContext = unknown> {
+    connect: {
+        socket: AuthenticatedSocket<User, HttpContext>;
+    };
+    disconnect: {
+        socket: AuthenticatedSocket<User, HttpContext>;
+        reason: string;
+    };
+    subscribe: {
+        socket: AuthenticatedSocket<User, HttpContext>;
+        channel: string;
+    };
+    unsubscribe: {
+        socket: AuthenticatedSocket<User, HttpContext>;
+        channel: string;
+    };
+}
+
+export { type AuthenticatedSocket as A, BaseChannel as B, type ChannelEventMap as C, type Middleware as M, PresenceManager as P, type RawSocket as R, type SocketEvents as S, type ChannelHandlerMap as a, type ChannelMatch as b, type PresenceData as c, type ChannelOptions as d, type SocketConfig as e, type SocketServiceStatus as f, type SocketHealthSnapshot as g, type ChannelHandlerFn as h, type MiddlewareClass as i, type MiddlewareContext as j, type MiddlewareFn as k, type PresenceMember as l, type SocketAuthenticationDetails as m, type SocketAuthenticationHandler as n, type SocketAuthenticationResult as o, type SocketHttpContextFactory as p, type SocketUpgradeContext as q };

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@rlanz/socket",
+  "version": "0.0.1-0",
+  "description": "WebSocket integration for AdonisJS",
+  "type": "module",
+  "main": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "files": [
+    "build"
+  ],
+  "exports": {
+    ".": "./build/index.js",
+    "./provider": "./build/providers/socket_provider.js",
+    "./services/main": "./build/services/socket.js",
+    "./decorators": "./build/src/decorators.js",
+    "./health_check": "./build/src/health_check.js",
+    "./otel": "./build/src/otel.js",
+    "./testing": "./build/src/testing.js",
+    "./types": "./build/src/types.js",
+    "./types/tracing_channels": "./build/src/types/tracing_channels.js",
+    "./client": "./build/src/client/index.js",
+    "./client/types": "./build/src/client/types.js"
+  },
+  "scripts": {
+    "build": "npm run compile",
+    "clean": "del-cli build",
+    "compile": "npm run clean && tsup-node",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "format": "oxfmt --check .",
+    "format:fix": "oxfmt --write .",
+    "prepublishOnly": "npm run build",
+    "release": "release-it",
+    "test": "node --import=@poppinss/ts-exec --enable-source-maps bin/test.ts",
+    "typecheck": "tsc --noEmit",
+    "version": "npm run build"
+  },
+  "dependencies": {
+    "@boringnode/bus": "^0.9.0",
+    "@poppinss/matchit": "^3.2.0",
+    "emittery": "^1.2.0",
+    "ws": "^8.21.0"
+  },
+  "devDependencies": {
+    "@adonisjs/core": "^7.0.1",
+    "@adonisjs/tsconfig": "^2.0.0",
+    "@japa/assert": "^4.2.0",
+    "@japa/runner": "^5.3.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/context-async-hooks": "^2.7.1",
+    "@opentelemetry/core": "^2.7.1",
+    "@opentelemetry/instrumentation": "^0.218.0",
+    "@opentelemetry/sdk-metrics": "^2.7.1",
+    "@opentelemetry/sdk-trace-base": "^2.7.1",
+    "@poppinss/ts-exec": "^1.4.4",
+    "@types/ws": "^8.18.1",
+    "del-cli": "^7.0.0",
+    "oxfmt": "^0.38.0",
+    "oxlint": "^1.53.0",
+    "release-it": "^19.2.4",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@adonisjs/core": "^7.0.1",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^1.30.0 || ^2.0.0",
+    "@opentelemetry/instrumentation": "^0.200.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    },
+    "@opentelemetry/core": {
+      "optional": true
+    },
+    "@opentelemetry/instrumentation": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "adonisjs",
+    "adonis",
+    "websocket",
+    "realtime"
+  ],
+  "homepage": "https://github.com/rlanz/socket#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rlanz/socket.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rlanz/socket/issues"
+  },
+  "author": "Romain Lanz <romain.lanz@pm.me>",
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "packageManager": "yarn@4.11.0"
+}