@marianmeres/ws 0.3.0 → 0.5.0

package/dist/protocol/constants.js

@@ -11,8 +11,13 @@
  *
  * It costs nothing today and it is the only thing that makes a breaking
  * protocol change survivable later.
+ *
+ * Version 2 split the protocol into a required **core** (handshake, messages
+ * in both directions, heartbeat) and an optional **rooms extension**
+ * (subscriptions, publishing, presence, broadcast), so a server that only
+ * needs a data channel implements the core and nothing else.
  */
-export const PROTOCOL_VERSION = 1;
+export const PROTOCOL_VERSION = 2;
 /** Namespace used when the client does not specify one. */
 export const DEFAULT_NAMESPACE = "default";
 /**
@@ -21,36 +26,48 @@ export const DEFAULT_NAMESPACE = "default";
  * Note these are *protocol* types and have nothing to do with whatever the
  * application puts inside `payload` — the payload is opaque and is never
  * inspected nor mutated by this library.
+ *
+ * Every server implements the **core** frames. The **rooms extension**
+ * frames are sent only when the application uses rooms (`subscribe()`,
+ * `publish()`, `broadcast()`, presence), so a server that does not support
+ * them never sees one.
  */
 export const FRAME = {
-    // client -> server
+    // core, client -> server
     /** Handshake. Always the first frame; carries the auth payload. */
     AUTH: "auth",
-    /** Join one or more rooms, optionally with presence. */
-    SUB: "sub",
-    /** Leave one or more rooms. */
-    UNSUB: "unsub",
-    /** Publish into a room within the connection's own namespace. */
-    PUB: "pub",
-    /** Publish into a room across every namespace. Gated server-side. */
-    BROADCAST: "broadcast",
     /** Liveness probe. Answered with `pong`. */
     PING: "ping",
-    // server -> client
-    /** Handshake accepted; carries the assigned id, namespace and version. */
+    // core, server -> client
+    /** Handshake accepted; carries the protocol version (and, with rooms, identity). */
     HELLO: "hello",
-    /** Positive acknowledgement of a correlated request. */
+    /** Positive acknowledgement of a frame that carried an `id`; may carry a reply. */
     ACK: "ack",
     /** Negative acknowledgement; carries a `WSErrorInfo`. */
     NACK: "nack",
-    /** A message delivered to a subscribed room. */
-    MSG: "msg",
-    /** A membership change in a presence-enabled room. */
-    PRESENCE: "presence",
     /** Reply to `ping`. */
     PONG: "pong",
     /** Uncorrelated error — not tied to any request id. */
     ERROR: "error",
+    // core, both directions
+    /**
+     * A message. Client -> server it is addressed to the server itself;
+     * server -> client it is either a direct message (core) or a room delivery
+     * (rooms extension, recognisable by its `room` field).
+     */
+    MSG: "msg",
+    // rooms extension, client -> server
+    /** Join one or more rooms, optionally with presence. */
+    SUB: "sub",
+    /** Leave one or more rooms. */
+    UNSUB: "unsub",
+    /** Publish into a room within the connection's own namespace. */
+    PUB: "pub",
+    /** Publish into a room across every namespace. Gated server-side. */
+    BROADCAST: "broadcast",
+    // rooms extension, server -> client
+    /** A membership change in a presence-enabled room. */
+    PRESENCE: "presence",
 };
 /**
  * WebSocket close codes.
@@ -104,10 +121,15 @@ export const ERROR_CODE = {
     BAD_REQUEST: "bad_request",
     /** Frame rate cap exceeded. */
     RATE_LIMITED: "rate_limited",
+    /**
+     * A frame type this server does not implement — typically a rooms frame
+     * sent to a core-only server, or a `msg` to a server with no handler.
+     */
+    UNSUPPORTED: "unsupported",
     /** Unexpected server-side failure. */
     INTERNAL: "internal",
 };
