ue-softphone-sdk 2.2.3 → 2.2.5

package/src/core/messages/outgoing-response.ts

@@ -0,0 +1,174 @@
+import { Body } from "./body";
+import { IncomingRequestMessage } from "./incoming-request-message";
+import { getReasonPhrase, newTag, utf8Length } from "./utils";
+
+/**
+ * A SIP message sent from a local server to a remote client.
+ * @remarks
+ * For indicating the status of a request sent from the client to the server.
+ * https://tools.ietf.org/html/rfc3261#section-7.2
+ * @public
+ */
+export interface OutgoingResponse {
+  /** The outgoing message. */
+  readonly message: string;
+}
+
+/**
+ * Response options bucket.
+ * @public
+ */
+export interface ResponseOptions {
+  /** Status code of the response. */
+  statusCode: number;
+  /** Reason phrase of the response. */
+  reasonPhrase?: string;
+  /** To tag of the response. If not provided, one is generated. */
+  toTag?: string;
+  /** User agent string for User-Agent header. */
+  userAgent?: string;
+  /** Support options tags for Supported header. */
+  supported?: Array<string>;
+  /** Extra headers to include in the message. */
+  extraHeaders?: Array<string>;
+  /** Body to include in the message. */
+  body?: Body;
+}
+
+/**
+ * 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.
+ * https://tools.ietf.org/html/rfc3261#section-8.2.6
+ * @internal
+ */
+export function constructOutgoingResponse(message: IncomingRequestMessage, options: ResponseOptions): OutgoingResponse {
+  const CRLF = "\r\n";
+
+  if (options.statusCode < 100 || options.statusCode > 699) {
+    throw new TypeError("Invalid statusCode: " + options.statusCode);
+  }
+  const reasonPhrase = options.reasonPhrase ? options.reasonPhrase : getReasonPhrase(options.statusCode);
+
+  // SIP responses are distinguished from requests by having a Status-Line
+  // as their start-line.  A Status-Line consists of the protocol version
+  // followed by a numeric Status-Code and its associated textual phrase,
+  // with each element separated by a single SP character.
+  // https://tools.ietf.org/html/rfc3261#section-7.2
+  let response = "SIP/2.0 " + options.statusCode + " " + reasonPhrase + CRLF;
+
+  // One largely non-method-specific guideline for the generation of
+  // responses is that UASs SHOULD NOT issue a provisional response for a
+  // non-INVITE request.  Rather, UASs SHOULD generate a final response to
+  // a non-INVITE request as soon as possible.
+  // https://tools.ietf.org/html/rfc3261#section-8.2.6.1
+  if (options.statusCode >= 100 && options.statusCode < 200) {
+    // TODO
+  }
+
+  // When a 100 (Trying) response is generated, any Timestamp header field
+  // present in the request MUST be copied into this 100 (Trying)
+  // response.  If there is a delay in generating the response, the UAS
+  // SHOULD add a delay value into the Timestamp value in the response.
+  // This value MUST contain the difference between the time of sending of
+  // the response and receipt of the request, measured in seconds.
+  // https://tools.ietf.org/html/rfc3261#section-8.2.6.1
+  if (options.statusCode === 100) {
+    // TODO
+  }
+
+  // The From field of the response MUST equal the From header field of
+  // the request.  The Call-ID header field of the response MUST equal the
+  // Call-ID header field of the request.  The CSeq header field of the
+  // response MUST equal the CSeq field of the request.  The Via header
+  // field values in the response MUST equal the Via header field values
+  // in the request and MUST maintain the same ordering.
+  // https://tools.ietf.org/html/rfc3261#section-8.2.6.2
+  const fromHeader = "From: " + message.getHeader("From") + CRLF;
+  const callIdHeader = "Call-ID: " + message.callId + CRLF;
+  const cSeqHeader = "CSeq: " + message.cseq + " " + message.method + CRLF;
+  const viaHeaders = message.getHeaders("via").reduce((previous, current) => {
+    return previous + "Via: " + current + CRLF;
+  }, "");
+
+  // If a request contained a To tag in the request, the To header field
+  // in the response MUST equal that of the request.  However, if the To
+  // header field in the request did not contain a tag, the URI in the To
+  // header field in the response MUST equal the URI in the To header
+  // field; additionally, the UAS MUST add a tag to the To header field in
+  // the response (with the exception of the 100 (Trying) response, in
+  // which a tag MAY be present).  This serves to identify the UAS that is
+  // responding, possibly resulting in a component of a dialog ID.  The
+  // same tag MUST be used for all responses to that request, both final
+  // and provisional (again excepting the 100 (Trying)).
+  // https://tools.ietf.org/html/rfc3261#section-8.2.6.2
+  let toHeader = "To: " + message.getHeader("to");
+  if (options.statusCode > 100 && !message.parseHeader("to").hasParam("tag")) {
+    let toTag = options.toTag;
+    if (!toTag) {
+      // Stateless UAS Behavior...
+      // o  To header tags MUST be generated for responses in a stateless
+      //    manner - in a manner that will generate the same tag for the
+      //    same request consistently.  For information on tag construction
+      //    see Section 19.3.
+      // https://tools.ietf.org/html/rfc3261#section-8.2.7
+      toTag = newTag(); // FIXME: newTag() currently generates random tags
+    }
+    toHeader += ";tag=" + toTag;
+  }
+  toHeader += CRLF;
+
+  // FIXME: TODO: needs review... moved to InviteUserAgentServer (as it is specific to that)
+  // let recordRouteHeaders = "";
+  // if (request.method === C.INVITE && statusCode > 100 && statusCode <= 200) {
+  //   recordRouteHeaders = request.getHeaders("record-route").reduce((previous, current) => {
+  //     return previous + "Record-Route: " + current + CRLF;
+  //   }, "");
+  // }
+
+  // FIXME: TODO: needs review...
+  let supportedHeader = "";
+  if (options.supported) {
+    supportedHeader = "Supported: " + options.supported.join(", ") + CRLF;
+  }
+
+  // FIXME: TODO: needs review...
+  let userAgentHeader = "";
+  if (options.userAgent) {
+    userAgentHeader = "User-Agent: " + options.userAgent + CRLF;
+  }
+
+  let extensionHeaders = "";
+  if (options.extraHeaders) {
+    extensionHeaders = options.extraHeaders.reduce((previous, current) => {
+      return previous + current.trim() + CRLF;
+    }, "");
+  }
+
+  // The relative order of header fields with different field names is not
+  // significant.  However, it is RECOMMENDED that header fields which are
+  // needed for proxy processing (Via, Route, Record-Route, Proxy-Require,
+  // Max-Forwards, and Proxy-Authorization, for example) appear towards
+  // the top of the message to facilitate rapid parsing.
+  // https://tools.ietf.org/html/rfc3261#section-7.3.1
+  // response += recordRouteHeaders;
+  response += viaHeaders;
+  response += fromHeader;
+  response += toHeader;
+  response += cSeqHeader;
+  response += callIdHeader;
+  response += supportedHeader;
+  response += userAgentHeader;
+  response += extensionHeaders;
+
+  if (options.body) {
+    response += "Content-Type: " + options.body.contentType + CRLF;
+    response += "Content-Length: " + utf8Length(options.body.content) + CRLF + CRLF;
+    response += options.body.content;
+  } else {
+    response += "Content-Length: " + 0 + CRLF + CRLF;
+  }
+
+  return { message: response };
+}

