@elliemae/pui-websocket-so 2.0.0

package/dist/esm/index.js

@@ -0,0 +1,4 @@
+import { WebSocketSO } from "./websocketSO.js";
+export {
+  WebSocketSO
+};

package/dist/esm/messageRouter.js

@@ -0,0 +1,91 @@
+class MessageRouter {
+  #subscriptionManager;
+  #onEvent;
+  #logger;
+  /**
+   * @param {SubscriptionManager} subscriptionManager - manages pending requests and active subscriptions
+   * @param {EventCallback} onEvent - callback invoked when a server event matches an active subscription
+   * @param {Logger} logger - logger instance for debug/error output
+   */
+  constructor(subscriptionManager, onEvent, logger) {
+    this.#subscriptionManager = subscriptionManager;
+    this.#onEvent = onEvent;
+    this.#logger = logger;
+  }
+  /**
+   * Entry point for all messages received from the WebSocket server.
+   * Dispatches to the correct handler based on message type.
+   * @param {ServerMessage} message - incoming server message
+   */
+  handleMessage = (message) => {
+    switch (message.type) {
+      case "subscribe_ack":
+        this.#handleSubscribeAck(message);
+        break;
+      case "unsubscribe_ack":
+        this.#handleUnsubscribeAck(message);
+        break;
+      case "error":
+        this.#handleError(message);
+        break;
+      case "event":
+        this.#handleEvent(message);
+        break;
+      default:
+        this.#logger.debug(
+          `Unknown message type received: ${message.type}`
+        );
+    }
+  };
+  #handleSubscribeAck(message) {
+    const { correlationId, subscriptionId } = message;
+    const resolved = this.#subscriptionManager.resolvePendingRequest(
+      correlationId,
+      { subscriptionId }
+    );
+    if (!resolved) {
+      this.#logger.debug(
+        `Received subscribe_ack for unknown correlationId: ${correlationId}`
+      );
+    }
+  }
+  #handleUnsubscribeAck(message) {
+    const { correlationId } = message;
+    const resolved = this.#subscriptionManager.resolvePendingRequest(
+      correlationId,
+      void 0
+    );
+    if (!resolved) {
+      this.#logger.debug(
+        `Received unsubscribe_ack for unknown correlationId: ${correlationId}`
+      );
+    }
+  }
+  #handleError(message) {
+    const { correlationId, errors } = message;
+    const errorMessages = errors.map((e) => `${e.code}: ${e.message}`).join("; ");
+    const rejected = this.#subscriptionManager.rejectPendingRequest(
+      correlationId,
+      new Error(errorMessages)
+    );
+    if (!rejected) {
+      this.#logger.debug(
+        `Received error for unknown correlationId: ${correlationId}. Errors: ${errorMessages}`
+      );
+    }
+  }
+  #handleEvent(message) {
+    const { subscriptionId } = message;
+    const subscription = this.#subscriptionManager.getSubscription(subscriptionId);
+    if (!subscription) {
+      this.#logger.debug(
+        `Received event for unknown subscriptionId: ${subscriptionId}`
+      );
+      return;
+    }
+    this.#onEvent(message, subscription);
+  }
+}
+export {
+  MessageRouter
+};

package/dist/esm/package.json

