ue-softphone-sdk 2.2.2 → 2.2.4

package/src/api/subscription.ts

@@ -0,0 +1,161 @@
+import { Logger, Subscription as SubscriptionDialog } from "../core";
+import { Emitter, EmitterImpl } from "./emitter";
+import { SubscriptionDelegate } from "./subscription-delegate";
+import { SubscriptionOptions } from "./subscription-options";
+import { SubscriptionState } from "./subscription-state";
+import { SubscriptionSubscribeOptions } from "./subscription-subscribe-options";
+import { SubscriptionUnsubscribeOptions } from "./subscription-unsubscribe-options";
+import { UserAgent } from "./user-agent";
+
+/**
+ * A subscription provides {@link Notification} of events.
+ *
+ * @remarks
+ * See {@link Subscriber} for details on establishing a subscription.
+ *
+ * @public
+ */
+export abstract class Subscription {
+  /**
+   * Property reserved for use by instance owner.
+   * @defaultValue `undefined`
+   */
+  public data: unknown;
+
+  /**
+   * Subscription delegate. See {@link SubscriptionDelegate} for details.
+   * @defaultValue `undefined`
+   */
+  public delegate: SubscriptionDelegate | undefined;
+
+  /**
+   * If the subscription state is SubscriptionState.Subscribed, the associated subscription dialog. Otherwise undefined.
+   * @internal
+   */
+  protected _dialog: SubscriptionDialog | undefined;
+
+  /**
+   * Our user agent.
+   * @internal
+   */
+  protected _userAgent: UserAgent;
+
+  private _disposed = false;
+  private _logger: Logger;
+  private _state: SubscriptionState = SubscriptionState.Initial;
+  private _stateEventEmitter: EmitterImpl<SubscriptionState>;
+
+  /**
+   * Constructor.
+   * @param userAgent - User agent. See {@link UserAgent} for details.
+   * @internal
+   */
+  protected constructor(userAgent: UserAgent, options: SubscriptionOptions = {}) {
+    this._logger = userAgent.getLogger("sip.Subscription");
+    this._stateEventEmitter = new EmitterImpl<SubscriptionState>();
+    this._userAgent = userAgent;
+    this.delegate = options.delegate;
+  }
+
+  /**
+   * Destructor.
+   */
+  public dispose(): Promise<void> {
+    if (this._disposed) {
+      return Promise.resolve();
+    }
+    this._disposed = true;
+    this._stateEventEmitter.removeAllListeners();
+    return Promise.resolve();
+  }
+
+  /**
+   * The subscribed subscription dialog.
+   */
+  public get dialog(): SubscriptionDialog | undefined {
+    return this._dialog;
+  }
+
+  /**
+   * True if disposed.
+   * @internal
+   */
+  public get disposed(): boolean {
+    return this._disposed;
+  }
+
+  /**
+   * Subscription state. See {@link SubscriptionState} for details.
+   */
+  public get state(): SubscriptionState {
+    return this._state;
+  }
+
+  /**
+   * Emits when the subscription `state` property changes.
+   */
+  public get stateChange(): Emitter<SubscriptionState> {
+    return this._stateEventEmitter;
+  }
+
+  /** @internal */
+  protected stateTransition(newState: SubscriptionState): void {
+    const invalidTransition = (): void => {
+      throw new Error(`Invalid state transition from ${this._state} to ${newState}`);
+    };
+
+    // Validate transition
+    switch (this._state) {
+      case SubscriptionState.Initial:
+        if (newState !== SubscriptionState.NotifyWait && newState !== SubscriptionState.Terminated) {
+          invalidTransition();
+        }
+        break;
+      case SubscriptionState.NotifyWait:
+        if (newState !== SubscriptionState.Subscribed && newState !== SubscriptionState.Terminated) {
+          invalidTransition();
+        }
+        break;
+      case SubscriptionState.Subscribed:
+        if (newState !== SubscriptionState.Terminated) {
+          invalidTransition();
+        }
+        break;
+      case SubscriptionState.Terminated:
+        invalidTransition();
+        break;
+      default:
+        throw new Error("Unrecognized state.");
+    }
+
+    // Guard against duplicate transition
+    if (this._state === newState) {
+      return;
+    }
+
+    // Transition
+    this._state = newState;
+    this._logger.log(`Subscription ${this._dialog ? this._dialog.id : undefined} transitioned to ${this._state}`);
+    this._stateEventEmitter.emit(this._state);
+
+    // Dispose
+    if (newState === SubscriptionState.Terminated) {
+      this.dispose();
+    }
+  }
+
+  /**
+   * Sends a re-SUBSCRIBE request if the subscription is "active".
+   */
+  public abstract subscribe(options?: SubscriptionSubscribeOptions): Promise<void>;
+
+  /**
+   * Unsubscribe from event notifications.
+   *
+   * @remarks
+   * If the subscription state is SubscriptionState.Subscribed, sends an in dialog SUBSCRIBE request
+   * with expires time of zero (an un-subscribe) and terminates the subscription.
+   * Otherwise a noop.
+   */
+  public abstract unsubscribe(options?: SubscriptionUnsubscribeOptions): Promise<void>;
+}

