Rebuild documentation

OpenSIPS · Jan 12, 2025 · b1057bb · b1057bb
1 parent fe1a50d
commit b1057bb
Show file tree

Hide file tree

Showing 12 changed files with 338 additions and 188 deletions.
diff --git a/modules/cachedb_redis/README b/modules/cachedb_redis/README
@@ -7,22 +7,27 @@ cachedb_redis Module
 
         1.1. Overview
         1.2. Advantages
-        1.3. Limitations
-        1.4. Dependencies
+        1.3. Redis Stack Support
+        1.4. Limitations
+        1.5. Dependencies
 
-              1.4.1. OpenSIPS Modules
-              1.4.2. External Libraries or Applications
+              1.5.1. OpenSIPS Modules
+              1.5.2. External Libraries or Applications
 
-        1.5. Exported Parameters
+        1.6. Exported Parameters
 
-              1.5.1. cachedb_url (string)
-              1.5.2. connect_timeout (integer)
-              1.5.3. query_timeout (integer)
-              1.5.4. shutdown_on_error (integer)
-              1.5.5. use_tls (integer)
+              1.6.1. cachedb_url (string)
+              1.6.2. connect_timeout (integer)
+              1.6.3. query_timeout (integer)
+              1.6.4. shutdown_on_error (integer)
+              1.6.5. use_tls (integer)
+              1.6.6. ftsearch_index_name (string)
+              1.6.7. ftsearch_json_prefix (string)
+              1.6.8. ftsearch_max_results (integer)
+              1.6.9. ftsearch_json_mset_expire (integer)
 
-        1.6. Exported Functions
-        1.7. Raw Query Syntax
+        1.7. Exported Functions
+        1.8. Raw Query Syntax
 
    2. Contributors
 
@@ -50,7 +55,11 @@ cachedb_redis Module
    1.4. Set connect_timeout parameter
    1.5. Set the shutdown_on_error parameter
    1.6. Set the use_tls parameter
-   1.7. Redis Raw Query Examples
+   1.7. Set the ftsearch_index_name parameter
+   1.8. Set the ftsearch_json_prefix parameter
+   1.9. Set the ftsearch_max_results parameter
+   1.10. Set the ftsearch_json_mset_expire parameter
+   1.11. Redis Raw Query Examples
 
 Chapter 1. Admin Guide
 
@@ -75,20 +84,36 @@ Chapter 1. Admin Guide
      * By creating a Redis Cluster, multiple OpenSIPS instances
        can easily share key-value information
 
-1.3. Limitations
+1.3. Redis Stack Support
+
+   Starting with OpenSIPS 3.6, the cachedb_redis module implements
+   the column-oriented cacheDB API functions. This makes it a
+   suitable cacheDB storage in scenarios such as user location
+   federation and full-sharing, which require this API to be
+   available.
+
+   The implementation makes use of RedisJSON and RediSearch --
+   these relatively new features are available in Redis Stack
+   Server, instead of the usual Redis Server (Redis OSS project).
+   More documentation is available on the Redis website.
+
+   OpenSIPS will auto-detect availability of the RedisJSON support
+   when necessary and log the appropriate messages.
+
+1.4. Limitations
 
      * keys (in key:value pairs) may not contain spaces or control
        characters
 
-1.4. Dependencies
+1.5. Dependencies
 
-1.4.1. OpenSIPS Modules
+1.5.1. OpenSIPS Modules
 
    The following modules must be loaded before this module:
      * If a use_tls is defined, the tls_mgm module will need to be
        loaded as well.
 
-1.4.2. External Libraries or Applications
+1.5.2. External Libraries or Applications
 
    The following libraries or applications must be installed
    before running OpenSIPS with this module loaded:
@@ -102,9 +127,9 @@ Chapter 1. Admin Guide
        If TLS connections are enabled via the use_tls modparam,
        hiredis needs to be compiled with TLS support.
 
-1.5. Exported Parameters
+1.6. Exported Parameters
 
-1.5.1. cachedb_url (string)
+1.6.1. cachedb_url (string)
 
    The URLs of the server groups that OpenSIPS will connect to in
    order to use, from script, the cache_store(), cache_fetch(),
@@ -132,7 +157,7 @@ cache_fetch("redis:cluster1", "key", $avp(10));
 cache_remove("redis:cluster1", "key");
 ...
 
-1.5.2. connect_timeout (integer)
+1.6.2. connect_timeout (integer)
 
    This parameter specifies how many milliseconds OpenSIPS should
    wait for connecting to a Redis node.
@@ -145,7 +170,7 @@ cache_remove("redis:cluster1", "key");
 modparam("cachedb_redis", "connect_timeout",1000)
 ...
 