package/src/core/messages/parser.ts

@@ -0,0 +1,265 @@
+/* eslint-disable no-inner-declarations */
+/* eslint-disable @typescript-eslint/no-namespace */
+import { Grammar } from "../../grammar";
+import { Logger } from "../log/logger";
+import { IncomingRequestMessage } from "./incoming-request-message";
+import { IncomingResponseMessage } from "./incoming-response-message";
+
+/**
+ * Extract and parse every header of a SIP message.
+ * @internal
+ */
+export namespace Parser {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export function getHeader(data: any, headerStart: number): number {
+    // 'start' position of the header.
+    let start: number = headerStart;
+    // 'end' position of the header.
+    let end = 0;
+    // 'partial end' position of the header.
+    let partialEnd = 0;
+
+    // End of message.
+    if (data.substring(start, start + 2).match(/(^\r\n)/)) {
+      return -2;
+    }
+
+    while (end === 0) {
+      // Partial End of Header.
+      partialEnd = data.indexOf("\r\n", start);
+
+      // 'indexOf' returns -1 if the value to be found never occurs.
+      if (partialEnd === -1) {
+        return partialEnd;
+      }
+
+      if (
+        !data.substring(partialEnd + 2, partialEnd + 4).match(/(^\r\n)/) &&
+        data.charAt(partialEnd + 2).match(/(^\s+)/)
+      ) {
+        // Not the end of the message. Continue from the next position.
+        start = partialEnd + 2;
+      } else {
+        end = partialEnd;
+      }
+    }
+
+    return end;
+  }
+
+  export function parseHeader(
+    message: IncomingRequestMessage | IncomingResponseMessage,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    data: any,
+    headerStart: number,
+    headerEnd: number
+  ): boolean | { error: string } {
+    const hcolonIndex: number = data.indexOf(":", headerStart);
+    const headerName: string = data.substring(headerStart, hcolonIndex).trim();
+    const headerValue: string = data.substring(hcolonIndex + 1, headerEnd).trim();
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let parsed: any;
+    // If header-field is well-known, parse it.
+    switch (headerName.toLowerCase()) {
+      case "via":
+      case "v":
+        message.addHeader("via", headerValue);
+        if (message.getHeaders("via").length === 1) {
+          parsed = message.parseHeader("Via");
+          if (parsed) {
+            message.via = parsed;
+            message.viaBranch = parsed.branch;
+          }
+        } else {
+          parsed = 0;
+        }
+        break;
+      case "from":
+      case "f":
+        message.setHeader("from", headerValue);
+        parsed = message.parseHeader("from");
+        if (parsed) {
+          message.from = parsed;
+          message.fromTag = parsed.getParam("tag");
+        }
+        break;
+      case "to":
+      case "t":
+        message.setHeader("to", headerValue);
+        parsed = message.parseHeader("to");
+        if (parsed) {
+          message.to = parsed;
+          message.toTag = parsed.getParam("tag");
+        }
+        break;
+      case "record-route":
+        parsed = Grammar.parse(headerValue, "Record_Route");
+
+        if (parsed === -1) {
+          parsed = undefined;
+          break;
+        }
+        if (!(parsed instanceof Array)) {
+          parsed = undefined;
+          break;
+        }
+
+        parsed.forEach((header) => {
+          message.addHeader("record-route", headerValue.substring(header.position, header.offset));
+          message.headers["Record-Route"][message.getHeaders("record-route").length - 1].parsed = header.parsed;
+        });
+        break;
+      case "call-id":
+      case "i":
+        message.setHeader("call-id", headerValue);
+        parsed = message.parseHeader("call-id");
+        if (parsed) {
+          message.callId = headerValue;
+        }
+        break;
+      case "contact":
+      case "m":
+        parsed = Grammar.parse(headerValue, "Contact");
+
+        if (parsed === -1) {
+          parsed = undefined;
+          break;
+        }
+        if (!(parsed instanceof Array)) {
+          parsed = undefined;
+          break;
+        }
+
+        parsed.forEach((header) => {
+          message.addHeader("contact", headerValue.substring(header.position, header.offset));
+          message.headers.Contact[message.getHeaders("contact").length - 1].parsed = header.parsed;
+        });
+        break;
+      case "content-length":
+      case "l":
+        message.setHeader("content-length", headerValue);
+        parsed = message.parseHeader("content-length");
+        break;
+      case "content-type":
+      case "c":
+        message.setHeader("content-type", headerValue);
+        parsed = message.parseHeader("content-type");
+        break;
+      case "cseq":
+        message.setHeader("cseq", headerValue);
+        parsed = message.parseHeader("cseq");
+        if (parsed) {
+          message.cseq = parsed.value;
+        }
+        if (message instanceof IncomingResponseMessage) {
+          message.method = parsed.method;
+        }
+        break;
+      case "max-forwards":
+        message.setHeader("max-forwards", headerValue);
+        parsed = message.parseHeader("max-forwards");
+        break;
+      case "www-authenticate":
+        message.setHeader("www-authenticate", headerValue);
+        parsed = message.parseHeader("www-authenticate");
+        break;
+      case "proxy-authenticate":
+        message.setHeader("proxy-authenticate", headerValue);
+        parsed = message.parseHeader("proxy-authenticate");
+        break;
+      case "refer-to":
+      case "r":
+        message.setHeader("refer-to", headerValue);
+        parsed = message.parseHeader("refer-to");
+        if (parsed) {
+          message.referTo = parsed;
+        }
+        break;
+      default:
+        // Do not parse this header.
+        message.addHeader(headerName.toLowerCase(), headerValue);
+        parsed = 0;
+    }
+
+    if (parsed === undefined) {
+      return {
+        error: "error parsing header '" + headerName + "'"
+      };
+    } else {
+      return true;
+    }
+  }
+
+  export function parseMessage(
+    data: string,
+    logger: Logger
+  ): IncomingRequestMessage | IncomingResponseMessage | undefined {
+    let headerStart = 0;
+    let headerEnd: number = data.indexOf("\r\n");
+
+    if (headerEnd === -1) {
+      logger.warn("no CRLF found, not a SIP message, discarded");
+      return;
+    }
+
+    // Parse first line. Check if it is a Request or a Reply.
+    const firstLine: string = data.substring(0, headerEnd);
+    const parsed = Grammar.parse(firstLine, "Request_Response");
+    let message: IncomingRequestMessage | IncomingResponseMessage;
+
+    if (parsed === -1) {
+      logger.warn('error parsing first line of SIP message: "' + firstLine + '"');
+      return;
+    } else if (!parsed.status_code) {
+      message = new IncomingRequestMessage();
+      message.method = parsed.method;
+      message.ruri = parsed.uri;
+    } else {
+      message = new IncomingResponseMessage();
+      message.statusCode = parsed.status_code;
+      message.reasonPhrase = parsed.reason_phrase;
+    }
+
+    message.data = data;
+    headerStart = headerEnd + 2;
+
+    // Loop over every line in data. Detect the end of each header and parse
+    // it or simply add to the headers collection.
+    let bodyStart: number;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      headerEnd = getHeader(data, headerStart);
+
+      // The SIP message has normally finished.
+      if (headerEnd === -2) {
+        bodyStart = headerStart + 2;
+        break;
+      } else if (headerEnd === -1) {
+        // data.indexOf returned -1 due to a malformed message.
+        logger.error("malformed message");
+        return;
+      }
+
+      const parsedHeader = parseHeader(message, data, headerStart, headerEnd);
+
+      if (parsedHeader && parsedHeader !== true) {
+        logger.error(parsedHeader.error);
+        return;
+      }
+
+      headerStart = headerEnd + 2;
+    }
+
+    // RFC3261 18.3.
+    // If there are additional bytes in the transport packet
+    // beyond the end of the body, they MUST be discarded.
+    if (message.hasHeader("content-length")) {
+      message.body = data.substr(bodyStart, Number(message.getHeader("content-length")));
+    } else {
+      message.body = data.substring(bodyStart);
+    }
+
+    return message;
+  }
+}

