drachtio-srf

The Dialog class is an EventEmitter that emits several events based on incoming SIP messages. When you attach a handler to these events, you are responsible for generating a SIP response using the provided res.send() method. If no handler is attached, the library automatically sends a 200 OK for most methods.

Common Events:

• destroy: Triggered when the dialog is torn down from the far end (e.g., receiving a BYE).
• modify: Triggered when the far end sends a re-INVITE. You must call res.send() to respond.
• refresh: Triggered when the far end sends a session refresh (notification only; no response required).
• hold / unhold: Triggered when the far end modifies the session to hold or unhold.
• info: Triggered when an INFO message is received.
• notify: Triggered when a NOTIFY message is received.
• options: Triggered when an OPTIONS message is received.
• update: Triggered when an UPDATE message is received.
• refer: Triggered when a REFER message is received.
• message: Triggered when a MESSAGE message is received.
• subscribe: Triggered when a SUBSCRIBE request is received.
• ack: Triggered when an ACK is received.

To use drachtio-srf, you must instantiate a DrachtioAgent and connect it to a drachtio server. The agent acts as the primary interface for sending SIP requests and receiving SIP messages.

When connecting, you must provide a secret for authentication and optionally tags to identify the agent to the server. The agent uses a callback mechanism (passed to the constructor) to route incoming requests and responses to your application middleware.

Common events to listen for include connect, close, and error.

const DrachtioAgent = require('drachtio-srf').DrachtioAgent;

// The callback passed to the constructor is the middleware handler
const agent = new DrachtioAgent((req, res) => {
  // Handle incoming SIP requests here
  console.log('Received request:', req.method, req.uri);
});

agent.connect({
  host: '127.0.0.1',
  port: 9022,
  secret: 'your-secret',
  tags: ['my-agent']
}, (err) => {
  if (err) {
    console.error('Connection error:', err);
    return;
  }
  console.log('Connected to drachtio server');
});

The createB2BUA() method allows you to bridge two SIP legs (a User Agent Client and a User Agent Server). It is typically called within an invite handler.

Parameters:

• uri: The target SIP URI (e.g., 'sip:1234@10.10.100.1').
• req: The incoming SIP request.
• res: The incoming SIP response.
• options: An object containing configuration, such as localSdpB to provide local SDP.

Returns: Returns a Promise that resolves to an object containing {uas, uac}. You should listen for the 'destroy' event on both legs to ensure that when one side terminates, the other side is also hung up.

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}`);
    });
});

You can act as a SIP proxy by using srf.proxyRequest(). This method takes an incoming request, a list of target destinations, and an optional configuration object. It returns a Promise that resolves with the results of the proxy operation.

Options:

• recordRoute: Boolean indicating if Record-Route should be used.
• followRedirects: Boolean indicating if redirects should be followed.
• provisionalTimeout: A string representing the timeout for provisional responses (e.g., '2s').

Result Object: Resolves to an object containing:

• finalStatus: The final SIP status code.
• finalResponse: The final SIP response object.
• responses: An array of intermediate responses.

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(results)); 
    // {finalStatus: 200, finalResponse:{..}, responses: [..]}
  });
});