FreeSWITCH ESL Bindings for Node.js
A Library for handling low-level FreeSWITCH ESLconnections, and associated ESLevents.
Purpose
Though there is already a Node.js "library" for this on github,
it does not actually implement the Event Socket Library
interface, and instead has it's own thing. This library was written to implement the full Event
Socket Library interface, and provide a meaningful semantic when dealing with FreeSWITCH in Node.js.
This library supports both "Inbound" (connection going into FreeSWITCH) and "Outbound" (connections
coming out of FreeSWITCH). Also included is a helper esl.Server
object that manages multiple
esl.Connection
objects; making it trivial to have multiple "Outbound" connections from FreeSWITCH.
Installation
The easiest way to install is via npm:
npm install modesl
As in "Mod ESL".
Usage
The most basic usage example is to open a connection, and send a status command:
var esl = require('modesl'),
conn = new esl.Connection('127.0.0.1', 8021, 'ClueCon', function() {
conn.api('status', function(res) {
console.log(res.getBody());
});
});
Something to be aware of is that all functions that interact with FreeSWITCH are asynchronous on the Library side.
However, there are many functions (api
, execute
, etc) that are synchronous on the FreeSWITCH side. Because of this
the event you will get back in your callback on, for example, api
and the same command on bgapi
will be different.
The api
command's callback will be executed immediately when the command/reply
message is received, with all the
returned data. However, that same command using bgapi
will not call the callback when the command/reply
message
is received, this is because FreeSWITCH returns the command/reply
message immediately for background commands before
the command is run. The Library will automatically track the command, and call the callback on the BACKGROUND_JOB
message that denotes a completed Background Job.
The body for the same command issued with api
and bgapi
should be the same; even when the headers, event type, and
time it takes for the callback to execute are different. The Library attempts to smooth these differences out by providing
a common interface, even though behind the scenes things are quite different.
Interface
This library exposes 3 main classes:
esl.Connection
esl.Event
esl.Server
esl.Parser
(Used internally for parsing the raw socket stream; not for public use)
Which implement the ESLconnection
and ESLevent interfaces, respectively.
The esl.Server
object is for creating a server to manage multiple "Outbound" connections; that is, multiple
esl.Connection
objects coming from FreeSWITCH. The esl
object actually exported from this module is
considered to implement the ESL Object interface.
You can read the documentation about the Event Socket Library
to understand what each function does. However, there are a couple caveats. This interface was meant to be blocking
in many different places, however due to the nature of node nearly all are asynchronous (though some commands
such as api
will still block on the freeswitch side, they are non-blocking on the node side).
A couple caveats are:
esl.Connection
Constructor
The documentation lists 2 ways this constructor can be called either:
var conn = new esl.Connection(host, port, password[, readyCallback]);
Which will create a new connection client, an "Inbound" Connection, which connects up to FreeSWITCH and will
allow you to send commands to the server. This is the same as in the documentation (with the addition of a
ready callback parameter which is called once the connection is opened, and authenticated).
The other however, expects a raw file descriptor and is in the format:
var conn = new esl.Connection(fd);
The reasoning is because, according to the documentation:
The standard method for using this function is to listen for an incomingconnection on a socket, accept
the incoming connection from FreeSWITCH, fork a new copy of your process if you want to listen for more
connections, and then pass the file number of the socket to new($fd).
However, node doesn't need to fork to accept multiple connections. But an esl.Connection
instance should
still be only 1 Channel Connection instance. To solve this issue, the second form will accept an instance of
Node's net.Socket
. In this way you can do the server
management yourself (or using esl.Server
to do it for you).
This changes the constructor call for an "Outbound" connection to look like:
var conn = new esl.Connection(socket[, readyCallback]);
The readyCallback is called once the connection is stored, the connect
command is issued, and a CHANNEL_DATA
event is received.
esl.Connection::sendRecv(command[, args][, body][, callback]);
This function according to the documentation is suppossed to send the command via esl.Connection::send()
(which it does), then call esl.Connection::recvEvent()
in a loop until it received the command/reply
ESLevent.
The reason it wants to do this (in addition to some crazy event queue specs) is to emulate an evented system;
but Node is already evented. Therefore this function will instead use the built-in node event system to
wait for esl::command::reply
(the event emitted by this library on command/reply
) then execute the callback
if one was passed.
esl.Connection::bgapi(command[, args][, jobid][, callback]);
The jobid
argument is not currently implemented and will be ignored.
esl.Connection::recvEvent(callback);
This function is part of the crazy event system FreeSWITCH has to implement in non-evented languages. Node has
a better event system than this, so all this function does is connection.once('esl::event::*', cb);
. You could
just do the same yourself, but the function is here to meet the interface.
Library Events
Below is a comprehensive list of the events that the library can emit, along with parameters, and description.
Both the esl.Connection
and esl.Server
objects use EventEmitter2
to send namespaced events. For example every event raises the esl::event::EVENT_NAME::EVENT_UUID
event, where
EVENT_NAME
is the name of the event and EVENT_UUID
is the uuid of the event. Listening to esl::event::**
will
give you every event with any name with any uuid; whereas esl::event::MESSAGE::*
will give you only each MESSAGE
event, reguardless of uuid.
Note that two asterisks ('**'
) with match anything accross multiple delimiters ('::'
); while one asterisk does
not match accross delimiters. That is esl::**
will match esl::connect
, esl::event::EVENT_NAME
, etc.; while
esl::*
will only match esl::connect
, esl::ready
, and esl::end
esl.Connection
Events
Here is the event list (with some wildcards) in the form of event_name(param1 {type1}, ..., paramN {typeN})
:
error(err {Error})
- An error has occurred, this is not namespaced to
esl::
as to match node's error event system
<dt><code>esl::connect()</code></dt>
<dd>The connection has connected to FSW, but has not authenticated.</dd>
<dt><code>esl::ready()</code></dt>
<dd>The connection is ready; it is both connected and authenticated.</dd>
<dt><code>esl::end()</code></dt>
<dd>The connection to FreeSWITCH has closed</dd>
<dt><code>esl::**([evt {esl.Event}])</code></dt>
<dd>Will pick up any esl event emitted from the Library, including <code>connect</code> and other events with no parameters</dd>
<dt><code>esl::event::**(evt {esl.Event})</code></dt>
<dd>Called each time an event is picked up from FSW by the Client</dd>
<dt><code>esl::event::EVENT_NAME::*(evt {esl.Event})</code></dt>
<dd>Each event is emitted on this channel where <CODE>EVENT_NAME</CODE> is the Event's <code>Event-Name</code> header value</dd>
<dt><code>esl::event::EVENT_NAME::EVENT_UUID(evt {esl.Event})</code></dt>
<dd>Each event is emitted with a UUID, the <CODE>EVENT_UUID</CODE> is determined by first checking for a <code>Job-UUID</code> (background job uuid), then <code>Unique-ID</code> (channel uuid), and finally the <code>Core-UUID</code> (message's uuid). This to track a particular job, channel, or message stream.</dd>
<dt><code>esl::event::auth::*([evt {esl.Event}])</code></dt>
<dd>Picks up any auth event, whether it is <code>request</code>, <code>success</code>, or <code>fail</code></dd>
<dt><code>esl::event::auth::request(evt {esl.Event})</code></dt>
<dd>FSW has requested authentication from the Library; The Library with auth for you.</dd>
<dt><code>esl::event::auth::success()</code></dt>
<dd>Authentication with FSW has passed; the `readyCallback`, if specified, is also called.</dd>
<dt><code>esl::event::auth::fail()</code></dt>
<dd>Authentication with FSW has failed</dd>
<dt><code>esl::event::command::reply(evt {esl.Event})</code></dt>
<dd>A reply to an issued command has come back</dd>
<dt><code>esl::event::api::response(evt {esl.Event})</code></dt>
<dd>A response to an issued api command has come back</dd>
<dt><code>esl::event::log::data(evt {esl.Event})</code></dt>
<dd>A log event from FSW</dd>
<dt><code>esl::event::disconnect::notice(evt {esl.Event})</code></dt>
<dd>FSW has notified the library it will be disconnected</dd>
<dt><code>esl::event::raw::*(evt {esl.Event})</code></dt>
<dd>Captures any raw event that had a Content-Type the Library did not parse</dd>
<dt><code>esl::event::raw::CONTENT_TYPE(evt {esl.Event})</code></dt>
<dd>Any Content-Type not parsed by the library is emmited on this channel, where `CONTENT_TYPE` is the Event's `Content-Type` header value</dd>
esl.Server
Events
Here is the event list in the form of event_name(param1 {type1}, ..., paramN {typeN})
:
connection::open(connection {esl.Connection})
- FreeSWITCH has opened a connection to the server, however the connection object is not ready to be used yet
<dt><code>connection::ready(connection {esl.Connection})</code></dt>
<dd>A newly opened connection is now ready to be used</dd>
<dt><code>connection::close(connection {esl.Connection})</code></dt>
<dd>A connection has been closed</dd>
Library API
Since this library implements the Event Socket Library
interface, the API is the same as on that page. The code is also heavily commented describing each
function in full. However, since some function prototypes changed slightly in translation, and for quick
reference they are listed below in the form function_name(param1 {type1}, ..., paramN {typeN})
:
esl
(Module Export)
esl.setLogLevel([level {number}])
esl.Connection
esl.Event
esl.Server
esl.Connection
Connection(host {string}, port {number}, password {string}[, readyCallback {function}]);
(ctor)Connection(socket {net.Socket}[, readyCallback {function}]);
(ctor)socketDescriptor();
connected()
getInfo()
send(command {string}, args {object})
sendRecv(command {string}[, args {object}][, body {string}][, callback {function}])
api(command {string}[, args {array}][, callback {function}])
bgapi(command {string}[, args {array}][, callback {function}])
sendEvent(name {string}, event {esl.Event}[, callback {function}])
recvEvent(callback {function})
recvEventTimed(ms {number}[, callback {function}])
filter(header {string}, value {string}[, callback {function}])
events(type {string:'plain'|'xml'|'json'}, events {string,array}[, callback {function}])
execute(app {?}, arg {?}, uuid {string})
(NOT IMPLEMENTED)executeAsync(app {?}, arg {?}, uuid {string})
(NOT IMPLEMENTED)setAsyncExecute(value {boolean})
setEventLock(value {boolean})
disconnect()
auth([callback {function}])
subscribe(events {string|array}[, callback {function}]
originate(profile {string}, gateway {string}, number {string}[, app {string}][, sync {boolean}][, callback {function}])
message(to {string}, from {string}, profile {string}, body {string}[, subject {string}][, callback])
esl.Event
Event.PRIORITY
(object containing valid priorities)Event(type {string}[, subclass {string}])
(ctor)Event(headers {object}[, body {string}])
(ctor)serialize([format {string:'plain'|'xml'|'json'}])
(defaults to 'plain')setPriority(priority {esl.Event.PRIORITY})
getHeader(name {string})
getBody()
getType()
addBody(value {string})
(appends to current body)addHeader(name {string}, value {string})
(if name
exists, overwrites value)delHeader(name {string})
firstHeader()
nextHeader()
esl.Server
Server([options {object}][, readyCb {function}])
readyCb
is called once the server is listening for connectionsoptions
defaults to the following:
{ port: 8022, host: '127.0.0.1', server: null }
- If server is specified it will be used instead of creating a server (and port/host will be ignored)
- WARNING: Only pass a
server
after its listening
event has been fired.
TODO
- Add tests for
esl.Connection
, esl.Parser
, and esl.Server
- Add more examples for
- SMS Messaging
- IVR App
- Faxing App
- fs_cli clone
- Add more abstraction/sugar functions
- Build out the Wiki and trim down the README
- Add LICENSE file
- Implement the logging of
log/data
events - Implement
bgapi
's jobid
parameter - Better error messages on
error
event
License
This module is distributed under the Mozilla Public License 2.0.