@elliemae/pui-websocket-so 2.0.0

package/dist/cjs/websocketSO.js

@@ -0,0 +1,338 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var websocketSO_exports = {};
+__export(websocketSO_exports, {
+  WebSocketSO: () => WebSocketSO
+});
+module.exports = __toCommonJS(websocketSO_exports);
+var import_ssf_host = require("@elliemae/ssf-host");
+var import_pui_wsclient = require("@elliemae/pui-wsclient");
+var import_subscriptionManager = require("./subscriptionManager.js");
+var import_messageRouter = require("./messageRouter.js");
+const SCRIPTING_OBJECT_NAME = "websocket";
+const EVENT_NAME = "message";
+const EVENT_ID = `${SCRIPTING_OBJECT_NAME}.${EVENT_NAME}`;
+class WebSocketSO extends import_ssf_host.ScriptingObject {
+  #client;
+  #logger;
+  #host;
+  #subscriptionManager;
+  #messageRouter;
+  #isOpen = false;
+  /**
+   * Tracks in-flight subscribe promises keyed by lookup key.
+   * Prevents concurrent identical subscribes from creating duplicate
+   * server-side subscriptions.
+   */
+  #pendingSubscribes = /* @__PURE__ */ new Map();
+  /** Event dispatched to subscribed guests when the server sends an event message. */
+  Message = new import_ssf_host.Event({
+    name: EVENT_NAME,
+    objectId: SCRIPTING_OBJECT_NAME
+  });
+  /**
+   * Creates a new WebSocket scripting object.
+   * @param {WebSocketSOOptions} options - configuration options
+   */
+  constructor({ logger, host, url, token, onError }) {
+    super(SCRIPTING_OBJECT_NAME);
+    if (!logger) throw new Error("logger is required");
+    if (!host) throw new Error("host is required");
+    if (!url) throw new Error("url is required");
+    if (!token) throw new Error("token is required");
+    this.#logger = logger;
+    this.#host = host;
+    this.#subscriptionManager = new import_subscriptionManager.SubscriptionManager();
+    this.#messageRouter = new import_messageRouter.MessageRouter(
+      this.#subscriptionManager,
+      this.#handleEvent,
+      this.#logger
+    );
+    this.#client = new import_pui_wsclient.WSClient({
+      url,
+      token,
+      logger,
+      contentType: import_pui_wsclient.WSContentType.JSON,
+      onMessage: (message) => {
+        this.#messageRouter.handleMessage(message);
+      },
+      onError
+    });
+    this.#client.onOpen = this.#handleReconnect;
+    Object.defineProperty(this, "open", { enumerable: false });
+    Object.defineProperty(this, "close", { enumerable: false });
+  }
+  /**
+   * Opens the WebSocket connection to the server.
+   * Must be called before guests can subscribe. Idempotent — calling
+   * while already open is a no-op.
+   * @returns {Promise<void>} promise that resolves when the connection is established
+   */
+  open = async () => {
+    if (this.#isOpen) return;
+    await this.#client.open();
+    this.#isOpen = true;
+  };
+  /**
+   * Closes the WebSocket connection and cleans up all subscriptions.
+   * Idempotent — calling while already closed is a no-op.
+   */
+  close = () => {
+    if (!this.#isOpen) return;
+    this.#isOpen = false;
+    this.#pendingSubscribes.clear();
+    this.#client.close();
+    this.#subscriptionManager.dispose();
+  };
+  /**
+   * Validates subscribe preconditions and returns the guestId + destructured options.
+   * @param {SubscribeOptions} options - subscribe options to validate
+   * @returns {{ guestId: string; resource: string; resourceId?: string; filter?: Record<string, string[]> }} validated fields
+   * @throws {Error} if any validation fails
+   */
+  #validateSubscribe = (options) => {
+    const guestId = this.subscribe.callContext?.guest?.id;
+    if (!guestId) {
+      throw new Error("unable to identify calling guest from callContext");
+    }
+    if (!this.#isOpen) {
+      throw new Error("WebSocket connection is not open. Call open() first.");
+    }
+    const { resource, resourceId, filter } = options;
+    if (!resource) {
+      throw new Error("resource is required");
+    }
+    if (!resourceId && !filter) {
+      throw new Error("either resourceId or filter must be provided");
+    }
+    return { guestId, resource, resourceId, filter };
+  };
+  /**
+   * Subscribe to a WebSocket resource on behalf of the calling guest.
+   * If an identical subscription already exists for this guest, returns
+   * the existing subscriptionId and increments the reference count.
+   * @param {SubscribeOptions} options - resource, resourceId or filter
+   * @returns {Promise<SubscribeResult>} resolves with the subscriptionId
+   */
+  subscribe = (options) => {
+    let validated;
+    try {
+      validated = this.#validateSubscribe(options);
+    } catch (err) {
+      return Promise.reject(err);
+    }
+    const { guestId, resource, resourceId, filter } = validated;
+    const criteria = { resource, guestId, resourceId, filter };
+    const existing = this.#subscriptionManager.findExistingSubscription(criteria);
+    if (existing) {
+      this.#subscriptionManager.incrementRefCount(existing.subscriptionId);
+      return Promise.resolve({ subscriptionId: existing.subscriptionId });
+    }
+    const lookupKey = import_subscriptionManager.SubscriptionManager.buildLookupKey(criteria);
+    const inflight = this.#pendingSubscribes.get(lookupKey);
+    if (inflight) {
+      return inflight.then((result) => {
+        this.#subscriptionManager.incrementRefCount(result.subscriptionId);
+        return result;
+      });
+    }
+    return this.#sendSubscribeCommand(criteria, lookupKey);
+  };
+  /**
+   * Sends the subscribe command to the server and tracks the in-flight promise.
+   * @param {Omit<Subscription, 'subscriptionId' | 'refCount'>} criteria - subscription criteria
+   * @param {string} lookupKey - key for in-flight dedup
+   * @returns {Promise<SubscribeResult>} resolves with the subscriptionId
+   */
+  #sendSubscribeCommand = (criteria, lookupKey) => {
+    const { guestId, resource, resourceId, filter } = criteria;
+    const correlationId = crypto.randomUUID();
+    const command = {
+      type: "subscribe",
+      correlationId,
+      resource,
+      ...resourceId != null && { resourceId },
+      ...filter != null && { filter }
+    };
+    const promise = new Promise((resolve, reject) => {
+      this.#subscriptionManager.addPendingRequest(
+        correlationId,
+        (result) => {
+          this.#subscriptionManager.addSubscription({
+            subscriptionId: result.subscriptionId,
+            resource,
+            guestId,
+            resourceId,
+            filter
+          });
+          this.#logger.debug(
+            `Guest ${guestId} subscribed to ${resource} with subscriptionId: ${result.subscriptionId}`
+          );
+          resolve(result);
+        },
+        reject
+      );
+      this.#sendCommand(command).catch((err) => {
+        this.#subscriptionManager.rejectPendingRequest(correlationId, err);
+      });
+    });
+    this.#pendingSubscribes.set(lookupKey, promise);
+    promise.finally(() => this.#pendingSubscribes.delete(lookupKey)).catch(() => {
+    });
+    return promise;
+  };
+  /**
+   * Unsubscribe from an active subscription. Decrements the reference
+   * count; the server-side unsubscribe is only sent when the last
+   * consumer releases the subscription.
+   * @param {string} subscriptionId - id of the subscription to release
+   * @returns {Promise<void>} resolves when the unsubscribe completes
+   */
+  unsubscribe = (subscriptionId) => {
+    if (!subscriptionId) {
+      return Promise.reject(new Error("subscriptionId is required"));
+    }
+    if (!this.#isOpen) {
+      return Promise.reject(
+        new Error("WebSocket connection is not open. Call open() first.")
+      );
+    }
+    const guestId = this.unsubscribe.callContext?.guest?.id;
+    if (!guestId) {
+      return Promise.reject(
+        new Error("unable to identify calling guest from callContext")
+      );
+    }
+    const subscription = this.#subscriptionManager.getSubscription(subscriptionId);
+    if (!subscription || subscription.guestId !== guestId) {
+      return Promise.reject(
+        new Error(
+          `subscription ${subscriptionId} is not available for this guest`
+        )
+      );
+    }
+    const remaining = this.#subscriptionManager.decrementRefCount(subscriptionId);
+    if (remaining > 0) {
+      this.#logger.debug(
+        `Decremented refCount for ${subscriptionId} to ${remaining}`
+      );
+      return Promise.resolve();
+    }
+    const correlationId = crypto.randomUUID();
+    const command = {
+      type: "unsubscribe",
+      correlationId,
+      subscriptionId
+    };
+    return new Promise((resolve, reject) => {
+      this.#subscriptionManager.addPendingRequest(
+        correlationId,
+        () => {
+          this.#logger.debug(
+            `Unsubscribed from subscriptionId: ${subscriptionId}`
+          );
+          resolve();
+        },
+        reject
+      );
+      this.#sendCommand(command).catch((err) => {
+        this.#subscriptionManager.rejectPendingRequest(correlationId, err);
+      });
+    });
+  };
+  /**
+   * Sends a command to the WebSocket server via the underlying WSClient.
+   * @param {ClientMessage} command - subscribe or unsubscribe command
+   * @returns {Promise<void>} resolves when the message is sent
+   */
+  #sendCommand = (command) => this.#client.send(command);
+  /**
+   * Re-subscribes all active subscriptions after a WSClient reconnection.
+   * Server-side subscription state is lost on disconnect, so we must
+   * re-establish them.
+   */
+  #handleReconnect = () => {
+    const subscriptions = this.#subscriptionManager.getAllSubscriptions();
+    if (subscriptions.length === 0) return;
+    this.#logger.debug(
+      `WebSocket reconnected \u2014 re-subscribing ${subscriptions.length} subscription(s)`
+    );
+    subscriptions.forEach((sub) => {
+      const correlationId = crypto.randomUUID();
+      const command = {
+        type: "subscribe",
+        correlationId,
+        resource: sub.resource,
+        ...sub.resourceId != null && { resourceId: sub.resourceId },
+        ...sub.filter != null && { filter: sub.filter }
+      };
+      this.#subscriptionManager.addPendingRequest(
+        correlationId,
+        (result) => {
+          this.#subscriptionManager.removeSubscription(sub.subscriptionId);
+          this.#subscriptionManager.addSubscription({
+            ...sub,
+            subscriptionId: result.subscriptionId
+          });
+          this.#logger.debug(
+            `Re-subscribed guest ${sub.guestId} to ${sub.resource}: ${sub.subscriptionId} \u2192 ${result.subscriptionId}`
+          );
+        },
+        (err) => {
+          this.#subscriptionManager.removeSubscription(sub.subscriptionId);
+          this.#logger.error(
+            `Failed to re-subscribe guest ${sub.guestId} to ${sub.resource}: ${err.message}. Subscription removed.`
+          );
+        }
+      );
+      this.#sendCommand(command).catch((err) => {
+        this.#subscriptionManager.rejectPendingRequest(correlationId, err);
+      });
+    });
+  };
+  /**
+   * Dispatches a server event to the owning guest via the host's dispatchEvent.
+   * @param {EventMessage} event - the server event message
+   * @param {Subscription} subscription - the matching subscription with guestId
+   */
+  #handleEvent = (event, subscription) => {
+    const eventParams = {
+      subscriptionId: event.subscriptionId,
+      resource: event.resource,
+      payload: event.payload
+    };
+    this.#host.dispatchEvent({
+      event: { id: EVENT_ID, name: EVENT_NAME },
+      eventParams,
+      eventOptions: { guestId: subscription.guestId }
+    }).catch((err) => {
+      this.#logger.error(
+        `Failed to dispatch event to guest ${subscription.guestId}: ${err.message}`
+      );
+    });
+  };
+  /**
+   * Lifecycle hook called by the host framework when the SO is removed.
+   * Closes the WebSocket connection and cleans up all state.
+   */
+  // eslint-disable-next-line no-underscore-dangle
+  _dispose = () => {
+    this.close();
+  };
+}