diff --git a/docs/configuration.rst b/docs/configuration.rst index b51ad6c3b..95d4e1d9c 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -4,7 +4,7 @@ 4.1. cgr-rater configuration file --------------------------------- -Organized into configuration sections. All configuration options come with defaults and we have tried our best to choose the best ones for a minimum of efforts necessary to run. +Organized into configuration sections. All configuration options come with defaults and we have tried our best to choose the best ones for a minimum of efforts necessary when running. Bellow is the default configuration file which comes hardcoded into cgr-rater. diff --git a/docs/freeswitch.rst b/docs/freeswitch.rst new file mode 100644 index 000000000..9882fe5c3 --- /dev/null +++ b/docs/freeswitch.rst @@ -0,0 +1,82 @@ +8.1. FreeSWITCH integration +================================ + +FreeSWITCH_ used as Telecom Switch is fully supported by all of the 3 rating modes: prepaid/postpaid/pseudoprepaid. +A typical use case would be like the one in the diagram bellow: + +.. image:: images/CGRateSFSTypicalUsage.png + +The process of rating is decoupled into two different components: + +8.1.1. SessionManager +--------------------- + +- Attached to FreeSWITCH_ via the socket library, enhancing CGRateS with real-time call monitoring and call control functions. +- In Prepaid mode implements the following behaviour: + - On *CHANNEL_PARK* event received from FreeSWITCH_: + - Authorize the call by calling *GetMaxSessionTime* on the Rater. + - Sets the channel variable *cgr_notify* via *uuid_setvar* to one of the following values: + - MISSING_PARAMETER: if one of the required channel variables is missing and CGRateS cannot make rating. + - SYSTEM_ERROR: if rating could not be performed due to a system error. + - INSUFFICIENT_FUNDS: if MaximSessionTime is 0. + - AUTH_OK: Call is authorized to proceed. + - Un-Park the call via *uuid_transfer* to original dialed number. The FreeSWITCH_ administrator is expected to make use of *cgr_notify* variable value to either allow the call going further or reject it (eg: towards an IVR or returning authorization fail message to call originator). + - On *CHANNEL_ANSWER* event received: + - Starts debit loop by calling at configured interval *MaxDebit* on the Rater. + - If any of the debits fail: + - Set *cgr_notify* channel variable to either SYSTEM_ERROR in case of errors or INSUFFICIENT_FUNDS of there would be not enough balance for the next debit to proceed. + - Send *hangup* command with cause *MANAGER_REQUEST*. + + - On *CHANNEL_HANGUP_COMPLETE* event received: + - Refund the reserved balance back to the user's account (works for both monetary and minutes debited). + - Save call costs into CGRateS LogDB. + +- In Postpaid mode: + - On *CHANNEL_ANSWER* event received: + - Index the call into CGRateS's cache + - On *CHANNEL_HANGUP_COMPLETE* event received: + - Call *Debit* RPC method on the Rater. + - Save call costs into CGRateS LogDB. + +- On CGRateS Shutdown execute, for security reasons, hangup commands on calls which can be CGR related: + - *hupall MANAGER_REQUEST cgr_reqtype prepaid* + - *hupall MANAGER_REQUEST cgr_reqtype postpaid* + + +8.1.2. Mediator +--------------- + +Attaches costs to FreeSWITCH_ native written .csv files. Since writing channel variables during hangup is asynchronous and can be missed by the CDR recorder mechanism of FreeSWITCH_, we decided to keep this as separate process after the call is completed and do not write the costs via channel variables. + + +8.1.2.1. Modes of operation +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Mediator process for FreeSWITCH works in two different modes: + +- Costs from LogDB (activated by setting -1 as *subject_idx* in the *cgrates.cfg*: + - Queries LogDB for a previous saved price by SessionManager. + - This behavior is typical for prepaid/postpaid calls which were previously processed by SessionManager and important in the sense that we write in CDRs exactly what was billed real-time from user's account. +- Costs queried from Rater: + - This mode is specific for multiple process mediation and does not necessary reflect the price which was deducted from the user's account during real-time rating. + - Another application for this mode is pseudoprepaid when there is no SessionManager monitoring and charging calls in real-time (debit done directly from CDRs). + - This mode is triggered from configuration file by setting proper indexes (or leave them defaults if cgrates rating template is using whitin FreeSWITCH_ cdr_csv configuration file. + +A typical usage into our implementations is a combination between the two modes of operation (by setting at a minimum -1 as subject_idx to run from LogDB and succesive mediation processes with different indexes). + + +8.1.2.2. Implementation logic +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- The Mediator process is configured and started in the *cgrates.cfg* file and is alive as long as the *cgr-rater* application is on. +- To avoid concurrency issues, the Mediator does not process active maintained CDR csv files by FreeSWITCH_ but picks them up as soon as FreeSWITCH_ has done with them by rotating. The information about rotation comes in real-time on the Linux OS through the use of inotify. +- Based on configured indexes in the configuration file, the Mediator will start multiple processes for the same CDR. +- For each mediation process configured the Mediator will apped the original CDR with costs calculated. In case of errors of some kind, the value *-1* will be prepended. +- When mediation is completed on a file, the file will be moved to configured *cdr_out_dir* path. + + + + +.. _FreeSWITCH: http://www.freeswitch.org + + diff --git a/docs/images/CGRateSFSTypicalUsage.png b/docs/images/CGRateSFSTypicalUsage.png new file mode 100644 index 000000000..586d6752d Binary files /dev/null and b/docs/images/CGRateSFSTypicalUsage.png differ diff --git a/docs/introduction.rst b/docs/introduction.rst index b90b08e84..660c5e7a0 100644 --- a/docs/introduction.rst +++ b/docs/introduction.rst @@ -2,10 +2,11 @@ ============== CGRateS is a very fast and easy scalable rating engine targeted especially for ISPs and Telecom Operators. -It is written in Go (http://golang.org) and accessible from any language via JSON RPC. The code is well documented (go doc compliant API docs) and heavily tested. +It is written in Go_ and accessible from any language via JSON RPC. The code is well documented (go doc compliant API docs) and heavily tested. After testing various databases like Kyoto_ cabinet, Redis_ or Mongodb_, the project focused on Redis as it delivers the best trade-off between speed, configuration and scalability. Despite that a connection to any database can be easily integrated by writing a simple adapter. +.. _Go: http://golang.org .. _kyoto: http://fallabs.com/kyotocabinet .. _Redis: http://redis.io .. _Mongodb: http://www.mongodb.org diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst index 201f7a098..edc035252 100644 --- a/docs/miscellaneous.rst +++ b/docs/miscellaneous.rst @@ -1,2 +1,7 @@ 8. Miscellaneous ================ + +.. toctree:: + :maxdepth: 2 + + freeswitch diff --git a/sessionmanager/session.go b/sessionmanager/session.go index ccded4cea..b85d617c7 100644 --- a/sessionmanager/session.go +++ b/sessionmanager/session.go @@ -77,7 +77,7 @@ func NewSession(ev Event, sm SessionManager) (s *Session) { return } -// the debit loop method (to be stoped by sending somenting on stopDebit channel) +// the debit loop method (to be stoped by sending somenthing on stopDebit channel) func (s *Session) startDebitLoop() { nextCd := *s.callDescriptor index := 0.0