drachtio is a Node.js-based middleware framework for building SIP applications. It is inspired by classic http middleware frameworks such as connect and expressjs, and developers who are familiar with such frameworks will find it quite easy to understand and work with.
For developers new to SIP and VoIP in general, drachtio provides an easy path to building full-functional SIP applications; those more experienced with the SIP protocol will appreciate the flexibility that drachtio provides in terms of enabling any kind of SIP element: proxy servers, registars, user agent clients and servers, and back-to-back user agents.
drachtio works in concert with [drachtio-server](https://github.com/davehorton/drachtio-server) -- drachtio-server implements the SIP stack and handles low-level SIP message processing, while drachtio-based applications provide the higher level application logic and control the actions of a drachtio server over a TCP network connection.
drachtio also enables the higher level frameworks drachtio-srf - the drachtio sigaling resource framework, and drachtio-fsmrf - the drachtio media resource framework. Generally speaking, developers should consider using drachtio for simpler SIP applications such as proxy servers and registrars, using drachtio-srf for more complex application patterns such as back-to-back user agents, and should incorporate drachtio-fsmrf when media processing features such as IVR, conferencing, or recording are required.
Note: API documentation for drachtio can be found here.
//sample application: a SIP proxy
var drachtio = require('drachtio');
var app = drachtio() ;
//connect to a drachtio server
app.connect({host:'localhost', port: 8022, secret: 'cymru'}) ;
app.invite( function( req, res ) {
var user = req.msg.uri.match(/sip:(.*?)@(.*?)$/) ;
//search for the user in 3 different locations
req.proxy({
destination: [
'sip:' + user[1] + '@site1.mycompany.com',
'sip:' + user[1] + '@site2.mycompany.com',
'sip:' + user[1] + '@site2.mycompany.com'
],
remainInDialog: true,
forking: 'simultaneous',
headers: {
'Subject': 'Incoming call for ' + user[1]
}
}, function(err, response){
if( err ) return console.error('Error attempting to proxy request: ', err) ;
console.log('Final response for proxy: ' + response.finalStatus ) ;
}) ;
}) ;
Getting Started
Creating an application
The first thing an application must do is to require the drachtio library and invoke the returned function to create an application. The application instance that is created is an EventEmitter.
var drachtio = require('drachtio') ;
var app = drachtio() ;
Connecting to the server
The next thing an application must do is to call the 'connect' method in order to connect to the drachtio-server that will be providing the SIP endpoint. By default, drachtio-server listens for TCP connections from clients on port 8022. Clients must also provide a shared secret as a means of authentication.
app.connect({
host:'localhost', //ip address or DNS name of drachtio-server
port: 8022, //defaults to 8022 if not provided
secret: 'cymru' //shared secret
}, function( err, hostport ) {
if( err ) throw err ;
console.log('success! drachtio-server is listening on ' + hostport) ;
}) ;
A 'connect' event is emitted by the app object when the connection has been established; alternatively, a callback can be passed to the connect method, as shown above.
The callback or event handler will an error object (null in the case of a successful connection) and a string variable describing the sip address and port the drachtio server is listening on for SIP messages.
Receiving and responding to sip requests (UAS)
A drachtio application can both send and receive SIP requests. To receive SIP requests (i.e to act as a User Agent Server), app[verb] methods are used. Request and Response objects are provided to the callback.The Request object contains information describing the incoming sip request, along with methods that can be used to act on the request (e.g., req#proxy is a method provided to proxy the request). The Response object contains methods that allow the application to control the generation of the sip response, in the case of an application acting as a SIP user agent server (UAS).
app.register( function( req, res ) {
var contact = req.getParsedHeader('Contact') ;
var expires = contact.params.expires || req.get('Expires') ;
console.log('Received a REGISTER request with Expires value: ' + expires) ;
res.send( 200, {
headers: {
'Expires': expires
}
})
}) ;
Notes:
- drachtio-server automatically sends a 100 Trying to all incoming INVITE messages, so a drachtio app does not need to do so.
- A 'Content-Length' header is automatically provided by drachtio-server, so the application should not include that header.
- A 'Content-Type' header of 'application/sdp' will automatically be added by drachtio-server, where appropriate. When sending any other content types, an application must explicitly include a 'Content-Type' header.
- Request and Response objects both support a `get` method to return the value of a named SIP header as a string value, and `getParsedHeader` to return object that represents the SIP header parsed into its component values.
Sending sip requests (UAC)
SIP requests can be sent (i.e., to act as a User Agent Client) using the app.request method:
// connect and then send an OPTIONS ping
app.connect({host:'localhost',port: 8022,secret: 'cymru'},
function(err, hostport){
if( err ) throw err ;
//connected ok
app.request({
uri: 'sip:1234@10.168.12.139'.
method: 'OPTION',
headers: {
'User-Agent': 'dracht.io'
}
} function( err, req ) {
if( err ) console.error( err ) ;
req.on('response', function(response){
console.log('response status was ' + response.status) ;
app.disconnect() ;
}) ;
}) ;
}
);