package/src/api/transport-state.ts

@@ -0,0 +1,37 @@
+/**
+ * {@link Transport} state.
+ *
+ * @remarks
+ * The {@link Transport} behaves in a deterministic manner according to the following
+ * Finite State Machine (FSM).
+ * ```txt
+ *                    ______________________________
+ *                   |    ____________              |
+ * Transport         v   v            |             |
+ * Constructed -> Disconnected -> Connecting -> Connected -> Disconnecting
+ *                     ^            ^    |_____________________^  |  |
+ *                     |            |_____________________________|  |
+ *                     |_____________________________________________|
+ * ```
+ * @public
+ */
+export enum TransportState {
+  /**
+   * The `connect()` method was called.
+   */
+  Connecting = "Connecting",
+  /**
+   * The `connect()` method resolved.
+   */
+  Connected = "Connected",
+  /**
+   * The `disconnect()` method was called.
+   */
+  Disconnecting = "Disconnecting",
+  /**
+   * The `connect()` method was rejected, or
+   * the `disconnect()` method completed, or
+   * network connectivity was lost.
+   */
+  Disconnected = "Disconnected"
+}

package/src/api/transport.ts

@@ -0,0 +1,169 @@
+import { Transport as CoreTransport } from "../core";
+import { Emitter } from "./emitter";
+import { TransportState } from "./transport-state";
+
+/**
+ * Transport layer interface expected by the `UserAgent`.
+ *
+ * @remarks
+ * The transport behaves in a deterministic manner according to the
+ * the state defined in {@link TransportState}.
+ *
+ * The "Connecting" state is ONLY entered in response to the user calling `connect()`.
+ * The "Disconnecting" state is ONLY entered in response to the user calling `disconnect()`.
+ * The `onConnect` callback is ALWAYS called upon transitioning to the "Connected" state.
+ * The `onDisconnect` callback is ALWAYS called upon transitioning from the "Connected" state.
+ *
+ * Adherence to the state machine by the transport implementation is critical as the
+ * UserAgent depends on this behavior. Furthermore it is critical that the transport
+ * transition to the "Disconnected" state in all instances where network connectivity
+ * is lost as the UserAgent, API, and application layer more generally depend on knowing
+ * network was lost. For example, from a practical standpoint registrations and subscriptions are invalidated
+ * when network is lost - particularly in the case of connection oriented transport
+ * protocols such as a secure WebSocket transport.
+ *
+ * Proper handling the application level protocol recovery must be left to the application layer,
+ * thus the transport MUST NOT attempt to "auto-recover" from or otherwise hide loss of network.
+ * Note that callbacks and emitters such as `onConnect`  and `onDisconnect` MUST NOT call methods
+ * `connect()` and `direct()` synchronously (state change handlers must not loop back). They may
+ * however do so asynchronously using a Promise resolution, `setTimeout`, or some other method.
+ * For example...
+ * ```ts
+ * transport.onDisconnect = () => {
+ *   Promise.resolve().then(() => transport.connect());
+ * }
+ * ```
+ * @public
+ */
+export interface Transport extends CoreTransport {
+  /**
+   * Transport state.
+   *
+   * @remarks
+   * The initial Transport state MUST be "disconnected" (after calling constructor).
+   */
+  readonly state: TransportState;
+
+  /**
+   * Transport state change emitter.
+   */
+  readonly stateChange: Emitter<TransportState>;
+
+  /**
+   * Callback on state transition to "Connected".
+   *
+   * @remarks
+   * When the `UserAgent` is constructed, this property is set.
+   * ```txt
+   * - The `state` MUST be "Connected" when called.
+   * ```
+   */
+  onConnect: (() => void) | undefined;
+
+  /**
+   * Callback on state transition from "Connected".
+   *
+   * @remarks
+   * When the `UserAgent` is constructed, this property is set.
+   * ```txt
+   * - The `state` MUST NOT "Connected" when called.
+   * - If prior `state` is "Connecting" or "Connected", `error` MUST be defined.
+   * - If prior `state` is "Disconnecting", `error` MUST NOT be undefined.
+   * ```
+   * If the transition from "Connected" occurs because the transport
+   * user requested it by calling `disconnect`, then `error` will be undefined.
+   * Otherwise `error` will be defined to provide an indication that the
+   * transport initiated the transition from "Connected" - for example,
+   * perhaps network connectivity was lost.
+   */
+  onDisconnect: ((error?: Error) => void) | undefined;
+
+  /**
+   * Callback on receipt of a message.
+   *
+   * @remarks
+   * When the `UserAgent` is constructed, this property is set.
+   * The `state` MUST be "Connected" when this is called.
+   */
+  onMessage: ((message: string) => void) | undefined;
+
+  /**
+   * Connect to network.
+   *
+   * @remarks
+   * ```txt
+   * - If `state` is "Connecting", `state` MUST NOT transition before returning.
+   * - If `state` is "Connected", `state` MUST NOT transition before returning.
+   * - If `state` is "Disconnecting", `state` MUST transition to "Connecting" before returning.
+   * - If `state` is "Disconnected" `state` MUST transition to "Connecting" before returning.
+   * - The `state` MUST transition to "Connected" before resolving (assuming `state` is not already "Connected").
+   * - The `state` MUST transition to "Disconnecting" or "Disconnected" before rejecting and MUST reject with an Error.
+   * ```
+   * Resolves when the transport connects. Rejects if transport fails to connect.
+   * Rejects with {@link StateTransitionError} if a loop is detected.
+   * In particular, callbacks and emitters MUST NOT call this method synchronously.
+   */
+  connect(): Promise<void>;
+
+  /**
+   * Disconnect from network.
+   *
+   * @remarks
+   * ```txt
+   * - If `state` is "Connecting", `state` MUST transition to "Disconnecting" before returning.
+   * - If `state` is "Connected", `state` MUST transition to "Disconnecting" before returning.
+   * - If `state` is "Disconnecting", `state` MUST NOT transition before returning.
+   * - If `state` is "Disconnected", `state` MUST NOT transition before returning.
+   * - The `state` MUST transition to "Disconnected" before resolving (assuming `state` is not already "Disconnected").
+   * - The `state` MUST transition to "Connecting" or "Connected" before rejecting and MUST reject with an Error.
+   * ```
+   * Resolves when the transport disconnects. Rejects if transport fails to disconnect.
+   * Rejects with {@link StateTransitionError} if a loop is detected.
+   * In particular, callbacks and emitters MUST NOT call this method synchronously.
+   */
+  disconnect(): Promise<void>;
+
+  /**
+   * Dispose.
+   *
+   * @remarks
+   * When the `UserAgent` is disposed or stopped, this method is called.
+   * The `UserAgent` MUST NOT continue to utilize the instance after calling this method.
+   */
+  dispose(): Promise<void>;
+
+  /**
+   * Returns true if the `state` equals "Connected".
+   *
+   * @remarks
+   * This is equivalent to `state === TransportState.Connected`.
+   * It is convenient. A common paradigm is, for example...
+   *
+   * @example
+   * ```ts
+   * // Monitor transport connectivity
+   * userAgent.transport.stateChange.addListener(() => {
+   *   if (userAgent.transport.isConnected()) {
+   *     // handle transport connect
+   *   } else {
+   *     // handle transport disconnect
+   *   }
+   * });
+   * ```
+   */
+  isConnected(): boolean;
+
+  /**
+   * Send a message.
+   *
+   * @remarks
+   * ```txt
+   * - If `state` is "Connecting", rejects with an Error.
+   * - If `state` is "Connected", resolves when the message is sent otherwise rejects with an Error.
+   * - If `state` is "Disconnecting", rejects with an Error.
+   * - If `state` is "Disconnected", rejects with an Error.
+   * ```
+   * @param message - Message to send.
+   */
+  send(message: string): Promise<void>;
+}

