@vercube/ws 1.2.0 → 1.3.0

package/dist/index.d.mts

@@ -10,7 +10,7 @@ import { Message as Message$1, Peer, WSError } from "crossws";
  * @param {string} path - The namespace path for websocket connections.
  * @returns {Function} - The decorator function.
  */
-declare function Namespace(path: string): Function;
+export declare function Namespace(path: string): Function;
 //#endregion
 //#region src/Decorators/Message.d.ts
 interface MessageDecoratorOptions {
@@ -26,7 +26,7 @@ interface MessageDecoratorOptions {
  * @param {MessageDecoratorOptions} params - The options for the message handler, including event and optional validation schema.
  * @returns {Function} - The decorator function.
  */
-declare function Message(params: MessageDecoratorOptions): Function;
+export declare function Message(params: MessageDecoratorOptions): Function;
 //#endregion
 //#region src/Decorators/Emit.d.ts
 /**
@@ -38,7 +38,7 @@ declare function Message(params: MessageDecoratorOptions): Function;
  * @param {string} event - The event name for the emitted websocket message.
  * @returns {Function} - The decorator function.
  */
-declare function Emit(event: string): Function;
+export declare function Emit(event: string): Function;
 //#endregion
 //#region src/Decorators/Broadcast.d.ts
 /**
@@ -50,7 +50,7 @@ declare function Emit(event: string): Function;
  * @param {string} event - The event name for the broadcasted websocket message.
  * @returns {Function} - The decorator function.
  */
-declare function Broadcast(event: string): Function;
+export declare function Broadcast(event: string): Function;
 //#endregion
 //#region src/Decorators/BroadcastOthers.d.ts
 /**
@@ -62,7 +62,7 @@ declare function Broadcast(event: string): Function;
  * @param {string} event - The event name for the broadcasted websocket message.
  * @returns {Function} - The decorator function.
  */
-declare function BroadcastOthers(event: string): Function;
+export declare function BroadcastOthers(event: string): Function;
 //#endregion
 //#region src/Decorators/OnConnectionAttempt.d.ts
 /**
@@ -78,7 +78,7 @@ declare function BroadcastOthers(event: string): Function;
  *
  * @returns {Function} - The decorator function.
  */
-declare function OnConnectionAttempt(): Function;
+export declare function OnConnectionAttempt(): Function;
 //#endregion
 //#region src/Plugins/WebsocketPlugin.d.ts
 /**
@@ -101,7 +101,7 @@ declare function OnConnectionAttempt(): Function;
  *
  * @see {@link https://vercube.dev} for full documentation
  */
-declare class WebsocketPlugin<T = unknown> extends BasePlugin<T> {
+export declare class WebsocketPlugin<T = unknown> extends BasePlugin<T> {
   /**
    * The name of the plugin.
    * @override
@@ -117,7 +117,7 @@ declare class WebsocketPlugin<T = unknown> extends BasePlugin<T> {
 }
 //#endregion
 //#region src/Types/WebsocketTypes.d.ts
-declare namespace WebsocketTypes {
+export declare namespace WebsocketTypes {
   enum HandlerAction {
     CONNECTION = "connection",
     MESSAGE = "message"
@@ -130,14 +130,7 @@ declare namespace WebsocketTypes {
 }
 //#endregion
 //#region src/Services/WebsocketService.d.ts
-/**
- * WebsocketService class responsible for dealing with Websocket connections.
- *
- * This class is responsible for:
- * - Registering namespaces and accepting websocket connections for them
- * - Registering event handlers and handling them
- */
-declare class WebsocketService {
+export declare class WebsocketService {
   /**
    * Http Server for injecting the server plugin
    */
@@ -213,9 +206,19 @@ declare class WebsocketService {
    * @returns {Promise<void>}
    */
   private handleMessage;
+  /**
+   * Dispatches one websocket message to its handler.
+   *
+   * @param {WSPeer} peer - The peer the message came from
+   * @param {WSMessage} rawMessage - The raw message
+   * @param {Span} span - The span covering this message
+   * @returns {Promise<void>} Resolves once the handler has run
+   * @private
+   */
+  private internalHandleMessage;
 }
 //#endregion
 //#region src/Symbols/WebsocketSymbols.d.ts
-declare const $WebsocketService: symbol;
+export declare const $WebsocketService: symbol;
 //#endregion
-export { $WebsocketService, Broadcast, BroadcastOthers, Emit, Message, Namespace, OnConnectionAttempt, type WSError, type Message$1 as WSMessage, type Peer as WSPeer, WebsocketPlugin, WebsocketService, WebsocketTypes };
+export type { WSError, Message$1 as WSMessage, Peer as WSPeer };

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import { BadRequestError, BasePlugin, HttpServer, ValidationProvider, initializeMetadata, initializeMetadataMethod, safeJsonParse, sanitizeObject } from "@vercube/core";
 import { BaseDecorator, Identity, Inject, InjectOptional, createDecorator } from "@vercube/di";
 import { Logger } from "@vercube/logger";
+import { SpanKind, ValueType, createInstrument } from "@vercube/telemetry/instrument";
 import { defineHooks } from "crossws";
 import { plugin } from "crossws/server";
 //#region src/Decorators/Namespace.ts
@@ -33,7 +34,7 @@ let WebsocketTypes;
 	}({});
 })(WebsocketTypes || (WebsocketTypes = {}));
 //#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/decorate.js
+//#region \0@oxc-project+runtime@0.150.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -49,6 +50,33 @@ function __decorate(decorators, target, key, desc) {
 * - Registering namespaces and accepting websocket connections for them
 * - Registering event handlers and handling them
 */
+/**
+* Records websocket signals.
+*
+* The toolkit comes from `@vercube/telemetry/instrument`, which is the only
+* place in the framework that speaks to OpenTelemetry directly.
+*/
+const instrument = createInstrument("@vercube/ws");
+/** Attribute naming the namespace a peer or message belongs to. */
+const WS_NAMESPACE = "vercube.ws.namespace";
+/**
+* Records a change in the number of connected peers.
+*
+* An up/down counter rather than a gauge: connects and disconnects are events
+* the service already sees, and counting them is exact, where sampling a peer
+* list on a timer would miss everything that happened between two samples.
+*
+* @param {number} delta - `1` on connect, `-1` on disconnect
+* @param {string} namespace - The namespace the peer belongs to
+* @returns {void}
+*/
+function countConnection(delta, namespace) {
+	instrument.upDownCounter("vercube.ws.connections", {
+		description: "Currently connected websocket peers.",
+		unit: "{connection}",
+		valueType: ValueType.INT
+	}).add(delta, { [WS_NAMESPACE]: namespace });
+}
 var WebsocketService = class {
 	/**
 	* Http Server for injecting the server plugin
@@ -153,7 +181,8 @@ var WebsocketService = class {
 			upgrade: async (request) => {
 				const url = new URL(request.url);
 				const namespace = url.pathname;
-				const parameters = sanitizeObject(Object.fromEntries(url.searchParams));
+				const unsafeParameters = Object.fromEntries(url.searchParams);
+				const parameters = sanitizeObject(unsafeParameters);
 				if (!!!this.fNamespaces?.[namespace?.toLowerCase()]) {
 					this.gLogger?.warn("WebsocketService::initialize", `Namespace "${namespace}" is not registered. Connection rejected.`);
 					return new Response("Namespace not registered", { status: 403 });
@@ -172,7 +201,10 @@ var WebsocketService = class {
 			},
 			open: async (peer) => {
 				const namespace = peer.namespace?.toLowerCase();
-				if (namespace && this.fNamespaces[namespace]) this.fNamespaces[namespace].push(peer);
+				if (namespace && this.fNamespaces[namespace]) {
+					this.fNamespaces[namespace].push(peer);
+					countConnection(1, namespace);
+				}
 			},
 			message: async (peer, message) => {
 				await this.handleMessage(peer, message);
@@ -182,6 +214,7 @@ var WebsocketService = class {
 				if (namespace && this.fNamespaces[namespace]) {
 					const peers = this.fNamespaces[namespace];
 					this.fNamespaces[namespace] = peers.filter((p) => p.id !== peer.id);
+					countConnection(-1, namespace);
 				}
 			},
 			error: async (peer, error) => {
@@ -203,11 +236,28 @@ var WebsocketService = class {
 	* @returns {Promise<void>}
 	*/
 	async handleMessage(peer, rawMessage) {
+		await instrument.span("ws.message", {
+			kind: SpanKind.CONSUMER,
+			attributes: { [WS_NAMESPACE]: peer.namespace ?? "" }
+		}, (span) => this.internalHandleMessage(peer, rawMessage, span));
+	}
+	/**
+	* Dispatches one websocket message to its handler.
+	*
+	* @param {WSPeer} peer - The peer the message came from
+	* @param {WSMessage} rawMessage - The raw message
+	* @param {Span} span - The span covering this message
+	* @returns {Promise<void>} Resolves once the handler has run
+	* @private
+	*/
+	async internalHandleMessage(peer, rawMessage, span) {
 		try {
 			const msg = safeJsonParse(rawMessage.text());
 			const namespace = peer.namespace?.toLowerCase();
 			const event = msg.event;
 			const data = msg.data;
+			span.updateName(`ws.message ${String(event)}`);
+			span.setAttribute("vercube.ws.event", String(event));
 			const handler = this.fHandlers[WebsocketTypes.HandlerAction.MESSAGE]?.[namespace]?.[event];
 			if (!handler) {
 				this.gLogger?.warn("WebsocketService::handleMessage", `No message handler for event "${event}" in namespace "${namespace}"`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercube/ws",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Websocket module for Vercube framework",
   "repository": {
     "type": "git",
@@ -22,14 +22,15 @@
     "README.md"
   ],
   "devDependencies": {
-    "zod": "4.4.3"
+    "zod": "4.6.5"
   },
   "dependencies": {
-    "crossws": "0.4.10",
-    "srvx": "0.12.5",
-    "@vercube/core": "1.2.0",
-    "@vercube/logger": "1.2.0",
-    "@vercube/di": "1.2.0"
+    "@vercube/core": "1.3.0",
+    "@vercube/di": "1.3.0",
+    "@vercube/logger": "1.3.0",
+    "@vercube/telemetry": "1.3.0",
+    "crossws": "0.4.12",
+    "srvx": "1.0.5"
   },
   "publishConfig": {
     "access": "public"