| Overview |  |
ldclient module.
+
+
+ldclient module
Acts as an interface to most common SDK functions: starting and stopping +client instances, and evaluating feature flags for contexts.
+ + Most use cases only need a single client instance for the lifetime of + their application. Consider using multiple instances only if you need to + simultaneously access more than one environment. Do not start an instance + every time you need to make a variation or other SDK call. +| all_flags_state/1 | Evaluate all flags for a given context and return their values. |
| all_flags_state/2 | Evaluate all flags for a given context and given client instance. |
| all_flags_state/3 | Returns an object that encapsulates the state of all feature flags for a given context. |
| identify/1 | Identify reports details about a context. |
| identify/2 | Identify reports details about a context. |
| initialized/1 | Returns whether the LaunchDarkly client has initialized. |
| is_offline/1 | Returns whether the LaunchDarkly client is in offline mode. |
| start_instance/1 | Start client with default options. |
| start_instance/2 | Start client with custom name or options. |
| start_instance/3 | Start client with custom name and options. |
| stop_all_instances/0 | Stop all client instances. |
| stop_instance/0 | Stop client instance. |
| stop_instance/1 | Stop client with the custom name. |
| track/3 | Track reports that a context has performed an event. |
| track/4 | Track reports that a context has performed an event. |
| track_metric/4 | Reports that a context has performed an event, and associates it with a numeric value. |
| track_metric/5 | Reports that a context has performed an event, and associates it with a numeric value. |
| variation/3 | Evaluate given flag key for given context. |
| variation/4 | Evaluate given flag key for given context and given client instance. |
| variation_detail/3 | Evaluate given flag key for given context. |
| variation_detail/4 | Evaluate given flag key for given context and given client instance. |
all_flags_state(Context::ldclient_user:user() | ldclient_context:context()) -> ldclient_eval:feature_flags_state()
+
Evaluate all flags for a given context and return their values
+ + Evaluates all existing flags, but does not create any events as a side + effect of the evaluation. It returns a map of flag keys to evaluated values. + +all_flags_state(Context::ldclient_user:user() | ldclient_context:context(), Tag::atom()) -> ldclient_eval:feature_flags_state()
+
Evaluate all flags for a given context and given client instance
+ + Evaluates all existing flags, but does not create any events as a side + effect of the evaluation. It returns a map of flag keys to evaluated values. + +all_flags_state(Context::ldclient_user:user() | ldclient_context:context(), Options::ldclient_eval:all_flags_state_options(), Tag::atom()) -> ldclient_eval:feature_flags_state()
+
Returns an object that encapsulates the state of all feature flags for a given context.
+ +This includes the flag values, and also metadata that can be used on the front end. +The most common use case for this method is to bootstrap a set of client-side feature flags from a +back-end service.
+ + If you are not using this to boostrap a client, then you likely want all_flags_state/1 or all_flags_state/2. + +identify(Context::ldclient_user:user() | ldclient_context:context()) -> ok
+
Identify reports details about a context
+ + This function uses the default client instance. + +identify(Context::ldclient_user:user() | ldclient_context:context(), Tag::atom()) -> ok
+
Identify reports details about a context
+ + This is useful to report context to a specific client instance. + +initialized(Tag::atom()) -> boolean()
+
Returns whether the LaunchDarkly client has initialized.
+ +If this value is true, it means the client has succeeded at some point in connecting to LaunchDarkly and +has received feature flag data. It could still have encountered a connection problem after that point, so +this does not guarantee that the flags are up to date. Alternatively, it could also mean that the client +is in offline mode.
+ + If this value is false, it means the client has not yet connected to LaunchDarkly, or has permanently + failed. In this state, feature flag evaluations will always return default values. + +is_offline(Tag::atom()) -> boolean()
+
Returns whether the LaunchDarkly client is in offline mode.
+ + In some situations, you might want to stop making remote calls to LaunchDarkly and + fall back to default values for your feature flags, this tells you whether only default + values will be returned. + +start_instance(SdkKey::string()) -> ok | {error, atom(), term()}
+
Start client with default options
+ + The SDK key is required to connect. Default streamer URL, storage backend + and instance namedefault will be used.
+
+start_instance(SdkKey::string(), TagOrOptions::atom() | map()) -> ok | {error, atom(), term()}
+
Start client with custom name or options
+ + WhenTagOrOptions is an atom, the instance is started with that name. When
+ it's a map, it can be used to start with custom options.
+
+start_instance(SdkKey::string(), Tag::atom(), Options::map()) -> ok | {error, atom(), term()}
+
Start client with custom name and options
+ + Specify both custom client name and options when starting the client. + +stop_all_instances() -> ok
+
Stop all client instances +
+ +stop_instance() -> ok | {error, not_found, term()}
+
Stop client instance
+ + Stops the default client instance. + +stop_instance(Tag::atom()) -> ok | {error, not_found, term()}
+
Stop client with the custom name
+ + This is useful if a client instance was started with a custom name. + +track(Key::binary(), Context::ldclient_user:user() | ldclient_context:context(), Data::ldclient_event:event_data()) -> ok
+
Track reports that a context has performed an event
+ + Custom data can be attached to the event. + +track(Key::binary(), Context::ldclient_user:user() | ldclient_context:context(), Data::ldclient_event:event_data(), Tag::atom()) -> ok
+
Track reports that a context has performed an event
+ + This is useful for specifying a specific client instance. + +track_metric(Key::binary(), Context::ldclient_user:user() | ldclient_context:context(), Data::ldclient_event:event_data(), Metric::number()) -> ok
+
Reports that a context has performed an event, and associates it with a numeric value.
+ +This value is used by the LaunchDarkly experimentation feature in numeric custom metrics, and will also +be returned as part of the custom event for Data Export.
+ + Custom data can also be attached to the event. + +track_metric(Key::binary(), Context::ldclient_user:user() | ldclient_context:context(), Data::ldclient_event:event_data(), Metric::number(), Tag::atom()) -> ok
+
Reports that a context has performed an event, and associates it with a numeric value.
+ +This value is used by the LaunchDarkly experimentation feature in numeric custom metrics, and will also +be returned as part of the custom event for Data Export.
+ + Custom data can also be attached to the event. + +variation(FlagKey::binary(), Context::ldclient_user:user() | ldclient_context:context(), DefaultValue::ldclient_eval:result_value()) -> ldclient_eval:result_value()
+
Evaluate given flag key for given context
+ + Evaluates the flag and returns the resulting variation value. The default + value will be returned in case of any errors. + +variation(FlagKey::binary(), Context::ldclient_user:user() | ldclient_context:context(), DefaultValue::ldclient_eval:result_value(), Tag::atom()) -> ldclient_eval:result_value()
+
Evaluate given flag key for given context and given client instance
+ + Evaluates the flag and returns the resulting variation value. The default + value will be returned in case of any errors. + +variation_detail(FlagKey::binary(), Context::ldclient_user:user() | ldclient_context:context(), DefaultValue::ldclient_eval:result_value()) -> ldclient_eval:detail()
+
Evaluate given flag key for given context
+ + Evaluates the flag and returns the result detail containing the variation + index, value, and reason why the specific result was chosen. The default + value will be returned in case of any errors. + +variation_detail(FlagKey::binary(), Context::ldclient_user:user() | ldclient_context:context(), DefaultValue::ldclient_eval:result_value(), Tag::atom()) -> ldclient_eval:detail()
+
Evaluate given flag key for given context and given client instance
+ + Evaluates the flag and returns the result detail containing the variation + index, value, and reason why the specific result was chosen. The default + value will be returned in case of any errors. +Generated by EDoc
+ + diff --git a/ldclient_config.html b/ldclient_config.html new file mode 100644 index 0000000..c8f1638 --- /dev/null +++ b/ldclient_config.html @@ -0,0 +1,158 @@ + + + + +ldclient_config module.
+
+
+ldclient_config module
app_info() = #{id => binary(), version => binary()}
+ + +http_options() = #{tls_options => [ssl:tls_client_option()] | undefined, connect_timeout => pos_integer() | undefined, custom_headers => [{Key::string(), Value::string()}] | undefined}
+ + +instance() = #{sdk_key => string(), base_uri => string(), events_uri => string(), stream_uri => string(), feature_store => atom(), events_capacity => pos_integer(), events_flush_interval => pos_integer(), events_dispatcher => atom(), context_keys_capacity => pos_integer(), private_attributes => private_attributes(), stream => boolean(), polling_interval => pos_integer(), polling_update_requestor => atom(), offline => boolean(), redis_host => string(), redis_port => pos_integer(), redis_database => integer(), redis_password => string(), redis_prefix => string(), redis_tls => [ssl:tls_option()] | undefined, cache_ttl => integer(), use_ldd => boolean(), send_events => boolean(), file_datasource => boolean(), file_paths => [string() | binary()], file_auto_update => boolean(), file_poll_interval => pos_integer(), file_allow_duplicate_keys => boolean(), testdata_tag => atom(), datasource => poll | stream | file | testdata | undefined, http_options => http_options(), stream_initial_retry_delay_ms => non_neg_integer(), application => app_info()}
+ + +private_attributes() = all | [ldclient_attribute_reference:attribute_reference()]
+ + +| get_event_schema/0 | |
| get_registered_tags/0 | Get all registered tags. |
| get_user_agent/0 | |
| get_value/2 | Gets application environment variable value. |
| get_version/0 | |
| init/0 | Initialize settings environment map. |
| register/2 | Register settings for a new client instance. |
| tls_basic_certifi_options/0 | Provide basic TLS options using the bundled certifi store. |
| tls_basic_linux_options/0 | Provide basic options for using TLS with the default linux store. |
| tls_basic_options/0 | Provide basic options for using TLS. |
| tls_ca_certfile_options/1 | Provide basic options for using TLS with the given store. |
| unregister/1 | Unregister settings for a client instance. |
| with_tls_revocation/1 | Append the specified TLS options with certificate revocation. |
get_event_schema() -> string()
+
get_registered_tags() -> [atom()]
+
Get all registered tags +
+ +get_user_agent() -> string()
+
get_value(Tag::atom(), Key::atom()) -> undefined | term()
+
Gets application environment variable value
+ + This is a convenience function to retrieve application environment variables + in one place.Tag is the instance tag. Key is the key of the
+ configuration option.
+
+get_version() -> string()
+
init() -> ok
+
Initialize settings environment map
+ + Initializes an empty map for instance settings in application environment. + +register(Tag::atom(), Settings::instance()) -> ok
+
Register settings for a new client instance +
+ +tls_basic_certifi_options() -> [ssl:tls_client_option()]
+
Provide basic TLS options using the bundled certifi store. +
+ +tls_basic_linux_options() -> [ssl:tls_client_option()]
+
Provide basic options for using TLS with the default linux store. + This will try to use the a certificate store located at + /etc/ssl/certs/ca-certificates.crt. +
+ +tls_basic_options() -> [ssl:tls_client_option()]
+
Provide basic options for using TLS. + This will try to use the a certificate store located at + /etc/ssl/certs/ca-certificates.crt, but if that file + does not exist, then it will use the bundled certifi store. +
+ +tls_ca_certfile_options(CaStorePath::string()) -> [ssl:tls_client_option()]
+
Provide basic options for using TLS with the given store. +
+ +unregister(Tag::atom()) -> ok
+
Unregister settings for a client instance +
+ +with_tls_revocation(Options::[ssl:tls_client_option()]) -> [ssl:tls_client_option()]
+
Append the specified TLS options with certificate revocation. + The crl_cache does not actually cache at this time, so this will + result in an additional request per TLS handshake. +
+Generated by EDoc
+ + diff --git a/ldclient_context.html b/ldclient_context.html new file mode 100644 index 0000000..331317b --- /dev/null +++ b/ldclient_context.html @@ -0,0 +1,420 @@ + + + + +Context data type +When constructing a context by hand, not using new/1, new/2 or new_from_map, +then you must include a kind attribute.
+ + The kind attribute is used to differentiate between a map representing + a ldclient_user and one representing a ldclient_context. +attribute_key() = binary() | key | kind | anonymous | private_attributes | name
+ Attribute keys must be binary() strings. They should not be empty, and they must not be <<"_meta">>.
attribute_map() = #{attribute_key() => attribute_value()}
+ + +attribute_value() = binary() | integer() | float() | boolean() | attribute_map() | [attribute_value()]
+Attribute values should all be data types which are compatible with JSON and nested JSON collections. + The leaf nodes of these values are what are ultimately used when evaluating flags which are dependent on attributes.
+ +context() = single_context() | multi_context()
+ + +context_part() = #{key := key(), name := binary(), private_attributes => [binary()], anonymous => boolean(), attributes => attribute_map()}
+ The content of a multi context. Should be the same as a single_context/0 aside from missing 'kind'.
+ A multi context is keyed by the 'kind'.
key() = binary()
+ Keys may be any non-empty binary() string. <<>> and <<"">> are not valid.
+ Keys must be binaries, and should match those in LaunchDarkly exactly.
+ No casing conversions will be applied <<"my_attribute">> will only match <<"my_attribute">>, it would not match
+ <<"myAttribute">>.
kind_value() = binary()
+ May only contain ASCII letters, numbers, ., _ or -.
+ <<"my_kind.0-1">> would be valid.
+ <<"my:kind.{0}">> would not, it contains ':' and '{}' which are not allowed.
+ Kinds should be binaries, and should match the context kinds exactly.
+ No casing conversions will be applied <<"my_kind">> will only match <<"my_kind">>, it would not match
+ <<"myKind">>.
multi_context() = #{kind := kind_value(), kind_value() := context_part()}
+A context which represents multiple kinds. Each kind having its own key and attributes.
+ +A multi-context must contain kind => <<"multi">> at the root.
MyMultiContext = #{
+ %% Multi-contexts must be of kind <<"multi">>.
+ kind => <<"multi">>,
+ %% The context is namespaced by its kind. This is an 'org' kind context.
+ <<"org">> => #{
+ // Each component context has its own key and attributes.
+ key => <<"my-org-key">>,
+ attributes => #{
+ <<"someAttribute">> => <<"my-attribute-value">>,
+ }
+ },
+ <<"user">> => #{
+ key => <<"my-user-key">>,
+ %% Each component context has its own meta attributes. This will only apply the this
+ %% 'user' context.
+ private_attributes => [<<"firstName">>]
+ attributes => #{
+ <<"firstName">> => <<"Bob">>,
+ <<"lastName">> => <<"Bobberson">>,
+ }
+ }
+ }.
+
+ The above multi-context contains both an 'org' and a 'user'. Each with their own key,
+ attributes, and _meta attributes.
+
+single_context() = #{key := key(), name => binary(), kind := kind_value(), private_attributes => [binary()], anonymous => boolean(), attributes => attribute_map()}
+A context which represents a single kind.
+ +For a single kind context the 'kind' may not be <<"multi">>.
MyOrgContext = #{
+ kind => <<"org">>,
+ key => <<"my-org-key">>,
+ attributes => #{
+ <<"someAttribute">> => <<"my-attribute-value">>
+ }
+ }.
+
+ The above context would be a single kind context representing an organization. It has a key
+ for that organization, and a single attribute 'someAttribute'.
+
+| get/3 | Get an attribute value from the specified context kind by the specified attribute reference. |
| get_canonical_key/1 | A string that describes the entire Context based on Kind and Key values. |
| get_key/2 | Get the key for the specified context kind. |
| get_kinds/1 | Get all the kinds in the specified context. |
| is_valid/2 | Verify a context is valid. |
| new/1 | Create a new 'user' context with the specified key. |
| new/2 | Create a new context with the specified key and kind. |
| new_from_json/1 | Parse a map created from the JSON representation of a context into an ldclient_context:context(). |
| new_from_map/1 | Create a context from a map. |
| new_from_user/1 | Create a context from an ldclient_user:user(). |
| new_multi_from/1 | Create a multi context from several multiple single kind contexts. |
| set/3 | Set an attribute value with the specified key in a single kind context. |
| set/4 | Set an attribute value in the specified context kind with the specified key. |
| set_private_attributes/2 | Set private attributes for a single kind context. |
| set_private_attributes/3 | Set private attributes for the specified context kind. |
get(ContextKind::kind_value(), AttributeReference::ldclient_attribute_reference:attribute_reference() | binary(), Context::context()) -> attribute_value() | null
+
Get an attribute value from the specified context kind by the specified attribute reference
+ +If the context is a single kind context, and the ContextKind matches the context's kind, and the context contains +the specified attribute, then that value will be provided.
+ +If the context is a multi-context, and it contains the specified context kind, and that context kind contains +the specified attribute, then that value will be provided.
+ + If the attribute value does not exist, then the null atom will be returned. + +get_canonical_key(Context::context()) -> binary()
+
A string that describes the entire Context based on Kind and Key values.
+ + This value is used whenever LaunchDarkly needs a string identifier based on all of the Kind and + Key values in the context; the SDK may use this for caching previously seen contexts, for instance. + +get_key(ContextKind::kind_value(), Context::context()) -> binary() | null
+
Get the key for the specified context kind.
+ +If the context is of a single kind, and it does not match the specified context kind, then null will be returned.
+ + If the context is a multi-context, and does not contain the specified kind, then null will be returned. + +get_kinds(Context::context()) -> [binary()]
+
Get all the kinds in the specified context. Can be a single or multi context.
+ + The kind in the context may be an atom or a binary, but this will always return them as binaries for use + in comparison against strings from LaunchDarkly. + +is_valid(Context::context(), AllowEmptyKey::boolean()) -> boolean()
+
Verify a context is valid.
+ +This will ensure that the context, or contexts of a multi context, have:
+ +1.) Valid keys. Key must exist, must be a binary, and cannot be empty.
+ An exception is made for contexts created from an ldclient_user:user().
2.) Valid kind. Kind must exist, must be a binary, and must be composed of ASCII letters, numbers, as well as
+ '-', '.', and '_'. A context created from a ldclient_user:user() will have a <<"user">> kind.
3.) All parts of a multi context meet #1 and #2.
+ +Other aspects of the context may be invalid, and evaluation will proceed, but those invalid +parts will not impact the evaluation. For example an attribute with an atom() key will not successfully targeted +by rules. Some of these issues can be avoided by using the new_from_map function which will convert keys.
+ + Evaluations which are done against an invalid context will return default values with a reason + of user_not_specified. + +new(Key::binary()) -> single_context()
+
Create a new 'user' context with the specified key. +
+ +new(Key::binary(), Kind::kind_value()) -> single_context()
+
Create a new context with the specified key and kind. +
+ +new_from_json(JsonMap::map()) -> context() | undefined
+
Parse a map created from the JSON representation of a context into an ldclient_context:context().
undefined will be returned.
+
+new_from_map(MapContext::map()) -> Context::context()
+
Create a context from a map.
+ +Using this method will help to ensure that all your context keys and values are of supported types. For instance +converting all atom() keys into binary() (both for attribute keys and kinds). This can be useful for contexts +from a serialized source.
+ +If the map contains a 'kind' attribute, then the resulting context will be of that kind.
+ If the map contains a 'kind' attribute, with the value of <<"multi">>, then a multi context will be created,
+and each top level field in the map will be a component of that context.
If the input map contains invalid data, such as bad kinds, then the context will still be created. +If the context contains invalid data, then evaluations will return default values with a reason of +'user_not_specified'.
+ + The same key should not be provided in the map as both an atom and a binary. For instance: + #{key => <<"the-key">>, <<"key">> => <<"the-key">>}
+
+ Create a context without a kind specified:
+ ldclient_context:new_from_map(#{
+ key => <<"my-key">>,
+ attributes => #{
+ nested => #{
+ deeper => #{
+ value => <<"my-value">>
+ }
+ }
+ }
+ }).
+ Produces the context
+ #{
+ key := <<"my-key">>,
+ kind := <<"user">>,
+ attributes := #{
+ <<"nested">> := #{
+ <<"deeper">> := #{
+ <<"value">> := <<"my-value">>
+ }
+ }
+ }
+ }.
+ No kind was included, so it was defaulted to a <<"user">> kind.
+ Notice that all the keys, and nested keys, within attributes have been converted to binaries.
+
+ Creating a context with a specified kind.
+ ldclient_context:new_from_map(#{<<"key">> => <<"my-key">>, <<"kind">> => <<"the-kind">>}).
+ Produces the context
+ {key := <<"my-key">>, kind := <<"the-kind">>}.
+ Notice here how the built-in keys have been corrected to atoms.
+
+ ldclient_context:new_from_map(#{
+ kind => <<"multi">>,
+ <<"meal">> => #{
+ key => <<"user-key">>,
+ <<"name">> => <<"the-name">>, %% Key that will become an atom.
+ attributes => #{
+ potato => #{ %% Key that will become a binary.
+ <<"bacon">> => true,
+ <<"cheese">> => true
+ }
+ }
+ },
+ <<"location">> => #{
+ key => <<"location-key">>
+ }
+ }).
+ Produces the context
+ #{
+ kind := <<"multi">>,
+ <<"meal">> := #{
+ key := <<"user-key">>,
+ name := <<"the-name">>,
+ attributes := #{
+ <<"potato">> := #{
+ <<"bacon">> := true,
+ <<"cheese">> := true
+ }
+ }
+ },
+ <<"location">> := #{
+ key := <<"location-key">>
+ }
+ }
+
+new_from_user(User::ldclient_user:user()) -> context()
+
Create a context from an ldclient_user:user().
This function is primarily intended for use by the SDK. It will be used when calling variation methods with
+ ldclient_user:user(). An ldclient_user:user() is detected by the lack of kind.
Creating contexts directly, using ldclient_context:new/1, ldclient_context:new/2,
+ ldclient_context:new_from_map/1, or creating context(), will avoid this conversion.
ldclient_user:user(). A map can be converted to a user using
+ ldclient_user:new_from_map/1. If the user does not have at least a key, then an empty map
+ is returned and it will not validate. An invalid context will result in default values from variation methods.
+
+new_multi_from(Contexts::[single_context()]) -> multi_context() | single_context()
+
Create a multi context from several multiple single kind contexts.
+ +MyMultiContext = ldclient_context:new_multi_from([ + ldclient_context:new(<<"user-key">>), %% This defaults to a <<"user">> kind. + ldclient_context:new(<<"org-key">>, <<"org">>)]).+ +
Each of the contexts being combined should have unique keys. If more than one context of the same kind is added, +then only a single context of the duplicated type will remain.
+ + Ifnew_from_multi is called with a list containing a single context, then the single context will be returned.
+ A multi context should contain more than one kind.
+
+set(AttributeKey::attribute_key(), AttributeValue::attribute_value(), Context::single_context()) -> single_context()
+
Set an attribute value with the specified key in a single kind context.
+ +This method cannot be used to set attributes in nested maps.
+ +Any built-in attributes private_attributes, anonymous, key, kind, will be set at the top level of the context. +Any attributes that are not built-ins will be set in an 'attributes' map.
+ + Attempting to set 'attributes' will result in an attribute named<<"attributes">>.
+
+set(ContextKind::kind_value(), AttributeKey::attribute_key(), AttributeValue::attribute_value(), Context::context()) -> multi_context()
+
Set an attribute value in the specified context kind with the specified key.
+ +If the context is a single kind, then it must be of the kind specified.
+ +If it is a multi context, then specified kind must exist in it.
+ + This method cannot be used to set attributes in nested maps. + +set_private_attributes(AttributeValues::[binary()], Context::single_context()) -> single_context()
+
Set private attributes for a single kind context.
+ +Designate any number of Context attributes, or properties within them, as private: that is, +their values will not be sent to LaunchDarkly.
+ +Each parameter can be a simple attribute name, such as "email". Or, if the first character is +a slash, the parameter is interpreted as a slash-delimited path to a property within a JSON +object, where the first path component is a Context attribute name and each following +component is a nested property name: for example, suppose the attribute "address" had the +following value
+ + #{<<"street">>: #{<<"line1">>: <<"abc">>, <<"line2">>: <<"def">>}}
+
+ Using ["/address/street/line1"] in this case would cause the "line1" property to be marked as +private. This syntax deliberately resembles JSON Pointer, but other JSON Pointer features +such as array indexing are not supported for Private.
+ +This action only affects analytics events that involve this particular Context. To mark some +(or all) Context attributes as private for all users, use the overall configuration for the +SDK.
+ +The attributes "kind" and "key", and the meta attributes (like private_attribute_names) cannot be made private.
+ +In this example, firstName is marked as private, but lastName is not:
+ + Context = #{
+ kind => <<"org">>,
+ key => <<"my-key">>,
+ private_attributes: [<<"firstName">>],
+ attributes => #{
+ <<"firstName">> => <<"Pierre">>,
+ <<"lastName">> => <<"Menard">>
+ }
+ }.
+
+ This is a metadata property, rather than an attribute that can be addressed in evaluations:
+ that is, a rule clause that references the attribute name "private_attributes", will not use
+ this value, but instead will use whatever value (if any) you have set for that name with a
+ method such as set/3 or by including it in the attributes map.
+
+set_private_attributes(ContextKind::kind_value(), AttributeValues::[binary()], Context::context()) -> context()
+
Set private attributes for the specified context kind.
+ + Context can either be a single kind context of the specified kind or a multi context containing the kind. +Generated by EDoc
+ + diff --git a/ldclient_flagbuilder.html b/ldclient_flagbuilder.html new file mode 100644 index 0000000..5f9fbff --- /dev/null +++ b/ldclient_flagbuilder.html @@ -0,0 +1,382 @@ + + + + +abstract datatype: flag_builder()
+ A builder for feature flag configurations to be used with ldclient_testdata.
abstract datatype: flag_rule_builder()
+ A builder for feature flag rules to be used with flag_builder().
variation() = boolean() | non_neg_integer()
+ + +| and_match/3 | Adds another clause, using the "is one of" operator. |
| and_match/4 | Adds another clause, using the "is one of" operator. |
| and_not_match/3 | Adds another clause, using the "is not one of" operator. |
| and_not_match/4 | Adds another clause, using the "is not one of" operator. |
| boolean_flag/1 | A shortcut for setting the flag to use the standard boolean configuration. |
| clear_rules/1 | Removes any existing rules from the flag. |
| clear_targets/1 | Removes any existing targets from the flag. |
| fallthrough_variation/2 | Specifies the fallthrough variation for a flag. |
| if_match/3 | Starts defining a flag rule, using the "is one of" operator. |
| if_match/4 | Starts defining a flag rule, using the "is one of" operator. |
| if_not_match/3 | Starts defining a flag rule, using the "is not one of" operator. |
| if_not_match/4 | Starts defining a flag rule, using the "is not one of" operator. |
| off_variation/2 | Specifies the off variation for a flag. |
| on/2 | Sets targeting to be on or off for this flag. |
| then_return/2 | Finishes defining the rule, specifying the result variation. |
| value_for_all/2 | Sets the flag to always return the specified variation value for all contexts. |
| variation_for_all/2 | Sets the flag to always return the specified variation for all contexts. |
| variation_for_context/4 | Sets the flag to return the specified variation for a specific context kind and key when +targeting is on. |
| variations/2 | Sets the flag to always return the specified variation value for all contexts. |
and_match(ContextAttribute::ldclient_context:attribute_key(), Values::[term()], RuleBuilder::flag_rule_builder()) -> flag_rule_builder()
ContextAttribute: the context attribute to match against
+Values: values to compare to
+RuleBuilder: the rule builder to modify
+
returns: the modified rule builder
+Adds another clause, using the "is one of" operator. The kind of the context is implicitly "user"
+ for non-user contexts use any_match/4.
For example, this creates a rule that returns true if the name is "Patsy" and the
+country is "gb":
{ok, Flag} = ldclient_testdata:flag(TestData, <<"flag">>),
+ RuleBuilder = ldclient_flagbuilder:and_match(<<"country">>, [<<"gb">>],
+ ldclient_flagbuilder:if_match(<<"name">>, [<<"Patsy">>], Flag)),
+ UpdatedFlag = ldclient_flagbuilder:then_return(true, RuleBuilder),
+ ldclient_testdata:update(TestData, UpdatedFlag).
+
+
+and_match(ContextKind::ldclient_context:kind_value(), ContextAttribute::ldclient_context:attribute_key(), Values::[term()], RuleBuilder::flag_rule_builder()) -> flag_rule_builder()
ContextAttribute: the context attribute to match against
+Values: values to compare to
+RuleBuilder: the rule builder to modify
+
returns: the modified rule builder
+Adds another clause, using the "is one of" operator. The kind of the context is implicitly "user"
+ for non-user contexts use any_match/4.
For example, this creates a rule that returns true if the name is "Patsy" and the
+country is "gb":
{ok, Flag} = ldclient_testdata:flag(TestData, <<"flag">>),
+ RuleBuilder = ldclient_flagbuilder:and_match(<<"user">>, <<"country">>, [<<"gb">>],
+ ldclient_flagbuilder:if_match(<<"user">>, <<"name">>, [<<"Patsy">>], Flag)),
+ UpdatedFlag = ldclient_flagbuilder:then_return(true, RuleBuilder),
+ ldclient_testdata:update(TestData, UpdatedFlag).
+
+
+and_not_match(ContextAttribute::ldclient_context:attribute_key(), Values::[term()], RuleBuilder::flag_rule_builder()) -> flag_rule_builder()
ContextAttribute: the context attribute to match against
+Values: values to compare to
+RuleBuilder: the rule builder to modify
+
returns: the modified rule builder
+Adds another clause, using the "is not one of" operator. The kind of the context is implicitly "user"
+ for non-user contexts use any_match/4.
For example, this creates a rule that returns true if the name is "Patsy" and the
+country is not "gb":
{ok, Flag} = ldclient_testdata:flag(TestData, <<"flag">>),
+ RuleBuilder = ldclient_flagbuilder:and_not_match(<<"country">>, [<<"gb">>],
+ ldclient_flagbuilder:if_match(<<"name">>, [<<"Patsy">>], Flag)),
+ UpdatedFlag = ldclient_flagbuilder:then_return(true, RuleBuilder),
+ ldclient_testdata:update(TestData, UpdatedFlag).
+
+
+and_not_match(ContextKind::ldclient_context:kind_value(), ContextAttribute::ldclient_context:attribute_key(), Values::[term()], RuleBuilder::flag_rule_builder()) -> flag_rule_builder()
ContextAttribute: the context attribute to match against
+Values: values to compare to
+RuleBuilder: the rule builder to modify
+
returns: the modified rule builder
+Adds another clause, using the "is not one of" operator.
+ +For example, this creates a rule that returns true if the name is "Patsy" and the
+country is not "gb":
{ok, Flag} = ldclient_testdata:flag(TestData, <<"flag">>),
+ RuleBuilder = ldclient_flagbuilder:and_not_match(<<"user">>, <<"country">>, [<<"gb">>],
+ ldclient_flagbuilder:if_match(<<"user">>, <<"name">>, [<<"Patsy">>], Flag)),
+ UpdatedFlag = ldclient_flagbuilder:then_return(true, RuleBuilder),
+ ldclient_testdata:update(TestData, UpdatedFlag).
+
+
+boolean_flag(FlagBuilder::flag_builder()) -> flag_builder()
FlagBuilder: the flag builder to modify
+
returns: the modified builder
+A shortcut for setting the flag to use the standard boolean configuration.
+ + This is the default for all new flags created withldclient_testdata:flag/2.
+ The flag will have two variations, true and false (in that order); it will return
+ false whenever targeting is off, and true when targeting is on if no other
+ settings specify otherwise.
+
+
+clear_rules(FlagBuilder::flag_builder()) -> flag_builder()
FlagBuilder: the flag builder to modify
+
returns: the modified builder
+Removes any existing rules from the flag.
+ + This undoes the effect ofif_match/3 and if_not_match/3.
+
+
+clear_targets(FlagBuilder::flag_builder()) -> flag_builder()
FlagBuilder: the flag builder to modify
+
returns: the modified builder
+Removes any existing targets from the flag.
+ + This undoes the effect ofvariation_for_context/4.
+
+
+fallthrough_variation(Variation::variation(), FlagBuilder::flag_builder()) -> flag_builder()
Variation: true, false, or the index of the desired variation to return: 0 for the first, 1 for the second, etc.
+FlagBuilder: the flag builder to modify
+
returns: the modified builder
+Specifies the fallthrough variation for a flag.
+ +The fallthrough is the value that is returned if targeting is on +and the user was not matched by a more specific target or rule.
+ + If the flag was previously configured with other variations and a boolean variation is specified, + this also changes the flagbuilder to a boolean flag. + + +if_match(ContextAttribute::ldclient_context:attribute_key(), Values::[term()], FlagBuilder::flag_builder()) -> flag_rule_builder()
ContextAttribute: the context attribute to match against
+Values: values to compare to
+FlagBuilder: the flag builder to modify
+
returns: a flag_rule_builder(); call then_return/2 to finish the rule,
+ or add more tests with and_match/4 or and_not_match/4.
Starts defining a flag rule, using the "is one of" operator. The kind of the context is implicitly "user"
+ for non-user contexts use if_match/4.
For example, this creates a rule that returns true if the name is "Patsy" or "Edina":
{ok, Flag} = ldclient_testdata:flag(TestData, <<"flag">>),
+ RuleBuilder = ldclient_flagbuilder:if_match(<<"name">>, [<<"Patsy">>, <<"Edina">>], Flag),
+ UpdatedFlag = ldclient_flagbuilder:then_return(true, RuleBuilder),
+ ldclient_testdata:update(TestData, UpdatedFlag).
+
+
+if_match(ContextKind::ldclient_context:kind_value(), ContextAttribute::ldclient_context:attribute_key(), Values::[term()], FlagBuilder::flag_builder()) -> flag_rule_builder()
ContextAttribute: the context attribute to match against
+Values: values to compare to
+FlagBuilder: the flag builder to modify
+
returns: a flag_rule_builder(); call then_return/2 to finish the rule,
+ or add more tests with and_match/4 or and_not_match/4.
Starts defining a flag rule, using the "is one of" operator.
+ +For example, this creates a rule that returns true if the name is "Patsy" or "Edina":
{ok, Flag} = ldclient_testdata:flag(TestData, <<"flag">>),
+ RuleBuilder = ldclient_flagbuilder:if_match(<<"user">>, <<"name">>, [<<"Patsy">>, <<"Edina">>], Flag),
+ UpdatedFlag = ldclient_flagbuilder:then_return(true, RuleBuilder),
+ ldclient_testdata:update(TestData, UpdatedFlag).
+
+
+if_not_match(ContextAttribute::ldclient_context:attribute_key(), Values::[term()], FlagBuilder::flag_builder()) -> flag_rule_builder()
ContextAttribute: the context attribute to match against
+Values: values to compare to
+FlagBuilder: the flag builder to modify
+
returns: a flag_rule_builder(); call then_return/2 to finish the rule,
+ or add more tests with and_match/4 or and_not_match/4.
Starts defining a flag rule, using the "is not one of" operator. The kind of the context is implicitly
+ "user" for non-user contexts use if_not_match/4.
For example, this creates a rule that returns true if the name is neither "Saffron" nor "Bubble":
{ok, Flag} = ldclient_testdata:flag(TestData, <<"flag">>),
+ RuleBuilder = ldclient_flagbuilder:if_not_match(<<"name">>, [<<"Saffron">>, <<"Bubble">>], Flag),
+ UpdatedFlag = ldclient_flagbuilder:then_return(true, RuleBuilder),
+ ldclient_testdata:update(TestData, UpdatedFlag).
+
+
+if_not_match(ContextKind::ldclient_context:kind_value(), ContextAttribute::ldclient_context:attribute_key(), Values::[term()], FlagBuilder::flag_builder()) -> flag_rule_builder()
ContextAttribute: the context attribute to match against
+Values: values to compare to
+FlagBuilder: the flag builder to modify
+
returns: a flag_rule_builder(); call then_return/2 to finish the rule,
+ or add more tests with and_match/4 or and_not_match/4.
Starts defining a flag rule, using the "is not one of" operator.
+ +For example, this creates a rule that returns true if the name is neither "Saffron" nor "Bubble":
{ok, Flag} = ldclient_testdata:flag(TestData, <<"flag">>),
+ RuleBuilder = ldclient_flagbuilder:if_not_match(<<"user">>, <<"name">>, [<<"Saffron">>, <<"Bubble">>], Flag),
+ UpdatedFlag = ldclient_flagbuilder:then_return(true, RuleBuilder),
+ ldclient_testdata:update(TestData, UpdatedFlag).
+
+
+off_variation(Variation::variation(), FlagBuilder::flag_builder()) -> flag_builder()
Variation: true, false, or the index of the desired variation to return: 0 for the first, 1 for the second, etc.
+FlagBuilder: the flag builder to modify
+
returns: the modified builder
+Specifies the off variation for a flag.
+ +The off variation is the value that is returned whenever targeting is off
+ + If the flag was previously configured with other variations and a boolean Variation is specified, + this also changes the FlagBuilder to a boolean flag. + + +on(IsOn::boolean(), FlagBuilder::flag_builder()) -> flag_builder()
IsOn: true if targeting should be on
+FlagBuilder: the flag builder to modify
+
returns: the modified builder +
+Sets targeting to be on or off for this flag.
+ + The effect of this depends on the rest of the flag configuration, just as it does on the + real LaunchDarkly dashboard. In the default configuration that you get from calling +ldclient_testdata:flag/2 with a new flag key, the flag will return false
+ whenever targeting is off, and true when targeting is on.
+
+
+then_return(Variation::variation(), RuleBuilder::flag_rule_builder()) -> flag_builder()
Variation: true, false, or the index of the desired variation to return: 0 for the first, 1 for the second, etc.
+RuleBuilder: the rule builder to use
+
returns: the modified flag builder that initially created this rule builder
+Finishes defining the rule, specifying the result variation.
+ + If the flag was previously configured with other variations and a boolean variation is specified, + this also changes the FlagBuilder to a boolean flag. + + +value_for_all(Value::term(), FlagBuilder::flag_builder()) -> flag_builder()
Value: the desired value to be returned for all contexts
+FlagBuilder: the flag builder to modify
+
returns: the modified builder
+Sets the flag to always return the specified variation value for all contexts.
+ + The value may be of any JSON type, as defined by }. This method changes the + flag to have only a single variation, which is this value, and to return the same + variation regardless of whether targeting is on or off. Any existing targets or rules + are removed. + + +variation_for_all(Variation::variation(), FlagBuilder::flag_builder()) -> flag_builder()
Variation: true, false, or the index of the desired variation to return: 0 for the first, 1 for the second, etc.
+FlagBuilder: the flag builder to modify
+
returns: the modified builder
+Sets the flag to always return the specified variation for all contexts.
+ +The variation is set, targeting is switched on, and any existing targets or rules are removed. +The fallthrough variation is set to the specified value. +The off variation is left unchanged.
+ + If the flag was previously configured with other variations and a boolean variation is specified, + this also changes the flagbuilder to a boolean flag. + + +variation_for_context(Variation::variation(), ContextKind::ldclient_context:kind_value(), ContextKey::binary(), FlagBuilder::flag_builder()) -> flag_builder()
Variation: true, false, or the index of the desired variation to return: 0 for the first, 1 for the second, etc.
+ContextKind: the kind of context to target
+ContextKey: the key of the context to target
+FlagBuilder: the flag builder to modify
+
returns: the modified builder
+Sets the flag to return the specified variation for a specific context kind and key when +targeting is on.
+ +This has no effect when targeting is turned off for the flag.
+ + If the flag was previously configured with other variations and a boolean variation is specified, + this also changes the flagbuilder to a boolean flag. + + +variations(Values::[ldclient_flag:variation_value()], FlagBuilder::flag_builder()) -> flag_builder()
FlagBuilder: the flag builder to modify
+
returns: the modified builder
+Sets the flag to always return the specified variation value for all contexts.
+ + The value may be of any JSON type. + This method changes the flag to have only a single variation, which is this value, + and to return the same variation regardless of whether targeting is on or off. + Any existing targets or rules are removed. + +Generated by EDoc
+ + diff --git a/ldclient_testdata.html b/ldclient_testdata.html new file mode 100644 index 0000000..c89e123 --- /dev/null +++ b/ldclient_testdata.html @@ -0,0 +1,152 @@ + + + + +Behaviours: gen_server.
+ +TestData server
+ +A mechanism for providing dynamically updatable feature flag state +in a simplified form to an SDK client in test scenarios.
+ +Unlike the file data mechanism, this does not use any external resources. +It provides only the data that the application has put into it using +the update/2 function.
+ + {ok, Flag} = ldclient_testdata:flag("flag-key-1"),
+ ldclient_testdata:update(ldclient_flagbuilder:variation_for_all(true, Flag)),
+
+ Options = #{
+ datasource => testdata,
+ send_events => false,
+ feature_store => ldclient_storage_map
+ },
+ ldclient:start_instance(SdkKey, Options),
+
+ %% flags can be updated at any time:
+ {ok, Flag2} = ldclient_testdata:flag("flag-key-2"),
+ UpdatedFlag2 = ldclient_flagbuilder:fallthrough_variation(false,
+ ldclient_flagbuilder:variation_for_context(<<"user">>, <<"some-user-key">>, true, Flag2)),
+
+ The above example uses a simple boolean flag, but more complex configurations
+ are possible using the functions in ldclient_flagbuilder.
ldclient_flagbuilder supports many of the ways a flag can be configured
+ on the LaunchDarkly dashboard, but does not currently support
+ ldclient_testdata instance is used to configure multiple ldclient_instance instances, any changes made to the data will propagate to all of the instances
+
+| child_spec/2 | |
| flag/1 | Creates or copies a ldclient_flagbuilder:flag_builder()
+for building a test flag configuration. |
| flag/2 | Creates or copies a ldclient_flagbuilder:flag_builder()
+for building a test flag configuration. |
| update/1 | Updates the test data with the specified flag configuration. |
| update/2 | Updates the test data with the specified flag configuration. |
child_spec(Tag::atom(), Args::[term()]) -> supervisor:child_spec()
+
flag(FlagKey::binary() | string()) -> {ok, ldclient_flagbuilder:flag_builder()}
FlagKey: the flag key
+
returns: a flag configuration builder
+Creates or copies a ldclient_flagbuilder:flag_builder()
+for building a test flag configuration.
If this flag key has already been defined in this ldclient_testdata instance,
+then the builder starts with the same configuration that was last provided for this flag.
Otherwise, it starts with a new default configuration in which the flag has true
+ and false variations, is true for all contexts when targeting is turned on and
+ false otherwise, and currently has targeting turned on.
You can change any of those properties, and provide more complex behavior,
+ using the functions in ldclient_flagbuilder.
update/2.
+
+See also: update/1.
+ +flag(Tag::atom() | pid(), FlagKey::binary()) -> {ok, ldclient_flagbuilder:flag_builder()}
Tag: the tag or pid of the ldclient_testdata instance
+FlagKey: the flag key
+
returns: a flag configuration builder
+Creates or copies a ldclient_flagbuilder:flag_builder()
+for building a test flag configuration.
If this flag key has already been defined in this ldclient_testdata instance,
+then the builder starts with the same configuration that was last provided for this flag.
Otherwise, it starts with a new default configuration in which the flag has true
+ and false variations, is true for all contexts when targeting is turned on and
+ false otherwise, and currently has targeting turned on.
You can change any of those properties, and provide more complex behavior,
+ using the functions in ldclient_flagbuilder.
update/2.
+
+See also: update/2.
+ +update(Flag::ldclient_flagbuilder:flag_builder()) -> ok
Flag: a flag configuration builder
+
Updates the test data with the specified flag configuration.
+ + This has the same effect as if a flag were added or modified on the LaunchDarkly dashboard. + It immediately propagates the flag change to anyldclient_instance(s) that you have
+ already configured to use this ldclient_testdata. If no ldclient_instance has
+ been started yet, it simply adds this flag to the test data which will be provided
+ to any ldclient_instance that you subsequently configure.
+
+See also: flag/1.
+ +update(Tag::atom() | pid(), Flag::ldclient_flagbuilder:flag_builder()) -> ok
Flag: a flag configuration builder
+
Updates the test data with the specified flag configuration.
+ + This has the same effect as if a flag were added or modified on the LaunchDarkly dashboard. + It immediately propagates the flag change to anyldclient_instance(s) that you have
+ already configured to use this ldclient_testdata. If no ldclient_instance has
+ been started yet, it simply adds this flag to the test data which will be provided
+ to any ldclient_instance that you subsequently configure.
+
+See also: flag/2.
+Generated by EDoc
+ + diff --git a/ldclient_user.html b/ldclient_user.html new file mode 100644 index 0000000..727c972 --- /dev/null +++ b/ldclient_user.html @@ -0,0 +1,115 @@ + + + + +attribute() = binary() | atom()
+ + +custom_attributes() = #{binary() := any()}
+ + +key() = binary() | null
+ + +private_attribute_names() = [binary()]
+ + +user() = #{key := key(), ip => binary(), country => binary(), email => binary(), first_name => binary(), last_name => binary(), avatar => binary(), name => binary(), anonymous => boolean(), custom => custom_attributes(), private_attribute_names => private_attribute_names()}
+ + +| event_format/1 | Formats a user for use in an event. |
| get/2 | Get an attribute value of a user. |
| new/1 | |
| new_from_map/1 | |
| scrub/2 | Scrub private attributes from user. |
| set/3 | Set an attribute value for a user. |
| set_private_attribute_names/2 | Sets a list of private attribute names for a user. |
Formats a user for use in an event.
+ + Returns the user with first_name and last_name attributes changed to firstName and + lastName so that LaunchDarkly can properly record user data. + +get(Attribute::attribute(), User::user()) -> term()
+
Get an attribute value of a user
+ + Lookup includes custom attributes. Returnsnull if attribute doesn't exist.
+
+new_from_map(Map::map()) -> user()
+
scrub(User::user(), GlobalPrivateAttributes::ldclient_config:private_attributes()) -> {user(), private_attribute_names()}
+
Scrub private attributes from user
+ + Returns the scrubbed user and the list of attributes that were actually + scrubbed. + +set(Attribute::attribute(), Value::any(), User::user()) -> user()
+
Set an attribute value for a user
+ + Sets given attribute to given value and returns the new user. This function + can handle both built-in and custom user attributes. + +set_private_attribute_names(AttributeNames::[attribute()], User::user()) -> user()
+
Sets a list of private attribute names for a user
+ + Any attributes that are on this list will not be sent to and indexed by + LaunchDarkly. However, they are still available for flag evaluations + performed by the SDK locally. This handles both built-in and custom + attributes. The built-inkey attribute cannot be made private - it will
+ always be sent.
+Generated by EDoc
+ + diff --git a/modules-frame.html b/modules-frame.html new file mode 100644 index 0000000..2c7794b --- /dev/null +++ b/modules-frame.html @@ -0,0 +1,17 @@ + + + +| ldclient |
| ldclient_config |
| ldclient_context |
| ldclient_flagbuilder |
| ldclient_testdata |
| ldclient_user |
LaunchDarkly is a feature management platform that serves over 100 billion feature flags daily to help teams build better software, faster.
+ +This version of the LaunchDarkly SDK is compatible with Erlang/OTP 21 or higher. +Generated by EDoc
+ + diff --git a/overview.edoc b/overview.edoc new file mode 100644 index 0000000..24832a4 --- /dev/null +++ b/overview.edoc @@ -0,0 +1,4 @@ +@title LaunchDarkly Server-Side SDK for Erlang/Elixir +@doc LaunchDarkly is a feature management platform that serves over 100 billion feature flags daily to help teams build better software, faster. + +This version of the LaunchDarkly SDK is compatible with Erlang/OTP 21 or higher. \ No newline at end of file diff --git a/stylesheet.css b/stylesheet.css new file mode 100644 index 0000000..ab170c0 --- /dev/null +++ b/stylesheet.css @@ -0,0 +1,55 @@ +/* standard EDoc style sheet */ +body { + font-family: Verdana, Arial, Helvetica, sans-serif; + margin-left: .25in; + margin-right: .2in; + margin-top: 0.2in; + margin-bottom: 0.2in; + color: #000000; + background-color: #ffffff; +} +h1,h2 { + margin-left: -0.2in; +} +div.navbar { + background-color: #add8e6; + padding: 0.2em; +} +h2.indextitle { + padding: 0.4em; + background-color: #add8e6; +} +h3.function,h3.typedecl { + background-color: #add8e6; + padding-left: 1em; +} +div.spec { + margin-left: 2em; + background-color: #eeeeee; +} +a.module { + text-decoration:none +} +a.module:hover { + background-color: #eeeeee; +} +ul.definitions { + list-style-type: none; +} +ul.index { + list-style-type: none; + background-color: #eeeeee; +} + +/* + * Minor style tweaks + */ +ul { + list-style-type: square; +} +table { + border-collapse: collapse; +} +td { + padding: 3 +}