ue-softphone-sdk 2.1.9 → 2.2.0

package/src/core/user-agents/user-agent-client.ts

@@ -1,378 +0,0 @@
-import { Dialog } from "../dialogs";
-import { TransportError } from "../exceptions";
-import { Logger, LoggerFactory } from "../log";
-import {
-  C,
-  IncomingResponseMessage,
-  OutgoingRequest,
-  OutgoingRequestDelegate,
-  OutgoingRequestMessage,
-  RequestOptions
-} from "../messages";
-import {
-  ClientTransaction,
-  ClientTransactionUser,
-  NonInviteClientTransaction,
-  TransactionState
-} from "../transactions";
-import { Transport } from "../transport";
-import { UserAgentCore } from "../user-agent-core";
-
-type ClientTransactionConstructor = new (
-  message: OutgoingRequestMessage,
-  transport: Transport,
-  user: ClientTransactionUser
-) => ClientTransaction;
-
-/**
- * User Agent Client (UAC).
- * @remarks
- * A user agent client is a logical entity
- * that creates a new request, and then uses the client
- * transaction state machinery to send it.  The role of UAC lasts
- * only for the duration of that transaction.  In other words, if
- * a piece of software initiates a request, it acts as a UAC for
- * the duration of that transaction.  If it receives a request
- * later, it assumes the role of a user agent server for the
- * processing of that transaction.
- * https://tools.ietf.org/html/rfc3261#section-6
- * @public
- */
-export class UserAgentClient implements OutgoingRequest {
-  protected logger: Logger;
-
-  private _transaction: ClientTransaction | undefined;
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private credentials: any;
-  private challenged = false;
-  private stale = false;
-
-  constructor(
-    private transactionConstructor: ClientTransactionConstructor,
-    protected core: UserAgentCore,
-    public message: OutgoingRequestMessage,
-    public delegate?: OutgoingRequestDelegate
-  ) {
-    this.logger = this.loggerFactory.getLogger("sip.user-agent-client");
-    this.init();
-  }
-
-  public dispose(): void {
-    this.transaction.dispose();
-  }
-
-  get loggerFactory(): LoggerFactory {
-    return this.core.loggerFactory;
-  }
-
-  /** The transaction associated with this request. */
-  get transaction(): ClientTransaction {
-    if (!this._transaction) {
-      throw new Error("Transaction undefined.");
-    }
-    return this._transaction;
-  }
-
-  /**
-   * Since requests other than INVITE are responded to immediately, sending a
-   * CANCEL for a non-INVITE request would always create a race condition.
-   * A CANCEL request SHOULD NOT be sent to cancel a request other than INVITE.
-   * https://tools.ietf.org/html/rfc3261#section-9.1
-   * @param options - Cancel options bucket.
-   */
-  public cancel(reason?: string, options: RequestOptions = {}): OutgoingRequestMessage {
-    if (!this.transaction) {
-      throw new Error("Transaction undefined.");
-    }
-    if (!this.message.to) {
-      throw new Error("To undefined.");
-    }
-    if (!this.message.from) {
-      throw new Error("From undefined.");
-    }
-
-    // The following procedures are used to construct a CANCEL request.  The
-    // Request-URI, Call-ID, To, the numeric part of CSeq, and From header
-    // fields in the CANCEL request MUST be identical to those in the
-    // request being cancelled, including tags.  A CANCEL constructed by a
-    // client MUST have only a single Via header field value matching the
-    // top Via value in the request being cancelled.  Using the same values
-    // for these header fields allows the CANCEL to be matched with the
-    // request it cancels (Section 9.2 indicates how such matching occurs).
-    // However, the method part of the CSeq header field MUST have a value
-    // of CANCEL.  This allows it to be identified and processed as a
-    // transaction in its own right (See Section 17).
-    // https://tools.ietf.org/html/rfc3261#section-9.1
-    const message = this.core.makeOutgoingRequestMessage(
-      C.CANCEL,
-      this.message.ruri,
-      this.message.from.uri,
-      this.message.to.uri,
-      {
-        toTag: this.message.toTag,
-        fromTag: this.message.fromTag,
-        callId: this.message.callId,
-        cseq: this.message.cseq
-      },
-      options.extraHeaders
-    );
-
-    // TODO: Revisit this.
-    // The CANCEL needs to use the same branch parameter so that
-    // it matches the INVITE transaction, but this is a hacky way to do this.
-    // Or at the very least not well documented. If the the branch parameter
-    // is set on the outgoing request, the transaction will use it.
-    // Otherwise the transaction will make a new one.
-    message.branch = this.message.branch;
-
-    if (this.message.headers.Route) {
-      message.headers.Route = this.message.headers.Route;
-    }
-
-    if (reason) {
-      message.setHeader("Reason", reason);
-    }
-
-    // If no provisional response has been received, the CANCEL request MUST
-    // NOT be sent; rather, the client MUST wait for the arrival of a
-    // provisional response before sending the request. If the original
-    // request has generated a final response, the CANCEL SHOULD NOT be
-    // sent, as it is an effective no-op, since CANCEL has no effect on
-    // requests that have already generated a final response.
-    // https://tools.ietf.org/html/rfc3261#section-9.1
-    if (this.transaction.state === TransactionState.Proceeding) {
-      new UserAgentClient(NonInviteClientTransaction, this.core, message);
-    } else {
-      this.transaction.addStateChangeListener(
-        () => {
-          if (this.transaction && this.transaction.state === TransactionState.Proceeding) {
-            new UserAgentClient(NonInviteClientTransaction, this.core, message);
-          }
-        },
-        { once: true }
-      );
-    }
-
-    return message;
-  }
-
-  /**
-   * If a 401 (Unauthorized) or 407 (Proxy Authentication Required)
-   * response is received, the UAC SHOULD follow the authorization
-   * procedures of Section 22.2 and Section 22.3 to retry the request with
-   * credentials.
-   * https://tools.ietf.org/html/rfc3261#section-8.1.3.5
-   * 22 Usage of HTTP Authentication
-   * https://tools.ietf.org/html/rfc3261#section-22
-   * 22.1 Framework
-   * https://tools.ietf.org/html/rfc3261#section-22.1
-   * 22.2 User-to-User Authentication
-   * https://tools.ietf.org/html/rfc3261#section-22.2
-   * 22.3 Proxy-to-User Authentication
-   * https://tools.ietf.org/html/rfc3261#section-22.3
-   *
-   * FIXME: This "guard for and retry the request with credentials"
-   * implementation is not complete and at best minimally passable.
-   * @param response - The incoming response to guard.
-   * @param dialog - If defined, the dialog within which the response was received.
-   * @returns True if the program execution is to continue in the branch in question.
-   *          Otherwise the request is retried with credentials and current request processing must stop.
-   */
-  protected authenticationGuard(message: IncomingResponseMessage, dialog?: Dialog): boolean {
-    const statusCode = message.statusCode;
-    if (!statusCode) {
-      throw new Error("Response status code undefined.");
-    }
-
-    // If a 401 (Unauthorized) or 407 (Proxy Authentication Required)
-    // response is received, the UAC SHOULD follow the authorization
-    // procedures of Section 22.2 and Section 22.3 to retry the request with
-    // credentials.
-    // https://tools.ietf.org/html/rfc3261#section-8.1.3.5
-    if (statusCode !== 401 && statusCode !== 407) {
-      return true;
-    }
-
-    // Get and parse the appropriate WWW-Authenticate or Proxy-Authenticate header.
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    let challenge: any;
-    let authorizationHeaderName: string;
-    if (statusCode === 401) {
-      challenge = message.parseHeader("www-authenticate");
-      authorizationHeaderName = "authorization";
-    } else {
-      challenge = message.parseHeader("proxy-authenticate");
-      authorizationHeaderName = "proxy-authorization";
-    }
-
-    // Verify it seems a valid challenge.
-    if (!challenge) {
-      this.logger.warn(statusCode + " with wrong or missing challenge, cannot authenticate");
-      return true;
-    }
-
-    // Avoid infinite authentications.
-    if (this.challenged && (this.stale || challenge.stale !== true)) {
-      this.logger.warn(statusCode + " apparently in authentication loop, cannot authenticate");
-      return true;
-    }
-
-    // Get credentials.
-    if (!this.credentials) {
-      this.credentials = this.core.configuration.authenticationFactory();
-      if (!this.credentials) {
-        this.logger.warn("Unable to obtain credentials, cannot authenticate");
-        return true;
-      }
-    }
-
-    // Verify that the challenge is really valid.
-    if (!this.credentials.authenticate(this.message, challenge)) {
-      return true;
-    }
-
-    this.challenged = true;
-    if (challenge.stale) {
-      this.stale = true;
-    }
-
-    // If response to out of dialog request, assume incrementing the CSeq will suffice.
-    let cseq = (this.message.cseq += 1);
-
-    // If response to in dialog request, get a valid next CSeq number.
-    if (dialog && dialog.localSequenceNumber) {
-      dialog.incrementLocalSequenceNumber();
-      cseq = this.message.cseq = dialog.localSequenceNumber;
-    }
-
-    this.message.setHeader("cseq", cseq + " " + this.message.method);
-    this.message.setHeader(authorizationHeaderName, this.credentials.toString());
-
-    // Calling init (again) will swap out our existing client transaction with a new one.
-    // FIXME: HACK: An assumption is being made here that there is nothing that needs to
-    // be cleaned up beyond the client transaction which is being replaced. For example,
-    // it is assumed that no early dialogs have been created.
-    this.init();
-
-    return false;
-  }
-
-  /**
-   * 8.1.3.1 Transaction Layer Errors
-   * In some cases, the response returned by the transaction layer will
-   * not be a SIP message, but rather a transaction layer error.  When a
-   * timeout error is received from the transaction layer, it MUST be
-   * treated as if a 408 (Request Timeout) status code has been received.
-   * If a fatal transport error is reported by the transport layer
-   * (generally, due to fatal ICMP errors in UDP or connection failures in
-   * TCP), the condition MUST be treated as a 503 (Service Unavailable)
-   * status code.
-   * https://tools.ietf.org/html/rfc3261#section-8.1.3.1
-   */
-  protected onRequestTimeout(): void {
-    this.logger.warn("User agent client request timed out. Generating internal 408 Request Timeout.");
-    const message = new IncomingResponseMessage();
-    message.statusCode = 408;
-    message.reasonPhrase = "Request Timeout";
-    this.receiveResponse(message);
-    return;
-  }
-
-  /**
-   * 8.1.3.1 Transaction Layer Errors
-   * In some cases, the response returned by the transaction layer will
-   * not be a SIP message, but rather a transaction layer error.  When a
-   * timeout error is received from the transaction layer, it MUST be
-   * treated as if a 408 (Request Timeout) status code has been received.
-   * If a fatal transport error is reported by the transport layer
-   * (generally, due to fatal ICMP errors in UDP or connection failures in
-   * TCP), the condition MUST be treated as a 503 (Service Unavailable)
-   * status code.
-   * https://tools.ietf.org/html/rfc3261#section-8.1.3.1
-   * @param error - Transport error
-   */
-  protected onTransportError(error: TransportError): void {
-    this.logger.error(error.message);
-    this.logger.error("User agent client request transport error. Generating internal 503 Service Unavailable.");
-    const message = new IncomingResponseMessage();
-    message.statusCode = 503;
-    message.reasonPhrase = "Service Unavailable";
-    this.receiveResponse(message);
-  }
-
-  /**
-   * Receive a response from the transaction layer.
-   * @param message - Incoming response message.
-   */
-  protected receiveResponse(message: IncomingResponseMessage): void {
-    if (!this.authenticationGuard(message)) {
-      return;
-    }
-
-    const statusCode = message.statusCode ? message.statusCode.toString() : "";
-    if (!statusCode) {
-      throw new Error("Response status code undefined.");
-    }
-
-    switch (true) {
-      case /^100$/.test(statusCode):
-        if (this.delegate && this.delegate.onTrying) {
-          this.delegate.onTrying({ message });
-        }
-        break;
-      case /^1[0-9]{2}$/.test(statusCode):
-        if (this.delegate && this.delegate.onProgress) {
-          this.delegate.onProgress({ message });
-        }
-        break;
-      case /^2[0-9]{2}$/.test(statusCode):
-        if (this.delegate && this.delegate.onAccept) {
-          this.delegate.onAccept({ message });
-        }
-        break;
-      case /^3[0-9]{2}$/.test(statusCode):
-        if (this.delegate && this.delegate.onRedirect) {
-          this.delegate.onRedirect({ message });
-        }
-        break;
-      case /^[4-6][0-9]{2}$/.test(statusCode):
-        if (this.delegate && this.delegate.onReject) {
-          this.delegate.onReject({ message });
-        }
-        break;
-      default:
-        throw new Error(`Invalid status code ${statusCode}`);
-    }
-  }
-
-  private init(): void {
-    // We are the transaction user.
-    const user: ClientTransactionUser = {
-      loggerFactory: this.loggerFactory,
-      onRequestTimeout: () => this.onRequestTimeout(),
-      onStateChange: (newState) => {
-        if (newState === TransactionState.Terminated) {
-          // Remove the terminated transaction from the core.
-          // eslint-disable-next-line @typescript-eslint/no-use-before-define
-          this.core.userAgentClients.delete(userAgentClientId);
-          // FIXME: HACK: Our transaction may have been swapped out with a new one
-          // post authentication (see above), so make sure to only to dispose of
-          // ourselves if this terminating transaction is our current transaction.
-          // eslint-disable-next-line @typescript-eslint/no-use-before-define
-          if (transaction === this._transaction) {
-            this.dispose();
-          }
-        }
-      },
-      onTransportError: (error) => this.onTransportError(error),
-      receiveResponse: (message) => this.receiveResponse(message)
-    };
-    // Create a new transaction with us as the user.
-    const transaction = new this.transactionConstructor(this.message, this.core.transport, user);
-    this._transaction = transaction;
-    // Add the new transaction to the core.
-    const userAgentClientId = transaction.id + transaction.request.method;
-    this.core.userAgentClients.set(userAgentClientId, this);
-  }
-}

