@eleven-am/pondsocket 0.1.217 → 0.1.219

package/README.md

@@ -1,212 +1,132 @@
 # PondSocket
 
-PondSocket is a high-performance, minimalist, and bidirectional socket framework designed for Node.js. It provides a seamless way to handle real-time communication between server and client applications, making it an ideal choice for building WebSocket-based projects.
+Typed WebSocket channels for Node.js with presence, private assigns, request/reply events, and Redis-backed distribution.
 
-## Installation
-
-To integrate PondSocket into your Node.js project, simply install it via npm:
+## Install
 
 ```bash
 npm install @eleven-am/pondsocket
 ```
 
-## Overview
-
-PondSocket simplifies the complexity of handling WebSocket connections by abstracting the communication process into individual requests rather than dealing with intricate callbacks within the connection event. It offers a lightweight yet powerful solution for managing bidirectional communication channels, enabling real-time updates and collaboration between server and client components.
-
-## Key Features
-
-- **Simple and Efficient API**: PondSocket offers an easy-to-use API, making WebSocket communication straightforward and hassle-free.
-- **Organized Channels**: Channels provide a structured approach for grouping users and facilitating efficient communication.
-- **Assigns**: PondSocket allows the storage of private information for users and channels, enhancing data security.
-- **Presence**: The presence feature keeps track of users' current states and notifies other users about any changes.
-- **Broadcasting**: PondSocket enables broadcasting messages to all users or specific groups within a channel, facilitating real-time updates.
-- **Type Safety**: The codebase is thoroughly typed with TypeScript, providing a seamless development experience with improved IDE suggestions.
-- **Middleware Support**: Extensible middleware system for request processing and validation.
-- **Distributed Support**: Built-in support for distributed deployment with state synchronization.
-
-## Server-side Usage
+## Server
 
-When setting up the server, PondSocket allows you to create multiple endpoints, each serving as a gateway for sockets to connect and communicate. Each endpoint operates independently, ensuring that sockets from one endpoint cannot interact with sockets from another. This isolation enhances security and simplifies resource management.
-
-```typescript
-import PondSocket from "@eleven-am/pondsocket";
+```ts
+import { PondSocket } from '@eleven-am/pondsocket';
 
 const pond = new PondSocket();
 