-1.5.3. query_timeout (integer)
+1.6.3. query_timeout (integer)
 
    This parameter specifies how many milliseconds OpenSIPS should
    wait for a query response from a Redis node.
@@ -158,7 +183,7 @@ modparam("cachedb_redis", "connect_timeout",1000)
 modparam("cachedb_redis", "query_timeout",1000)
 ...
 
-1.5.4. shutdown_on_error (integer)
+1.6.4. shutdown_on_error (integer)
 
    By setting this parameter to 1, OpenSIPS will abort startup if
    the initial connection to Redis is not possible. Runtime
@@ -173,7 +198,7 @@ modparam("cachedb_redis", "query_timeout",1000)
 modparam("cachedb_redis", "shutdown_on_error", 1)
 ...
 
-1.5.5. use_tls (integer)
+1.6.5. use_tls (integer)
 
    Setting this parameter will allow you to use TLS for Redis
    connections. In order to enable TLS for a specific connection,
@@ -207,20 +232,82 @@ modparam("cachedb_redis", "cachedb_url","redis://localhost:6379/?tls_dom
 ain=redis")
 ...
 
-1.6. Exported Functions
+1.6.6. ftsearch_index_name (string)
+
+   Only relevant with RedisJSON and RediSearch server-side
+   support.
+
+   A global index name to be used for all internal JSON full-text
+   search operations. Future extensions may add, e.g., a
+   connection-level index name setting.
+
+   Default value is "idx:usrloc".
+
+   Example 1.7. Set the ftsearch_index_name parameter
+
+modparam("cachedb_redis", "ftsearch_index_name", "ix::usrloc")
+
+
+1.6.7. ftsearch_json_prefix (string)
+
+   Only relevant with RedisJSON and RediSearch server-side
+   support.
+
+   A key naming prefix for all internally-created Redis JSON
+   objects (e.g. created with JSON.SET or JSON.MSET).
+
+   Default value is "usrloc:".
+
+   Example 1.8. Set the ftsearch_json_prefix parameter
+
+modparam("cachedb_redis", "ftsearch_json_prefix", "userlocation:")
+
+
+1.6.8. ftsearch_max_results (integer)
+
+   Only relevant with RedisJSON and RediSearch server-side
+   support.
+
+   The maximum number of results returned by each
+   internally-triggered FT.SEARCH JSON lookup query.
+
+   Default value is 10000 max results.
+
+   Example 1.9. Set the ftsearch_max_results parameter
+
+modparam("cachedb_redis", "ftsearch_max_results", 100)
+
+
+1.6.9. ftsearch_json_mset_expire (integer)
+
+   Only relevant with RedisJSON and RediSearch server-side
+   support.
+
+   A Redis EXPIRE timer to set/refresh on the JSON key after each
+   JSON.MSET operation (create the JSON or add/remove subkeys), in
+   seconds. A value of 0 disables the EXPIRE queries completely.
+
+   Default value is 3600 seconds.
+
+   Example 1.10. Set the ftsearch_json_mset_expire parameter
+
+modparam("cachedb_redis", "ftsearch_json_mset_expire", 7200)
+
+
+1.7. Exported Functions
 
    The module does not export functions to be used in
    configuration script.
 
-1.7. Raw Query Syntax
+1.8. Raw Query Syntax
 
    The cachedb_redis module allows to run RAW queries, thus taking
    full advantage of the capabilities of the back-end. The query
    syntax is the typical REDIS one.
 
    Here are a couple examples of running some Redis queries :
 
-   Example 1.7. Redis Raw Query Examples
+   Example 1.11. Redis Raw Query Examples
 ...
         $var(my_hash) = "my_hash_name";
         $var(my_key) = "my_key_name";
@@ -257,8 +344,8 @@ Chapter 2. Contributors
    Table 2.1. Top contributors by DevScore^(1), authored
    commits^(2) and lines added/removed^(3)
      Name DevScore Commits Lines ++ Lines --
-   1. Vlad Paiu (@vladpaiu) 33 19 1446 50
-   2. Liviu Chircu (@liviuchircu) 29 19 558 277
+   1. Liviu Chircu (@liviuchircu) 42 22 1719 287
+   2. Vlad Paiu (@vladpaiu) 33 19 1446 50
    3. Razvan Crainea (@razvancrainea) 16 13 130 35
    4. Vlad Patrascu (@rvlad-patrascu) 12 6 595 38
    5. Bogdan-Andrei Iancu (@bogdan-iancu) 7 5 7 5
@@ -292,9 +379,9 @@ Chapter 2. Contributors
 
    Table 2.2. Most recently active contributors^(1) to this module
                       Name                   Commit Activity
-   1.  Vlad Paiu (@vladpaiu)               Oct 2011 - Nov 2024
-   2.  tcresson                            Oct 2023 - Oct 2023
-   3.  Liviu Chircu (@liviuchircu)         Mar 2014 - Oct 2023
+   1.  Liviu Chircu (@liviuchircu)         Mar 2014 - Jan 2025
+   2.  Vlad Paiu (@vladpaiu)               Oct 2011 - Nov 2024
+   3.  tcresson                            Oct 2023 - Oct 2023
    4.  zhengsh                             Aug 2023 - Aug 2023
    5.  Maksym Sobolyev (@sobomax)          Feb 2023 - Feb 2023
    6.  John Burke (@john08burke)           Apr 2022 - Apr 2022

diff --git a/modules/cachedb_redis/doc/contributors.xml b/modules/cachedb_redis/doc/contributors.xml
@@ -20,20 +20,20 @@
 	<tbody>
 	<row>
 		<entry>1. </entry>
+		<entry>Liviu Chircu (<ulink url="https://github.com/liviuchircu">@liviuchircu</ulink>)</entry>
+		<entry align="center">42</entry>
+		<entry align="center">22</entry>
+		<entry align="center">1719</entry>
+		<entry align="center">287</entry>
+	</row>
+	<row>
+		<entry>2. </entry>
 		<entry>Vlad Paiu (<ulink url="https://github.com/vladpaiu">@vladpaiu</ulink>)</entry>
 		<entry align="center">33</entry>
 		<entry align="center">19</entry>
 		<entry align="center">1446</entry>
 		<entry align="center">50</entry>
 	</row>
-	<row>
-		<entry>2. </entry>
-		<entry>Liviu Chircu (<ulink url="https://github.com/liviuchircu">@liviuchircu</ulink>)</entry>
-		<entry align="center">29</entry>
-		<entry align="center">19</entry>
-		<entry align="center">558</entry>
-		<entry align="center">277</entry>
-	</row>
 	<row>
 		<entry>3. </entry>
 		<entry>Razvan Crainea (<ulink url="https://github.com/razvancrainea">@razvancrainea</ulink>)</entry>
@@ -128,18 +128,18 @@
 	<tbody>
 	<row>
 		<entry>1. </entry>
-		<entry>Vlad Paiu (<ulink url="https://github.com/vladpaiu">@vladpaiu</ulink>)</entry>
-		<entry align="center">Oct 2011 - Nov 2024</entry>
+		<entry>Liviu Chircu (<ulink url="https://github.com/liviuchircu">@liviuchircu</ulink>)</entry>
+		<entry align="center">Mar 2014 - Jan 2025</entry>
 	</row>
 	<row>
 		<entry>2. </entry>
-		<entry>tcresson</entry>
-		<entry align="center">Oct 2023 - Oct 2023</entry>
+		<entry>Vlad Paiu (<ulink url="https://github.com/vladpaiu">@vladpaiu</ulink>)</entry>
+		<entry align="center">Oct 2011 - Nov 2024</entry>
 	</row>
 	<row>
 		<entry>3. </entry>
-		<entry>Liviu Chircu (<ulink url="https://github.com/liviuchircu">@liviuchircu</ulink>)</entry>
-		<entry align="center">Mar 2014 - Oct 2023</entry>
+		<entry>tcresson</entry>
+		<entry align="center">Oct 2023 - Oct 2023</entry>
 	</row>
 	<row>
 		<entry>4. </entry>

diff --git a/modules/dispatcher/README b/modules/dispatcher/README
@@ -1516,7 +1516,7 @@ Chapter 3. Contributors
    commits^(2) and lines added/removed^(3)
      Name DevScore Commits Lines ++ Lines --
    1. Bogdan-Andrei Iancu (@bogdan-iancu) 169 108 3331 2025
-   2. Liviu Chircu (@liviuchircu) 109 70 1670 1433
+   2. Liviu Chircu (@liviuchircu) 110 71 1679 1440
    3. Daniel-Constantin Mierla (@miconda) 82 39 3372 844
    4. Andrei Datcu (@andrei-datcu) 48 15 2153 846
    5. Razvan Crainea (@razvancrainea) 46 37 602 175
@@ -1558,9 +1558,9 @@ Chapter 3. Contributors
 
    Table 3.2. Most recently active contributors^(1) to this module
                       Name                   Commit Activity
-   1.  Norman Brandinger (@NormB)          Nov 2024 - Nov 2024
-   2.  Alexandra Titoc                     Sep 2024 - Sep 2024
-   3.  Liviu Chircu (@liviuchircu)         Aug 2012 - Sep 2024
+   1.  Liviu Chircu (@liviuchircu)         Aug 2012 - Jan 2025
+   2.  Norman Brandinger (@NormB)          Nov 2024 - Nov 2024
+   3.  Alexandra Titoc                     Sep 2024 - Sep 2024
    4.  Bogdan-Andrei Iancu (@bogdan-iancu) Oct 2005 - Feb 2024
    5.  Vlad Paiu (@vladpaiu)               Mar 2012 - Dec 2023
    6.  Maksym Sobolyev (@sobomax)          Feb 2023 - Nov 2023

diff --git a/modules/dispatcher/doc/contributors.xml b/modules/dispatcher/doc/contributors.xml
@@ -29,10 +29,10 @@
 	<row>
 		<entry>2. </entry>
 		<entry>Liviu Chircu (<ulink url="https://github.com/liviuchircu">@liviuchircu</ulink>)</entry>
-		<entry align="center">109</entry>
-		<entry align="center">70</entry>
-		<entry align="center">1670</entry>
-		<entry align="center">1433</entry>
+		<entry align="center">110</entry>
+		<entry align="center">71</entry>
+		<entry align="center">1679</entry>
+		<entry align="center">1440</entry>
 	</row>
 	<row>
 		<entry>3. </entry>
@@ -128,18 +128,18 @@
 	<tbody>
 	<row>
 		<entry>1. </entry>
-		<entry>Norman Brandinger (<ulink url="https://github.com/NormB">@NormB</ulink>)</entry>
-		<entry align="center">Nov 2024 - Nov 2024</entry>
+		<entry>Liviu Chircu (<ulink url="https://github.com/liviuchircu">@liviuchircu</ulink>)</entry>
+		<entry align="center">Aug 2012 - Jan 2025</entry>
 	</row>
 	<row>
 		<entry>2. </entry>
-		<entry>Alexandra Titoc</entry>
-		<entry align="center">Sep 2024 - Sep 2024</entry>
+		<entry>Norman Brandinger (<ulink url="https://github.com/NormB">@NormB</ulink>)</entry>
+		<entry align="center">Nov 2024 - Nov 2024</entry>
 	</row>
 	<row>
 		<entry>3. </entry>
-		<entry>Liviu Chircu (<ulink url="https://github.com/liviuchircu">@liviuchircu</ulink>)</entry>
-		<entry align="center">Aug 2012 - Sep 2024</entry>
+		<entry>Alexandra Titoc</entry>
+		<entry align="center">Sep 2024 - Sep 2024</entry>
 	</row>
 	<row>
 		<entry>4. </entry>

diff --git a/modules/presence/README b/modules/presence/README
@@ -1084,11 +1084,11 @@ Chapter 3. Contributors
    Maksym Sobolyev (@sobomax), Vlad Paiu (@vladpaiu), Juha
    Heinanen (@juha-h), Edson Gellert Schubert, Alexandra Titoc,
    Stanislaw Pitucha, Damien Sandras (@dsandras), Kobi Eshun
-   (@ekobi), Carsten Bock, Dusan Klinec (@ph4r05), Angel Marin,
-   Klaus Darilion, Carlos Oliva, Sergio Gutierrez, Kennard White,
-   Elena-Ramona Modroiu, Jasper Hafkenscheid, Vasil Kolev, Benny
-   Prijono, James Criscuolo, Peter Lemenkov (@lemenkov),
-   Vallimamod Abdullah, UnixDev, Norman Brandinger (@NormB), Denis
+   (@ekobi), Carsten Bock, Norman Brandinger (@NormB), Dusan
+   Klinec (@ph4r05), Angel Marin, Klaus Darilion, Carlos Oliva,
+   Sergio Gutierrez, Kennard White, Elena-Ramona Modroiu, Jasper
+   Hafkenscheid, Vasil Kolev, Benny Prijono, James Criscuolo,
+   Peter Lemenkov (@lemenkov), Vallimamod Abdullah, UnixDev, Denis
    Bilenko, Julián Moreno Patiño, John Riordan, Julien Blache.
 
    (1) DevScore = author_commits + author_lines_added /
@@ -1111,8 +1111,8 @@ Chapter 3. Contributors
 
    Table 3.2. Most recently active contributors^(1) to this module
                       Name                   Commit Activity
-   1.  Alexandra Titoc                     Sep 2024 - Sep 2024
-   2.  Norman Brandinger (@NormB)          May 2024 - May 2024
+   1.  Norman Brandinger (@NormB)          May 2024 - Nov 2024
+   2.  Alexandra Titoc                     Sep 2024 - Sep 2024
    3.  Bogdan-Andrei Iancu (@bogdan-iancu) Oct 2006 - Apr 2024
    4.  Carsten Bock                        Mar 2024 - Mar 2024
    5.  Maksym Sobolyev (@sobomax)          Jan 2021 - Nov 2023