Module launchdarkly-server-sdk
Server-side SDK for LaunchDarkly.
Functions
| makeLogBackend (enabled, write) | Creates a new custom log backend. |
| makeUser (fields) | This function is deprecated and provided as a convenience. |
| makeContext (A, A[, A[, A[, An]]]) | Create a new opaque context object. |
| version () | Return SDK version. |
| clientInit (string, int, config) | Initialize a new client, and connect to LaunchDarkly. |
| valid (context) | Returns true if the context is valid. |
| errors (context) | Returns an error string if the context is invalid. |
| canonicalKey (context) | Returns the canonical key of the context. |
| getAttribute (context, kind, attribute_reference) | Returns the value of a context attribute. |
| privateAttributes (context, kind) | Returns the private attribute references associated with a particular context kind. |
| boolVariation (context, key, fallback) | Evaluate a boolean flag |
| boolVariationDetail (context, key, fallback) | Evaluate a boolean flag and return an explanation |
| intVariation (context, key, fallback) | Evaluate an integer flag |
| intVariationDetail (context, key, fallback) | Evaluate an integer flag and return an explanation |
| doubleVariation (context, key, fallback) | Evaluate a double flag |
| doubleVariationDetail (context, key, fallback) | Evaluate a double flag and return an explanation |
| stringVariation (context, key, fallback) | Evaluate a string flag |
| stringVariationDetail (context, key, fallback) | Evaluate a string flag and return an explanation |
| jsonVariation (context, key, fallback) | Evaluate a json flag |
| jsonVariationDetail (context, key, fallback) | Evaluate a json flag and return an explanation |
| flush () | Immediately flushes queued events. |
| track (key, context[, data[, metric]]) | Reports that a context has performed an event. |
| isInitialized () | Check if a client has been fully initialized. |
| identify (context) | Generates an identify event for a context. |
| allFlags (context) | Returns a map from feature flag keys to values for a given context. |
Tables
| EvaluationDetail | EvaluationDetail contains extra information related to evaluation of a flag. |
Functions
- makeLogBackend (enabled, write)
-
Creates a new custom log backend. The functions provided must be thread safe as the SDK
does not perform any locking.
Parameters:
- enabled function A function that returns true if the specified log level is enabled. The signature should be (level: string) -> boolean, where the known level strings are 'debug', 'info', 'warn', and 'error'.
- write function A function that writes a log message at a specified level. The signature should be (level: string, message: string) -> void.
Returns:
-
A
new custom log backend, suitable for use in SDK `logging` configuration.
- makeUser (fields)
-
This function is deprecated and provided as a convenience. Please transition
to using makeContext instead.
Create a new opaque context object of kind 'user'. This method has changed from the previous Lua SDK v1.x `makeUser`, as users are no longer supported.
Specifically: 1. 'secondary' attribute is no longer supported. 2. 'privateAttributeNames' is now called 'privateAttributes' and supports attribute references (similar to JSON pointer syntax, e.g. `/foo/bar`). 3. all fields under 'custom' become top-level context attributes, rather than being nested under an attribute named 'custom'.
For example, `{ custom = { foo = "bar" } }` would result in a context with attribute 'foo' equal to 'bar'.
Parameters:
- fields list of user fields.
- key string The user's key
- anonymous boolean Mark the user as anonymous (optional)
- ip string Set the user's IP (optional)
- firstName string Set the user's first name (optional)
- lastName string Set the user's last name (optional)
- email string Set the user's email (optional)
- name string Set the user's name (optional)
- avatar string Set the user's avatar (optional)
- country string Set the user's country (optional)
- privateAttributes table A list of attributes to redact (optional)
- custom table A table of additional context attributes. (optional)
Returns:
-
an opaque context object
- fields list of user fields.
- makeContext (A, A[, A[, A[, An]]])
-
Create a new opaque context object. This method can be used to create single
or multi-kind contexts. The context's kind must always be specified, even if
it is a user.
For example, to create a context with a single user kind: ``` local context = ld.makeContext({ user = { key = "alice-123", name = "alice", attributes = { age = 52, contact = { email = "alice@mail.com", phone = "555-555-5555" } }, privateAttributes = { "age", "/contact/phone" } } }) ```
A multi-kind context can be useful when targeting based on multiple kinds of data. For example, to associate a device context with a user:
``` local context = ld.makeContext({ user = { key = "alice-123", name = "alice", anonymous = true }, device { key = "device-123", attributes = { manufacturer = "bigcorp" } } }) ```
SDK methods will automatically check for context validity. You may check manually by calling valid to detect errors earlier.
Parameters:
- A [kind.attributes] table of arbitrary attributes to associate with the context. (optional)
- A [kind.attributes] table of arbitrary attributes to associate with the context. (optional)
- A [kind.attributes] table of arbitrary attributes to associate with the context. (optional)
- A [kind.attributes] table of arbitrary attributes to associate with the context. (optional)
- An [kind.privateAttributes] array of attribute references, indicating which attributes should be marked private. Attribute references may be simple attribute names (like 'age'), or may use a JSON-pointer-like syntax (like '/contact/phone'). (optional)
Returns:
-
A
fresh context.
- version ()
-
Return SDK version.
Returns:
-
SDK version string.
- clientInit (string, int, config)
-
Initialize a new client, and connect to LaunchDarkly.
Applications should instantiate a single instance for the lifetime of their application.
To initialize with default configuration, you may pass nil or an empty table as the third argument.
Parameters:
- string Environment SDK key
- int Initialization timeout in milliseconds. clientInit will block for this long before returning a non-fully initialized client. Pass 0 to return immediately without waiting (note that the client will continue initializing in the background.)
- config optional configuration options, or nil/empty table for default configuration.
- offline boolean Sets whether this client is offline. An offline client will not make any network connections to LaunchDarkly or a data source like Redis, nor send any events, and will return application-defined default values for all feature flags. (optional)
- logging table Options related to the SDK's logging facilities. The `basic` and `custom` configs are mutually exclusive. If you only need to change logging verbosity or the log tag, use `basic`. If you need to replace the log verbosity logic & printing entirely, use `custom`. (optional)
- logging.basic table Modify the SDK's default logger. (optional)
- logging.basic.tag string A tag to include in log messages, for example 'launchdarkly'. (optional)
- logging.basic.level string The minimum level of log messages to include. Known options include 'debug', 'info', 'warn', or 'error'. (optional)
- logging.custom userdata A custom log backend, created with makeLogBackend. (optional)
- serviceEndpoints table If you set one custom service endpoint URL, you must set all of them. You probably don't need to set this unless instructed by LaunchDarkly. (optional)
- serviceEndpoints.streamingBaseURL string Set the streaming URL for connecting to LaunchDarkly. (optional)
- serviceEndpoints.eventsBaseURL string Set the events URL for connecting to LaunchDarkly. (optional)
- serviceEndpoints.pollingBaseURL string Set the polling URL for connecting to LaunchDarkly. (optional)
- events table Options related to event generation and delivery. (optional)
- events.enabled bool Sets whether to send analytics events back to LaunchDarkly. By default, the client will send events. This differs from top-level config option 'offline' in that it only affects sending events, not receiving data. (optional)
- events.capacity int The capacity of the events buffer. The client buffers up to this many events in memory before flushing. If the capacity is exceeded before the buffer is flushed, events will be discarded. (optional)
- events.flushIntervalMilliseconds int The time between flushes of the event buffer. Decreasing the flush interval means that the event buffer is less likely to reach capacity. (optional)
- events.allAttributesPrivate boolean Sets whether or not all context attributes (other than the key) should be hidden from LaunchDarkly. If this is true, all context attribute values will be private, not just the attributes specified via events.privateAttributes. (optional)
- events.contextKeysCapacity int The number of context keys that the event processor can remember at an one time, so that duplicate context details will not be sent in analytics. (optional)
- events.privateAttributes table Marks a set of context attribute as private. Any contexts sent to LaunchDarkly with this configuration active will have attributes refered to removed. (optional)
- appInfo table Specify metadata related to your application. (optional)
- appInfo.identifier string An identifier for the application. (optional)
- appInfo.version string The version of the application. (optional)
- dataSystem table Change configuration of the default streaming data source, switch to a polling source, or specify a read-only database source. (optional)
- dataSystem.enabled bool Set to false to disable receiving any data from any LaunchDarkly data source (streaming or polling) or a database source (like Redis.) (optional)
- dataSystem.backgroundSync table Change streaming or polling configuration. The SDK uses streaming by default. Note that streaming and polling are mutually exclusive. (optional)
- dataSystem.backgroundSync.streaming.initialReconnectDelayMilliseconds int The time to wait before the first reconnection attempt, if the streaming connection is dropped. (optional)
- dataSystem.backgroundSync.polling.intervalSeconds int The time between individual polling requests. (optional)
- dataSystem.lazyLoad.cacheRefreshMilliseconds int How long a data item (flag/segment) remains cached in memory before requiring a refresh from the source. (optional)
- dataSystem.lazyLoad.source userdata A custom data source. Currently only Redis is supported. (optional)
Returns:
-
A fresh client.
- valid (context)
-
Returns true if the context is valid.
Parameters:
- context context An opaque context object from makeUser or makeContext
Returns:
-
True
if valid, otherwise false.
- errors (context)
-
Returns an error string if the context is invalid.
Parameters:
- context context An opaque context object from makeUser or makeContext
Returns:
-
Error
string if valid, otherwise nil.
- canonicalKey (context)
-
Returns the canonical key of the context.
Parameters:
- context context An opaque context object from makeUser or makeContext
Returns:
-
Canonical
key of the context, or nil if the context isn't valid.
- getAttribute (context, kind, attribute_reference)
-
Returns the value of a context attribute.
Parameters:
- context context An opaque context object from makeUser or makeContext
- kind string The kind of the context.
- attribute_reference string An attribute reference naming the attribute to get.
Returns:
-
Lua
value of the attribute, or nil if the attribute isn't present in the context.
- privateAttributes (context, kind)
-
Returns the private attribute references associated with a particular
context kind.
Parameters:
- context context An opaque context object from makeUser or makeContext
- kind string The kind of the context.
Returns:
-
Array
of private attribute references, or nil if the kind isn't present in
the context.
- boolVariation (context, key, fallback)
-
Evaluate a boolean flag
Parameters:
- context context An opaque context object from makeUser or makeContext
- key string The key of the flag to evaluate.
- fallback boolean The value to return on error
Returns:
-
boolean
The evaluation result, or the fallback value
- boolVariationDetail (context, key, fallback)
-
Evaluate a boolean flag and return an explanation
Parameters:
- context context An opaque context object from makeUser or makeContext
- key string The key of the flag to evaluate.
- fallback boolean The value to return on error
Returns:
- intVariation (context, key, fallback)
-
Evaluate an integer flag
Parameters:
- context context An opaque context object from makeUser or makeContext
- key string The key of the flag to evaluate.
- fallback int The value to return on error
Returns:
-
int
The evaluation result, or the fallback value
- intVariationDetail (context, key, fallback)
-
Evaluate an integer flag and return an explanation
Parameters:
- context context An opaque context object from makeUser or makeContext
- key string The key of the flag to evaluate.
- fallback int The value to return on error
Returns:
- doubleVariation (context, key, fallback)
-
Evaluate a double flag
Parameters:
- context context An opaque context object from makeUser or makeContext
- key string The key of the flag to evaluate.
- fallback number The value to return on error
Returns:
-
double
The evaluation result, or the fallback value
- doubleVariationDetail (context, key, fallback)
-
Evaluate a double flag and return an explanation
Parameters:
- context context An opaque context object from makeUser or makeContext
- key string The key of the flag to evaluate.
- fallback number The value to return on error
Returns:
- stringVariation (context, key, fallback)
-
Evaluate a string flag
Parameters:
- context context An opaque context object from makeUser or makeContext
- key string The key of the flag to evaluate.
- fallback string The value to return on error
Returns:
-
string
The evaluation result, or the fallback value
- stringVariationDetail (context, key, fallback)
-
Evaluate a string flag and return an explanation
Parameters:
- context context An opaque context object from makeUser or makeContext
- key string The key of the flag to evaluate.
- fallback string The value to return on error
Returns:
- jsonVariation (context, key, fallback)
-
Evaluate a json flag
Parameters:
- context context An opaque context object from makeUser or makeContext
- key string The key of the flag to evaluate.
- fallback table The value to return on error
Returns:
-
table
The evaluation result, or the fallback value
- jsonVariationDetail (context, key, fallback)
-
Evaluate a json flag and return an explanation
Parameters:
- context context An opaque context object from makeUser or makeContext
- key string The key of the flag to evaluate.
- fallback table The value to return on error
Returns:
- flush ()
-
Immediately flushes queued events.
Returns:
-
nil
- track (key, context[, data[, metric]])
-
Reports that a context has performed an event. Custom data, and a metric
can be attached to the event as JSON.
Parameters:
- key string The name of the event
- context context An opaque context object from makeUser or makeContext
- data table A value to be associated with an event (optional)
- metric number A value to be associated with an event (optional)
Returns:
-
nil
- isInitialized ()
-
Check if a client has been fully initialized. This may be useful if the
initialization timeout was reached.
Returns:
-
boolean
true if fully initialized
- identify (context)
-
Generates an identify event for a context.
Parameters:
- context context An opaque context object from makeUser or makeContext
Returns:
-
nil
- allFlags (context)
-
Returns a map from feature flag keys to values for a given context.
This does not send analytics events back to LaunchDarkly.
Parameters:
- context context An opaque context object from makeUser or makeContext
Returns:
Tables
- EvaluationDetail
-
EvaluationDetail contains extra information related to evaluation of a flag.
Fields:
- kind string, one of: "OFF","FALLTHROUGH", "TARGET_MATCH", "RULE_MATCH", "PREREQUISITE_FAILED", "ERROR", "UNKNOWN".
- errorKind string, only present if 'kind' is "ERROR"; one of: "CLIENT_NOT_READY", "FLAG_NOT_FOUND", "USER_NOT_SPECIFIED", "MALFORMED_FLAG", "WRONG_TYPE", "MALFORMED_FLAG", "EXCEPTION", "UNKNOWN".
- inExperiment bool, whether the flag was part of an experiment.
- variationIndex int, only present if the evaluation was successful. The zero-based index of the variation.
- value LDJSON, the value of the flag.