-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Server-side SDK for integrating with LaunchDarkly
--
-- Please see the README on GitHub at
-- https://github.com/launchdarkly/haskell-server-sdk#readme
@package launchdarkly-server-sdk
@version 4.0.2
-- | The LaunchDarkly SDK supports a subset of Aeson 1.x and 2.x. These two
-- versions differ in their type signatures, but are otherwise largely
-- compatible. To support both versions, we provide this compatibility
-- module.
--
-- Depending on the version of Aeson you have installed, this module will
-- expose a KeyMap type that is either
--
--
-- - In the case of 1.x, a HashMap T.Text, or
-- - In the case of 2.x, the new KeyMap type
--
--
-- The compatibility layer exposes common map operations that the SDK
-- needs and may prove useful to customers. In nearly all instances,
-- these are simple aliases for the underlying Aeson equivalents.
--
-- The Aeson 2.x KeyMap is keyed by a new Key type that does not exist in
-- 1.x. To keep the API as consistent as possible, all functions
-- requiring a key will provide a Text value. In the 2.x compatibility
-- layer, we will convert it to a from the appropriate Key type as
-- necessary.
module LaunchDarkly.AesonCompat
type KeyMap = KeyMap
null :: KeyMap v -> Bool
emptyObject :: KeyMap v
singleton :: Text -> v -> KeyMap v
fromList :: [(Text, v)] -> KeyMap v
toList :: KeyMap v -> [(Text, v)]
deleteKey :: Text -> KeyMap v -> KeyMap v
lookupKey :: Text -> KeyMap v -> Maybe v
objectKeys :: KeyMap v -> [Text]
objectValues :: KeyMap v -> [v]
keyToText :: Key -> Text
insertKey :: Text -> v -> KeyMap v -> KeyMap v
filterKeys :: (Key -> Bool) -> KeyMap a -> KeyMap a
filterObject :: (v -> Bool) -> KeyMap v -> KeyMap v
adjustKey :: (v -> v) -> Key -> KeyMap v -> KeyMap v
mapValues :: (v1 -> v2) -> KeyMap v1 -> KeyMap v2
mapWithKey :: (Text -> v1 -> v2) -> KeyMap v1 -> KeyMap v2
mapMaybeValues :: (v1 -> Maybe v2) -> KeyMap v1 -> KeyMap v2
keyMapUnion :: KeyMap v -> KeyMap v -> KeyMap v
foldrWithKey :: (Text -> v -> a -> a) -> a -> KeyMap v -> a
-- | Reference is an attribute name or path expression identifying a value
-- within a Context.
--
-- This type is mainly intended to be used internally by LaunchDarkly SDK
-- and service code, where efficiency is a major concern so it's
-- desirable to do any parsing or preprocessing just once. Applications
-- are unlikely to need to use the Reference type directly.
--
-- It can be used to retrieve a value with getValueForReference or
-- to identify an attribute or nested value that should be considered
-- private.
--
-- Parsing and validation are done at the time that the Reference is
-- constructed. If a Reference instance was created from an invalid
-- string, it is considered invalid. The error can be inspected with
-- getError.
--
-- Syntax
--
-- The string representation of an attribute reference in LaunchDarkly
-- JSON data uses the following syntax:
--
-- If the first character is not a slash, the string is interpreted
-- literally as an attribute name. An attribute name can contain any
-- characters, but must not be empty.
--
-- If the first character is a slash, the string is interpreted as a
-- slash-delimited path where the first path component is an attribute
-- name, and each subsequent path component is the name of a property in
-- a JSON object. Any instances of the characters "/" or "~" in a path
-- component are escaped as "~1" or "~0" respectively. This syntax
-- deliberately resembles JSON Pointer, but no JSON Pointer behaviors
-- other than those mentioned here are supported.
--
-- Examples
--
-- Suppose there is a context whose JSON implementation looks like this:
--
-- { "kind": "user", "key": "value1", "address": { "street": { "line1":
-- "value2", "line2": "value3" }, "city": "value4" }, "good/bad":
-- "value5" }
--
-- The attribute references "key" and "/key" would both point to
-- "value1".
--
-- The attribute reference "addressstreet/line1" would point to
-- "value2".
--
-- The attribute references "goodbad" and "good~1bad" would both
-- point to "value5".
module LaunchDarkly.Server.Reference
-- | data record for the Reference type.
data Reference
-- | Creates a Reference from a string. For the supported syntax and
-- examples, see comments on the LaunchDarkly.Server.Reference
-- module.
--
-- This function always returns a Reference that preserves the original
-- string, even if validation fails, so that accessing getRawPath
-- (or serializing the Reference to JSON) will produce the original
-- string. If validation fails, getError will return an error and
-- any SDK method that takes this Reference as a parameter will consider
-- it invalid.
makeReference :: Text -> Reference
-- | makeLiteral is similar to makeReference except that it always
-- interprets the string as a literal attribute name, never as a
-- slash-delimited path expression. There is no escaping or unescaping,
-- even if the name contains literal / or ~ characters.
-- Since an attribute name can contain any characters, this method always
-- returns a valid Reference unless the name is empty.
--
-- For example: makeLiteral "name" is exactly equivalent to
-- makeReference "name". makeLiteral "a/b" is exactly
-- equivalent to makeReference "a/b" (since the syntax used by
-- makeReference treats the whole string as a literal as long as
-- it does not start with a slash), or to makeReference "/a~1b".
makeLiteral :: Text -> Reference
-- | Returns True for a valid Reference; False otherwise.
--
-- A Reference is invalid if the input string is empty, or starts with a
-- slash but is not a valid slash-delimited path, or starts with a slash
-- and contains an invalid escape sequence.
--
-- Otherwise, the Reference is valid, but that does not guarantee that
-- such an attribute exists in any given Context. For instance,
-- makeReference "name" is a valid Reference, but a specific
-- Context might or might not have a name.
--
-- See comments on the LaunchDarkly.Server.Reference module for
-- more details of the attribute reference syntax.
isValid :: Reference -> Bool
-- | Returns an empty string for a valid Reference, or a Text error
-- description for an invalid Reference.
--
-- See comments on the LaunchDarkly.Server.Reference module for
-- more details of the attribute reference syntax.
getError :: Reference -> Text
-- | Retrieves path components from the attribute reference.
--
-- Invalid references will return an empty list.
--
--
-- makeReference "" & getComponents -- returns []
-- makeReference "a" & getComponents -- returns ["a"]
-- makeReference "/a/b" & getComponents -- returns ["a", "b"]
--
getComponents :: Reference -> [Text]
-- | Returns the attribute reference as a string, in the same format
-- provided to makeReference.
--
-- If the Reference was created with makeReference, this value is
-- identical to the original string. If it was created with
-- makeLiteral, the value may be different due to unescaping (for
-- instance, an attribute whose name is "/a" would be represented as
-- "~1a").
getRawPath :: Reference -> Text
instance GHC.Classes.Eq LaunchDarkly.Server.Reference.Reference
instance GHC.Show.Show LaunchDarkly.Server.Reference.Reference
instance GHC.Classes.Ord LaunchDarkly.Server.Reference.Reference
instance Data.Aeson.Types.ToJSON.ToJSON LaunchDarkly.Server.Reference.Reference
-- | This module contains details for external store implementations.
module LaunchDarkly.Server.Store
-- | The result type for every PersistentDataStore function. Instead
-- of throwing an exception, any store related error should return
-- Left. Exceptions unrelated to the store should not be caught.
type StoreResult a = IO (Either Text a)
-- | Represents the key for a given feature.
type FeatureKey = Text
-- | Represents a namespace such as features or segments
type FeatureNamespace = Text
-- | The interface implemented by external stores for use by the SDK.
data PersistentDataStore
PersistentDataStore :: !FeatureNamespace -> StoreResult (KeyMap SerializedItemDescriptor) -> !FeatureNamespace -> FeatureKey -> StoreResult (Maybe SerializedItemDescriptor) -> !FeatureNamespace -> FeatureKey -> SerializedItemDescriptor -> StoreResult Bool -> !StoreResult Bool -> !KeyMap (KeyMap SerializedItemDescriptor) -> StoreResult () -> PersistentDataStore
-- | A map of all features in a given namespace including deleted.
[$sel:persistentDataStoreAllFeatures:PersistentDataStore] :: PersistentDataStore -> !FeatureNamespace -> StoreResult (KeyMap SerializedItemDescriptor)
-- | Return the value of a key in a namespace.
[$sel:persistentDataStoreGetFeature:PersistentDataStore] :: PersistentDataStore -> !FeatureNamespace -> FeatureKey -> StoreResult (Maybe SerializedItemDescriptor)
-- | Upsert a given feature. Versions should be compared before upsert. The
-- result should indicate if the feature was replaced or not.
[$sel:persistentDataStoreUpsertFeature:PersistentDataStore] :: PersistentDataStore -> !FeatureNamespace -> FeatureKey -> SerializedItemDescriptor -> StoreResult Bool
-- | Checks if the external store has been initialized, which may have been
-- done by another instance of the SDK.
[$sel:persistentDataStoreIsInitialized:PersistentDataStore] :: PersistentDataStore -> !StoreResult Bool
-- | A map of namespaces, and items in namespaces. The entire store state
-- should be replaced with these values.
[$sel:persistentDataStoreInitialize:PersistentDataStore] :: PersistentDataStore -> !KeyMap (KeyMap SerializedItemDescriptor) -> StoreResult ()
-- | A record representing an object that can be persisted in an external
-- store.
data SerializedItemDescriptor
SerializedItemDescriptor :: !Maybe ByteString -> !Natural -> !Bool -> SerializedItemDescriptor
-- | A serialized item. If the item is deleted or does not exist this
-- should be Nothing.
[$sel:item:SerializedItemDescriptor] :: SerializedItemDescriptor -> !Maybe ByteString
-- | The version of a given item. If the item does not exist this should be
-- zero.
[$sel:version:SerializedItemDescriptor] :: SerializedItemDescriptor -> !Natural
-- | True if this is a placeholder (tombstone) for a deleted item.
[$sel:deleted:SerializedItemDescriptor] :: SerializedItemDescriptor -> !Bool
-- | Generate a ByteString representation of the
-- SerializedItemDescriptor.
--
-- If the SerializedItemDescriptor has either a Nothing
-- value, or is marked as deleted, the ByteString representation will be
-- a tombstone marker containing the version and deletion status.
--
-- Otherwise, the internal item representation is returned.
serializeWithPlaceholder :: SerializedItemDescriptor -> ByteString
-- | Partially decode the provided ByteString into a VersionedData
-- struct.
--
-- This is useful for persistent stores who need to perform version
-- comparsions before persisting data.
byteStringToVersionedData :: ByteString -> Maybe VersionedData
-- | A mechanism for providing dynamically updatable feature flag state in
-- a simplified form to an SDK client in test scenarios.
--
-- Unlike LaunchDarkly.Server.Integrations.FileData, this
-- mechanism does not use any external resources. It provides only the
-- data that the application has put into it using the update
-- function.
--
--
-- td <- TestData.newTestData
-- update td =<< (flag td "flag-key-1"
-- <&> booleanFlag
-- <&> variationForAll True)
--
-- let config = makeConfig "sdkKey"
-- & configSetDataSourceFactory (dataSourceFactory td)
-- client <- makeClient config
--
-- -- flags can be updated at any time:
-- update td =<<
-- (flag td "flag-key-2"
-- <&> variationForKey "user" "some-user-key" True
-- <&> fallthroughVariation False)
--
--
-- The above example uses a simple boolean flag, but more complex
-- configurations are possible using the methods of the
-- FlagBuilder that is returned by flag. FlagBuilder
-- supports many of the ways a flag can be configured on the LaunchDarkly
-- dashboard, but does not currently support:
--
--
-- - Rule operators other than "in" and "not in"
-- - Percentage rollouts.
--
--
-- If the same TestData instance is used to configure multiple
-- Client instances, any changes made to the data will propagate
-- to all of the Clients.
--
-- see LaunchDarkly.Server.Integrations.FileData
module LaunchDarkly.Server.Integrations.TestData
data TestData
-- | Creates a new instance of the test data source.
newTestData :: IO TestData
-- | Creates or copies a FlagBuilder for building a test flag
-- configuration.
--
-- If this flag key has already been defined in this 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 users 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
-- FlagBuilder methods.
--
-- Once you have set the desired configuration, pass the builder to
-- update.
--
-- see update
flag :: TestData -> Text -> IO FlagBuilder
-- | 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
-- any Client instance(s) that you have already configured to use
-- this TestData. If no Client has been started yet, it
-- simply adds this flag to the test data which will be provided to any
-- Client that you subsequently configure.
--
-- Any subsequent changes to this FlagBuilder instance do not
-- affect the test data, unless you call update
--
-- see flag
update :: TestData -> FlagBuilder -> IO ()
dataSourceFactory :: TestData -> DataSourceFactory
-- | A builder for feature flag configurations to be used with
-- LaunchDarkly.Server.Integrations.TestData.
--
-- see flag and update
data FlagBuilder
-- | A shortcut for setting the flag to use the standard boolean
-- configuration.
--
-- This is the default for all new flags created with flag. 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.
booleanFlag :: FlagBuilder -> FlagBuilder
-- | 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 flag with a new flag
-- key, the flag will return False whenever targeting is off,
-- and True when targeting is on.
on :: Bool -> FlagBuilder -> FlagBuilder
-- | Specifies the fallthrough variation. The fallthrough is the value that
-- is returned if targeting is on and the context was not matched by a
-- more specific target or rule.
--
-- If the flag was previously configured with other variations and the
-- variation specified is a boolean, this also changes it to a boolean
-- flag.
fallthroughVariation :: Variation val => val -> FlagBuilder -> FlagBuilder
-- | Specifies the off variation for a flag. This is the variation that is
-- returned whenever targeting is off.
--
-- If the flag was previously configured with other variations and the
-- variation specified is a boolean, this also changes it to a boolean
-- flag.
offVariation :: Variation val => val -> FlagBuilder -> FlagBuilder
-- | Sets the flag to always return the specified variation for all
-- contexts.
--
-- The variation is specified, 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 the
-- variation specified is a boolean, this also changes it to a boolean
-- flag.
variationForAll :: Variation val => val -> FlagBuilder -> FlagBuilder
-- | Sets the flag to always return the specified variation for all users.
--
-- The variation is specified, 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 the
-- variation specified is a boolean, this also changes it to a boolean
-- flag.
-- | Deprecated: Use variationForAll instead
variationForAllUsers :: Variation val => val -> FlagBuilder -> FlagBuilder
-- | Sets the flag to always return the specified variation value for all
-- contexts.
--
-- The value may be of any type that implements ToJSON. 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.
valueForAll :: ToJSON value => value -> FlagBuilder -> FlagBuilder
-- | Sets the flag to always return the specified variation value for all
-- users.
--
-- This function is an alias to valueForAll.
--
-- The value may be of any type that implements ToJSON. 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.
-- | Deprecated: Use valueForAll instead
valueForAllUsers :: ToJSON value => value -> FlagBuilder -> FlagBuilder
-- | 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 the
-- variation specified is a boolean, this also changes it to a boolean
-- flag.
variationForKey :: Variation val => Text -> Text -> val -> FlagBuilder -> FlagBuilder
-- | Sets the flag to return the specified variation for a specific user
-- 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 the
-- variation specified is a boolean, this also changes it to a boolean
-- flag.
-- | Deprecated: Use variationForKey instead
variationForUser :: Variation val => Text -> val -> FlagBuilder -> FlagBuilder
-- | Changes the allowable variation values for the flag.
--
-- The value may be of any JSON type, as defined by Value. For
-- instance, a boolean flag normally has [toJSON True, toJSON False]; a
-- string-valued flag might have [toJSON "red", toJSON "green"]; etc.
variations :: [Value] -> FlagBuilder -> FlagBuilder
-- | Starts defining a flag rule, using the "is one of" operator.
--
-- This is a shortcut for calling ifMatch with a context kind of
-- "user".
--
-- For example, this creates a rule that returns True if the
-- name is "Patsy" or "Edina":
--
--
-- testData
-- & flag "flag"
-- & ifMatch "name" [toJSON "Patsy", toJSON "Edina"]
-- & thenReturn True
--
-- | Deprecated: Use ifMatchContext instead
ifMatch :: Text -> [Value] -> FlagBuilder -> FlagRuleBuilder
-- | 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":
--
--
-- testData
-- & flag "flag"
-- & ifMatchContext "user" "name" [toJSON "Patsy", toJSON "Edina"]
-- & thenReturn True
--
ifMatchContext :: Text -> Text -> [Value] -> FlagBuilder -> FlagRuleBuilder
-- | Starts defining a flag rule, using the "is not one of" operator.
--
-- This is a shortcut for calling ifNotMatchContext with a context
-- kind of "user".
--
-- For example, this creates a rule that returns True if the
-- name is neither "Saffron" nor "Bubble"
--
--
-- testData
-- & flag "flag"
-- & ifNotMatch "name" [toJSON "Saffron", toJSON "Bubble"]
-- & thenReturn True
--
-- | Deprecated: Use ifNotMatchContext instead
ifNotMatch :: Text -> [Value] -> FlagBuilder -> FlagRuleBuilder
-- | 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"
--
--
-- testData
-- & flag "flag"
-- & ifNotMatchContext "user" "name" [toJSON "Saffron", toJSON "Bubble"]
-- & thenReturn True
--
ifNotMatchContext :: Text -> Text -> [Value] -> FlagBuilder -> FlagRuleBuilder
type VariationIndex = Integer
-- | A builder for feature flag rules to be used with FlagBuilder.
--
-- In the LaunchDarkly model, a flag can have any number of rules, and a
-- rule can have any number of clauses. A clause is an individual test
-- such as "name is 'X'". A rule matches a context if all of the rule's
-- clauses match the context.
--
-- To start defining a rule, use one of the matching functions such as
-- ifMatch or ifNotMatch. This defines the first clause for
-- the rule.
--
-- Optionally, you may add more clauses with the rule builder functions
-- such as andMatch and andNotMatch.
--
-- Finally, call thenReturn to finish defining the rule.
data FlagRuleBuilder
-- | Adds another clause, using the "is one of" operator.
--
-- This is a shortcut for calling andMatchContext with a context
-- kind of "user".
--
-- For example, this creates a rule that returns True if the
-- name is "Patsy" and the country is "gb":
--
--
-- testData
-- & flag "flag"
-- & ifMatch "name" [toJSON "Patsy"]
-- & andMatch "country" [toJSON "gb"]
-- & thenReturn True
--
-- | Deprecated: Use andMatchContext instead
andMatch :: Text -> [Value] -> FlagRuleBuilder -> FlagRuleBuilder
-- | Adds another clause, using the "is one of" operator.
--
-- For example, this creates a rule that returns True if the
-- name is "Patsy" and the country is "gb":
--
--
-- testData
-- & flag "flag"
-- & ifMatch "name" [toJSON "Patsy"]
-- & andMatch "country" [toJSON "gb"]
-- & thenReturn True
--
andMatchContext :: Text -> Text -> [Value] -> FlagRuleBuilder -> FlagRuleBuilder
-- | Adds another clause, using the "is not one of" operator.
--
-- This is a shortcut for calling andNotMatchContext with a
-- context kind of "user".
--
-- For example, this creates a rule that returns True if the
-- name is "Patsy" and the country is not "gb":
--
--
-- testData
-- & flag "flag"
-- & ifMatch "name" [toJSON "Patsy"]
-- & andNotMatch "country" [toJSON "gb"]
-- & thenReturn True
--
-- | Deprecated: Use andNotMatchContext instead
andNotMatch :: Text -> [Value] -> FlagRuleBuilder -> FlagRuleBuilder
-- | 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":
--
--
-- testData
-- & flag "flag"
-- & ifMatchContext "user" "name" [toJSON "Patsy"]
-- & andNotMatchContext "user" "country" [toJSON "gb"]
-- & thenReturn True
--
andNotMatchContext :: Text -> Text -> [Value] -> FlagRuleBuilder -> FlagRuleBuilder
-- | Finishes defining the rule, specifying the result as either a boolean
-- or a variation index.
--
-- If the flag was previously configured with other variations and the
-- variation specified is a boolean, this also changes it to a boolean
-- flag.
thenReturn :: Variation val => val -> FlagRuleBuilder -> FlagBuilder
-- | Integration between the LaunchDarkly SDK and file data.
--
-- The file data source allows you to use local files as a source of
-- feature flag state. This would typically be used in a test
-- environment, to operate using a predetermined feature flag state
-- without an actual LaunchDarkly connection. See
-- dataSourceFactory for details.
module LaunchDarkly.Server.Integrations.FileData
-- | Creates a DataSourceFactory which uses the configured file
-- data sources.
--
-- This allows you to use local files as a source of feature flag state,
-- instead of using an actual LaunchDarkly connection.
--
-- To use the file dataSource you can add it to the Config using
-- configSetDataSourceFactory
--
--
-- let config = configSetDataSourceFactory (FileData.dataSourceFactory [".testDataflags.json"]) $
-- makeConfig "sdk-key"
-- client <- makeClient config
--
--
-- This will cause the client not to connect to LaunchDarkly to
-- get feature flags. The client may still make network connections to
-- send analytics events, unless you have disabled this with
-- configSetSendEvents to False. IMPORTANT: Do not
-- set configSetOffline to True; doing so would not just
-- put the SDK "offline" with regard to LaunchDarkly, but will completely
-- turn off all flag data sources to the SDK /including the file data
-- source/.
--
-- Flag data files can be either JSON or YAML. They contain an object
-- with three possible properties:
--
--
-- - flags Feature flag definitions.
-- - flagValues Simplified feature flags that contain
-- only a value.
-- - segments Context segment definitions.
--
--
-- The format of the data in flags and segments is
-- defined by the LaunchDarkly application and is subject to change.
-- Rather than trying to construct these objects yourself, it is simpler
-- to request existing flags directly from the LaunchDarkly server in
-- JSON format, and use this output as the starting point for your file.
-- In Linux you would do this:
--
--
-- curl -H "Authorization: {your sdk key}" https://sdk.launchdarkly.com/sdk/latest-all
--
--
-- The output will look something like this (but with many more
-- properties):
--
--
-- {
-- "flags": {
-- "flag-key-1": {
-- "key": "flag-key-1",
-- "on": true,
-- "variations": [ "a", "b" ]
-- },
-- "flag-key-2": {
-- "key": "flag-key-2",
-- "on": true,
-- "variations": [ "c", "d" ]
-- }
-- },
-- "segments": {
-- "segment-key-1": {
-- "key": "segment-key-1",
-- "includes": [ "user-key-1" ]
-- }
-- }
-- }
--
--
-- Data in this format allows the SDK to exactly duplicate all the kinds
-- of flag behavior supported by LaunchDarkly. However, in many cases you
-- will not need this complexity, but will just want to set specific flag
-- keys to specific values. For that, you can use a much simpler format:
--
--
-- {
-- "flagValues": {
-- "my-string-flag-key": "value-1",
-- "my-boolean-flag-key": true,
-- "my-integer-flag-key": 3
-- }
-- }
--
--
-- Or, in YAML:
--
--
-- flagValues:
-- my-string-flag-key: "value-1"
-- my-boolean-flag-key: true
--
--
-- It is also possible to specify both flags and
-- flagValues, if you want some flags to have simple values and
-- others to have complex behavior. However, it is an error to use the
-- same flag key or segment key more than once, either in a single file
-- or across multiple files.
--
-- If the data source encounters any error in any file(malformed content,
-- a missing file) it will not load flags from that file. If the data
-- source encounters a duplicate key it will ignore that duplicate entry.
dataSourceFactory :: [FilePath] -> DataSourceFactory
instance GHC.Classes.Eq LaunchDarkly.Server.Integrations.FileData.FileFlag
instance GHC.Show.Show LaunchDarkly.Server.Integrations.FileData.FileFlag
instance Data.Aeson.Types.FromJSON.FromJSON LaunchDarkly.Server.Integrations.FileData.FileFlag
instance GHC.Generics.Generic LaunchDarkly.Server.Integrations.FileData.FileFlag
instance GHC.Classes.Eq LaunchDarkly.Server.Integrations.FileData.FileSegment
instance GHC.Show.Show LaunchDarkly.Server.Integrations.FileData.FileSegment
instance Data.Aeson.Types.FromJSON.FromJSON LaunchDarkly.Server.Integrations.FileData.FileSegment
instance GHC.Generics.Generic LaunchDarkly.Server.Integrations.FileData.FileSegment
instance Data.Aeson.Types.FromJSON.FromJSON LaunchDarkly.Server.Integrations.FileData.FileBody
instance GHC.Show.Show LaunchDarkly.Server.Integrations.FileData.FileBody
instance GHC.Generics.Generic LaunchDarkly.Server.Integrations.FileData.FileBody
instance GHC.Base.Semigroup LaunchDarkly.Server.Integrations.FileData.FileBody
instance GHC.Base.Monoid LaunchDarkly.Server.Integrations.FileData.FileBody
-- | This module is for configuration of the SDK.
module LaunchDarkly.Server.Config
-- | Config allows advanced configuration of the LaunchDarkly client.
data Config
-- | Create a default configuration from a given SDK key.
makeConfig :: Text -> Config
-- | Set the SDK key used to authenticate with LaunchDarkly.
configSetKey :: Text -> Config -> Config
-- | The base URI of the main LaunchDarkly service. This should not
-- normally be changed except for testing.
configSetBaseURI :: Text -> Config -> Config
-- | The base URI of the LaunchDarkly streaming service. This should not
-- normally be changed except for testing.
configSetStreamURI :: Text -> Config -> Config
-- | The base URI of the LaunchDarkly service that accepts analytics
-- events. This should not normally be changed except for testing.
configSetEventsURI :: Text -> Config -> Config
-- | Sets whether streaming mode should be enabled. By default, streaming
-- is enabled. It should only be disabled on the advice of LaunchDarkly
-- support.
configSetStreaming :: Bool -> Config -> Config
-- | The initial delay in milliseconds before reconnecting after an error
-- in the SSE client. Defaults to 1 second.
--
-- This only applies to the streaming connection. Providing a
-- non-positive integer is a no-op.
configSetInitialRetryDelay :: Int -> Config -> Config
-- | 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 in
-- PrivateAttributeNames.
configSetAllAttributesPrivate :: Bool -> Config -> Config
-- | Marks a set of context attribute names private. Any contexts sent to
-- LaunchDarkly with this configuration active will have attributes with
-- these names removed.
configSetPrivateAttributeNames :: Set Reference -> Config -> Config
-- | The time between flushes of the event buffer. Decreasing the flush
-- interval means that the event buffer is less likely to reach capacity.
configSetFlushIntervalSeconds :: Natural -> Config -> Config
-- | The polling interval (when streaming is disabled).
configSetPollIntervalSeconds :: Natural -> Config -> Config
-- | The number of context keys that the event processor can remember at
-- any one time, so that duplicate context details will not be sent in
-- analytics events.
configSetContextKeyLRUCapacity :: Natural -> Config -> Config
-- | Deprecated historically named function which proxies to
-- configSetContextKeyLRUCapacity.
-- | Deprecated: Use configSetContextKeyLRUCapacity instead
configSetUserKeyLRUCapacity :: Natural -> Config -> Config
-- | 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.
configSetEventsCapacity :: Natural -> Config -> Config
-- | Set the logger to be used by the client.
configSetLogger :: (LoggingT IO () -> IO ()) -> Config -> Config
-- | Sets the Manager to use with the client. If not set explicitly
-- a new Manager will be created when creating the client.
configSetManager :: Manager -> Config -> Config
-- | Sets whether to send analytics events back to LaunchDarkly. By
-- default, the client will send events. This differs from Offline in
-- that it only affects sending events, not streaming or polling for
-- events from the server.
configSetSendEvents :: Bool -> Config -> Config
-- | Sets whether this client is offline. An offline client will not make
-- any network connections to LaunchDarkly, and will return default
-- values for all feature flags.
configSetOffline :: Bool -> Config -> Config
-- | Sets how long an the HTTP client should wait before a response is
-- returned.
configSetRequestTimeoutSeconds :: Natural -> Config -> Config
-- | Configures a handle to an external store such as Redis.
configSetStoreBackend :: Maybe PersistentDataStore -> Config -> Config
-- | When a store backend is configured, control how long values should be
-- cached in memory before going back to the backend.
configSetStoreTTL :: Natural -> Config -> Config
-- | Sets whether this client should use the LaunchDarkly Relay Proxy in
-- daemon mode. In this mode, the client does not subscribe to the
-- streaming or polling API, but reads data only from the feature store.
-- See: https://docs.launchdarkly.com/home/relay-proxy
configSetUseLdd :: Bool -> Config -> Config
-- | Sets a data source to use instead of the default network based data
-- source see LaunchDarkly.Server.Integrations.FileData
configSetDataSourceFactory :: Maybe DataSourceFactory -> Config -> Config
-- | An object that allows configuration of application metadata.
--
-- Application metadata may be used in LaunchDarkly analytics or other
-- product features, but does not affect feature flag evaluations.
--
-- If you want to set non-default values for any of these fields, provide
-- the appropriately configured dict to the Config object.
configSetApplicationInfo :: ApplicationInfo -> Config -> Config
-- | An object that allows configuration of application metadata.
--
-- Application metadata may be used in LaunchDarkly analytics or other
-- product features, but does not affect feature flag evaluations.
--
-- To use these properties, provide an instance of ApplicationInfo to the
-- Config with configSetApplicationInfo.
data ApplicationInfo
-- | Create a default instance
makeApplicationInfo :: ApplicationInfo
-- | Set a new name / value pair into the application info instance.
--
-- Values have the following restrictions: - Cannot be empty - Cannot
-- exceed 64 characters in length - Can only contain a-z, A-Z, 0-9,
-- period (.), dash (-), and underscore (_).
--
-- Invalid values or unsupported keys will be ignored.
withApplicationValue :: Text -> Text -> ApplicationInfo -> ApplicationInfo
-- | Context is a collection of attributes that can be referenced in flag
-- evaluations and analytics events.
--
-- To create a Context of a single kind, such as a user, you may use
-- makeContext.
--
-- To create an LDContext with multiple kinds, use
-- makeMultiContext.
--
-- Additional properties can be set on a single-kind context using the
-- set methods found in this module.
--
-- Each method will always return a Context. However, that Context may be
-- invalid. You can check the validity of the resulting context, and the
-- associated errors by calling isValid and getError.
module LaunchDarkly.Server.Context
-- | data record for the Context type
data Context
-- | Create a single kind context from the provided hash.
--
-- The provided hash must match the format as outlined in the SDK
-- documentation.
makeContext :: Text -> Text -> Context
-- | Create a multi-kind context from the list of Contexts provided.
--
-- A multi-kind context is comprised of two or more single kind contexts.
-- You cannot include a multi-kind context instead another multi-kind
-- context.
--
-- Additionally, the kind of each single-kind context must be unique. For
-- instance, you cannot create a multi-kind context that includes two
-- user kind contexts.
--
-- If you attempt to create a multi-kind context from one single-kind
-- context, this method will return the single-kind context instead of a
-- new multi-kind context wrapping that one single-kind.
makeMultiContext :: [Context] -> Context
-- | Sets the name attribute for a single-kind context.
--
-- Calling this method on an invalid or multi-kind context is a no-op.
withName :: Text -> Context -> Context
-- | Sets the anonymous attribute for a single-kind context.
--
-- Calling this method on an invalid or multi-kind context is a no-op.
withAnonymous :: Bool -> Context -> Context
-- | Sets the value of any attribute for the context.
--
-- This includes only attributes that are addressable in evaluations --
-- not metadata such as private attributes. For example, if the attribute
-- name is "privateAttributes", you will be setting an attribute with
-- that name which you can use in evaluations or to record data for your
-- own purposes, but it will be unrelated to
-- withPrivateAttributes.
--
-- If attribute name is "privateAttributeNames", it is ignored and no
-- attribute is set.
--
-- This method uses the Value type to represent a value of any JSON type:
-- null, boolean, number, string, array, or object. For all attribute
-- names that do not have special meaning to LaunchDarkly, you may use
-- any of those types. Values of different JSON types are always treated
-- as different values: for instance, null, false, and the empty string
-- "" are not the same, and the number 1 is not the same as the string
-- "1".
--
-- The following attribute names have special restrictions on their value
-- types, and any value of an unsupported type will be ignored (leaving
-- the attribute unchanged):
--
--
-- - "name": Must be a string.
-- - "anonymous": Must be a boolean.
--
--
-- The attribute name "_meta" is not allowed, because it has special
-- meaning in the JSON schema for contexts; any attempt to set an
-- attribute with this name has no effect.
--
-- The attribute names "kind" and "key" are not allowed. They must be
-- provided during the initial context creation. See makeContext.
--
-- Values that are JSON arrays or objects have special behavior when
-- referenced in flag/segment rules.
--
-- For attributes that aren't subject to the special restrictions
-- mentioned above, a value of Null is equivalent to removing any current
-- non-default value of the attribute. Null is not a valid attribute
-- value in the LaunchDarkly model; any expressions in feature flags that
-- reference an attribute with a null value will behave as if the
-- attribute did not exist.
--
-- Calling this method on an invalid or multi-kind context is a no-op.
withAttribute :: Text -> Value -> Context -> Context
-- | Sets the private attributes for a single-kind context.
--
-- Calling this method on an invalid or multi-kind context is a no-op.
withPrivateAttributes :: Set Reference -> Context -> Context
-- | Determines if the provided context is valid.
isValid :: Context -> Bool
-- | Returns the error associated with the context if it is invalid.
getError :: Context -> Text
-- | Returns the single-kind Context corresponding to one of the kinds in
-- this context.
--
-- If this method is called on a single-kind Context and the requested
-- kind matches the context's kind, then that context is returned.
--
-- If the method is called on a multi-context, the provided kind must
-- match the context kind of one of the individual contexts.
--
-- If there is no context corresponding to
-- $sel:kind:SingleContext, the method returns Nothing.
getIndividualContext :: Text -> Context -> Maybe Context
-- | Looks up the value of any attribute of the Context, or a value
-- contained within an attribute, based on a Reference instance.
-- This includes only attributes that are addressable in evaluations--
-- not metadata such as private attributes.
--
-- This implements the same behavior that the SDK uses to resolve
-- attribute references during a flag evaluation. In a single-kind
-- context, the Reference can represent a simple attribute name--
-- either a built-in one like "name" or "key", or a custom attribute --
-- or, it can be a slash-delimited path using a JSON-Pointer-like syntax.
-- See Reference for more details.
--
-- For a multi-kind context, the only supported attribute name is "kind".
-- Use getIndividualContext to inspect a Context for a particular
-- kind and then get its attributes.
--
-- If the value is found, the return value is the attribute value;
-- otherwise, it is Null.
getValueForReference :: Reference -> Context -> Value
-- | Looks up the value of any attribute of the Context by name. This
-- includes only attributes that are addressable in evaluations-- not
-- metadata such as private attributes.
--
-- For a single-kind context, the attribute name can be any custom
-- attribute. It can also be one of the built-in ones like "kind", "key",
-- or "name".
--
-- For a multi-kind context, the only supported attribute name is "kind".
-- Use getIndividualContext to inspect a Context for a particular
-- kind and then get its attributes.
--
-- This method does not support complex expressions for getting
-- individual values out of JSON objects or arrays, such as
-- "addressstreet". Use getValueForReference for that
-- purpose.
--
-- If the value is found, the return value is the attribute value;
-- otherwise, it is Null.
getValue :: Text -> Context -> Value
-- | This module contains the core functionality of the SDK.
module LaunchDarkly.Server.Client
-- | Client is the LaunchDarkly client. Client instances are thread-safe.
-- Applications should instantiate a single instance for the lifetime of
-- their application.
data Client
-- | Create a new instance of the LaunchDarkly client.
makeClient :: Config -> IO Client
-- | The version string for this library.
clientVersion :: Text
-- | Evaluate a Boolean typed flag.
boolVariation :: Client -> Text -> Context -> Bool -> IO Bool
-- | Evaluate a Boolean typed flag, and return an explanation.
boolVariationDetail :: Client -> Text -> Context -> Bool -> IO (EvaluationDetail Bool)
-- | Evaluate a String typed flag.
stringVariation :: Client -> Text -> Context -> Text -> IO Text
-- | Evaluate a String typed flag, and return an explanation.
stringVariationDetail :: Client -> Text -> Context -> Text -> IO (EvaluationDetail Text)
-- | Evaluate a Number typed flag, and truncate the result.
intVariation :: Client -> Text -> Context -> Int -> IO Int
-- | Evaluate a Number typed flag, truncate the result, and return an
-- explanation.
intVariationDetail :: Client -> Text -> Context -> Int -> IO (EvaluationDetail Int)
-- | Evaluate a Number typed flag.
doubleVariation :: Client -> Text -> Context -> Double -> IO Double
-- | Evaluate a Number typed flag, and return an explanation.
doubleVariationDetail :: Client -> Text -> Context -> Double -> IO (EvaluationDetail Double)
-- | Evaluate a JSON typed flag.
jsonVariation :: Client -> Text -> Context -> Value -> IO Value
-- | Evaluate a JSON typed flag, and return an explanation.
jsonVariationDetail :: Client -> Text -> Context -> Value -> IO (EvaluationDetail Value)
-- | Combines the result of a flag evaluation with an explanation of how it
-- was calculated.
data EvaluationDetail value
EvaluationDetail :: !value -> !Maybe Integer -> !EvaluationReason -> EvaluationDetail value
-- | The result of the flag evaluation. This will be either one of the
-- flag's variations or the default value passed by the application.
[$sel:value:EvaluationDetail] :: EvaluationDetail value -> !value
-- | The index of the returned value within the flag's list of variations,
-- e.g. 0 for the first variation - or Nothing if the default value was
-- returned.
[$sel:variationIndex:EvaluationDetail] :: EvaluationDetail value -> !Maybe Integer
-- | Describes the main factor that influenced the flag evaluation value.
[$sel:reason:EvaluationDetail] :: EvaluationDetail value -> !EvaluationReason
-- | Defines the possible values of the Kind property of EvaluationReason.
data EvaluationReason
-- | Indicates that the flag was off and therefore returned its configured
-- off value.
EvaluationReasonOff :: EvaluationReason
-- | indicates that the context key was specifically targeted for this
-- flag.
EvaluationReasonTargetMatch :: EvaluationReason
EvaluationReasonRuleMatch :: !Natural -> !Text -> !Bool -> EvaluationReason
-- | The index of the rule that was matched (0 being the first).
[$sel:ruleIndex:EvaluationReasonOff] :: EvaluationReason -> !Natural
-- | The unique identifier of the rule that was matched.
[$sel:ruleId:EvaluationReasonOff] :: EvaluationReason -> !Text
-- | Whether the evaluation was part of an experiment. Is true if the
-- evaluation resulted in an experiment rollout *and* served one of the
-- variations in the experiment. Otherwise false.
[$sel:inExperiment:EvaluationReasonOff] :: EvaluationReason -> !Bool
EvaluationReasonPrerequisiteFailed :: !Text -> EvaluationReason
-- | The flag key of the prerequisite that failed.
[$sel:prerequisiteKey:EvaluationReasonOff] :: EvaluationReason -> !Text
EvaluationReasonFallthrough :: !Bool -> EvaluationReason
-- | Whether the evaluation was part of an experiment. Is true if the
-- evaluation resulted in an experiment rollout *and* served one of the
-- variations in the experiment. Otherwise false.
[$sel:inExperiment:EvaluationReasonOff] :: EvaluationReason -> !Bool
EvaluationReasonError :: !EvalErrorKind -> EvaluationReason
-- | Describes the type of error.
[$sel:errorKind:EvaluationReasonOff] :: EvaluationReason -> !EvalErrorKind
-- | Defines the possible values of the errorKind property of
-- EvaluationReason.
data EvalErrorKind
-- | Indicates that there was an internal inconsistency in the flag data,
-- e.g. a rule specified a nonexistent variation.
EvalErrorKindMalformedFlag :: EvalErrorKind
-- | Indicates that the caller provided a flag key that did not match any
-- known flag.
EvalErrorFlagNotFound :: EvalErrorKind
-- | Indicates that the result value was not of the requested type, e.g.
-- you called boolVariationDetail but the value was an integer.
EvalErrorWrongType :: EvalErrorKind
-- | Indicates that the caller tried to evaluate a flag before the client
-- had successfully initialized.
EvalErrorClientNotReady :: EvalErrorKind
-- | Indicates that the caller tried to evaluate a flag with an invalid
-- context
EvalErrorInvalidContext :: EvalErrorKind
-- | Indicates that some error was returned by the external feature store.
EvalErrorExternalStore :: !Text -> EvalErrorKind
-- | 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.
--
-- The first parameter will limit to only flags that are marked for use
-- with the client-side SDK (by default, all flags are included).
--
-- The second parameter will include evaluation reasons in the state.
--
-- The third parameter will omit any metadata that is normally only used
-- for event generation, such as flag versions and evaluation reasons,
-- unless the flag has event tracking or debugging turned on
--
-- For more information, see the Reference Guide:
-- https://docs.launchdarkly.com/sdk/features/all-flags#haskell
allFlagsState :: Client -> Context -> Bool -> Bool -> Bool -> IO AllFlagsState
-- | AllFlagsState captures the state of all feature flag keys as evaluated
-- for a specific context. This includes their values, as well as other
-- metadata.
data AllFlagsState
-- | Generates the secure mode hash value for a context.
--
-- For more information, see the Reference Guide:
-- https://docs.launchdarkly.com/sdk/features/secure-mode#haskell.
secureModeHash :: Client -> Context -> Text
-- | Close shuts down the LaunchDarkly client. After calling this, the
-- LaunchDarkly client should no longer be used. The method will block
-- until all pending analytics events have been sent.
close :: Client -> IO ()
-- | Flush tells the client that all pending analytics events (if any)
-- should be delivered as soon as possible. Flushing is asynchronous, so
-- this method will return before it is complete.
flushEvents :: Client -> IO ()
-- | Identify reports details about a context.
identify :: Client -> Context -> IO ()
-- | Track reports that a context has performed an event. Custom data can
-- be attached to the event, and / or a numeric value.
--
-- The numeric 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.
track :: Client -> Context -> Text -> Maybe Value -> Maybe Double -> IO ()
-- | The status of the client initialization.
data Status
-- | The client has not yet finished connecting to LaunchDarkly.
Uninitialized :: Status
-- | The client attempted to connect to LaunchDarkly and was denied.
Unauthorized :: Status
-- | The client has successfuly connected to LaunchDarkly.
Initialized :: Status
-- | The client is being terminated
ShuttingDown :: Status
-- | Return the initialization status of the Client
getStatus :: Client -> IO Status
instance GHC.Generics.Generic LaunchDarkly.Server.Client.FlagState
instance GHC.Show.Show LaunchDarkly.Server.Client.FlagState
instance GHC.Generics.Generic LaunchDarkly.Server.Client.AllFlagsState
instance GHC.Show.Show LaunchDarkly.Server.Client.AllFlagsState
instance Data.Aeson.Types.ToJSON.ToJSON LaunchDarkly.Server.Client.AllFlagsState
instance Data.Aeson.Types.ToJSON.ToJSON LaunchDarkly.Server.Client.FlagState
-- | This module re-exports the Client, Config, and Context modules.
module LaunchDarkly.Server