package/src/core/messages/utils.ts

@@ -0,0 +1,144 @@
+/**
+ * SIP Response Reasons
+ * DOC: http://www.iana.org/assignments/sip-parameters
+ * @internal
+ */
+const REASON_PHRASE: { [code: number]: string } = {
+  100: "Trying",
+  180: "Ringing",
+  181: "Call Is Being Forwarded",
+  182: "Queued",
+  183: "Session Progress",
+  199: "Early Dialog Terminated", // draft-ietf-sipcore-199
+  200: "OK",
+  202: "Accepted", // RFC 3265
+  204: "No Notification", // RFC 5839
+  300: "Multiple Choices",
+  301: "Moved Permanently",
+  302: "Moved Temporarily",
+  305: "Use Proxy",
+  380: "Alternative Service",
+  400: "Bad Request",
+  401: "Unauthorized",
+  402: "Payment Required",
+  403: "Forbidden",
+  404: "Not Found",
+  405: "Method Not Allowed",
+  406: "Not Acceptable",
+  407: "Proxy Authentication Required",
+  408: "Request Timeout",
+  410: "Gone",
+  412: "Conditional Request Failed", // RFC 3903
+  413: "Request Entity Too Large",
+  414: "Request-URI Too Long",
+  415: "Unsupported Media Type",
+  416: "Unsupported URI Scheme",
+  417: "Unknown Resource-Priority", // RFC 4412
+  420: "Bad Extension",
+  421: "Extension Required",
+  422: "Session Interval Too Small", // RFC 4028
+  423: "Interval Too Brief",
+  428: "Use Identity Header", // RFC 4474
+  429: "Provide Referrer Identity", // RFC 3892
+  430: "Flow Failed", // RFC 5626
+  433: "Anonymity Disallowed", // RFC 5079
+  436: "Bad Identity-Info", // RFC 4474
+  437: "Unsupported Certificate", // RFC 4744
+  438: "Invalid Identity Header", // RFC 4744
+  439: "First Hop Lacks Outbound Support", // RFC 5626
+  440: "Max-Breadth Exceeded", // RFC 5393
+  469: "Bad Info Package", // draft-ietf-sipcore-info-events
+  470: "Consent Needed", // RFC 5360
+  478: "Unresolvable Destination", // Custom code copied from Kamailio.
+  480: "Temporarily Unavailable",
+  481: "Call/Transaction Does Not Exist",
+  482: "Loop Detected",
+  483: "Too Many Hops",
+  484: "Address Incomplete",
+  485: "Ambiguous",
+  486: "Busy Here",
+  487: "Request Terminated",
+  488: "Not Acceptable Here",
+  489: "Bad Event", // RFC 3265
+  491: "Request Pending",
+  493: "Undecipherable",
+  494: "Security Agreement Required", // RFC 3329
+  500: "Internal Server Error",
+  501: "Not Implemented",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Server Time-out",
+  505: "Version Not Supported",
+  513: "Message Too Large",
+  580: "Precondition Failure", // RFC 3312
+  600: "Busy Everywhere",
+  603: "Decline",
+  604: "Does Not Exist Anywhere",
+  606: "Not Acceptable"
+};
+
+/**
+ * @param size -
+ * @param base -
+ * @internal
+ */
+export function createRandomToken(size: number, base = 32): string {
+  let token = "";
+  for (let i = 0; i < size; i++) {
+    const r: number = Math.floor(Math.random() * base);
+    token += r.toString(base);
+  }
+  return token;
+}
+
+/**
+ * @internal
+ */
+export function getReasonPhrase(code: number): string {
+  return REASON_PHRASE[code] || "";
+}
+
+/**
+ * @internal
+ */
+export function newTag(): string {
+  return createRandomToken(10);
+}
+
+/**
+ * @param str -
+ * @internal
+ */
+export function headerize(str: string): string {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const exceptions: any = {
+    "Call-Id": "Call-ID",
+    Cseq: "CSeq",
+    "Min-Se": "Min-SE",
+    Rack: "RAck",
+    Rseq: "RSeq",
+    "Www-Authenticate": "WWW-Authenticate"
+  };
+  const name: Array<string> = str.toLowerCase().replace(/_/g, "-").split("-");
+  const parts: number = name.length;
+  let hname = "";
+
+  for (let part = 0; part < parts; part++) {
+    if (part !== 0) {
+      hname += "-";
+    }
+    hname += name[part].charAt(0).toUpperCase() + name[part].substring(1);
+  }
+  if (exceptions[hname]) {
+    hname = exceptions[hname];
+  }
+  return hname;
+}
+
+/**
+ * @param str -
+ * @internal
+ */
+export function utf8Length(str: string): number {
+  return encodeURIComponent(str).replace(/%[A-F\d]{2}/g, "U").length;
+}

