@arena-im/buzz-client 1.1.0

package/src/lib/index.ts

@@ -0,0 +1,362 @@
+import {
+  FaultTolerantWebSocket,
+  WebsocketOptions,
+} from "./fault_tolerant_websocket";
+import { Request, ThrottledQueue } from "./throttled_queue";
+import { TokenManager } from "./token-manager";
+
+import { Topic } from "./topic";
+import { BuzzEnvironment, resolveBuzzConfig } from "./config";
+
+// These should match buzz' throttling constants
+const throttleWindowDuration = 5000;
+const throttleWindowThreshold = 25;
+
+const defaultCommandTimeout = 10 * 1000;
+
+type TimerID = ReturnType<typeof setTimeout>;
+export type CommandContent = Record<string, unknown>;
+
+export type EventCallback = (event: Event) => void;
+type EventCallbackRegistry = { [K: string]: EventCallback[] };
+type Command<T> = Request & {
+  requestId: string;
+  timeoutTimer?: TimerID;
+  resolve: (value: CommandResponse<T>) => void;
+  reject: (reason?: any) => void;
+};
+interface Event {
+  topic: string;
+  eventName: string;
+}
+type CommandErrorResponseType = "rejected" | "error" | "blocked";
+interface Message {
+  eventName?: string;
+  responseType?: CommandErrorResponseType | "ack" | "ok";
+  requestId?: string;
+  topic?: string;
+  reason?: string;
+}
+type ClientOptions = {
+  commandTimeout?: number;
+  websocket?: WebsocketOptions;
+  // Optional override for identity service URL when using a custom websocket endpoint
+  identityUrl?: string;
+};
+export interface CommandResponse<T> {
+  content: T;
+  responseType: "ok" | "ack" | "error" | "rejected";
+  requestId: string;
+}
+
+export class BuzzClient {
+  ws: FaultTolerantWebSocket | null = null;
+  nextRequestId = 0;
+  pendingCommands: Record<string, Command<any>> = {};
+  eventListeners: Record<string, EventCallbackRegistry> = {};
+  queue;
+  private unsubscribeTokenChange: (() => void) | null = null;
+  private readonly websocketUrl: string;
+  private readonly tokenManager: TokenManager;
+
+  constructor(
+    envOrWebsocketUrl: BuzzEnvironment | string,
+    private readonly namespace: string,
+    siteId: string,
+    token: string | null,
+    private options: ClientOptions = {}
+  ) {
+    // If the first arg is a known environment, resolve from config; otherwise treat it as a direct websocket URL
+    const isEnv = envOrWebsocketUrl === "dev" || envOrWebsocketUrl === "prod";
+    const envConfig = resolveBuzzConfig(
+      isEnv ? (envOrWebsocketUrl as BuzzEnvironment) : "prod"
+    );
+
+    this.websocketUrl = isEnv
+      ? envConfig.websocketUrl
+      : (envOrWebsocketUrl as string);
+
+    const identityUrl = this.options.identityUrl ?? envConfig.identityUrl;
+    this.tokenManager = new TokenManager(siteId, identityUrl);
+    this.tokenManager.setIdToken(token);
+
+    this.queue = new ThrottledQueue(
+      throttleWindowDuration,
+      throttleWindowThreshold,
+      this.onQueueError
+    );
+  }
+
+  private async getWebsocketUrl(): Promise<string> {
+    const token = await this.tokenManager.getBuzzToken();
+    return `${this.websocketUrl}?ns=${this.namespace}&token=${token}`;
+  }
+
+  private async ensureSocket(): Promise<FaultTolerantWebSocket> {
+    this.attachTokenListener();
+    if (!this.ws) {
+      this.ws = await this.createSocket();
+    }
+    return this.ws;
+  }
+
+  private attachTokenListener(): void {
+    if (this.unsubscribeTokenChange) return;
+    this.unsubscribeTokenChange = this.tokenManager.onTokenChange(
+      async (token: string | null) => {
+        if (!token) return;
+        if (this.ws) this.ws.close();
+        this.ws = await this.createSocket();
+      }
+    );
+  }
+
+  setToken(token: string | null) {
+    this.tokenManager.setIdToken(token);
+    if (this.ws) this.ws.close();
+    this.ws = null;
+  }
+
+  private async createSocket() {
+    return new FaultTolerantWebSocket(
+      await this.getWebsocketUrl(),
+      this.onWebsocketOpen,
+      this.onWebsocketMessage,
+      this.onWebsocketError,
+      this.options.websocket
+    );
+  }
+
+  async subscribe(topic: string) {
+    await this.sendCommand("buzz:subscribe", topic);
+  }
+
+  async unsubscribe(topic: string) {
+    await this.sendCommand("buzz:unsubscribe", topic);
+  }
+
+  topic(topic: string) {
+    return new Topic(this, topic);
+  }
+
+  async sendCommand<T>(
+    type: string,
+    topic: string,
+    content?: CommandContent
+  ): Promise<CommandResponse<T>> {
+    const requestId = `${this.nextRequestId++}`;
+    const payload = {
+      requestId,
+      type,
+      topic,
+      content,
+    };
+
+    const result = new Promise<CommandResponse<T>>((resolve, reject) => {
+      const command: Command<T> = {
+        requestId,
+        run: () => this.sendWithTimeout(payload, command),
+        resolve,
+        reject,
+      };
+      this.pendingCommands[requestId] = command;
+      this.queue.push(command);
+    });
+
+    // Ensure the websocket connection is established so the queue can run.
+    // Without this, the first command could wait forever for onOpen to trigger run().
+    void this.ensureSocket();
+
+    return result;
+  }
+
+  onEvent(topic: string, eventName: string, callback: EventCallback) {
+    if (!this.eventListeners[topic]) {
+      this.eventListeners[topic] = {};
+    }
+
+    if (!this.eventListeners[topic][eventName]) {
+      this.eventListeners[topic][eventName] = [];
+    }
+
+    this.eventListeners[topic][eventName].push(callback);
+  }
+
+  offEvent(topic: string, eventName: string, callback: EventCallback) {
+    const topicRegistry = this.eventListeners[topic];
+    if (!topicRegistry) return;
+    const callbacks = topicRegistry[eventName];
+    if (!callbacks) return;
+    const index = callbacks.indexOf(callback);
+    if (index !== -1) {
+      callbacks.splice(index, 1);
+    }
+    if (callbacks.length === 0) {
+      delete topicRegistry[eventName];
+    }
+    if (Object.keys(topicRegistry).length === 0) {
+      delete this.eventListeners[topic];
+    }
+  }
+
+  clearEventListeners() {
+    this.eventListeners = {};
+  }
+
+  async disconnect() {
+    const ws = await this.ensureSocket();
+    ws.close();
+    this.ws = null;
+    this.queue.destroy();
+    this.pendingCommands = {};
+    this.eventListeners = {};
+  }
+
+  private async sendWithTimeout<T>(payload: unknown, command: Command<T>) {
+    const ws = await this.ensureSocket();
+    // Ensure the socket is open before attempting to send to avoid race conditions
+    if (typeof (ws as any).whenOpen === "function") {
+      await (ws as any).whenOpen();
+    }
+    ws.send(JSON.stringify(payload));
+    command.timeoutTimer = setTimeout(() => {
+      this.rejectCommand(command, new CommandTimeoutError());
+    }, this.options.commandTimeout || defaultCommandTimeout);
+  }
+
+  private dispatchEvent(event: Event) {
+    if (
+      !this.eventListeners[event.topic] ||
+      !this.eventListeners[event.topic][event.eventName]
+    ) {
+      return;
+    }
+
+    this.eventListeners[event.topic][event.eventName].forEach((callback) =>
+      callback(event)
+    );
+  }
+
+  // Defined with arrow for correct `this` binding
+  private onQueueError = (error: unknown, request: Request) => {
+    const requestId = (request as Command<unknown>).requestId;
+    const errorMessage = error instanceof Error ? error.message : `${error}`;
+    const command = this.pendingCommands[requestId];
+    if (command === undefined) {
+      console.warn(`Request ID not found; request: ${JSON.stringify(request)}`);
+      return;
+    }
+
+    this.rejectCommand(command, new WebsocketError(errorMessage));
+  };
+
+  // Defined with arrow for correct `this` binding
+  private onWebsocketOpen = () => {
+    this.queue.run();
+  };
+
+  // Defined with arrow for correct `this` binding
+  private onWebsocketError = () => {
+    // Abort all queued commands
+    this.queue.destroy();
+    this.queue = new ThrottledQueue(
+      throttleWindowDuration,
+      throttleWindowThreshold,
+      this.onQueueError
+    );
+    // Fail all pending commands
+    const error = new WebsocketError("websocket connection error");
+    Object.values(this.pendingCommands).forEach((command) =>
+      this.rejectCommand(command, error)
+    );
+    this.pendingCommands = {};
+  };
+
+  // Defined with arrow for correct `this` binding
+  private onWebsocketMessage = (rawMessage: string) => {
+    const message = JSON.parse(rawMessage) as Message;
+    // Event case
+    if (message.eventName && message.topic) {
+      this.dispatchEvent(message as Event);
+      return;
+    }
+
+    // Command response case
+
+    // This should never happen if `throttleWindowDuration` and `throttleWindowThreshold`
+    // settings match buzz server's throttle settings
+    if (message.responseType === "rejected" && message.reason === "throttled") {
+      console.error(
+        "Buzz server throttled this connection. Review client throttling settings"
+      );
+    }
+
+    // no-op
+    if (message.responseType === "ack") {
+      return;
+    }
+
+    if (message.requestId === undefined) {
+      console.warn(`Missing request ID; message: ${JSON.stringify(message)}`);
+      return;
+    }
+
+    const requestId = `${message.requestId}`;
+    const command = this.pendingCommands[requestId];
+    if (command === undefined) {
+      console.warn(`Request ID not found; message: ${JSON.stringify(message)}`);
+      return;
+    }
+
+    // `responseType` field is absent in some successful responses from buzz.
+    // When this is fixed in buzz (set to `ok`) this `undefined` check can be removed
+    if (message.responseType === "ok" || message.responseType === undefined) {
+      clearTimeout(command.timeoutTimer);
+      command.resolve(message as CommandResponse<unknown>);
+      delete this.pendingCommands[requestId];
+      return;
+    }
+
+    const error = new CommandErrorResponse(
+      message.reason || "",
+      message.responseType
+    );
+    this.rejectCommand(command, error);
+  };
+
+  private rejectCommand(command: Command<any>, error: Error) {
+    clearTimeout(command.timeoutTimer);
+    command.reject(error);
+    delete this.pendingCommands[command.requestId];
+  }
+}
+
+export class CommandErrorResponse extends Error {
+  constructor(message: string, public errorType: CommandErrorResponseType) {
+    super(message);
+    this.name = "CommandErrorResponse";
+
+    // Fix prototype chain (needed in some environments like TS + ES5)
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class CommandTimeoutError extends Error {
+  constructor() {
+    super("timeout");
+    this.name = "CommandTimeoutError";
+
+    // Fix prototype chain (needed in some environments like TS + ES5)
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class WebsocketError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "WebsocketError";
+
+    // Fix prototype chain (needed in some environments like TS + ES5)
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/src/lib/throttled_queue.ts

@@ -0,0 +1,136 @@
+// A request queue that executes up to `threshold` requests every `windowDuration` milliseconds,
+// enforcing rate limits to prevent throttling
+
+export interface Request {
+  run: () => void;
+}
+type OnErrorCallback = (error: unknown, request: Request) => void;
+
+const windowSafetyPadding = 500;
+
+/**
+ * Queue Status Flow:
+ *
+ *   [Buffering]
+ *       |
+ *       | run()
+ *       v
+ *   [Running] <------------------------.
+ *       |                              |
+ *       | (queue drained)              | push() while Idle
+ *       v                              |
+ *     [Idle] -------------------------'
+ *       |
+ *       | destroy()
+ *       v
+ *   [Destroyed]
+ *
+ * - Initial state is Buffering: queue accepts requests via push(), but does not process them yet.
+ * - run() transitions from Buffering -> Running, starting request processing.
+ * - When all queued requests have been processed, transitions to Idle.
+ * - If a new request arrives while Idle, transitions back to Running.
+ * - destroy() can be called from any state, transitioning to Destroyed.
+ * - Once in Destroyed, no further operations are allowed; push() will throw.
+ */
+const enum QueueStatus {
+  Buffering,
+  Idle,
+  Running,
+  Destroyed,
+}
+
+type TimerID = ReturnType<typeof setTimeout>;
+
+export class ThrottledQueue {
+  requests: Request[] = [];
+  requestCount: number = 0;
+  waitTimer?: TimerID;
+  status = QueueStatus.Buffering;
+  windowStart: number = 0;
+
+  constructor(
+    private windowDuration: number,
+    private threshold: number,
+    private onError: OnErrorCallback
+  ) {}
+
+  push(request: Request) {
+    if (this.status === QueueStatus.Destroyed) {
+      throw new Error(`push to a destroyed queue`);
+    }
+
+    this.requests.push(request);
+    if (this.status === QueueStatus.Idle) {
+      this.awake();
+    }
+  }
+
+  run() {
+    if (this.status !== QueueStatus.Buffering) {
+      return;
+    }
+    console.debug('Throttled queue processing started');
+    this.awake();
+  }
+
+  destroy() {
+    if (this.waitTimer !== undefined) {
+      clearTimeout(this.waitTimer);
+    }
+    console.debug('Throttled queue destroyed');
+    this.status = QueueStatus.Destroyed;
+  }
+
+  private awake() {
+    this.status = QueueStatus.Running;
+    this.processNext();
+  }
+
+  private processNext() {
+    if (this.status === QueueStatus.Destroyed) {
+      return;
+    }
+
+    const now = Date.now();
+    if (now - this.windowStart > this.windowDuration) {
+      this.windowStart = now;
+      this.requestCount = 0;
+    }
+
+    const next = this.requests.shift();
+    if (next === undefined) {
+      this.status = QueueStatus.Idle;
+      return;
+    }
+
+    this.runRequest(next);
+    this.requestCount++;
+    if (this.requestCount === this.threshold) {
+      this.waitNextWindow();
+      return;
+    }
+
+    // Giving external code a chance to call `push` or `destroy`
+    setTimeout(() => this.processNext(), 0);
+  }
+
+  private runRequest(request: Request) {
+    try {
+      request.run();
+    } catch (error) {
+      this.onError(error, request);
+    }
+  }
+
+  private waitNextWindow() {
+    console.warn('Throttling activated');
+    const wait = Math.max(
+      0,
+      this.windowStart + this.windowDuration - Date.now() + windowSafetyPadding
+    );
+    this.waitTimer = setTimeout(() => {
+      console.debug('Throttling deactivated');
+      this.processNext();
+    }, wait);
+  }
+}

package/src/lib/token-manager.ts

@@ -0,0 +1,75 @@
+export class TokenManager {
+  private currentBuzzToken: string | null = null;
+  private currentIdToken: string | null | undefined = null;
+  private isExchanging = false;
+  private pendingPromise: Promise<void> | null = null;
+  private listeners = new Set<(token: string | null) => void>();
+
+  constructor(
+    private readonly siteId: string,
+    private readonly identityBaseUrl: string
+  ) {}
+
+  private notify(token: string | null): void {
+    this.listeners.forEach((l) => l(token));
+  }
+
+  private async exchange(): Promise<void> {
+    if (this.isExchanging) return this.pendingPromise ?? Promise.resolve();
+    this.isExchanging = true;
+    this.pendingPromise = (async () => {
+      try {
+        if (this.currentIdToken) {
+          const data = await this.exchangeAuthenticated(this.currentIdToken);
+          this.currentBuzzToken = data.access_token ?? null;
+        } else {
+          const data = await this.getAnonymous();
+          const authToken = data.access_token;
+          const exchanged = await this.exchangeAuthenticated(authToken);
+          this.currentBuzzToken = exchanged.access_token ?? null;
+        }
+      } finally {
+        this.isExchanging = false;
+        this.pendingPromise = null;
+        this.notify(this.currentBuzzToken);
+      }
+    })();
+    return this.pendingPromise;
+  }
+
+  private async exchangeAuthenticated(
+    idToken: string
+  ): Promise<{ access_token: string }> {
+    const url = `${
+      this.identityBaseUrl
+    }/exchange-token?siteId=${encodeURIComponent(
+      this.siteId
+    )}&accessToken=${encodeURIComponent(idToken)}`;
+    const res = await fetch(url, { method: "POST", credentials: "omit" });
+    if (!res.ok) throw new Error(`exchangeAuthenticated failed: ${res.status}`);
+    return (await res.json()) as { access_token: string };
+  }
+
+  private async getAnonymous(): Promise<{ access_token: string }> {
+    const url = `${this.identityBaseUrl}/anonymous-token`;
+    const res = await fetch(url, { method: "POST", credentials: "omit" });
+    if (!res.ok) throw new Error(`getAnonymous failed: ${res.status}`);
+    return (await res.json()) as { access_token: string };
+  }
+
+  public async getBuzzToken(): Promise<string> {
+    if (!this.currentBuzzToken) await this.exchange();
+    if (!this.currentBuzzToken) throw new Error("Failed to acquire buzz token");
+    return this.currentBuzzToken;
+  }
+
+  public async setIdToken(idToken?: string | null): Promise<void> {
+    this.currentIdToken = idToken ?? null;
+    await this.exchange();
+  }
+
+  public onTokenChange(cb: (token: string | null) => void): () => void {
+    this.listeners.add(cb);
+    return () => this.listeners.delete(cb);
+  }
+}

package/src/lib/topic.ts

@@ -0,0 +1,74 @@
+import { type BuzzClient, type CommandContent } from "./index";
+
+export type EmitResult<T> = {
+  requestId: string;
+  type: string;
+  responseType: "ok" | "ack" | "error" | "rejected";
+} & T;
+
+export class Topic {
+  private subscriptionPromise: Promise<void>;
+  private listenerWrappers: Record<
+    string,
+    Map<Function, (event: unknown) => void>
+  > = {};
+
+  constructor(private client: BuzzClient, private topic: string) {
+    this.subscriptionPromise = this.client.subscribe(this.topic);
+  }
+
+  public async emit<T>(eventName: string, content?: CommandContent) {
+    try {
+      await this.subscriptionPromise;
+      const result = await this.client.sendCommand(
+        eventName,
+        this.topic,
+        content
+      );
+      return result as unknown as EmitResult<T>;
+    } catch (error) {
+      throw error;
+    }
+  }
+
+  public async on<T>(eventName: string, callback: (event: T) => void) {
+    await this.subscriptionPromise;
+    const wrapper = (event: unknown) => {
+      callback(event as T);
+    };
+
+    if (!this.listenerWrappers[eventName]) {
+      this.listenerWrappers[eventName] = new Map();
+    }
+    this.listenerWrappers[eventName].set(
+      callback as unknown as Function,
+      wrapper
+    );
+
+    this.client.onEvent(this.topic, eventName, wrapper);
+  }
+
+  public async off<T>(eventName: string, callback?: (event: T) => void) {
+    await this.subscriptionPromise;
+
+    const wrapperMap = this.listenerWrappers[eventName];
+    if (!wrapperMap) return;
+
+    if (callback) {
+      const wrapper = wrapperMap.get(callback as unknown as Function);
+      if (wrapper) {
+        this.client.offEvent(this.topic, eventName, wrapper as any);
+        wrapperMap.delete(callback as unknown as Function);
+      }
+      if (wrapperMap.size === 0) {
+        delete this.listenerWrappers[eventName];
+      }
+      return;
+    }
+
+    for (const wrapper of wrapperMap.values()) {
+      this.client.offEvent(this.topic, eventName, wrapper as any);
+    }
+    delete this.listenerWrappers[eventName];
+  }
+}