[![Build Status](https://travis-ci.org/shimaore/tough-rate.svg?branch=master)](https://travis-ci.org/shimaore/tough-rate)

About
=====

`tough-rate` is a Least Cost Routing (LCR) application for FreeSwitch.

It runs under Node.js and uses CouchDB for provisioning.

It is part of the [CCNQ SoftSwitch](http://ccnq.shimaore.net/).

Controlling Records
===================

Gateway Attributes
------------------

The following parameters are common to all gateways, they might be inserted by carrier records, gateways definitions, rulesets, destination, individual rules, or individual item in a `gwlist`.
They are all optional.

    disabled          (default false)
    progress_timeout  (default 4)  from invite to progress (180, 183, ...) - maximum post-dial-delay
    answer_timeout    (default 90) from progress to answer (200) - maximum ringback time
    dialog_timeout    (default 28800) from answer to end - maximum call duration
    attrs             (default {})

The following attributes are available as well, but generally not defined at the gateway level:

    priority          (default: 0 for the last gateway in a list, 1 for the previous one, etc.)
    local_gateway_extra_priority (default 0.5)  added to priority if the gateway is on the same host
    weight            (default 1, must be > 0)
    gwlist            (default [])

Different attribute values might be present. They are always resolved in the following order: default, carrier, gateway, ruleset, destination, rule, gwlist entry.

The values in `attrs` are merged, the most specific value is kept.
The values for `disabled` are ORed so that any item disabled in the list will disable.

gateway (individual gateway records)
------------------------------------

    _id: "gateway:#{sip_domain_name}:#{gwid}"
    type: 'gateway'

    sip_domain_name
    gwid
    address           (required) "#{ip}:#{host}", DNS name
    carrierid         (optional)

    disabled
    progress_timeout
    answer_timeout
    dialog_timeout
    attrs

gateway (as part of host)
-------------------------

Gateways are defined inside `sip_profiles`; the following fields are available inside a given `sip_profiles` entry:

    egress.gwid
    egress.carrierid

    egress.disabled
    egress.progress_timeout
    egress.answer_timeout
    egress.dialog_timeout
    egress.attrs

The following gateway fields do not need to be specified:
- `address` is computed based on the profile's data;
- `sip_domain_name` is taken from the host.

carrier
-------

A carrier offers one or more gateways.

A carrier is indicated alongside a gateway definition, either inside a `gateway` record, or in the `sip_profiles` part of a host definition.

A carrier record might optionally be created to provide carrier-wide default values for the gateways listed under that carrier.

    _id: "carrier:{sip_domain_name}:{carrierid}"
    type: 'carrier'

    sip_domain_name
    carrierid
    try (default 1, must be > 0)

    local_gateway_extra_priority
    disabled
    progress_timeout
    answer_timeout
    dialog_timeout
    attrs

ruleset
-------

Rulesets records are found in the main provisioning database.

    _id: "ruleset:#{sip_domain_name}:#{groupid}"
    type: 'ruleset'
    sip_domain_name
    groupid
    title
    description
    database

    disabled
    attrs

The title is the name shown in the management tools.
The description is a longer description of what this ruleset is about.
The database indicates the name of the database used to store the ruleset.

Rules
=====

Rules are defined in a ruleset database. There is one ruleset database per ruleset.

The gwlist is converted into a list of gateways as follows:
- Each record in the list is assigned an additional priority, starting from 0 for the last item in the list and adding 1 going backwards in the list.
- Records which have a `carrierid` and no `gwid` are replaced with a list of the gateways for that carrierid, up to `try` entries. The value of `try` defaults to the number of gateways for that carrier. Gateways are selected using weighted round-robin.
- Records which have a `gwid` are gateways. Other records are rejected.
- Any gateway local to the host receives an additional `local_gateway_priority` (by default 0.5).
- In the resulting list, gateways are sorted by descending priority if no `weight` field is present.

destination
-----------

A destination record might be referenced by a prefix in order to provide values for that prefix.

    _id: "destination:#{destination}"
    type: 'destination'
    destination: destination

    disabled

    gwlist: [
      {gwid, weight, attrs,...}
      {carrierid, weight, try, attrs,...}
    ]

    progress_timeout
    answer_timeout
    dialog_timeout
    attrs

`prefix` record
---------------

Prefixes are first looked-up in `prefix` records:

    _id: "prefix:{prefix}"
    type: 'prefix'
    prefix: "{prefix}"

    disabled

    destination: "{destination}"

Sometimes it is more convenient to store data directly inside the prefix:

    _id: "prefix:{prefix}"
    type: 'prefix'
    prefix: "{prefix}"

    gwlist: [
      {gwid, weight, attrs,...}
      {carrierid, weight, try, attrs,...}
    ]

    disabled
    progress_timeout
    answer_timeout
    dialog_timeout
    attrs