-// Create an endpoint for handling socket connections
-const endpoint = pond.createEndpoint('/api/socket', (ctx, next) => {
-    // Handle socket connection and authentication
-    const token = ctx.request.query.token;
-    
-    if (isValidToken(token)) {
-        const role = getRoleFromToken(token);
-        ctx.accept({ role }); // Assign the user's role to the socket
-    } else {
-        ctx.reject('Invalid token', 401);
+const endpoint = pond.createEndpoint('/v1/socket', (ctx) => {
+    const token = ctx.query.token;
+
+    if (!token) {
+        ctx.decline('Missing token', 401);
+        return;
     }
+
+    ctx.accept({ role: 'member' });
 });
 
-// Create a channel with path parameters
-const channel = endpoint.createChannel('/channel/:id', (ctx, next) => {
-    const { role } = ctx.user.assigns;
-    const { username } = ctx.joinParams;
-    const { id } = ctx.event.params;
-
-    if (role === 'admin') {
-        ctx.accept({ username })
-            .trackPresence({
-                username,
-                role,
-                status: 'online',
-                onlineSince: Date.now(),
-            });
-    } else {
-        ctx.decline('Insufficient permissions', 403);
-    }
+const chat = endpoint.createChannel('/chat/:roomId', (ctx) => {
+    ctx.params.roomId.toUpperCase();
+    ctx.accept({ displayName: ctx.joinParams.displayName });
+    ctx.trackPresence({ online: true });
 });
 
-// Handle channel events
-channel.onEvent('message', (ctx, next) => {
-    const { text } = ctx.event.payload;
-    
-    // Broadcast to all users in the channel
-    ctx.broadcast('message', { text });
-    
-    // Or broadcast to specific users
-    ctx.broadcastTo(['user1', 'user2'], 'message', { text });
-    
-    // Or broadcast to all except sender
-    ctx.broadcastFrom('message', { text });
+chat.onEvent('message/:messageId', (ctx) => {
+    ctx.params.messageId.toUpperCase();
+    ctx.broadcast(ctx.event.event, ctx.payload);
 });
 
-// Start the server
 pond.listen(3000);
 ```
 
-## Client-side Usage
+Connection and join handlers must call `accept()`, `decline()`, or delegate with `next()`. A handler that completes without deciding is declined instead of leaving the client pending.
+
+## Shared schema
+
+Schemas are optional. A definition can be shared by Core, the Nest adapter, and the client without repeating route literals as generic arguments.
+
+```ts
+import {
+    definePondChannel,
+    definePondEndpoint,
+    definePondSchema,
+    PondSocket,
+} from '@eleven-am/pondsocket';
+
+interface ChatSchema {
+    events: {
+        message: { text: string };
+        ping: [{ sentAt: number }, { receivedAt: number }];
+    };
+    presence: {
+        online: boolean;
+    };
+    assigns: {
+        role: 'admin' | 'member';
+    };
+    joinParams: {
+        token: string;
+    };
+}
+
+export const Socket = definePondEndpoint('/v1/socket');
+export const Chat = definePondChannel(
+    definePondSchema<ChatSchema>(),
+    '/chat/:roomId',
+);
 
-On the client-side, PondSocket provides the PondClient class to establish connections with the server. Clients can easily initiate connections, join channels, and participate in real-time interactions.
-
-```typescript
-import PondClient from "@eleven-am/pondsocket-client";
-
-// Create a new client instance
-const socket = new PondClient('ws://your-server/api/socket', {
-    token: 'your-auth-token'
-});
-
-// Connect to the server
-socket.connect();
-
-// Handle connection state changes
-socket.onConnectionChange((connected) => {
-    if (connected) {
-        console.log('Connected to the server');
-    } else {
-        console.log('Disconnected from the server');
-    }
-});
+const pond = new PondSocket();
+const endpoint = pond.createEndpoint(Socket, (ctx) => ctx.accept());
 
-// Create and join a channel
-const channel = socket.createChannel('/channel/123', {
-    username: 'user123'
+const channel = endpoint.createChannel(Chat, (ctx) => {
+    ctx.params.roomId.toUpperCase();
+    ctx.joinParams.token.toUpperCase();
+    ctx.accept({ role: 'member' }).trackPresence({ online: true });
 });
 
-// Join the channel
-channel.join();
-
-// Handle channel events
-const subscription = channel.onMessage((event, message) => {
-    console.log(`Received message: ${message.text}`);
+channel.onEvent('ping', (ctx) => {
+    ctx.payload.sentAt.toFixed();
+    ctx.reply('ping', { receivedAt: Date.now() });
 });
-
-// Send a message
-channel.broadcast('message', { text: 'Hello, PondSocket!' });
-
-// Leave the channel
-channel.leave();
-
-// Unsubscribe from events
-subscription();
 ```
 
-## Advanced Features
+The schema types event names and payloads, request/response tuples, join params, presence, assigns, channel route params, and event route params.
 
-### Presence Management
+## Distribution
 
-```typescript
-// Server-side
-channel.onEvent('presence', (ctx, next) => {
-    ctx.trackPresence({
-        username: ctx.user.assigns.username,
-        status: 'online',
-        lastSeen: Date.now()
-    });
-});
+```ts
+import { PondSocket, RedisDistributedBackend } from '@eleven-am/pondsocket';
 
-// Client-side
-channel.onPresence((presences) => {
-    console.log('Current users:', presences);
+const backend = new RedisDistributedBackend({
+    url: process.env.REDIS_URL,
+    namespace: 'my-app',
 });
-```
-
-### User Assigns
 
-```typescript
-// Server-side
-channel.onEvent('update-profile', (ctx, next) => {
-    ctx.assign({
-        ...ctx.user.assigns,
-        profile: ctx.event.payload
-    });
-});
+const pond = new PondSocket({ distributedBackend: backend });
 
-// Client-side
-channel.onAssigns((assigns) => {
-    console.log('User data updated:', assigns);
-});
+await pond.ready();
 ```
 
-### Error Handling
+Distributed messages use the PondSocket v1 protocol shared by the supported server implementations. Events, presence, assigns, user removal, and cross-node user lookup are propagated through the backend.
 
-```typescript
-// Server-side
-channel.onEvent('message', (ctx, next) => {
-    try {
-        // Your logic here
-        ctx.accept();
-    } catch (error) {
-        ctx.decline(error.message, 400);
-    }
-});
-
-// Client-side
-channel.onError((error) => {
-    console.error('Channel error:', error);
-});
-```
-
-## Distributed Deployment
+## Lifecycle
 
-PondSocket supports distributed deployment through its distributed backend system. This allows you to scale your application across multiple nodes while maintaining state synchronization.
+`ready()` reports distributed-backend initialization failures. `isHealthy()` reports backend/server health. `closeAsync()` stops heartbeat work, closes WebSockets, unsubscribes from the backend, and optionally closes the HTTP server.
 
-```typescript
-import PondSocket from "@eleven-am/pondsocket";
-import { RedisBackend } from "@eleven-am/pondsocket";
+When PondSocket uses a framework-owned HTTP server, pass `closeHttpServerOnShutdown: false`.
 
+```ts
 const pond = new PondSocket({
-    backend: new RedisBackend({
-        host: 'localhost',
-        port: 6379
-    })
+    server: existingHttpServer,
+    closeHttpServerOnShutdown: false,
 });
-```
 
-## Contributing
+await pond.closeAsync();
+```
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Channel patterns use path syntax. `/jobs/:id` and a whole `*` segment are supported; `job:*` is invalid and throws during registration. An unmatched join receives `CHANNEL_NOT_FOUND` with the original channel name and request ID.
 
 ## License
 
-This project is licensed under the GPL-3.0 License - see the LICENSE file for details.
+GPL-3.0

package/{abstracts → dist/abstracts}/types.d.ts

@@ -6,7 +6,7 @@ import { WebSocket, WebSocketServer } from 'ws';
 import { ConnectionContext } from '../contexts/connectionContext';
 import { EventContext } from '../contexts/eventContext';
 import { JoinContext } from '../contexts/joinContext';
-import { OutgoingContext } from '../contexts/outgoingContext';
+import { OutgoingHandlerContext } from '../contexts/outgoingContext';
 import { EndpointEngine } from '../engines/endpointEngine';
 import { HttpError } from '../errors/httpError';
 import { Channel } from '../wrappers/channel';
@@ -23,7 +23,7 @@ export type EventKey<Schema extends AnyPondSchema> = Extract<keyof EventsOf<Sche
 export type ConnectionHandler<Path extends string> = (ctx: ConnectionContext<Path>, next: NextFunction) => unknown | Promise<unknown>;
 export type AuthorizationHandler<Path extends string, Schema extends AnyPondSchema = AnyPondSchema> = (ctx: JoinContext<Path, Schema>, next: NextFunction) => unknown | Promise<unknown>;
 export type EventHandler<Path extends string, Schema extends AnyPondSchema = AnyPondSchema, Event extends EventKey<Schema> = EventKey<Schema>> = (ctx: EventContext<Path, Schema, Event>, next: NextFunction) => unknown | Promise<unknown>;
-export type OutgoingEventHandler<Path extends string, Schema extends AnyPondSchema = AnyPondSchema, Event extends EventKey<Schema> = EventKey<Schema>> = (event: OutgoingContext<Path, Schema, Event>, next: NextFunction) => EventPayload<EventsOf<Schema>, Event> | Promise<EventPayload<EventsOf<Schema>, Event>> | void | Promise<void>;
+export type OutgoingEventHandler<Path extends string, Schema extends AnyPondSchema = AnyPondSchema, Event extends EventKey<Schema> = EventKey<Schema>> = (event: OutgoingHandlerContext<Path, Schema, Event>) => void | Promise<void>;
 export interface ConnectionParams {
     head: Buffer;
     socket: internal.Duplex;
@@ -65,4 +65,4 @@ export interface LeaveEvent {
     user: UserData<PondPresence, PondAssigns>;
     channel: Channel;
 }
-export type LeaveCallback = (event: LeaveEvent) => void;
+export type LeaveCallback = (event: LeaveEvent) => unknown | Promise<unknown>;

package/{contexts → dist/contexts}/baseContext.d.ts

@@ -14,12 +14,14 @@ export declare abstract class BaseContext<Path extends string, Schema extends An
     get channel(): Channel<Schema>;
     get presences(): UserPresences<PresenceOf<Schema>>;
     get assigns(): UserAssigns<AssignsOf<Schema>>;
-    get user(): import("@eleven-am/pondsocket-common").UserData<PresenceOf<Schema>, AssignsOf<Schema>> | null;
+    get user(): import("@eleven-am/pondsocket-common").UserData<PresenceOf<Schema>, AssignsOf<Schema>>;
     broadcast<Event extends Extract<keyof EventsOf<Schema>, string>>(event: Event, payload: EventPayload<EventsOf<Schema>, Event>): this;
     broadcastFrom<Event extends Extract<keyof EventsOf<Schema>, string>>(event: Event, payload: EventPayload<EventsOf<Schema>, Event>): this;
     broadcastTo<Event extends Extract<keyof EventsOf<Schema>, string>>(event: Event, payload: EventPayload<EventsOf<Schema>, Event>, userIds: string | string[]): this;
     protected abstract _sendMessageToRecipients(recipient: ChannelReceivers, event: string, payload: PondObject): void;
     protected get engine(): ChannelEngine;
     protected get sender(): string;
+    protected get currentPayload(): Payload;
+    protected updatePayload(payload: Payload): void;
     protected updateParams(params: EventParams<Path>): void;
 }

package/{contexts → dist/contexts}/baseContext.js

@@ -76,6 +76,12 @@ class BaseContext {
     get sender() {
         return __classPrivateFieldGet(this, _BaseContext_sender, "f");
     }
+    get currentPayload() {
+        return __classPrivateFieldGet(this, _BaseContext_payload, "f");
+    }
+    updatePayload(payload) {
+        __classPrivateFieldSet(this, _BaseContext_payload, payload, "f");
+    }
     updateParams(params) {
         __classPrivateFieldSet(this, _BaseContext_params, params, "f");
     }

package/{contexts → dist/contexts}/eventContext.d.ts

@@ -1,4 +1,4 @@
-import { ChannelReceivers, AnyPondSchema, AssignsOf, EventParams, EventPayload, EventsOf, PondObject, PresenceOf } from '@eleven-am/pondsocket-common';
+import { ChannelReceivers, AnyPondSchema, AssignsOf, EventParams, EventPayload, EventReplyPayload, EventsOf, PondObject, PresenceOf } from '@eleven-am/pondsocket-common';
 import { BaseContext } from './baseContext';
 import { BroadcastEvent } from '../abstracts/types';
 import { ChannelEngine } from '../engines/channelEngine';
@@ -7,7 +7,7 @@ export declare class EventContext<Path extends string, Schema extends AnyPondSch
     constructor(event: BroadcastEvent, params: EventParams<Path>, engine: ChannelEngine);
     get payload(): EventPayload<EventsOf<Schema>, EventName>;
     assign(assigns: Partial<AssignsOf<Schema>>): EventContext<Path, Schema, EventName>;
-    reply<Event extends Extract<keyof EventsOf<Schema>, string>>(event: Event, payload: EventPayload<EventsOf<Schema>, Event>): this;
+    reply<Event extends Extract<keyof EventsOf<Schema>, string>>(event: Event, payload: EventReplyPayload<EventsOf<Schema>, Event>): this;
     trackPresence(presence: PresenceOf<Schema>, userId?: string): EventContext<Path, Schema, EventName>;
     updatePresence(presence: Partial<PresenceOf<Schema>>, userId?: string): EventContext<Path, Schema, EventName>;
     evictUser(reason: string, userId?: string): EventContext<Path, Schema, EventName>;

package/{contexts → dist/contexts}/joinContext.js

@@ -51,7 +51,7 @@ class JoinContext extends baseContext_1.BaseContext {
         }
         __classPrivateFieldGet(this, _JoinContext_instances, "m", _JoinContext_performChecks).call(this);
         const onMessage = this.engine.parent.parent.sendMessage.bind(this.engine.parent.parent, __classPrivateFieldGet(this, _JoinContext_user, "f").socket);
-        const subscription = this.engine.addUser(__classPrivateFieldGet(this, _JoinContext_user, "f").clientId, __classPrivateFieldGet(this, _JoinContext_newAssigns, "f"), onMessage);
+        const subscription = this.engine.addUser(__classPrivateFieldGet(this, _JoinContext_user, "f").clientId, __classPrivateFieldGet(this, _JoinContext_newAssigns, "f"), onMessage, __classPrivateFieldGet(this, _JoinContext_user, "f").requestId);
         const wrappedSubscription = () => {
             var _a;
             subscription();
@@ -68,8 +68,14 @@ class JoinContext extends baseContext_1.BaseContext {
         const errorMessage = {
             event: pondsocket_common_1.ErrorTypes.UNAUTHORIZED_JOIN_REQUEST,
             payload: {
+                code: pondsocket_common_1.ErrorTypes.UNAUTHORIZED_JOIN_REQUEST,
                 message: message || 'Unauthorized connection',
-                code: errorCode || 401,
+                status: errorCode || 401,
+                statusCode: errorCode || 401,
+                error: {
+                    message: message || 'Unauthorized connection',
+                    status: errorCode || 401,
+                },
             },
             channelName: this.engine.name,
             action: pondsocket_common_1.ServerActions.ERROR,

package/dist/contexts/outgoingContext.d.ts

@@ -0,0 +1,36 @@
+import { ChannelReceivers, AnyPondSchema, Event, EventParams, EventPayload, EventReplyPayload, EventsOf, PondEvent, PondMessage, PondObject, ServerActions } from '@eleven-am/pondsocket-common';
+import { BaseContext } from './baseContext';
+import { ChannelEngine } from '../engines/channelEngine';
+export declare class OutgoingContext<Path extends string, Schema extends AnyPondSchema = AnyPondSchema, EventName extends Extract<keyof EventsOf<Schema>, string> = Extract<keyof EventsOf<Schema>, string>, Action extends Event['action'] = Event['action']> extends BaseContext<Path, Schema, EventName, OutgoingPayload<Schema, EventName, Action>> {
+    #private;
+    constructor(event: Event, params: EventParams<Path>, engine: ChannelEngine, userid: string);
+    get action(): Action;
+    get event(): PondEvent<Path> & {
+        action: Action;
+        event: EventName;
+        payload: OutgoingPayload<Schema, EventName, Action>;
+    };
+    get payload(): OutgoingPayload<Schema, EventName, Action>;
+    /**
+     * Blocks the outgoing context, preventing further processing of the event.
+     */
+    block(): this;
+    /**
+     * Checks if the outgoing context is blocked.
+     * @returns {boolean} - True if blocked, false otherwise.
+     */
+    isBlocked(): boolean;
+    /**
+     * Transforms the outgoing context with a new payload.
+     * @param payload - The new payload to set for the context.
+     */
+    transform(payload: OutgoingPayload<Schema, EventName, Action>): this;
+    /**
+     * Updates the parameters of the outgoing context.
+     * @param params - The new parameters to set for the context.
+     */
+    updateParams(params: EventParams<Path>): void;
+    protected _sendMessageToRecipients(_recipient: ChannelReceivers, _event: string, _payload: PondObject): void;
+}
+export type OutgoingPayload<Schema extends AnyPondSchema, EventName extends Extract<keyof EventsOf<Schema>, string>, Action extends Event['action']> = Action extends ServerActions.BROADCAST ? EventPayload<EventsOf<Schema>, EventName> : Action extends ServerActions.SYSTEM ? EventReplyPayload<EventsOf<Schema>, EventName> : PondMessage;
+export type OutgoingHandlerContext<Path extends string, Schema extends AnyPondSchema, EventName extends Extract<keyof EventsOf<Schema>, string>> = OutgoingContext<Path, Schema, EventName, ServerActions.BROADCAST> | OutgoingContext<Path, Schema, EventName, ServerActions.SYSTEM>;

package/{contexts → dist/contexts}/outgoingContext.js

@@ -10,20 +10,26 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _OutgoingContext_payload, _OutgoingContext_isBlocked;
+var _OutgoingContext_action, _OutgoingContext_isBlocked;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OutgoingContext = void 0;
 const baseContext_1 = require("./baseContext");
 class OutgoingContext extends baseContext_1.BaseContext {
     constructor(event, params, engine, userid) {
         super(engine, params, event.event, event.payload, userid);
-        _OutgoingContext_payload.set(this, void 0);
+        _OutgoingContext_action.set(this, void 0);
         _OutgoingContext_isBlocked.set(this, void 0);
-        __classPrivateFieldSet(this, _OutgoingContext_payload, event.payload, "f");
+        __classPrivateFieldSet(this, _OutgoingContext_action, event.action, "f");
         __classPrivateFieldSet(this, _OutgoingContext_isBlocked, false, "f");
     }
+    get action() {
+        return __classPrivateFieldGet(this, _OutgoingContext_action, "f");
+    }
+    get event() {
+        return Object.assign(Object.assign({}, super.event), { action: __classPrivateFieldGet(this, _OutgoingContext_action, "f"), payload: this.currentPayload });
+    }
     get payload() {
-        return __classPrivateFieldGet(this, _OutgoingContext_payload, "f");
+        return this.currentPayload;
     }
     /**
      * Blocks the outgoing context, preventing further processing of the event.
@@ -44,7 +50,7 @@ class OutgoingContext extends baseContext_1.BaseContext {
      * @param payload - The new payload to set for the context.
      */
     transform(payload) {
-        __classPrivateFieldSet(this, _OutgoingContext_payload, payload, "f");
+        this.updatePayload(payload);
         return this;
     }
     /**
@@ -59,4 +65,4 @@ class OutgoingContext extends baseContext_1.BaseContext {
     }
 }
 exports.OutgoingContext = OutgoingContext;
-_OutgoingContext_payload = new WeakMap(), _OutgoingContext_isBlocked = new WeakMap();
+_OutgoingContext_action = new WeakMap(), _OutgoingContext_isBlocked = new WeakMap();

package/{engines → dist/engines}/channelEngine.d.ts

@@ -8,7 +8,7 @@ export declare class ChannelEngine {
     constructor(parent: LobbyEngine, name: string, backend?: IDistributedBackend | null);
     get name(): string;
     get users(): Set<string>;
-    addUser(userId: string, assigns: PondAssigns, onMessage: (event: ChannelEvent) => void): Unsubscribe;
+    addUser(userId: string, assigns: PondAssigns, onMessage: (event: ChannelEvent) => void, requestId?: string): Unsubscribe;
     sendMessage(sender: ChannelSenders, recipient: ChannelReceivers, action: ServerActions, event: string, payload: PondMessage, requestId?: string): void;
     broadcastMessage(userId: string, message: ClientMessage): void;
     trackPresence(userId: string, presence: PondPresence): void;
@@ -17,6 +17,8 @@ export declare class ChannelEngine {
     upsertPresence(userId: string, presence: PondPresence): void;
     updateAssigns(userId: string, assigns: PondMessage): void;
     kickUser(userId: string, reason: string): void;
+    requestUserRemoval(userId: string): void;
+    getUserAcrossNodes(userId: string, timeoutMs?: number): Promise<UserData | null>;
     getAssigns(): UserAssigns;
     getPresence(): UserPresences;
     destroy(reason?: string): void;