@@ -0,0 +1,7 @@
+{
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/dist/esm/subscriptionManager.js

@@ -0,0 +1,204 @@
+const DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+class SubscriptionManager {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  #pendingRequests = /* @__PURE__ */ new Map();
+  #subscriptions = /* @__PURE__ */ new Map();
+  /** Reverse index: composite lookup key → subscriptionId for O(1) duplicate detection. */
+  #keyIndex = /* @__PURE__ */ new Map();
+  #requestTimeoutMs;
+  /**
+   * @param {number} [requestTimeoutMs=30000] - timeout in ms before a pending request is auto-rejected
+   */
+  constructor(requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+    this.#requestTimeoutMs = requestTimeoutMs;
+  }
+  /**
+   * Register a pending request that will be resolved/rejected when the
+   * server responds with a message matching the given correlationId.
+   * @param {string} correlationId - unique id correlating request to response
+   * @param {Function} resolve - callback invoked on success
+   * @param {Function} reject - callback invoked on failure or timeout
+   */
+  addPendingRequest(correlationId, resolve, reject) {
+    const existing = this.#pendingRequests.get(correlationId);
+    if (existing) {
+      clearTimeout(existing.timeoutId);
+      existing.reject(
+        new Error(`Pending request replaced (correlationId: ${correlationId})`)
+      );
+    }
+    const timeoutId = setTimeout(() => {
+      this.#pendingRequests.delete(correlationId);
+      reject(
+        new Error(
+          `Request timed out after ${this.#requestTimeoutMs}ms (correlationId: ${correlationId})`
+        )
+      );
+    }, this.#requestTimeoutMs);
+    this.#pendingRequests.set(correlationId, { resolve, reject, timeoutId });
+  }
+  /**
+   * Resolve a pending request with a successful result.
+   * @param {string} correlationId - unique id of the pending request
+   * @param {*} value - the value to resolve with
+   * @returns {boolean} true if the request was found and resolved
+   */
+  resolvePendingRequest(correlationId, value) {
+    const pending = this.#pendingRequests.get(correlationId);
+    if (!pending) return false;
+    clearTimeout(pending.timeoutId);
+    this.#pendingRequests.delete(correlationId);
+    pending.resolve(value);
+    return true;
+  }
+  /**
+   * Reject a pending request with an error.
+   * @param {string} correlationId - unique id of the pending request
+   * @param {Error} error - the error to reject with
+   * @returns {boolean} true if the request was found and rejected
+   */
+  rejectPendingRequest(correlationId, error) {
+    const pending = this.#pendingRequests.get(correlationId);
+    if (!pending) return false;
+    clearTimeout(pending.timeoutId);
+    this.#pendingRequests.delete(correlationId);
+    pending.reject(error);
+    return true;
+  }
+  /**
+   * Find an existing subscription matching the given resource criteria and guest.
+   * Uses a secondary key index for O(1) lookup.
+   * @param {Omit<Subscription, 'subscriptionId' | 'refCount'>} criteria - fields to match
+   * @returns {Subscription | undefined} matching subscription or undefined
+   */
+  findExistingSubscription(criteria) {
+    const key = SubscriptionManager.#buildLookupKey(criteria);
+    const subscriptionId = this.#keyIndex.get(key);
+    if (!subscriptionId) return void 0;
+    return this.#subscriptions.get(subscriptionId);
+  }
+  /**
+   * Register a new active subscription. Initialises refCount to 1.
+   * @param {Omit<Subscription, 'refCount'>} subscription - subscription data (refCount is set internally)
+   */
+  addSubscription(subscription) {
+    const entry = {
+      ...subscription,
+      filter: subscription.filter ? JSON.parse(JSON.stringify(subscription.filter)) : void 0,
+      refCount: 1
+    };
+    this.#subscriptions.set(subscription.subscriptionId, entry);
+    this.#keyIndex.set(
+      SubscriptionManager.#buildLookupKey(entry),
+      subscription.subscriptionId
+    );
+  }
+  /**
+   * Increment the reference count for an existing subscription.
+   * @param {string} subscriptionId - subscription to increment
+   * @returns {number} the new refCount, or -1 if the subscription was not found
+   */
+  incrementRefCount(subscriptionId) {
+    const sub = this.#subscriptions.get(subscriptionId);
+    if (!sub) return -1;
+    sub.refCount += 1;
+    return sub.refCount;
+  }
+  /**
+   * Decrement the reference count and remove when it reaches 0.
+   * @param {string} subscriptionId - subscription to decrement
+   * @returns {number} the new refCount (0 means removed), or -1 if not found
+   */
+  decrementRefCount(subscriptionId) {
+    const sub = this.#subscriptions.get(subscriptionId);
+    if (!sub) return -1;
+    sub.refCount -= 1;
+    if (sub.refCount <= 0) {
+      this.#keyIndex.delete(SubscriptionManager.#buildLookupKey(sub));
+      this.#subscriptions.delete(subscriptionId);
+      return 0;
+    }
+    return sub.refCount;
+  }
+  /**
+   * Unconditionally remove a subscription regardless of refCount.
+   * Used during reconnection to replace old entries.
+   * @param {string} subscriptionId - subscription to remove
+   * @returns {boolean} true if the subscription existed and was removed
+   */
+  removeSubscription(subscriptionId) {
+    const sub = this.#subscriptions.get(subscriptionId);
+    if (sub) {
+      this.#keyIndex.delete(SubscriptionManager.#buildLookupKey(sub));
+    }
+    return this.#subscriptions.delete(subscriptionId);
+  }
+  /**
+   * Retrieve subscription metadata by id.
+   * @param {string} subscriptionId - subscription to look up
+   * @returns {Subscription | undefined} the subscription, or undefined if not found
+   */
+  getSubscription(subscriptionId) {
+    return this.#subscriptions.get(subscriptionId);
+  }
+  /**
+   * Check whether a subscription is currently active.
+   * @param {string} subscriptionId - subscription to check
+   * @returns {boolean} true if the subscription exists
+   */
+  hasSubscription(subscriptionId) {
+    return this.#subscriptions.has(subscriptionId);
+  }
+  /**
+   * Returns all active subscriptions.
+   * Used for re-subscribing after a reconnection.
+   * @returns {Subscription[]} array of active subscriptions
+   */
+  getAllSubscriptions() {
+    return Array.from(this.#subscriptions.values());
+  }
+  /**
+   * Clean up all pending requests and subscriptions.
+   * Rejects any outstanding pending requests.
+   */
+  dispose() {
+    this.#pendingRequests.forEach((pending) => {
+      clearTimeout(pending.timeoutId);
+      pending.reject(new Error("WebSocket scripting object disposed"));
+    });
+    this.#pendingRequests.clear();
+    this.#subscriptions.clear();
+    this.#keyIndex.clear();
+  }
+  /**
+   * Compute the canonical lookup key for a set of subscription criteria.
+   * Exposed so callers can track in-flight subscribes by the same key.
+   * @param {Omit<Subscription, 'subscriptionId' | 'refCount'>} criteria - subscription fields
+   * @returns {string} composite lookup key
+   */
+  static buildLookupKey(criteria) {
+    return SubscriptionManager.#buildLookupKey(criteria);
+  }
+  /**
+   * Builds a canonical composite key for O(1) subscription lookup.
+   * Uses NUL (\0) as separator to avoid collisions with real values.
+   * Filter keys are sorted for order-independent comparison.
+   * @param {Pick<Subscription, 'guestId' | 'resource' | 'resourceId' | 'filter'>} sub - subscription fields
+   * @returns {string} composite lookup key
+   */
+  static #buildLookupKey(sub) {
+    const { guestId, resource, resourceId, filter } = sub;
+    if (resourceId != null) {
+      return `${guestId}\0${resource}\0rid:${resourceId}`;
+    }
+    if (filter != null) {
+      const sortedKeys = Object.keys(filter).sort();
+      const canonical = sortedKeys.map((k) => `${k}=${filter[k].join(",")}`).join("&");
+      return `${guestId}\0${resource}\0f:${canonical}`;
+    }
+    return `${guestId}\0${resource}`;
+  }
+}
+export {
+  SubscriptionManager
+};

package/dist/esm/websocketSO.js

@@ -0,0 +1,318 @@
+import { ScriptingObject, Event } from "@elliemae/ssf-host";
+import { WSClient, WSContentType } from "@elliemae/pui-wsclient";
+import { SubscriptionManager } from "./subscriptionManager.js";
+import { MessageRouter } from "./messageRouter.js";
+const SCRIPTING_OBJECT_NAME = "websocket";
+const EVENT_NAME = "message";
+const EVENT_ID = `${SCRIPTING_OBJECT_NAME}.${EVENT_NAME}`;
+class WebSocketSO extends 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 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 SubscriptionManager();
+    this.#messageRouter = new MessageRouter(
+      this.#subscriptionManager,
+      this.#handleEvent,
+      this.#logger
+    );
+    this.#client = new WSClient({
+      url,
+      token,
+      logger,
+      contentType: 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 = 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();
+  };
+}
+export {
+  WebSocketSO
+};