13.1.0 • Public • Published

    FreeSwitch controlled by Node.js middleware

    useful-wind is a middleware framework for FreeSwitch. This module extends useful-wind with web and notification services to support call-handling. This module also provides a working FreeSwitch image as a Docker container under the name shimaore/thinkable-ducks.


    • Docker image with FreeSwitch and Node.js
    • FreeSwitch calls are controlled by Node.js using the Event Socket
    • Realtime notifications via extendable Socket.IO client


    Three processes are managed by a common supervisord instance:

    • the config application is ran once at startup to provide configuration, especially to create the FreeSwitch XML configuration file;
    • the server application provides the Event Socket handler, web services, etc.
    • FreeSwitch.

    Supervisord can be controlled using its HTTP interface.


    The config application will run any config middleware function.

    It will then create a FreeSwitch XML configuration file by rendering the freeswitch template in the configuration object. The templace could be an acoustic-line template, or any function that will return a valid FreeSwitch XML configuration file.

    Finally it will start the server application, and FreeSwitch itself.

    Note: if the configuration contains a server_only flag, no FreeSwitch configuration is created, and FreeSwitch is not started.


    The server application with first run any server_pre middleware function. This is used for example in the docker.tough-rate server module to initialize database access, etc.

    The application will then start the Event Socket server (useful-wind), the web service, and the notify service.

    Finally it will run any server_post middleware function.


    The web service provides by default:

    • GET /
    • GET /supervisor

    It may be extended by web middleware functions.

    Middleware modules

    Middleware modules are declared by setting cfg.use. They may contain the following fields:

    • name: the middleware name (string)
    • config: startup (function)
    • init: call-processing initialization (function)
    • include: call-processing middleware (function)
    • web: web service (function)
    • notify: notification service (function)

    The functions are executed as indicated below, in the order they are declared in the cfg.use array. They are executed inside a Promise chain and may therefor return Promises.

    config middlewares

    A thinkable-ducks middleware module may contain config-time middleware functions which are ran inside the config application. The config application is a separate process and runs before the server application and FreeSwitch are started.

    • config middleware in a context comprising of this.cfg.

    The this.cfg object is shared amongst all these functions, but not with the modules in the server application (since that application is a separate process and is ran after the config application is completed).

    server middlewares

    A thinkable-ducks middleware module may contain server-time middleware functions which are ran inside the server application. The server application is a Node.js process which runs concurrently to FreeSwitch.

    Some functions are executed by useful-wind:

    • init is ran after the call-router is created but before call-routing starts taking place; this is a good place to extend the cfg object with any application-specific call-processing-related data.
    • include is used to process FreeSwich calls.

    Some functions are executed by this module (thinkable-ducks):

    • web runs in the context of a zappajs application, extended with a this.cfg helper, and is used to provide web services.
    • notify runs in a context comprising of this.cfg and this.socket (the Socket.IO client), and is used to notify and receive notifications from e.g. a spicy-action server.

    The this.cfg object is shared amongst all these functions.


    An application is build out of middleware modules. The main application may look as follows.

    cfg = require process.env.CONFIG
    cfg.use = [
      require 'huge-play/middleware/setup'
      require 'huge-play/middleware/client/media'
      # etc. `require` any middleware module you might need
    # A renderable `acoustic-line` templace to generate
    # the FreeSwitch XML configuration.
    cfg.freeswitch = require 'tough-rate/conf/freeswitch'
    ducks = require 'thinkable-ducks'
    ducks cfg


    npm init

    coffee-script is required by the supervisord.conf scripts.

    npm install --save coffee-script

    Install any middleware package you may require (including your own packages).

    npm install --save thinkable-ducks huge-play tough-rate ...


    FROM shimaore/thinkable-ducks
    COPY . /opt/thinkable-ducks
    RUN npm install

    Build using

    docker build .


    npm i thinkable-ducks

    DownloadsWeekly Downloads






    Unpacked Size

    24.5 kB

    Total Files


    Last publish


    • shimaore