Srf

Srf

Applications create an instance of Srf in order to create and manage SIP Dialogs and SIP transactions. An application may have one or more Srf instances, although for most cases a single instance is sufficient.

Constructor

new Srf()

Creates an Srf instance. No arguments are supplied.
Source:

Methods

connect(opts)

make an inbound connection to a drachtio server
Source:
Parameters:
Name Type Description
opts Object connection options
Name Type Attributes Default Description
host string <optional>
'localhost' address drachtio server is listening on for client connections
port Number <optional>
9022 address drachtio server is listening on for client connections
secret String shared secret used to authenticate connections
Example
const Srf = require('drachtio-srf');
const srf = new Srf();

srf.connect({host: '127.0.0.1', port: 9022, secret: 'cymru'});
srf.on('connect', (hostport) => {
  console.log(`connected to drachtio server offering sip endpoints: ${hostport}`);
})
.on('error', (err) => {
  console.error(`error connecting: ${err}`);
});

srf.invite((req, res) => {..});

createB2BUA(req, res, uri, opts, progressCallbacksopt, callbackopt) → {Srf|Promise}

create back-to-back dialogs; i.e. act as a back-to-back user agent (B2BUA), creating a pair of dialogs {uas, uac} -- a UAS dialog facing the caller or A party, and a UAC dialog facing the callee or B party such that media flows between them
Source:
Parameters:
Name Type Attributes Description
req Object incoming sip request object
res Object incoming sip response object
uri string sip uri or IP address[:port] to send the UAC INVITE to
opts Object configuration options
Name Type Attributes Default Description
headers Object <optional>
SIP headers to include on the SIP INVITE request
localSdpA string | function <optional>
the local session description protocol to offer in the response to the SIP INVITE request on the A leg; either a string or a function may be provided. If a function is provided, it will be invoked with two parameters (sdp, res) correspnding to the SDP received from the B party, and the sip response object received on the response from B. The function must return either the SDP (as a string) or a Promise that resolves to the SDP. If no value is provided (neither string nor function), then the SDP returned by the B party in the provisional/final response on the UAC leg will be sent back to the A party in the answer.
localSdpB string the local session description protocol to offer in the SIP INVITE request on the B leg
proxyRequestHeaders Array <optional>
an array of header names which, if they appear in the INVITE request on the A leg, should be included unchanged on the generated B leg INVITE
proxyResponseHeaders Array <optional>
an array of header names which, if they appear in the response to the outgoing INVITE, should be included unchanged on the generated response to the A leg
passFailure Boolean <optional>
true specifies whether to pass a failure returned from B leg back to the A leg
progressCallbacks Object <optional>
callbacks providing call progress notification
Name Type Attributes Description
cbRequest function <optional>
callback that provides request sent over the wire, with signature (req)
cbProvisional function <optional>
callback that provides a provisional response with signature (provisionalRes)
callback function <optional>
if provided, callback with signature (err, {uas, uac})
Returns:
Type:
Srf | Promise
if a callback is supplied, a reference to the Srf instance.
If no callback is supplied, then a Promise that is resolved with the sip dialog that is created.
Examples

simple B2BUA

const Srf = require('drachtio-srf');
const srf = new Srf();

srf.invite((req, res) => {
  srf.createB2BUA('sip:1234@10.10.100.1', req, res, {localSdpB: req.body})
    .then({uas, uac} => {
      console.log('call connected');

      // when one side terminates, hang up the other
      uas.on('destroy', () => { uac.destroy(); });
      uac.on('destroy', () => { uas.destroy(); });
    })
    .catch((err) => {
      console.log(`call failed to connect: ${err}`);
    });
});

use opts.passFailure to attempt a fallback URI on failure

const Srf = require('drachtio-srf');
const srf = new Srf();

