@arcblock/ws 1.28.9 → 1.29.0

package/lib/server/index.d.cts

@@ -0,0 +1,138 @@
+import { Logger } from "../logger.cjs";
+import EventEmitter from "node:events";
+import http from "node:http";
+import { Duplex } from "node:stream";
+import WebSocket, { WebSocketServer } from "ws";
+
+//#region src/server/index.d.ts
+interface WsSocket extends WebSocket {
+  id: string;
+  channel: Record<string, {
+    authInfo?: unknown;
+  }>;
+  heartbeatAt: number;
+  authInfo?: unknown;
+}
+interface HookParams {
+  socket: WsSocket;
+  joinRef: string;
+  ref: string;
+  topic: string;
+  event: string;
+  payload: unknown;
+}
+interface Hooks {
+  authenticateJoinChannel: (params: any) => unknown;
+  preJoinChannel: (params: any) => void | Promise<void>;
+  postJoinChannel: (params: any) => void | Promise<void>;
+  preLeaveChannel: (params: any) => void | Promise<void>;
+  postLeaveChannel: (params: any) => void | Promise<void>;
+  postBroadcast: (opts: BroadcastResult) => void | Promise<void>;
+  postSend: (opts: SendOptions) => void | Promise<void>;
+  receiveMessage: (params: any) => void | Promise<void>;
+}
+interface WsServerOptions {
+  pathname?: string;
+  authenticate?: (req: http.IncomingMessage, cb: (err: Error | null, authInfo?: unknown) => void) => void;
+  hooks?: Partial<Hooks>;
+  logger?: Logger;
+  silent?: boolean;
+  skipLogOnHookError?: boolean;
+  broadcastEventName?: string;
+  heartbeatTimeout?: number;
+}
+interface BroadcastOptions {
+  enableLog?: boolean;
+  socketFilters?: Record<string, unknown>;
+  noCluster?: boolean;
+}
+interface BroadcastResult {
+  count: number;
+  topic: string;
+  event: string;
+  data: unknown;
+  options: BroadcastOptions;
+}
+interface SendOptions {
+  topic: string;
+  event: string;
+  data: unknown;
+  options: {
+    enableLog?: boolean;
+  };
+}
+/**
+ * Create a websocket server
+ *
+ * @param {Object} opts
+ * @param {String} opts.pathname - which path to mount the socket server
+ * @param {Object} opts.authenticate - authentication function to be called on connection
+ * @param {Object} opts.hooks - hooks to be called on events
+ * @param {Object} opts.logger - logger used to log messages
+ * @param {Object} opts.broadcastEventName - used in cluster mode, default is '@arcblock/ws:broadcast'
+ * @param {Object} opts.heartbeatTimeout - maximum non-response time of a connection socket
+ * @class WsServer
+ * @extends {EventEmitter}
+ */
+declare class WsServer extends EventEmitter {
+  pathname?: string;
+  authenticate: WsServerOptions['authenticate'];
+  hooks: Hooks;
+  logger: Logger;
+  skipLogOnHookError: boolean;
+  heartbeatTimeout: number;
+  wss: WebSocketServer;
+  topics: Record<string, Set<WsSocket>>;
+  broadcastEventName: string;
+  constructor(opts?: WsServerOptions);
+  attach(server: http.Server): this;
+  onConnect(request: http.IncomingMessage, socket: Duplex, head: Buffer): void;
+  /**
+   * Broadcast message to all subscribers of a topic, can be used as
+   * - broadcast(event, data) ==> broadcast(event, event, data)
+   * - broadcast(topic, event, data)
+   * - broadcast(topic, event, data, options)
+   */
+  broadcast(...args: unknown[]): Promise<void>;
+  _doBroadCast({
+    topic,
+    event,
+    data,
+    enableLog,
+    replyId,
+    socketFilters
+  }?: DoBroadcastParams): {
+    count: number;
+    error?: Error;
+  };
+  /**
+   * Send message to 1 subscriber of a topic, can be used as
+   * - send(socket, event, data)
+   * - send(socket, topic, event, data)
+   * - send(socket, topic, event, data, options)
+   */
+  send(...args: unknown[]): Promise<void>;
+  /**
+   * private
+   */
+  onWssConnection(socket: WebSocket): Promise<void>;
+  /**
+   * private
+   */
+  onWssClose(): void;
+  /**
+   * private
+   */
+  onWssError(error: Error): void;
+  _leaveChannel(socket: WsSocket, topic: string): void;
+}
+interface DoBroadcastParams {
+  topic: string;
+  event: string;
+  data: unknown;
+  enableLog?: boolean;
+  replyId?: string;
+  socketFilters?: Record<string, unknown>;
+}
+//#endregion
+export { HookParams, Hooks, WsSocket, WsServer as default };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcblock/ws",
-  "version": "1.28.9",
+  "version": "1.29.0",
   "description": "OCAP Chain websocket server and client",
   "keywords": [
     "websocket"
@@ -8,14 +8,31 @@
   "author": "arcblock <engineer@arcblock.io>",
   "homepage": "https://github.com/ArcBlock/blockchain#readme",
   "license": "Apache-2.0",
-  "main": "./lib/index.js",
-  "browser": "./lib/browser.js",
-  "directories": {
-    "lib": "lib",
-    "test": "__tests__"
+  "type": "module",
+  "main": "./lib/index.cjs",
+  "module": "./esm/index.mjs",
+  "types": "./esm/index.d.mts",
+  "browser": "./esm/browser.mjs",
+  "exports": {
+    ".": {
+      "types": "./esm/index.d.mts",
+      "import": "./esm/index.mjs",
+      "default": "./lib/index.cjs"
+    },
+    "./lib/*.js": {
+      "types": "./esm/*.d.mts",
+      "import": "./esm/*.mjs",
+      "default": "./lib/*.cjs"
+    },
+    "./lib/*": {
+      "types": "./esm/*.d.mts",
+      "import": "./esm/*.mjs",
+      "default": "./lib/*.cjs"
+    }
   },
   "files": [
-    "lib"
+    "lib",
+    "esm"
   ],
   "publishConfig": {
     "access": "public"
@@ -25,6 +42,8 @@
     "url": "git+https://github.com/ArcBlock/blockchain.git"
   },
   "scripts": {
+    "build": "tsdown",
+    "prebuild": "rm -rf lib esm",
     "lint": "biome check",
     "lint:fix": "biome check --write",
     "test": "bun test",
@@ -34,14 +53,17 @@
     "url": "https://github.com/ArcBlock/blockchain/issues"
   },
   "dependencies": {
-    "@arcblock/event-hub": "1.28.9",
-    "debug": "^4.3.6",
+    "@arcblock/event-hub": "1.29.0",
+    "debug": "^4.4.3",
     "eventemitter3": "^4.0.7",
-    "lodash": "^4.17.21",
+    "lodash": "^4.17.23",
     "phoenix": "1.7.2",
     "ws": "^8.18.0"
   },
   "devDependencies": {
+    "@types/debug": "^4.1.12",
+    "@types/lodash": "^4.17.15",
+    "@types/ws": "^8.5.13",
     "get-port": "^5.1.1"
   }
 }

package/lib/browser.js

@@ -1,5 +0,0 @@
-const WsClient = require('./client/browser');
-
-module.exports = {
-  WsClient,
-};

package/lib/client/base.js

@@ -1,134 +0,0 @@
-const createLogger = require('../logger');
-
-module.exports = (Socket, EventEmitter, transport) => {
-  return class WsClient extends Socket {
-    constructor(endpoint, opts = {}) {
-      super(endpoint, { transport, ...opts });
-
-      this._logger = createLogger('client', opts.silent);
-      this.emitter = new EventEmitter();
-
-      this.onOpen(() => {
-        this._logger.debug('socket open', endpoint);
-      });
-      this.onClose(() => {
-        this._logger.debug('socket close', endpoint);
-      });
-      this.onError((err) => {
-        this._logger.error('socket error', err.error);
-      });
-      this.onMessage((message) => {
-        this._logger.debug('socket message', message);
-      });
-    }
-
-    on(event, handler, params = {}) {
-      this.ensureJoinChannel(event, params);
-      this.emitter.on(event, handler);
-    }
-
-    off(event, handler) {
-      if (handler) {
-        this.emitter.off(event, handler);
-      } else {
-        this.emitter.removeAllListeners(event);
-      }
-
-      this.ensureLeaveChannel(event);
-    }
-
-    disconnect(callback, code, reason) {
-      this.emitter.eventNames().forEach((event) => {
-        this.emitter.removeAllListeners(event);
-      });
-      super.disconnect(callback, code, reason);
-    }
-
-    /**
-     * private
-     */
-    ensureJoinChannel(topic, params = {}) {
-      const count = this.emitter.listenerCount(topic);
-      if (count > 0) {
-        return;
-      }
-
-      const channel = this.channel(topic, params);
-      channel
-        .join()
-        .receive('ok', (message) => {
-          this._logger.debug('join success', { topic, message });
-        })
-        .receive('error', (error) => {
-          this._logger.error('join error', { topic, error });
-        })
-        .receive('timeout', () => {
-          this._logger.debug('join timeout', { topic });
-        });
-      channel.on(topic, ({ status, response: data }) => {
-        if (status === 'ok') {
-          this.emitter.emit(topic, data);
-        } else {
-          this._logger.debug('response error', { topic, status, data });
-        }
-      });
-    }
-
-    /**
-     * private
-     */
-    ensureLeaveChannel(topic) {
-      const count = this.emitter.listenerCount(topic);
-      if (count > 0) {
-        return;
-      }
-
-      const channel = this.channels.find((c) => c.topic === topic);
-      if (!channel) {
-        return;
-      }
-
-      this.remove(channel);
-      channel
-        .leave()
-        .receive('ok', (message) => {
-          this._logger.debug('leave success', { topic, message });
-        })
-        .receive('error', (err) => {
-          this._logger.error('leave error', { topic, err });
-        })
-        .receive('timeout', () => {
-          this._logger.debug('leave timeout', { topic });
-        });
-      channel.off(topic);
-    }
-
-    // More flexible subscribe
-    // Allow user to join a channel and listen to any POI events
-    subscribe(topic, params = {}) {
-      let channel = this.channels.find((c) => c.topic === topic);
-      if (channel) {
-        return channel;
-      }
-
-      channel = this.channel(topic, params);
-      channel
-        .join()
-        .receive('ok', (message) => {
-          this._logger.debug('join success', { topic, message });
-        })
-        .receive('error', (error) => {
-          this._logger.error('join error', { topic, error });
-        })
-        .receive('timeout', () => {
-          this._logger.debug('join timeout', { topic });
-        });
-
-      return channel;
-    }
-
-    unsubscribe(topic) {
-      this.ensureLeaveChannel(topic);
-    }
-  };
-};

package/lib/client/browser.js

@@ -1,6 +0,0 @@
-const EventEmitter = require('eventemitter3');
-const { Socket } = require('phoenix');
-
-const createClient = require('./base');
-
-module.exports = createClient(Socket, EventEmitter);

package/lib/client/index.js

@@ -1,7 +0,0 @@
-const EventEmitter = require('node:events');
-const { Socket } = require('phoenix');
-const WebSocket = require('ws');
-
-const createClient = require('./base');
-
-module.exports = createClient(Socket, EventEmitter, WebSocket);

package/lib/index.js

@@ -1,7 +0,0 @@
-const WsServer = require('./server');
-const WsClient = require('./client');
-
-module.exports = {
-  WsServer,
-  WsClient,
-};

package/lib/logger.js

@@ -1,12 +0,0 @@
-const debug = require('debug');
-
-module.exports = (subModule, silent = false) => {
-  const d = debug(['@arcblock/ws', subModule].join(':'));
-  return {
-    debug: d,
-    warn: d,
-    info: d,
-    trace: silent ? d : console.error,
-    error: silent ? d : console.error,
-  };
-};