sip.js

import { Transport as CoreTransport } from "../core/transport.js"; import { Emitter } from "./emitter.js"; import { TransportState } from "./transport-state.js"; /** * 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>; }