-/** Presence event kinds. */
+/** Presence event kinds (rooms extension). */
 export const PRESENCE = {
     /** Full membership snapshot, sent on every (re)subscribe. */
     SYNC: "sync",

package/dist/protocol/errors.d.ts

@@ -58,7 +58,12 @@ export declare class WSConnectTimeoutError extends WSError {
      */
     constructor(ms: number);
 }
-/** `sendTimeout` elapsed while queued, in flight, or awaiting an ack. */
+/**
+ * `sendTimeout` elapsed while queued, in flight, or awaiting an ack.
+ *
+ * A send that awaits no ack — `send()` without `{ ack: true }` — can only hit
+ * this while still queued, i.e. when no connection came up in time.
+ */
 export declare class WSTimeoutError extends WSError {
     /**
      * Reports the deadline that was exceeded.
@@ -71,7 +76,21 @@ export declare class WSTimeoutError extends WSError {
 export declare class WSOutboxDropError extends WSError {
     constructor();
 }
-/** The server rejected the operation with a `nack`. */
+/**
+ * The socket closed while the frame was in flight.
+ *
+ * Distinct from {@link WSTimeoutError} on purpose: this one means "retry when
+ * connected", that one means "the server is not answering".
+ */
+export declare class WSConnectionLostError extends WSError {
+    constructor();
+}
+/**
+ * The server rejected the operation with a `nack`.
+ *
+ * Also the way a server-side `onMessage` hook rejects a message on purpose:
+ * throw one, and its `code` and `message` travel back in the `nack` unchanged.
+ */
 export declare class WSRemoteError extends WSError {
     /** Machine-readable code from the server — see `ERROR_CODE`. */
     readonly code: string;

package/dist/protocol/errors.js

@@ -64,7 +64,12 @@ export class WSConnectTimeoutError extends WSError {
         super(`Not connected within ${ms}ms (still retrying in background)`);
     }
 }
-/** `sendTimeout` elapsed while queued, in flight, or awaiting an ack. */
+/**
+ * `sendTimeout` elapsed while queued, in flight, or awaiting an ack.
+ *
+ * A send that awaits no ack — `send()` without `{ ack: true }` — can only hit
+ * this while still queued, i.e. when no connection came up in time.
+ */
 export class WSTimeoutError extends WSError {
     /**
      * Reports the deadline that was exceeded.
@@ -72,7 +77,7 @@ export class WSTimeoutError extends WSError {
      * @param ms - the elapsed `sendTimeout`
      */
     constructor(ms) {
-        super(`No acknowledgement within ${ms}ms`);
+        super(`Send not completed within ${ms}ms`);
     }
 }
 /** The frame was evicted from a full outbox before it could be sent. */
@@ -81,7 +86,23 @@ export class WSOutboxDropError extends WSError {
         super("Dropped from outbox (capacity reached while disconnected)");
     }
 }
-/** The server rejected the operation with a `nack`. */
+/**
+ * The socket closed while the frame was in flight.
+ *
+ * Distinct from {@link WSTimeoutError} on purpose: this one means "retry when
+ * connected", that one means "the server is not answering".
+ */
+export class WSConnectionLostError extends WSError {
+    constructor() {
+        super("The connection closed before the server acknowledged the frame; it was not resent");
+    }
+}
+/**
+ * The server rejected the operation with a `nack`.
+ *
+ * Also the way a server-side `onMessage` hook rejects a message on purpose:
+ * throw one, and its `code` and `message` travel back in the `nack` unchanged.
+ */
 export class WSRemoteError extends WSError {
     /** Machine-readable code from the server — see `ERROR_CODE`. */
     code;

package/dist/protocol/frames.d.ts

@@ -7,6 +7,11 @@
  * application. Your payload may contain its own `type` field and nothing will
  * collide.
  *
+ * The frames come in two layers. The **core** — `auth`/`hello`, `msg` in both
+ * directions, `ack`/`nack`, `ping`/`pong`, `error` — is all a server must
+ * implement. The **rooms extension** — `sub`, `unsub`, `pub`, `broadcast`,
+ * `presence`, and the routing fields on a delivered `msg` — is opt-in.
+ *
  * @module
  */
 import type { FRAME, PRESENCE } from "./constants.js";
@@ -18,23 +23,45 @@ export interface WSErrorInfo {
     message: string;
 }
 /**
- * A message as delivered to application code.
+ * A message as delivered to application code — the `message` event fires
+ * with one for every inbound `msg` frame.
  *
  * A `msg` frame minus its `type` field *is* a `WSMessage` — there is no
  * translation layer and no divergence between wire names and API names.
+ *
+ * Only `payload` is guaranteed. A direct message from the server (core) has
+ * nothing else; a message delivered through a room (rooms extension) carries
+ * every routing field — see {@link WSRoomMessage}. `room` tells them apart.
  */
 export interface WSMessage<T = unknown> {
+    /** Opaque application payload. */
+    payload: T;
+    /** Room the message was published to. Absent on a direct message. */
+    room?: string;
+    /** Namespace the message belongs to. Absent on a direct message. */
+    namespace?: string;
+    /**
+     * Originating client id, `null` when injected server-side. Absent on a
+     * direct message, which always comes from the server.
+     */
+    from?: string | null;
+    /** Server-assigned epoch milliseconds. Absent on a direct message. */
+    timestamp?: number;
+}
+/**
+ * A message delivered through a room (rooms extension). This is what room
+ * handlers receive: every routing field is present.
+ */
+export interface WSRoomMessage<T = unknown> extends WSMessage<T> {
     /** Room the message was published to. */
     room: string;
-    /** Namespace the message belongs to. */
+    /** Namespace the message belongs to — always the receiver's own. */
     namespace: string;
     /**
      * Originating client id, or `null` when the message was injected
      * server-side (via the service API or the HTTP routes).
      */
     from: string | null;
-    /** Opaque application payload. */
-    payload: T;
     /** Server-assigned epoch milliseconds. */
     timestamp: number;
 }
@@ -42,7 +69,7 @@ export interface WSMessage<T = unknown> {
 export type PresenceEventType = (typeof PRESENCE)[keyof typeof PRESENCE];
 /**
  * A membership change in a room the client subscribed to with presence
- * enabled.
+ * enabled (rooms extension).
  *
  * `sync` carries the full snapshot and is emitted on every (re)subscribe —
  * crucially including after a reconnect, when membership may have changed
@@ -62,7 +89,7 @@ export interface WSPresenceEvent {
     /** Server-assigned epoch milliseconds. */
     timestamp: number;
 }
-/** A single room subscription request. */
+/** A single room subscription request (rooms extension). */
 export interface SubRequest {
     /** Room name to join. */
     room: string;
@@ -72,12 +99,24 @@ export interface SubRequest {
 /** Frames sent by the client. */
 export type ClientFrame = {
     type: typeof FRAME.AUTH;
-    id: string;
+    /**
+     * Not sent since protocol 2 and never acknowledged. Kept optional so a
+     * server keeps accepting a protocol-1 client that still sends it.
+     */
+    id?: string;
     protocol: number;
     payload: unknown;
     /** Preferred client id — the server may override it. */
     clientId?: string;
+    /** Requested namespace — sent only when the application chose one. */
     namespace?: string;
+} | {
+    type: typeof FRAME.MSG;
+    /** Present only when the sender awaits an `ack`/`nack`. */
+    id?: string;
+    payload: unknown;
+} | {
+    type: typeof FRAME.PING;
 } | {
     type: typeof FRAME.SUB;
     id: string;
@@ -97,36 +136,39 @@ export type ClientFrame = {
     id: string;
     room: string;
     payload: unknown;
-} | {
-    type: typeof FRAME.PING;
 };
 /** Frames sent by the server. */
 export type ServerFrame = {
     type: typeof FRAME.HELLO;
-    clientId: string;
-    namespace: string;
     protocol: number;
+    /** Assigned client id. Optional in the core; always sent with rooms. */
+    clientId?: string;
+    /** Assigned namespace. Optional in the core; always sent with rooms. */
+    namespace?: string;
 } | {
     type: typeof FRAME.ACK;
     id: string;
+    /** Delivery count, on `pub`/`broadcast` acks only. */
     recipients?: number;
+    /** The server's reply, on `msg` acks only. Any JSON value. */
+    payload?: unknown;
 } | {
     type: typeof FRAME.NACK;
     id: string;
     error: WSErrorInfo;
 } | ({
     type: typeof FRAME.MSG;
-} & WSMessage) | ({
-    type: typeof FRAME.PRESENCE;
-} & WSPresenceEvent) | {
+} & WSMessage) | {
     type: typeof FRAME.PONG;
 } | {
     type: typeof FRAME.ERROR;
     error: WSErrorInfo;
-};
+} | ({
+    type: typeof FRAME.PRESENCE;
+} & WSPresenceEvent);
 /** Any frame, in either direction. */
 export type WSFrame = ClientFrame | ServerFrame;
-/** Result of a successful `publish()` / `broadcast()`. */
+/** Result of a successful `publish()` / `broadcast()` (rooms extension). */
 export interface WSPublishResult {
     /**
      * Sockets the message was handed to **on the receiving server instance**.
@@ -136,6 +178,16 @@ export interface WSPublishResult {
      */
     recipients: number;
 }
+/**
+ * What the client proposed in its `auth` frame. Hints, not facts — they are
+ * whatever the socket sent, so validate them before honouring them.
+ */
+export interface WSRequestedIdentity {
+    /** The claimed client id, when the frame carried a usable one. */
+    clientId?: string;
+    /** The requested namespace, or the default when the frame carried none. */
+    namespace: string;
+}
 /** Outcome of the server's `verify()` hook. */
 export interface AuthResult {
     /** Assign a specific client id. Defaults to a generated one. */

package/dist/protocol/frames.js

@@ -7,6 +7,11 @@
  * application. Your payload may contain its own `type` field and nothing will
  * collide.
  *
+ * The frames come in two layers. The **core** — `auth`/`hello`, `msg` in both
+ * directions, `ack`/`nack`, `ping`/`pong`, `error` — is all a server must
+ * implement. The **rooms extension** — `sub`, `unsub`, `pub`, `broadcast`,
+ * `presence`, and the routing fields on a delivered `msg` — is opt-in.
+ *
  * @module
  */
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/ws",
-	"version": "0.3.0",
+	"version": "0.5.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",
@@ -27,7 +27,7 @@
 		"@marianmeres/clog": "^3.21.0",
 		"@marianmeres/pubsub": "^3.0.0",
 		"@marianmeres/ticker": "^1.17.1",
-		"@marianmeres/uid": "^1.1.0"
+		"@marianmeres/uid": "^1.2.0"
 	},
 	"repository": {
 		"type": "git",