function endCall(dlg1, dlg2) {
  dlg1.on('destroy', () => {dlg2.destroy();})
  dlg2.on('destroy', () => {dlg1.destroy();})
}
srf.invite((req, res) => {
  srf.createB2BUA('sip:1234@10.10.100.1', req, res, {localSdpB: req.body, passFailure: false})
    .then({uas, uac} => {
      console.log('call connected to primary destination');
      endcall(uas, uac);
    })
    .catch((err) => {
      // try backup if we got a sip non-success response and the caller did not hang up
      if (err instanceof Srf.SipError && err.status !== 487) {
          console.log(`failed connecting to primary, will try backup: ${err}`);
          srf.createB2BUA('sip:1234@10.10.100.2', req, res, {
            localSdpB: req.body}
          })
            .then({uas, uac} => {
              console.log('call connected to backup destination');
              endcall(uas.uac);
            })
            catch((err) => {
              console.log(`failed connecting to backup uri: ${err}`);
            });
      }
    });
});

B2BUA with media proxy using rtpengine

const Srf = require('drachtio-srf');
const srf = new Srf();
const rtpengine = require('rtpengine-client').Client

// helper functions

// clean up and free rtpengine resources when either side hangs up
function endCall(dlg1, dlg2, details) {
  [dlg1, dlg2].each((dlg) => {
    dlg.on('destroy', () => {(dlg === dlg1 ? dlg2 : dlg1).destroy();});
    rtpengine.delete(details);
  });
}

// function returning a Promise that resolves with the SDP to offer A leg in 18x/200 answer
function getSdpA(details, remoteSdp, res) {
  return rtpengine.answer(Object.assign(details, {
    'sdp': remoteSdp,
    'to-tag': res.getParsedHeader('To').params.tag
   }))
    .then((response) => {
      if (response.result !== 'ok') throw new Error(`Error calling answer: ${response['error-reason']}`);
      return response.sdp;
   })
}

// handle incoming invite
srf.invite((req, res) => {
  const from = req.getParsedHeader('From');
  const details = {'call-id': req.get('Call-Id'), 'from-tag': from.params.tag};

  rtpengine.offer(Object.assign(details, {'sdp': req.body})
    .then((rtpResponse) => {
      if (rtpResponse && rtpResponse.result === 'ok') return rtpResponse.sdp;
      throw new Error('rtpengine failure');
    })
    .then((sdpB) => {
      return srf.createB2BUA('sip:1234@10.10.100.1', req, res, {
        localSdpB: sdpB,
        localSdpA: getSdpA.bind(null, details)
      });
    })
    .then({uas, uac} => {
      console.log('call connected with media proxy');
      endcall(uas, uac, details);
    })
    .catch((err) => {
      console.log(`Error proxying call with media: ${err}`);
    });
});

createUAC(uri, opts, progressCallbacksopt, callbackopt) → {Srf|Promise}

create a SIP dialog, acting as a UAC (user agent client)
Source:
Parameters:
Name Type Attributes Description
uri string request uri to send to
opts Object configuration options
Name Type Attributes Description
headers Object <optional>
SIP headers to include on the SIP INVITE request
localSdp string the local session description protocol to include in the SIP INVITE request
progressCallbacks Object <optional>
callbacks providing call progress notification
Name Type Attributes Description
cbRequest function <optional>
callback that provides request sent over the wire, with signature (req)
cbProvisional function <optional>
callback that provides a provisional response with signature (provisionalRes)
callback function <optional>
if provided, callback with signature (err, dialog)
Returns:
Type:
Srf | Promise
if a callback is supplied, a reference to the Srf instance.
If no callback is supplied, then a Promise that is resolved with the sip dialog that is created.
Examples

returning a Promise

const Srf = require('drachtio-srf');
const srf = new Srf();

const mySdp; // populated somehow with SDP we want to offer
srf.createUac('sip:1234@10.10.100.1', {localSdp: mySdp})
  .then((uac) => {
    console.log(`dialog established, call-id is ${uac.sip.callId}`);
    uac.on('destroy', () => {
      console.log('called party hung up');
    });
  })
  .catch((err) => {
    console.log(`INVITE rejected with status: ${err.status}`);
  });
});

Using a callback

const Srf = require('drachtio-srf');
const srf = new Srf();

