kamailio:k43-async-sip-routing-nodejs

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
kamailio:k43-async-sip-routing-nodejs [2015/07/28 11:33] adminkamailio:k43-async-sip-routing-nodejs [2015/09/07 13:36] (current) – [Async SIP Routing with Kamailio and Node.js] admin
Line 1: Line 1:
 ====== Async SIP Routing with Kamailio and Node.js ====== ====== Async SIP Routing with Kamailio and Node.js ======
  
-**Work in progress -- the tutorial is not complete yet**+Node.js-based external routing decision engine for Kamailio. 
 + 
 +===== Overview =====
  
 The aim is to show how to leverage [[http://kamailio.org/docs/modules/stable/modules/evapi.html|evapi module]] to retrieve JSON-formatted routing information from external source, respectively a [[https://nodejs.org/|node.js]] application. The aim is to show how to leverage [[http://kamailio.org/docs/modules/stable/modules/evapi.html|evapi module]] to retrieve JSON-formatted routing information from external source, respectively a [[https://nodejs.org/|node.js]] application.
Line 7: Line 9:
 The [[http://kamailio.org/docs/modules/stable/modules/rtjson.html|module rtjson]] defines a format for JSON document that makes it straightforward to push new destinations for a SIP request. The [[http://kamailio.org/docs/modules/stable/modules/jansson.html|module jansson]] is used to parse the JSON document in kamailio.cfg for fetching additional attributes that are relevant for processing. The [[http://kamailio.org/docs/modules/stable/modules/rtjson.html|module rtjson]] defines a format for JSON document that makes it straightforward to push new destinations for a SIP request. The [[http://kamailio.org/docs/modules/stable/modules/jansson.html|module jansson]] is used to parse the JSON document in kamailio.cfg for fetching additional attributes that are relevant for processing.
  
 +{{ :kamailio:kamailio-evapi-rtjson-nodejs.png?400 |}}
 +===== SIP Routing =====
 +
 +The routing JSON document format specified by the [[http://kamailio.org/docs/modules/stable/modules/rtjson.html|module rtjson]] allows SIP serial or parallel forking. The addresses for next hops are going to be computed by the node.js application, in this tutorial they are statically set, but they can be retrieved from a database system.
 +
 +Serial and parallel forking are the basic mechanisms for forwarding SIP traffic:
 +
 +  * serial forking - try several destinations one after the other, waiting for a final response on each try, stopping when one answered with 200ok or there is no other destination to try
 +  * parallel forking - try several destinations at once, stopping when one answered with 200ok and cancelling the other active branches, or when all branches responded with a negative response.
 +
 +Leveraging the two routing mechanisms, one can implement various routing engine such as load balancer, least cost routing, group hunting, call forwarding (on no answer, busy, etc.). Kamailio has dedicated modules (e.g., dispatcher, lcr, ...) to provide those features, but sometimes the logic behind deciding what is the best route to follow might not match existing components. Writing an application in nodejs might be faster or better integrated in the overall environment (e.g., when dealing with multiple nodes), than writing a new module in C. Obviously, the code written in C is always expected to run faster.
 +
 +The tutorial here is aiming to offer a basic example, which should help building more complex external applications for deciding the SIP routing to be performed by Kamailio.
 +
 +==== RTJSON Routing Document ====
 +
 +The structure for RTJSON routing document is detailed at:
 +
 +  * [[http://kamailio.org/docs/modules/stable/modules/rtjson.html#rtjson.json-routing-structure|RTJSON Readme - Document Structure]]
 +
 +Next is a partial example, with the attributes for one destination:
 +
 +<code javascript>
 +{
 + "version": "1.0",
 + "routing": "serial",
 + "routes":
 +  [
 +   {
 +     "uri": "sip:127.0.0.1:5080",
 +     "dst_uri": "sip:127.0.0.1:5082",
 +     "path": "<sip:127.0.0.1:5084>, <sip:127.0.0.1:5086>",
 +     "socket": "udp:127.0.0.1:5060",
 +     "headers": {
 +       "from": {
 +         "display": "Alice",
 +         "uri": "sip:alice@wonderland.com"
 +       },
 +       "to": {
 +         "display": "Bob",
 +         "uri": "sip:bob@wonderland.com"
 +       },
 +       "extra": "X-Hdr-A: abc\r\nX-Hdr-B: bcd\r\n"
 +     },
 +     "branch_flags": 8,
 +     "fr_timer": 5000,
 +     "fr_inv_timer": 30000
 +   },
 +...
 +  ]
 +}
 +</code>
 +
 +The **routing** field specify if Kamailio has to do serial or parallel forking. After that, the relevant routing information is an array of destinations stored in **routes** field.
 +
 +Each destination corresponds to a SIP branch that is going to be created by Kamailio. For each branch can be specified values to set:
 +
 +  * request uri
 +  * outbound proxy address (dst uri)
 +  * display name and uri for From/To headers
 +  * extra headers
 +  * retransmission and ringing timeouts
 +  * local socket or the path to be followed
 +  * branch flags
 +
 +The example above results in: the request will be routed to sip:127.0.0.1:5080, via sip:127.0.0.1:5082, sip:127.0.0.1:5084, sip:127.0.0.1:5086; it will be sent using local socket udp:127.0.0.1:5060; From header display name will be set to **Alice** and From URI to **sip:alice@wonderland.com**; To header display name will be set to **Bob** and To URI to **sip:alice@wonderland.com**; branch flags will be updated with 8; retransmission will be done for 5000 milliseconds, waiting 30000 milliseconds while ringing.
 +
 +==== EVAPI Processing ====
 +
 +EVAPI is sort of generic framework to push events to external application from inside kamailio.cfg via TCP connections. It has the capability of suspending the processing of the SIP request until there is a response from the external application. By suspending the SIP request, other SIP messages can be processes, thus not blocking Kamailio while waiting for event response. This asynchronous mechanism enables high throughput for SIP routing.
 +===== Presentations =====
 +
 +The presentation at Cluecon 2015 by Daniel-Constantin Mierla includes content about this tutorial:
 +
 +  * [[http://www.kamailio.org/events/2015-ClueCon/dcm-kamailio-api-routing.pdf|The PDF with Slides]]
 +  * [[http://www.slideshare.net/miconda/kamailio-api-based-sip-routing|Slideshare]]
 ===== Kamailio Config File ===== ===== Kamailio Config File =====
  
Line 23: Line 101:
   * add the routing blocks specific for evapi module   * add the routing blocks specific for evapi module
   * use jansson to investigate returned JSON document and take decision of what to do   * use jansson to investigate returned JSON document and take decision of what to do
 +
 +==== Config Diff ====
  
 The diff of the config file comparing with the default one: The diff of the config file comparing with the default one:
Line 143: Line 223:
  
 </code> </code>
 +
 +==== Full Config ====
  
 The full config file is: The full config file is:
Line 860: Line 942:
   * http://nodejs.org   * http://nodejs.org
  
-A simple sample application is shown next:+A simple sample application is shown next example. It connects to Kamailio's EVAPI socket, waiting for messages with json content serialized as netstring. There response will contain two destinations built with static values (sip:127.0.0.1:5080 and sip:127.0.0.1:5090), again serialazed as netstring.
  
-<code js kanapi.js>+To read more about nestring format, see: 
 + 
 +  * https://en.wikipedia.org/wiki/Netstring 
 + 
 +Node.js application: 
 + 
 +<code javascript kanapi.js>
 var net = require('net'); var net = require('net');
  
Line 992: Line 1080:
 </code> </code>
  
 +===== Resources =====
 +
 +  * [[http://www.kamailio.org|Kamailio Project]]
 +  * [[http://kamailio.org/docs/modules/stable/modules/evapi.html|Kamaialio EVAPI Module]]
 +  * [[http://kamailio.org/docs/modules/stable/modules/rtjson.html|Kamailio RTJSON Module]]
 +  * [[http://kamailio.org/docs/modules/stable/modules/rtjson.html|Kamailio JANSSON Module]]
 +  * [[http://nodejs.org|NodeJS Project]]
 +  * [[https://en.wikipedia.org/wiki/Netstring|Netstring Format]]

100%


Copyright 2010-2020 Asipto.com