launch_darkly Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. sdk_key (string)
              1.3.2. ld_log_level (string)
              1.3.3. connect_wait (integer)
              1.3.4. re_init_interval (integer)

        1.4. Exported Functions

              1.4.1. ld_feature_enabled( flag, user, [user_extra],
                      [fallback])

   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 sdk_key parameter
   1.2. Set log_level parameter
   1.3. Set connect_wait parameter
   1.4. Set re_init_interval parameter
   1.5. ld_feature_enabled() function usage

Chapter 1. Admin Guide

1.1. Overview

   This module implements support for the Launch Darkly feature
   management cloud. The module provide the conectivity to the
   cloud and the ability to query for feature flags.

   OpenSIPS uses the server side C/C++ SDK provided by Launch
   Darkly.

1.2. Dependencies

1.2.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * none.

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * ldserverapi

   ldserverapi must be compiled and installed from the official
   GITHUB repository .

   The instructions for a quick installations of the library (note
   that it has to be compiled as shared lib in order to be
   compatible with the OpenSIPS modules):
...
        $ git clone https://github.com/launchdarkly/c-server-sdk.git
        $ cd c-server-sdk
        $ cmake -DBUILD_SHARED_LIBS=On -DBUILD_TESTING=OFF .
        $ sudo make install
...

1.3. Exported Parameters

1.3.1. sdk_key (string)

   The LaunchDarkly SDK key used to connect to the service. This
   is a mandatory parameter.

   Example 1.1. Set sdk_key parameter
...
modparam("launch_darkly", "sdk_key", "sdk-12345678-abcd-12ab-1234-012345
6789abc")
...

1.3.2. ld_log_level (string)

   The LaunchDarkly specific log level to be used by the LD
   SDK/libray to log its internal messages. Note that these log
   produced by the LD library (according to this ld_log_level)
   will be further subject to filtering according to the overall
   OpenSIPS log_level.

   Accepted values are LD_LOG_FATAL, LD_LOG_CRITICAL,
   LD_LOG_ERROR, LD_LOG_WARNING, LD_LOG_INFO, LD_LOG_DEBUG,
   LD_LOG_TRACE.

   If not set or set to an unsupported value, the LD_LOG_WARNING
   level will be used by default.

   Example 1.2. Set log_level parameter
...
modparam("launch_darkly", "ld_log_level", "LD_LOG_CRITICAL")
...

1.3.3. connect_wait (integer)

   The time to wait (in miliseconds) when connecting to the LD
   service. An initial failure in connecting to the LD service may
   be addressed by increasing this wait value.

   The default value is 500 miliseconds.

   Example 1.3. Set connect_wait parameter
...
modparam("launch_darkly", "connect_wait", 100)
...

1.3.4. re_init_interval (integer)

   The minimum time interval (in seconds) to try again to init the
   LD client in the situation when the module was not able to init
   the LC connection at startup. In case of such failure, the
   module will automatically re-try to init its LD client
   on-demand, whnever the feature flag is checked from script, but
   not sooner than `re_init_interval`. Note: if there are no flag
   checkings to be performed, the re-init may be attempted longer
   than `re_init_interval`.

   The default value is 10 seconds.

   Example 1.4. Set re_init_interval parameter
...
modparam("launch_darkly", "re_init_interval", 30)
...

1.4. Exported Functions

1.4.1.  ld_feature_enabled( flag, user, [user_extra], [fallback])

   Function to evaluate a LaunchDarkly boolean feature flag

   Returns 1 if the flag was found TRUE or -1 otherwise.

   In case of error, the fallback (TRUE or FALSE) value will be
   returned In such cases, a "fallback" TRUE is returned as 2 and
   a fallback FALSE as -2, so you can may a difference between a
   real TRUE (returned by the LD service) and a fallback TRUE due
   to an error.

   This function can be used from any route.

   The function has the following parameters:
     * flag (string) - the key of the flag to evaluate. May not be
       NULL or empty.
     * user (string) - the user to evaluate the flag against. May
       not be NULL or empty.
     * user_extra (AVP, optional) - an AVP holding one or multiple
       key-value attributes to be attached to the user. The format
       of the AVP value is "key=value".
     * fallback (int, optional) - the value to be returned on
       error. By default FALSE will be returned.

   Example 1.5. ld_feature_enabled() function usage
        ...
        $avp(extra) = "domainId=123456";
        if (ld_feature_enabled("my-flag","opensips", $avp(extra), false)
)
                xlog("-------TRUE\n");
        else
                xlog("-------FALSE\n");
        ...

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. Bogdan-Andrei Iancu (@bogdan-iancu) 8 1 717 0
   2. Razvan Crainea (@razvancrainea) 3 1 43 2

   (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. Razvan Crainea (@razvancrainea)     May 2024 - May 2024
   2. Bogdan-Andrei Iancu (@bogdan-iancu) Jan 2024 - Jan 2024

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

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu).

   Documentation Copyrights:

   Copyright © 2023 Five9 Inc.
