@service-broker/webclient 2.0.0 → 2.0.2

package/README.md

@@ -1,15 +1,111 @@
-# service-broker-webclient
-Browser JavaScript library for communicating with the service broker
+## @service-broker/webclient
+Browser ESM client library for communicating with a [Service Broker](https://github.com/service-broker/service-broker/wiki/specification)
 
-## Install
-`npm install @service-broker/webclient`
 
-## Usage
+### Install
+```bash
+npm install @service-broker/webclient
+```
+
+
+### Connect
+Connect to the Service Broker at the specified WebSocket URL.
+
 ```javascript
 import { ServiceBroker } from "@service-broker/webclient"
 
-const sb = new ServiceBroker("wss://sb.mydomain.com", console)
+const sb = new ServiceBroker("wss://sb.mydomain.com")
+```
+
+
+### Request
+Send a service request.  The broker will select a qualified provider based on service `name` and requested `capabilities`.  The parameter `request` contains the actual message that'll be delivered to the service provider.
+
+```typescript
+interface Message {
+  header: {
+    from: string      // the endpointId of the sender
+    to: string        // the endpointId of the recipient
+  },
+  payload: string     // the message payload, usually JSON
+}
+
+sb.request(
+  service: {
+    name: string,
+    capabilities?: string[]
+  },
+  request: Message,
+  timeout?: number
+): Promise<Message>
+```
+
+
+### Notify
+A notification is like a request except no response will be sent back.
+
+```typescript
+sb.notify(
+  service: {
+    name: string,
+    capabilities?: string[]
+  },
+  notification: Message
+): Promise<void>
+```
+
+
+### RequestTo
+Send a service request directly to an endpoint.
+
+```typescript
+sb.requestTo(
+  endpointId: string,
+  serviceName: string,
+  request: Message,
+  timeout?: number
+): Promise<Message>
+```
+
+
+### NotifyTo
+Send a notification directly to an endpoint.
+
+```typescript
+sb.notifyTo(
+  endpointId: string,
+  serviceName: string,
+  notification: Message
+): Promise<void>
+```
+
+
+### SetServiceHandler
+The `requestTo` and `notifyTo` methods can be used to send direct messages to an endpoint. For example, a chat service provider may publish a client's endpointId to other clients and allow them to send direct messages to one another.
+
+This method sets a handler for incoming requests and notifications.
+
+```typescript
+sb.setServiceHandler(
+  serviceName: string,
+  handler: (request: Message) => Message|void|Promise<Message|void>
+): void
+```
+
+
+### Publish/Subscribe
+```typescript
+sb.publish(
+  topic: string,
+  text: string
+): Promise<void>
+
+sb.subscribe(
+  topic: string,
+  handler: (text: string) => void
+): Promise<void>
 
-sb.request({name: "my-service"}, {payload: "my-request"})
-  .then(({payload}) => handleResult(payload))
+sb.unsubscribe(
+  topic: string
+): Promise<void>
 ```

package/dist/index.d.ts

@@ -1,34 +1,45 @@
-
-interface ServiceFilter {
-  name: string
-  capabilities?: string[]
+export interface ServiceSelector {
+    name: string;
+    capabilities?: string[];
 }
-
-export interface ServiceAdvert {
-  name: string
-  capabilities?: string[]
-  priority: number
-}
-
 export interface ServiceHandler {
-  (msg: Message): Partial<Message>|void|Promise<Partial<Message>|void>
+    (request: MessageWithHeader): Message | void | Promise<Message | void>;
+}
+type MessageHeader = Record<string, unknown>;
+type MessagePayload = string;
+export interface MessageWithHeader {
+    header: MessageHeader;
+    payload?: MessagePayload;
 }
-
-interface Message {
-  header: any
-  payload: any
+export interface Message {
+    header?: MessageHeader;
+    payload?: MessagePayload;
 }
-
 export declare class ServiceBroker {
-  constructor(url: string, logger: {error: Console["error"], debug: Console["debug"]});
-  request(service: ServiceFilter, req: Partial<Message>): Promise<Message>;
-  requestTo(endpointId: string, service: ServiceFilter, req: Partial<Message>): Promise<Message>;
-  advertise(service: ServiceAdvert, handler: ServiceHandler): Promise<void>;
-  unadvertise(serviceName: string): Promise<void>;
-  setHandler(serviceName: string, handler: ServiceHandler): void;
-  publish(topic: string, text: string): Promise<void>;
-  subscribe(topic: string, handler: (text: string) => void): Promise<void>;
-  unsubscribe(topic: string): Promise<void>;
-  isConnected(): boolean;
-  addConnectListener(listener: () => void): void;
+    private readonly url;
+    private readonly providers;
+    private ws;
+    private readonly connectListeners;
+    private pendingSend;
+    private readonly pendingResponses;
+    private pendingIdGen;
+    constructor(url: string);
+    private connect;
+    private onOpen;
+    private onClose;
+    private onMessage;
+    private onServiceResponse;
+    private onServiceRequest;
+    private send;
+    request(service: ServiceSelector, req: Message): Promise<Message>;
+    requestTo(endpointId: string | null, service: ServiceSelector, req: Message): Promise<Message>;
+    advertise(service: ServiceSelector, handler: ServiceHandler): void;
+    unadvertise(serviceName: string): void;
+    setServiceHandler(serviceName: string, handler: ServiceHandler): void;
+    publish(topic: string, text: string): void;
+    subscribe(topic: string, handler: (text: string) => void): void;
+    unsubscribe(topic: string): void;
+    isConnected(): boolean;
+    addConnectListener(listener: Function): void;
 }
+export {};

package/dist/index.js

@@ -1,182 +1,185 @@
-export function ServiceBroker(url, logger) {
-  var pending = {};
-  var pendingIdGen = 0;
-  var providers = {};
-  var ws;
-  var connectListeners = [];
-  var pendingSend = [];
-  connect();
-
-  function connect() {
-    var conn = new WebSocket(url);
-    conn.onopen = onOpen.bind(null, conn);
-    conn.onerror = function() {
-      logger.error("Failed to connect to service broker, retrying in 15");
-      setTimeout(connect, 15000);
-    };
-  }
-
-  function onOpen(conn) {
-    ws = conn;
-    ws.onerror = logger.error;
-    ws.onclose = onClose;
-    ws.onmessage = onMessage;
-    for (var i=0; i<connectListeners.length; i++) connectListeners[i]();
-    for (var i=0; i<pendingSend.length; i++) send(pendingSend[i].header, pendingSend[i].payload);
-    pendingSend = [];
-  }
-
-  function onClose() {
-    ws = null;
-    logger.error("Lost connection to service broker, reconnecting");
-    setTimeout(connect, 0);
-  }
-
-  function onMessage(e) {
-    var msg = messageFromString(e.data);
-    logger.debug("<<", msg.header, msg.payload);
-    if (msg.header.type == "ServiceResponse") onServiceResponse(msg);
-    else if (msg.header.type == "ServiceRequest") onServiceRequest(msg);
-    else if (msg.header.type == "SbStatusResponse") onServiceResponse(msg);
-    else if (msg.header.error) onServiceResponse(msg);
-    else logger.error("Unhandled", msg.header);
-  }
-
-  function messageFromString(text) {
-    var index = text.indexOf('\n');
-    if (index == -1) return {header: JSON.parse(text)};
-    else return {header: JSON.parse(text.substr(0,index)), payload: text.substr(index+1)};
-  }
-
-  function onServiceResponse(msg) {
-    if (pending[msg.header.id]) {
-      if (msg.header.error) pending[msg.header.id].reject(new Error(msg.header.error));
-      else pending[msg.header.id].fulfill(msg);
-      delete pending[msg.header.id];
-    }
-    else logger.error("Response received but no pending request", msg.header);
-  }
-
-  function onServiceRequest(msg) {
-    if (providers[msg.header.service.name]) {
-      Promise.resolve(providers[msg.header.service.name].handler(msg))
-        .then(function(res) {
-          if (!res) res = {};
-          if (msg.header.id) {
-            var header = {
-              to: msg.header.from,
-              id: msg.header.id,
-              type: "ServiceResponse"
-            };
-            send(Object.assign({}, res.header, header), res.payload);
-          }
-        })
-        .catch(function(err) {
-          if (msg.header.id) {
-            send({
-              to: msg.header.from,
-              id: msg.header.id,
-              type: "ServiceResponse",
-              error: err.message
+function messageFromString(text) {
+    const index = text.indexOf('\n');
+    if (index == -1) {
+        return {
+            header: JSON.parse(text)
+        };
+    }
+    else {
+        return {
+            header: JSON.parse(text.slice(0, index)),
+            payload: text.slice(index + 1)
+        };
+    }
+}
+export class ServiceBroker {
+    constructor(url) {
+        this.url = url;
+        this.providers = new Map();
+        this.ws = null;
+        this.connectListeners = [];
+        this.pendingSend = [];
+        this.pendingResponses = new Map();
+        this.pendingIdGen = 0;
+        this.connect();
+    }
+    connect() {
+        const conn = new WebSocket(this.url);
+        conn.onopen = () => this.onOpen(conn);
+        conn.onerror = () => {
+            console.error("Failed to connect to service broker, retrying in 15");
+            setTimeout(() => this.connect(), 15000);
+        };
+    }
+    onOpen(conn) {
+        this.ws = conn;
+        this.ws.onerror = console.error;
+        this.ws.onclose = () => this.onClose();
+        this.ws.onmessage = event => this.onMessage(event);
+        for (const listener of this.connectListeners)
+            listener();
+        for (const { header, payload } of this.pendingSend)
+            this.send(header, payload);
+        this.pendingSend = [];
+    }
+    onClose() {
+        this.ws = null;
+        console.error("Lost connection to service broker, reconnecting");
+        setTimeout(() => this.connect(), 0);
+    }
+    onMessage(e) {
+        const msg = messageFromString(e.data);
+        console.debug("<<", msg.header, msg.payload);
+        if (msg.header.type == "ServiceResponse")
+            this.onServiceResponse(msg);
+        else if (msg.header.type == "ServiceRequest")
+            this.onServiceRequest(msg);
+        else if (msg.header.type == "SbStatusResponse")
+            this.onServiceResponse(msg);
+        else if (msg.header.error)
+            this.onServiceResponse(msg);
+        else
+            console.error("Unhandled", msg.header);
+    }
+    onServiceResponse(message) {
+        const id = message.header.id;
+        const pendingResponse = this.pendingResponses.get(id);
+        if (pendingResponse) {
+            this.pendingResponses.delete(id);
+            if (message.header.error) {
+                pendingResponse.reject(new Error(message.header.error));
+            }
+            else {
+                pendingResponse.fulfill(message);
+            }
+        }
+        else {
+            console.error("Response received but no pending request", message.header);
+        }
+    }
+    onServiceRequest(msg) {
+        const service = msg.header.service;
+        const provider = this.providers.get(service.name);
+        if (provider) {
+            Promise.resolve(provider.handler(msg))
+                .then(res => {
+                if (msg.header.id) {
+                    this.send(Object.assign(Object.assign({}, res === null || res === void 0 ? void 0 : res.header), { to: msg.header.from, id: msg.header.id, type: "ServiceResponse" }), res === null || res === void 0 ? void 0 : res.payload);
+                }
             })
-          }
-          else logger.error(err.message, msg.header);
-        })
-    }
-    else logger.error("No handler for service " + msg.header.service.name);
-  }
-
-
-
-  this.request = function(service, req) {
-    return this.requestTo(null, service, req);
-  }
-
-  this.requestTo = function(endpointId, service, req) {
-    var id = ++pendingIdGen;
-    var promise = new Promise(function(fulfill, reject) {
-      pending[id] = {fulfill: fulfill, reject: reject};
-    })
-    var header = {
-      id: id,
-      type: "ServiceRequest",
-      service: service
-    };
-    if (endpointId) header.to = endpointId;
-    send(Object.assign({}, req.header, header), req.payload);
-    return promise;
-  }
-
-  function send(header, payload) {
-      if (!ws) {
-        pendingSend.push({header: header, payload: payload});
-        return;
-      }
-      logger.debug(">>", header, payload);
-      ws.send(JSON.stringify(header) + (payload ? "\n"+payload : ""));
-  }
-
-
-
-  this.advertise = function(service, handler) {
-    if (providers[service.name]) throw new Error(service.name + " provider already exists");
-    providers[service.name] = {
-      advertisedService: service,
-      handler: handler
-    }
-    return send({
-      type: "SbAdvertiseRequest",
-      services: Object.keys(providers)
-        .map(function(x) {return providers[x].advertisedService})
-        .filter(function(x) {return x})
-    })
-  }
-
-  this.unadvertise = function(serviceName) {
-    if (!providers[serviceName]) throw new Error(serviceName + " provider not exists");
-    delete providers[serviceName];
-    return send({
-      type: "SbAdvertiseRequest",
-      services: Object.keys(providers)
-        .map(function(x) {return providers[x].advertisedService})
-        .filter(function(x) {return x})
-    })
-  }
-
-  this.setHandler = function(serviceName, handler) {
-    if (providers[serviceName]) throw new Error("Handler already exists");
-    providers[serviceName] = {
-      handler: handler
-    }
-  }
-
-
-
-  this.publish = function(topic, text) {
-    return send({
-      type: "ServiceRequest",
-      service: {name: "#"+topic}
-    },
-    text);
-  }
-
-  this.subscribe = function(topic, handler) {
-    return this.advertise({name: "#"+topic}, function(msg) {
-      handler(msg.payload);
-      return null;
-    })
-  }
-
-  this.unsubscribe = function(topic) {
-    return this.unadvertise("#"+topic);
-  }
-
-  this.isConnected = function() {
-    return ws != null;
-  }
-
-  this.addConnectListener = function(listener) {
-    connectListeners.push(listener);
-    if (this.isConnected()) listener();
-  }
+                .catch(err => {
+                if (msg.header.id) {
+                    this.send({
+                        to: msg.header.from,
+                        id: msg.header.id,
+                        type: "ServiceResponse",
+                        error: err.message || err
+                    });
+                }
+                else {
+                    console.error(err.message, msg.header);
+                }
+            });
+        }
+        else {
+            console.error("No handler for service " + service.name);
+        }
+    }
+    send(header, payload) {
+        if (!this.ws) {
+            this.pendingSend.push({ header, payload });
+            return;
+        }
+        console.debug(">>", header, payload);
+        if (payload) {
+            this.ws.send(JSON.stringify(header) + "\n" + payload);
+        }
+        else {
+            this.ws.send(JSON.stringify(header));
+        }
+    }
+    request(service, req) {
+        return this.requestTo(null, service, req);
+    }
+    requestTo(endpointId, service, req) {
+        const id = ++this.pendingIdGen;
+        const promise = new Promise((fulfill, reject) => {
+            this.pendingResponses.set(id, { fulfill, reject });
+        });
+        const header = {
+            id: id,
+            type: "ServiceRequest",
+            service
+        };
+        if (endpointId)
+            header.to = endpointId;
+        this.send(Object.assign(Object.assign({}, req.header), header), req.payload);
+        return promise;
+    }
+    advertise(service, handler) {
+        if (this.providers.has(service.name)) {
+            throw new Error(service.name + " provider already exists");
+        }
+        this.providers.set(service.name, { advertisedService: service, handler });
+        return this.send({
+            type: "SbAdvertiseRequest",
+            services: Array.from(this.providers.values())
+                .filter(x => x.advertisedService)
+                .map(x => x.advertisedService)
+        });
+    }
+    unadvertise(serviceName) {
+        if (!this.providers.delete(serviceName)) {
+            throw new Error(serviceName + " provider not exists");
+        }
+        return this.send({
+            type: "SbAdvertiseRequest",
+            services: Array.from(this.providers.values())
+                .filter(x => x.advertisedService)
+                .map(x => x.advertisedService)
+        });
+    }
+    setServiceHandler(serviceName, handler) {
+        if (this.providers.has(serviceName)) {
+            throw new Error("Handler already exists");
+        }
+        this.providers.set(serviceName, { handler });
+    }
+    publish(topic, text) {
+        return this.send({ type: "ServiceRequest", service: { name: "#" + topic } }, text);
+    }
+    subscribe(topic, handler) {
+        return this.advertise({ name: "#" + topic }, msg => handler(msg.payload));
+    }
+    unsubscribe(topic) {
+        return this.unadvertise("#" + topic);
+    }
+    isConnected() {
+        return this.ws != null;
+    }
+    addConnectListener(listener) {
+        this.connectListeners.push(listener);
+        if (this.isConnected())
+            listener();
+    }
 }

package/package.json

@@ -1,18 +1,20 @@
 {
   "name": "@service-broker/webclient",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Browser ESM client library for communicating with the service broker",
   "type": "module",
   "main": "dist/index.js",
-  "types": "dist/index.d.ts",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/service-broker/service-broker-webclient.git"
+    "url": "git+https://github.com/service-broker/webclient.git"
   },
   "author": "Hai Phan <hai.phan@gmail.com>",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/service-broker/service-broker-webclient/issues"
+    "url": "https://github.com/service-broker/webclient/issues"
   },
-  "homepage": "https://github.com/service-broker/service-broker-webclient#readme"
+  "homepage": "https://github.com/service-broker/webclient#readme",
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  }
 }

package/src/index.ts

@@ -0,0 +1,228 @@
+
+export interface ServiceSelector {
+  name: string
+  capabilities?: string[]
+}
+
+export interface ServiceHandler {
+  (request: MessageWithHeader): Message | void | Promise<Message | void>
+}
+
+type MessageHeader = Record<string, unknown>
+type MessagePayload = string
+
+export interface MessageWithHeader {
+  header: MessageHeader
+  payload?: MessagePayload
+}
+
+export interface Message {
+  header?: MessageHeader
+  payload?: MessagePayload
+}
+
+interface PendingResponse {
+  fulfill(response: Message): void
+  reject(err: unknown): void
+}
+
+function messageFromString(text: string): MessageWithHeader {
+  const index = text.indexOf('\n')
+  if (index == -1) {
+    return {
+      header: JSON.parse(text)
+    }
+  } else {
+    return {
+      header: JSON.parse(text.slice(0, index)),
+      payload: text.slice(index + 1)
+    }
+  }
+}
+
+
+export class ServiceBroker {
+
+  private readonly providers = new Map<string, {
+    advertisedService?: ServiceSelector
+    handler: ServiceHandler
+  }>()
+  private ws: WebSocket | null = null
+  private readonly connectListeners: Function[] = []
+  private pendingSend: MessageWithHeader[] = []
+  private readonly pendingResponses = new Map<number, PendingResponse>()
+  private pendingIdGen = 0
+
+
+  constructor(private readonly url: string) {
+    this.connect()
+  }
+
+  private connect() {
+    const conn = new WebSocket(this.url)
+    conn.onopen = () => this.onOpen(conn)
+    conn.onerror = () => {
+      console.error("Failed to connect to service broker, retrying in 15")
+      setTimeout(() => this.connect(), 15000)
+    }
+  }
+
+  private onOpen(conn: WebSocket) {
+    this.ws = conn
+    this.ws.onerror = console.error
+    this.ws.onclose = () => this.onClose()
+    this.ws.onmessage = event => this.onMessage(event)
+    for (const listener of this.connectListeners) listener()
+    for (const { header, payload } of this.pendingSend) this.send(header, payload)
+    this.pendingSend = []
+  }
+
+  private onClose() {
+    this.ws = null
+    console.error("Lost connection to service broker, reconnecting")
+    setTimeout(() => this.connect(), 0)
+  }
+
+  private onMessage(e: MessageEvent) {
+    const msg = messageFromString(e.data);
+    console.debug("<<", msg.header, msg.payload);
+    if (msg.header.type == "ServiceResponse") this.onServiceResponse(msg)
+    else if (msg.header.type == "ServiceRequest") this.onServiceRequest(msg)
+    else if (msg.header.type == "SbStatusResponse") this.onServiceResponse(msg)
+    else if (msg.header.error) this.onServiceResponse(msg)
+    else console.error("Unhandled", msg.header)
+  }
+
+  private onServiceResponse(message: MessageWithHeader) {
+    const id = message.header.id as number
+    const pendingResponse = this.pendingResponses.get(id)
+    if (pendingResponse) {
+      this.pendingResponses.delete(id)
+      if (message.header.error) {
+        pendingResponse.reject(new Error(message.header.error as string))
+      } else {
+        pendingResponse.fulfill(message)
+      }
+    } else {
+      console.error("Response received but no pending request", message.header)
+    }
+  }
+
+  private onServiceRequest(msg: MessageWithHeader) {
+    const service = msg.header.service as ServiceSelector
+    const provider = this.providers.get(service.name)
+    if (provider) {
+      Promise.resolve(provider.handler(msg))
+        .then(res => {
+          if (msg.header.id) {
+            this.send({
+              ...res?.header,
+              to: msg.header.from,
+              id: msg.header.id,
+              type: "ServiceResponse"
+            }, res?.payload)
+          }
+        })
+        .catch(err => {
+          if (msg.header.id) {
+            this.send({
+              to: msg.header.from,
+              id: msg.header.id,
+              type: "ServiceResponse",
+              error: err.message || err
+            })
+          } else {
+            console.error(err.message, msg.header)
+          }
+        })
+    } else {
+      console.error("No handler for service " + service.name)
+    }
+  }
+
+  private send(header: MessageHeader, payload?: MessagePayload) {
+    if (!this.ws) {
+      this.pendingSend.push({ header, payload })
+      return;
+    }
+    console.debug(">>", header, payload);
+    if (payload) {
+      this.ws.send(JSON.stringify(header) + "\n" + payload)
+    } else {
+      this.ws.send(JSON.stringify(header))
+    }
+  }
+
+
+  request(service: ServiceSelector, req: Message) {
+    return this.requestTo(null, service, req);
+  }
+
+  requestTo(endpointId: string | null, service: ServiceSelector, req: Message) {
+    const id = ++this.pendingIdGen
+    const promise = new Promise<Message>((fulfill, reject) => {
+      this.pendingResponses.set(id, { fulfill, reject })
+    })
+    const header: MessageHeader = {
+      id: id,
+      type: "ServiceRequest",
+      service
+    };
+    if (endpointId) header.to = endpointId;
+    this.send({...req.header, ...header}, req.payload)
+    return promise;
+  }
+
+  advertise(service: ServiceSelector, handler: ServiceHandler) {
+    if (this.providers.has(service.name)) {
+      throw new Error(service.name + " provider already exists")
+    }
+    this.providers.set(service.name, { advertisedService: service, handler })
+    return this.send({
+      type: "SbAdvertiseRequest",
+      services: Array.from(this.providers.values())
+        .filter(x => x.advertisedService)
+        .map(x => x.advertisedService)
+    })
+  }
+
+  unadvertise(serviceName: string) {
+    if (!this.providers.delete(serviceName)) {
+      throw new Error(serviceName + " provider not exists")
+    }
+    return this.send({
+      type: "SbAdvertiseRequest",
+      services: Array.from(this.providers.values())
+        .filter(x => x.advertisedService)
+        .map(x => x.advertisedService)
+    })
+  }
+
+  setServiceHandler(serviceName: string, handler: ServiceHandler) {
+    if (this.providers.has(serviceName)) {
+      throw new Error("Handler already exists")
+    }
+    this.providers.set(serviceName, { handler })
+  }
+
+  publish(topic: string, text: string) {
+    return this.send({ type: "ServiceRequest", service: { name: "#" + topic } }, text)
+  }
+
+  subscribe(topic: string, handler: (text: string) => void) {
+    return this.advertise({ name: "#" + topic }, msg => handler(msg.payload!))
+  }
+
+  unsubscribe(topic: string) {
+    return this.unadvertise("#" + topic)
+  }
+
+  isConnected() {
+    return this.ws != null
+  }
+
+  addConnectListener(listener: Function) {
+    this.connectListeners.push(listener)
+    if (this.isConnected()) listener()
+  }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "module": "esnext",
+    "target": "es2017",
+    "strict": true,
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "newLine": "LF",
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": [
+    "src/**/*"
+  ]
+}