cachedb_cassandra Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Advantages
        1.3. Limitations
        1.4. Dependencies

              1.4.1. OpenSIPS Modules
              1.4.2. External Libraries or Applications

        1.5. Exported Parameters

              1.5.1. cachedb_url (string)
              1.5.2. connect_timeout (int)
              1.5.3. query_timeout (int)
              1.5.4. wr_consistency_level (int)
              1.5.5. rd_consistency_level (int)
              1.5.6. exec_threshold (int)

        1.6. Exported Functions
        1.7. Table Schema

   2. Contributors

        2.1. By Commit Statistics
        2.2. By Commit Activity

   3. Documentation

        3.1. Contributors

   List of Tables

   2.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   2.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Set cachedb_url parameter
   1.2. Use Cassandra servers
   1.3. Set connect_timeout parameter
   1.4. Set query_timeout parameter
   1.5. Set wr_consistency_level parameter
   1.6. Set rd_consistency_level parameter
   1.7. Set exec_threshold parameter

Chapter 1. Admin Guide

1.1. Overview

   This module is an implementation of a cache system designed to
   work with Cassandra servers. It uses the Key-Value interface
   exported from the core.

   The underlying client library is compatible with Cassandra
   versions 2.1+.

1.2. Advantages

     * memory costs are no longer on the server
     * many servers can be used inside a cluster, so the memory is
       virtually unlimited
     * the cache is 100% persistent. A restart of OpenSIPS server
       will not affect the DB. The Cassandra DB is also persistent
       so it can also be restarted without loss of information.
     * Cassandra is an open-source project so it can be used to
       exchange data with various other applications
     * By creating a Cassandra Cluster, multiple OpenSIPS
       instances can easily share key-value information

1.3. Limitations

     * keys (in key:value pairs) may not contain spaces or control
       characters

1.4. Dependencies

1.4.1. OpenSIPS Modules

   None.

1.4.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * libuv
     * cassandra-cpp-driver

   The DataStax C/C++ driver for Cassandra and the libuv
   dependency can be downloaded from:
   http://downloads.datastax.com/cpp-driver/.

1.5. Exported Parameters

1.5.1. cachedb_url (string)

   The urls of the server groups that OpenSIPS will connect to in
   order to use the from script cache_store,cache_fetch, etc
   operations. It can be set more than one time. The prefix part
   of the URL will be the identifier that will be used from the
   script.

   Cassandra does not support regular columns in a table that
   contains any counter columns so in order to use the
   add()/sub()/get_counter() methods in the Key-Value Interface
   you can specify an extra table reserved only for counters.

   The database part of the URL needs to be in the format
   Keyspace.Table[.CountersTable].

   Example 1.1. Set cachedb_url parameter
...
modparam("cachedb_cassandra", "cachedb_url",
        "cassandra:group1://localhost:9042/keyspace1.users.counters");

