====== New LCR Module Design (proposal) ======

A new design for Kamailio's LCR module making it simpler, more powerful, and easier to manage via an admin interface.
===== Introduction =====

Current LCR module lacks some useful features and it's hard to manage via an admin interface due to the complexity and not good relationship between its DB tables.

Some of the current design issues are:
  * LCR rule definitions are mixed with rule steps/targets in same 'lcr' table.
  * In order to reuse some gateway in two different groups it's required to duplicate all the information for the given gateway (ip, port, flags, ping...).
  * Summarizing, making an admin interface for LCR tables is difficult as the current design doesn't follow a good pattern.

Some desired features would be:
  * There si no way to make a rule stop if it fails to handle the request and we don't want other matching rules to be loaded (i.e: "I want calls to 001 just to use gw3 and not to use default gateways, those belonging to rule with NULL prefix, if gw3 is down).
  * Rules should be disabled without having to delete them.

In order to simplify implementation and use, gateway groups are no longer supported.  Instead, gateways are directly specified as rule targets, where each rule target has a priority and weight.


===== New DB schema =====
==== lcr_rule ====

^ Column           ^ Description                                   ^ Possible values   ^ Default value ^
| id               | Primary key: identifier of this rule        | Integer | |
| lcr_id           | Identifier of LCR instance                  | Integer | |
| prefix           | Prefix of Request URI user part             | NULL / String | NULL |
| from_uri         | Regular expression to match the From URI (or given pseudo-variable) | NULL / String (regular expression) | NULL |
| stopper          | If it's 1 no other rules would be inspected after finding this one | Integer (1=on / 0=off) | 0 |
| enabled          | Is it this rule active so it can be loaded?   | Integer (1=on / 0=off) | 1 |

Keys:
  * PRIMARY KEY: //id//
  * UNIQUE: //lcr_id// + //prefix// + //from_uri//
==== lcr_rule_target table ====

^ Column           ^ Description                                   ^ Possible values   ^ Default value ^
| id               | Primary key                                 | Integer | |
| rule_id          | Integer pointing to the //id// of an entry in //lcr_rule// table | Integer | |
| gw_id            | Gateway for this rule target (points to //id// in //lcr_gw// table) | Integer | |
| priority         | Priority of this rule target within all targets for the same rule | Integer (0-255) | |
| weight           | Weight of this rule target within all equal priority targets for the same rule | Integer (1-254) | |

Keys:
  * PRIMARY KEY: //id//
  * UNIQUE: //rule_id// + //gw_id//
  * INDEX: //rule_id//
==== lcr_gw table ====

^ Column           ^ Description                                   ^ Possible values   ^ Default value ^
| id               | Primary key, identifier of the gateway        | Integer | |
| lcr_id           | Identifier of LCR instance                    | Integer | |
| gw_name          | Name of the gateway (only for documentation)  | String | NULL |
| ip_addr          | IP of the gateway                             | NULL / String | NULL |
| port             | Port of the gateway                           | NULL (no port is added) / Integer (5060=sip / 5061=sips) | NULL |
| uri_scheme       | Scheme of the Request URI                     | NULL / Integer (NULL and 1 = sip / 2=sips) | NULL |
| transport        | Transport used for this gateway               | NULL (no transport is added) / Integer (0=udp / 1=tcp / 2=tls / 3=sctp) | NULL |
| params           | URI params to be added to Request URI         | NULL / String | NULL |
| hostname         | Hostname to set in Request URI host part      | NULL / String | NULL |
| strip            | Number of characters to be stripped from the front of Request URI user | NULL / Integer | NULL |
| tag              | Prefix to be added to Request URI user part after removing //strip// characters | NULL / String | NULL |
| flags            | Flags enabled when loading this gateway       | Integer | 0 |
| defunct          | Gateway is defunct until this Linux timestamp time            | NULL (= 0) / Integer | NULL |

Keys:
  * PRIMARY KEY: //id//
  * UNIQUE: //lcr_id// + //ip_addr// + //port// + //transport// + //hostname//


===== New module parameters, functions and flags =====
==== flag(DONT_STRIP_OR_TAG) ====

When calling //next_gw()// function the value of //flag(DONT_STRIP_OR_TAG)// is inspected. If it is set then //strip// and //tag// values of the selected gateway are ignored so the Request URI user part is not modified.

This is an optional module parameter. If it's not defined then //strip// and //tag// are always applied for each gateway.

An use case in which this flag is useful:

  * The PSTN gateway allows national format (NNNNNNNNN) and international format with "00" (00NNNNNNNNNNNN).
  * Kamailio is configured to normalize destination numbers to E.164 (+NNNNNNNNN) if the call is international, or leave it in national format (no E.164).
  * In this case it's required to replace "+" with "00" when such gateway is selected by LCR module.
  * But it's also required not to modify the RURI user part if the number format is national.

The following configuration would do the job:

  * //lcr_gw// entry for the PSTN gateway:
    * **strip:** 1
    * **tag:** 00

  * Script configuration:<code bash>
# This route ensures that the dialed number is in the form +XXXXXX
# (international E164) or national (XXXXXXX without + or 00):
route(NORMALIZE_NUMBER);

# Load gateways as usual.
load_gws(...);

# If the dialed number is national then enable the flag(DONT_USE_STRIP_TAG)
# to avoid the RURI user part being striped and tagged with gw values.
if !(starts_with("$rU", "+"))
  setflag(DONT_STRIP_OR_TAG);
  
next_gw();
</code>