const mySdp; // populated somehow with SDP we want to offer
srf.createUac('sip:1234@10.10.100.1', {localSdp: mySdp},
   (err, uac) => {
     if (err) {
       return console.log(`INVITE rejected with status: ${err.status}`);
     }
    uac.on('destroy', () => {
      console.log('called party hung up');
    });
  });

Canceling a request by using a progress callback

const Srf = require('drachtio-srf');
const srf = new Srf();

const mySdp; // populated somehow with SDP we want to offer
let inviteSent;
srf.createUac('sip:1234@10.10.100.1', {localSdp: mySdp},
  {
    cbRequest: (reqSent) => { inviteSent = req; }
  })
  .then((uac) => {
    // unexpected, in this case
    console.log('dialog established before we could cancel');
  })
  .catch((err) => {
    assert(err.status === 487); // expected sip response to a CANCEL
  });
});

// cancel the request after 0.5s
setTimeout(() => {
  inviteSent.cancel();
}, 500);

createUAS(req, res, opts, callbackopt) → {Srf|Promise}

create a SIP dialog, acting as a UAS (user agent server); i.e. respond to an incoming SIP INVITE with a 200 OK (or to a SUBSCRIBE request with a 202 Accepted). Note that the Dialog is generated (i.e. the callback invoked / the Promise resolved) at the moment that the 200 OK is sent back towards the requestor, not when the ACK is subsequently received.
Source:
Parameters:
Name Type Attributes Description
req Object the incoming sip request object
res Object the sip response object
opts Object configuration options
Name Type Attributes Description
localSdp string the local session description protocol to include in the SIP response
headers Object <optional>
SIP headers to include on the SIP response to the INVITE
callback function <optional>
if provided, callback with signature (err, dialog)
Returns:
Type:
Srf | Promise
if a callback is supplied, a reference to the Srf instance.
If no callback is supplied, then a Promise that is resolved with the sip dialog that is created.
Examples

returning a Promise

const Srf = require('drachtio-srf');
const srf = new Srf();

srf.invite((req, res) => {
  const mySdp; // populated somehow with SDP we want to answer in 200 OK
  srf.createUas(req, res, {localSdp: mySdp})
    .then((uas) => {
      console.log(`dialog established, remote uri is ${uas.remote.uri}`);
      uas.on('destroy', () => {
        console.log('caller hung up');
      });
    })
    .catch((err) => {
      console.log(`Error establishing dialog: ${err}`);
    });
});

using callback

const Srf = require('drachtio-srf');
const srf = new Srf();

srf.invite((req, res) => {
  const mySdp; // populated somehow with SDP we want to offer in 200 OK
  srf.createUas(req, res, {localSdp: mySdp},
    (err, uas) => {
      if (err) {
        return console.log(`Error establishing dialog: ${err}`);
      }
      console.log(`dialog established, local tag is ${uas.sip.localTag}`);
      uas.on('destroy', () => {
        console.log('caller hung up');
      });
    });
});

specifying standard or custom headers

srf.createUas(req, res, {
    localSdp: mySdp,
    headers: {
      'User-Agent': 'drachtio/iechyd-da',
      'X-Linked-UUID': '1e2587c'
    }
  }).then((uas) => { ..});

listen(opts)

listen for outbound connections from a drachtio server
Source:
Parameters:
Name Type Description
opts Object listen options
Name Type Description
port number address drachtio server is listening on for client connections
secret string shared secret used to authenticate connections
Example
const Srf = require('drachtio-srf');
const srf = new Srf();

srf.listen({port: 9023, secret: 'cymru'});

srf.invite((req, res) => {..});

proxyRequest(req, destinationopt, optsopt, callbackopt) → {Srf|Promise}