package/src/core/session/index.ts

@@ -0,0 +1,2 @@
+export * from "./session";
+export * from "./session-delegate";

package/src/core/session/session-delegate.ts

@@ -0,0 +1,88 @@
+import {
+  IncomingAckRequest,
+  IncomingByeRequest,
+  IncomingInfoRequest,
+  IncomingInviteRequest,
+  IncomingMessageRequest,
+  IncomingNotifyRequest,
+  IncomingPrackRequest,
+  IncomingReferRequest
+} from "../messages";
+
+/**
+ * Session delegate.
+ * @public
+ */
+export interface SessionDelegate {
+  /**
+   * Receive ACK request.
+   * @param request - Incoming ACK request.
+   * @returns
+   * The callback MUST return a promise if it asynchronously handles answers.
+   * For example, an ACK with an answer (offer in the 200 Ok) may require
+   * asynchronous processing in which case the callback MUST return a Promise
+   * which resolves when the answer handling is complete.
+   * @privateRemarks
+   * Unlike INVITE handling where we can rely on the generation of a response
+   * to indicate when offer/answer processing has been completed, ACK handling
+   * requires some indication from the handler that answer processing is complete
+   * so that we can avoid some race conditions (see comments in code for more details).
+   * Having the handler return a Promise provides said indication.
+   */
+  onAck?(request: IncomingAckRequest): Promise<void> | void;
+
+  /**
+   * Timeout waiting for ACK request.
+   * If no handler is provided the Session will terminated with a BYE.
+   * https://tools.ietf.org/html/rfc3261#section-13.3.1.4
+   */
+  onAckTimeout?(): void;
+
+  /**
+   * Receive BYE request.
+   * https://tools.ietf.org/html/rfc3261#section-15.1.2
+   * @param request - Incoming BYE request.
+   */
+  onBye?(request: IncomingByeRequest): void;
+
+  /**
+   * Receive INFO request.
+   * @param request - Incoming INFO request.
+   */
+  onInfo?(request: IncomingInfoRequest): void;
+
+  /**
+   * Receive re-INVITE request.
+   * https://tools.ietf.org/html/rfc3261#section-14.2
+   * @param request - Incoming INVITE request.
+   */
+  onInvite?(request: IncomingInviteRequest): void;
+
+  /**
+   * Receive MESSAGE request.
+   * https://tools.ietf.org/html/rfc3428#section-7
+   * @param request - Incoming MESSAGE request.
+   */
+  onMessage?(request: IncomingMessageRequest): void;
+
+  /**
+   * Receive NOTIFY request.
+   * https://tools.ietf.org/html/rfc6665#section-4.1.3
+   * @param request - Incoming NOTIFY request.
+   */
+  onNotify?(request: IncomingNotifyRequest): void;
+
+  /**
+   * Receive PRACK request.
+   * https://tools.ietf.org/html/rfc3262#section-3
+   * @param request - Incoming PRACK request.
+   */
+  onPrack?(request: IncomingPrackRequest): void;
+
+  /**
+   * Receive REFER request.
+   * https://tools.ietf.org/html/rfc3515#section-2.4.2
+   * @param request - Incoming REFER request.
+   */
+  onRefer?(request: IncomingReferRequest): void;
+}