package/src/api/user-agent-delegate.ts

@@ -0,0 +1,95 @@
+import { IncomingReferRequest, IncomingRegisterRequest, IncomingSubscribeRequest } from "../core";
+import { Invitation } from "./invitation";
+import { Message } from "./message";
+import { Notification } from "./notification";
+import { Referral } from "./referral";
+import { Subscription } from "./subscription";
+
+/**
+ * Delegate for {@link UserAgent}.
+ * @public
+ */
+export interface UserAgentDelegate {
+  /**
+   * Called upon transport transitioning to connected state.
+   */
+  onConnect?(): void;
+
+  /**
+   * Called upon transport transitioning from connected state.
+   * @param error - An error if disconnect triggered by transport. Otherwise undefined.
+   */
+  onDisconnect?(error?: Error): void;
+
+  /**
+   * Called upon receipt of an invitation.
+   * @remarks
+   * Handler for incoming out of dialog INVITE requests.
+   * @param invitation - The invitation.
+   */
+  onInvite?(invitation: Invitation): void;
+
+  /**
+   * Called upon receipt of a message.
+   * @remarks
+   * Handler for incoming out of dialog MESSAGE requests.
+   * @param message - The message.
+   */
+  onMessage?(message: Message): void;
+
+  /**
+   * Called upon receipt of a notification.
+   * @remarks
+   * Handler for incoming out of dialog NOTIFY requests.
+   * @param notification - The notification.
+   */
+  onNotify?(notification: Notification): void;
+
+  /**
+   * @alpha
+   * Called upon receipt of a referral.
+   * @remarks
+   * Handler for incoming out of dialog REFER requests.
+   * @param referral - The referral.
+   */
+  onRefer?(referral: Referral): void;
+
+  /**
+   * @alpha
+   * Called upon receipt of a registration.
+   * @remarks
+   * Handler for incoming out of dialog REGISTER requests.
+   * @param registration - The registration.
+   */
+  onRegister?(registration: unknown /* TODO: Registration */): void;
+
+  /**
+   * @alpha
+   * Called upon receipt of a subscription.
+   * @remarks
+   * Handler for incoming out of dialog SUBSCRIBE requests.
+   * @param subscription - The subscription.
+   */
+  onSubscribe?(subscription: Subscription): void;
+
+  /**
+   * @internal
+   * Called upon receipt of an out of dialog REFER. Used by test suite.
+   * @param request - The request.
+   */
+  onReferRequest?(request: IncomingReferRequest): void;
+
+  /**
+   * @internal
+   * Called upon receipt of a REGISTER request. Used by test suite.
+   * @param request - The request.
+   */
+  onRegisterRequest?(request: IncomingRegisterRequest): void;
+
+  /**
+   * @internal
+   * Called upon receipt of an out of dialog SUBSCRIBE request. Used by test suite.
+   * @param request - The request.
+   */
+  onSubscribeRequest?(request: IncomingSubscribeRequest): void;
+}