proxy an incoming request
Source:
Parameters:
Name Type Attributes Description
req Request drachtio request object representing an incoming SIP request
destination String | Array <optional>
an IP address[:port], or list of same, to proxy the request to
opts Object <optional>
configuration options for the proxy operation
Name Type Attributes Default Description
forking String <optional>
sequential when multiple destinations are provided, this option governs whether they are attempted sequentially or in parallel. Valid values are 'sequential' or 'parallel'
remainInDialog Boolean <optional>
false if true, add Record-Route header and remain in the SIP dialog (i.e. receiving futher SIP messaging for the dialog, including the terminating BYE request). Alias: `recordRoute`.
provisionalTimeout String <optional>
timeout after which to attempt the next destination if no 100 Trying response has been received. Examples of valid syntax for this property is '1500ms', or '2s'
finalTimeout String <optional>
timeout, in milliseconds, after which to cancel the current request and attempt the next destination if no final response has been received. Syntax is the same as for the provisionalTimeout property.
followRedirects Boolean <optional>
false if true, handle 3XX redirect responses by generating a new request as per the Contact header; otherwise, proxy the 3XX response back upstream without generating a new response
callback function <optional>
callback invoked when proxy operation completes, signature (err, results) where `results` is a JSON object describing the individual sip call attempts and results
Returns:
Type:
Srf | Promise
returns a Promise if no callback is supplied, otherwise the Srf object
Examples

simple proxy

const Srf = require('drachtio-srf');
const srf = new Srf();

srf.invite((req, res) => {
  srf.proxyRequest(req, 'sip.example.com');
});

proxy with options

const Srf = require('drachtio-srf');
const srf = new Srf();

srf.invite((req, res) => {
  srf.proxyRequest(req, ['sip.example1.com', 'sip.example2.com'], {
    recordRoute: true,
    followRedirects: true,
    provisionalTimeout: '2s'
  }).then((results) => {
    console.log(JSON.stringify(result)); // {finalStatus: 200, finalResponse:{..}, responses: [..]}
  });
});

request(uri, opts, headersopt, bodyopt, callbackopt)

send a SIP request outside of a dialog
Source:
Parameters:
Name Type Attributes Description
uri string sip request-uri to send request to
opts Object configuration options
Name Type Description
method String SIP method to send (lower-case)
headers Object <optional>
SIP headers to apply to the outbound request
body String <optional>
body to send with the SIP request
callback function <optional>
callback invoked when sip request has been sent, invoked with signature (err, request) where `request` is a sip request object representing the sip message that was sent.
Example

sending OPTIONS request

srf.request('sip.example.com', {
  method: 'OPTIONS',
  headers: {
    'User-Agent': 'drachtio'
  }
 }, (err, req) => {
  req.on('response', (res) => {
    console.log(`received ${res.statusCode} response`);
  });
});

Events

cdr:attempt

a cdr:attempt event is emitted by an Srf instance when a call attempt has been received (inbound) or initiated (outbound)
Source:
Parameters:
Name Type Description
source String 'network'|'application', depending on whether the INVITE is \inbound (received), or outbound (sent), respectively
time String the time (UTC) recorded by the SIP stack corresponding to the attempt
msg Object the actual message that was sent or received

cdr:start

a cdr:start event is emitted by an Srf instance when a call attempt has been connected successfully
Source:
Parameters:
Name Type Description
source String 'network'|'application', depending on whether the INVITE is inbound (received), or outbound (sent), respectively
time String the time (UTC) recorded by the SIP stack corresponding to the attempt
role String 'uac'|'uas'|'uac-proxy'|'uas-proxy' indicating whether the application is acting as a user agent client, user agent server, proxy (sending message), or proxy (receiving message) for this cdr
msg Object the actual message that was sent or received

cdr:stop

a cdr:stop event is emitted by an Srf instance when a connected call has ended
Source:
Parameters:
Name Type Description
source String 'network'|'application', depending on whether the INVITE is inbound (received), or outbound (sent), respectively
time String the time (UTC) recorded by the SIP stack corresponding to the attempt
reason String the reason the call was ended
msg Object the actual message that was sent or received

connect

a connect event is emitted by an Srf instance when a connect method completes with either success or failure
Source:
Parameters:
Name Type Description
err Object error encountered when attempting to connect
hostport String the SIP address[:port] drachtio server is listening on for incoming SIP messages