package/src/core/user-agents/user-agent-server.ts

@@ -1,276 +0,0 @@
-import { TransactionStateError } from "../exceptions";
-import { Logger, LoggerFactory } from "../log";
-import {
-  constructOutgoingResponse,
-  IncomingRequest,
-  IncomingRequestDelegate,
-  IncomingRequestMessage,
-  OutgoingResponse,
-  ResponseOptions,
-  URI
-} from "../messages";
-import { newTag } from "../messages/utils";
-
-import {
-  InviteServerTransaction,
-  NonInviteServerTransaction,
-  ServerTransaction,
-  ServerTransactionUser,
-  TransactionState
-} from "../transactions";
-import { Transport } from "../transport";
-import { UserAgentCore } from "../user-agent-core";
-
-type ServerTransactionConstructor = new (
-  message: IncomingRequestMessage,
-  transport: Transport,
-  user: ServerTransactionUser
-) => ServerTransaction;
-
-/**
- * User Agent Server (UAS).
- * @remarks
- * A user agent server is a logical entity
- * that generates a response to a SIP request.  The response
- * accepts, rejects, or redirects the request.  This role lasts
- * only for the duration of that transaction.  In other words, if
- * a piece of software responds to a request, it acts as a UAS for
- * the duration of that transaction.  If it generates a request
- * later, it assumes the role of a user agent client for the
- * processing of that transaction.
- * https://tools.ietf.org/html/rfc3261#section-6
- * @public
- */
-export class UserAgentServer implements IncomingRequest {
-  protected logger: Logger;
-  protected toTag: string;
-
-  private _transaction: ServerTransaction | undefined;
-
-  constructor(
-    private transactionConstructor: ServerTransactionConstructor,
-    protected core: UserAgentCore,
-    public message: IncomingRequestMessage,
-    public delegate?: IncomingRequestDelegate
-  ) {
-    this.logger = this.loggerFactory.getLogger("sip.user-agent-server");
-    this.toTag = message.toTag ? message.toTag : newTag();
-    this.init();
-  }
-
-  public dispose(): void {
-    this.transaction.dispose();
-  }
-
-  get loggerFactory(): LoggerFactory {
-    return this.core.loggerFactory;
-  }
-
-  /** The transaction associated with this request. */
-  get transaction(): ServerTransaction {
-    if (!this._transaction) {
-      throw new Error("Transaction undefined.");
-    }
-    return this._transaction;
-  }
-
-  public accept(options: ResponseOptions = { statusCode: 200 }): OutgoingResponse {
-    if (!this.acceptable) {
-      throw new TransactionStateError(`${this.message.method} not acceptable in state ${this.transaction.state}.`);
-    }
-    const statusCode = options.statusCode;
-    if (statusCode < 200 || statusCode > 299) {
-      throw new TypeError(`Invalid statusCode: ${statusCode}`);
-    }
-    const response = this.reply(options);
-    return response;
-  }
-
-  public progress(options: ResponseOptions = { statusCode: 180 }): OutgoingResponse {
-    if (!this.progressable) {
-      throw new TransactionStateError(`${this.message.method} not progressable in state ${this.transaction.state}.`);
-    }
-    const statusCode = options.statusCode;
-    if (statusCode < 101 || statusCode > 199) {
-      throw new TypeError(`Invalid statusCode: ${statusCode}`);
-    }
-    const response = this.reply(options);
-    return response;
-  }
-
-  public redirect(contacts: Array<URI>, options: ResponseOptions = { statusCode: 302 }): OutgoingResponse {
-    if (!this.redirectable) {
-      throw new TransactionStateError(`${this.message.method} not redirectable in state ${this.transaction.state}.`);
-    }
-    const statusCode = options.statusCode;
-    if (statusCode < 300 || statusCode > 399) {
-      throw new TypeError(`Invalid statusCode: ${statusCode}`);
-    }
-    const contactHeaders = new Array<string>();
-    contacts.forEach((contact) => contactHeaders.push(`Contact: ${contact.toString()}`));
-    options.extraHeaders = (options.extraHeaders || []).concat(contactHeaders);
-    const response = this.reply(options);
-    return response;
-  }
-
-  public reject(options: ResponseOptions = { statusCode: 480 }): OutgoingResponse {
-    if (!this.rejectable) {
-      throw new TransactionStateError(`${this.message.method} not rejectable in state ${this.transaction.state}.`);
-    }
-    const statusCode = options.statusCode;
-    if (statusCode < 400 || statusCode > 699) {
-      throw new TypeError(`Invalid statusCode: ${statusCode}`);
-    }
-    const response = this.reply(options);
-    return response;
-  }
-
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  public trying(options?: ResponseOptions): OutgoingResponse {
-    if (!this.tryingable) {
-      throw new TransactionStateError(`${this.message.method} not tryingable in state ${this.transaction.state}.`);
-    }
-    const response = this.reply({ statusCode: 100 });
-    return response;
-  }
-
-  /**
-   * If the UAS did not find a matching transaction for the CANCEL
-   * according to the procedure above, it SHOULD respond to the CANCEL
-   * with a 481 (Call Leg/Transaction Does Not Exist).  If the transaction
-   * for the original request still exists, the behavior of the UAS on
-   * receiving a CANCEL request depends on whether it has already sent a
-   * final response for the original request.  If it has, the CANCEL
-   * request has no effect on the processing of the original request, no
-   * effect on any session state, and no effect on the responses generated
-   * for the original request.  If the UAS has not issued a final response
-   * for the original request, its behavior depends on the method of the
-   * original request.  If the original request was an INVITE, the UAS
-   * SHOULD immediately respond to the INVITE with a 487 (Request
-   * Terminated).  A CANCEL request has no impact on the processing of
-   * transactions with any other method defined in this specification.
-   * https://tools.ietf.org/html/rfc3261#section-9.2
-   * @param request - Incoming CANCEL request.
-   */
-  public receiveCancel(message: IncomingRequestMessage): void {
-    // Note: Currently CANCEL is being handled as a special case.
-    // No UAS is created to handle the CANCEL and the response to
-    // it CANCEL is being handled statelessly by the user agent core.
-    // As such, there is currently no way to externally impact the
-    // response to the a CANCEL request.
-    if (this.delegate && this.delegate.onCancel) {
-      this.delegate.onCancel(message);
-    }
-  }
-
-  protected get acceptable(): boolean {
-    if (this.transaction instanceof InviteServerTransaction) {
-      return (
-        this.transaction.state === TransactionState.Proceeding || this.transaction.state === TransactionState.Accepted
-      );
-    }
-    if (this.transaction instanceof NonInviteServerTransaction) {
-      return (
-        this.transaction.state === TransactionState.Trying || this.transaction.state === TransactionState.Proceeding
-      );
-    }
-    throw new Error("Unknown transaction type.");
-  }
-
-  protected get progressable(): boolean {
-    if (this.transaction instanceof InviteServerTransaction) {
-      return this.transaction.state === TransactionState.Proceeding;
-    }
-    if (this.transaction instanceof NonInviteServerTransaction) {
-      return false; // https://tools.ietf.org/html/rfc4320#section-4.1
-    }
-    throw new Error("Unknown transaction type.");
-  }
-
-  protected get redirectable(): boolean {
-    if (this.transaction instanceof InviteServerTransaction) {
-      return this.transaction.state === TransactionState.Proceeding;
-    }
-    if (this.transaction instanceof NonInviteServerTransaction) {
-      return (
-        this.transaction.state === TransactionState.Trying || this.transaction.state === TransactionState.Proceeding
-      );
-    }
-    throw new Error("Unknown transaction type.");
-  }
-
-  protected get rejectable(): boolean {
-    if (this.transaction instanceof InviteServerTransaction) {
-      return this.transaction.state === TransactionState.Proceeding;
-    }
-    if (this.transaction instanceof NonInviteServerTransaction) {
-      return (
-        this.transaction.state === TransactionState.Trying || this.transaction.state === TransactionState.Proceeding
-      );
-    }
-    throw new Error("Unknown transaction type.");
-  }
-
-  protected get tryingable(): boolean {
-    if (this.transaction instanceof InviteServerTransaction) {
-      return this.transaction.state === TransactionState.Proceeding;
-    }
-    if (this.transaction instanceof NonInviteServerTransaction) {
-      return this.transaction.state === TransactionState.Trying;
-    }
-    throw new Error("Unknown transaction type.");
-  }
-
-  /**
-   * When a UAS wishes to construct a response to a request, it follows
-   * the general procedures detailed in the following subsections.
-   * Additional behaviors specific to the response code in question, which
-   * are not detailed in this section, may also be required.
-   *
-   * Once all procedures associated with the creation of a response have
-   * been completed, the UAS hands the response back to the server
-   * transaction from which it received the request.
-   * https://tools.ietf.org/html/rfc3261#section-8.2.6
-   * @param statusCode - Status code to reply with.
-   * @param options - Reply options bucket.
-   */
-  private reply(options: ResponseOptions): OutgoingResponse {
-    if (!options.toTag && options.statusCode !== 100) {
-      options.toTag = this.toTag;
-    }
-    options.userAgent = options.userAgent || this.core.configuration.userAgentHeaderFieldValue;
-    options.supported = options.supported || this.core.configuration.supportedOptionTagsResponse;
-    const response = constructOutgoingResponse(this.message, options);
-    this.transaction.receiveResponse(options.statusCode, response.message);
-    return response;
-  }
-
-  private init(): void {
-    // We are the transaction user.
-    const user: ServerTransactionUser = {
-      loggerFactory: this.loggerFactory,
-      onStateChange: (newState) => {
-        if (newState === TransactionState.Terminated) {
-          // Remove the terminated transaction from the core.
-          // eslint-disable-next-line @typescript-eslint/no-use-before-define
-          this.core.userAgentServers.delete(userAgentServerId);
-          this.dispose();
-        }
-      },
-      onTransportError: (error) => {
-        this.logger.error(error.message);
-        if (this.delegate && this.delegate.onTransportError) {
-          this.delegate.onTransportError(error);
-        } else {
-          this.logger.error("User agent server response transport error.");
-        }
-      }
-    };
-    // Create a new transaction with us as the user.
-    const transaction = new this.transactionConstructor(this.message, this.core.transport, user);
-    this._transaction = transaction;
-    // Add the new transaction to the core.
-    const userAgentServerId = transaction.id;
-    this.core.userAgentServers.set(transaction.id, this);
-  }
-}