# Defining multiple contact points for a Cassandra cluster
modparam("cachedb_cassandra", "cachedb_url",
        "cassandra:cluster1://10.0.0.10,10.0.0.15/keyspace2.keys.counter
s");
...

   Example 1.2. Use Cassandra servers
...
cache_store("cassandra:group1","key","$ru value");
cache_fetch("cassandra:cluster1","key",$avp(10));
cache_remove("cassandra:cluster1","key");
...

1.5.2. connect_timeout (int)

   The timeout in ms that will be triggered in case a connection
   attempt fails.

   Default value is “5000”.

   Example 1.3. Set connect_timeout parameter
...
modparam("cachedb_cassandra", "connect_timeout",1000);
...

1.5.3. query_timeout (int)

   The timeout in ms that will be triggered in case a Cassandra
   query takes too long.

   Default value is “5000”.

   Example 1.4. Set query_timeout parameter
...
modparam("cachedb_cassandra", "query_timeout",1000);
...

1.5.4. wr_consistency_level (int)

   The consistency level desired for write operations. Options are
   :
     * all - A write must be written to the commit log and
       memtable on all replica nodes in the cluster for that
       partition.
     * each_quorum - Strong consistency. A write must be written
       to the commit log and memtable on a quorum of replica nodes
       in each datacenter.
     * quorum - A write must be written to the commit log and
       memtable on a quorum of replica nodes across all
       datacenters.
     * local_quorum - Strong consistency. A write must be written
       to the commit log and memtable on a quorum of replica nodes
       in the same datacenter as the coordinator. Avoids latency
       of inter-datacenter communication.
     * one - A write must be written to the commit log and
       memtable of at least one replica node.
     * two - A write must be written to the commit log and
       memtable of at least two replica node.
     * three - A write must be written to the commit log and
       memtable of at least three replica node.
     * local_one - A write must be sent to, and successfully
       acknowledged by, at least one replica node in the local
       datacenter.
     * any - A write must be written to at least one node. If all
       replica nodes for the given partition key are down, the
       write can still succeed after a hinted handoff has been
       written. If all replica nodes are down at write time, an
       ANY write is not readable until the replica nodes for that
       partition have recovered.

   Default value is one.

   Example 1.5. Set wr_consistency_level parameter
...
modparam("cachedb_cassandra", "wr_consistency_level", "each_quorum");
...

1.5.5. rd_consistency_level (int)

   The consistency level desired for write operations. Options are
   :
     * all - Returns the record after all replicas have responded.
       The read operation will fail if a replica does not respond.
     * quorum - Returns the record after a quorum of replicas from
       all datacenters has responded.
     * local_quorum - Returns the record after a quorum of
       replicas in the current datacenter as the coordinator has
       reported. Avoids latency of inter-datacenter communication.
     * one - Returns a response from the closest replica, as
       determined by the snitch. By default, a read repair runs in
       the background to make the other replicas consistent.
     * two - Returns the most recent data from two of the closest
       replicas.
     * three - Returns the most recent data from three of the
       closest replicas.
     * local_one - Returns a response from the closest replica in
       the local datacenter.
     * serial - Allows reading the current (and possibly
       uncommitted) state of data without proposing a new addition
       or update. If a SERIAL read finds an uncommitted
       transaction in progress, it will commit the transaction as
       part of the read. Similar to QUORUM.
     * local_serial - Same as SERIAL, but confined to the
       datacenter. Similar to LOCAL_QUORUM.

   Default value is one.

   Example 1.6. Set rd_consistency_level parameter
...
modparam("cachedb_cassandra", "rd_consistency_level", "quorum");
...

1.5.6. exec_threshold (int)

   A cassandra cache query that lasts more than this threshold
   will trigger a warning message to the log.

   This value, if set, only makes sense to be lower than the
   query_timeout since any query taking longer than that value
   will be dropped anyway.

   Default value is “0 ( unlimited - no warnings )”.

   Example 1.7. Set exec_threshold parameter
...
modparam("cachedb_cassandra", "exec_threshold", 100000)
...

1.6. Exported Functions

   The module does not export functions to be used in
   configuration script.

1.7. Table Schema

   The table required for supporting the
   cache_store()/cache_fetch()/cache_remove() functions of the
   Key-Value interface needs to have at least the following
   columns:
     * opensipskey - as the primary key with type "text"
     * opensipsval - with type "text"

   The table required for supporting the
   cache_add()/cache_sub()/cache_counter_fetch() functions of the
   Key-Value interface needs to have at least the following
   columns:
     * opensipskey - as the primary key with type "text"
     * opensipsval - with type "counter"

Chapter 2. Contributors

2.1. By Commit Statistics

   Table 2.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Vlad Patrascu (@rvlad-patrascu) 373 13 1998 21057
   2. Vlad Paiu (@vladpaiu) 188 7 21444 38
   3. Liviu Chircu (@liviuchircu) 11 9 39 50
   4. Razvan Crainea (@razvancrainea) 8 6 16 14
   5. fabriziopicconi 4 2 5 5
   6. Maksym Sobolyev (@sobomax) 4 2 3 3
   7. Bogdan-Andrei Iancu (@bogdan-iancu) 4 2 3 1
   8. Julián Moreno Patiño 3 1 1 1
   9. Peter Lemenkov (@lemenkov) 3 1 1 1
   10. Jarrod Baumann (@jarrodb) 2 1 2 0

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

2.2. By Commit Activity

   Table 2.2. Most recently active contributors^(1) to this module
                      Name                   Commit Activity
   1.  Maksym Sobolyev (@sobomax)          Feb 2023 - Feb 2023
   2.  Liviu Chircu (@liviuchircu)         Mar 2014 - Apr 2021
   3.  Razvan Crainea (@razvancrainea)     Feb 2012 - Jan 2021
   4.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Jun 2020
   5.  Bogdan-Andrei Iancu (@bogdan-iancu) Oct 2014 - Apr 2019
   6.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   7.  Julián Moreno Patiño                Feb 2016 - Feb 2016
   8.  Jarrod Baumann (@jarrodb)           May 2015 - May 2015
   9.  fabriziopicconi                     Apr 2014 - Apr 2014
   10. Vlad Paiu (@vladpaiu)               Dec 2011 - Nov 2013

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Vlad Patrascu (@rvlad-patrascu), Peter Lemenkov
   (@lemenkov), Liviu Chircu (@liviuchircu), Julián Moreno Patiño,
   Vlad Paiu (@vladpaiu), Razvan Crainea (@razvancrainea).

   Documentation Copyrights:

   Copyright © 2011 www.opensips-solutions.com
