BilldogEng.Flags (BilldogEng v1.0.0-beta.1)

Feature-flag client supporting both remote and local (server-side) evaluation.

Local evaluation (local_evaluation: true) fetches flag DEFINITIONS once, caches them in a GenServer with a 5-minute TTL, and evaluates each flag deterministically on this process — the correct home for flag evaluation in a server SDK and the cross-platform-identical algorithm shared with web / iOS / Android.

Remote evaluation falls back to POST /experiment-config, which returns a pre-evaluated feature_flags map for the given user.

Mirrors the Node SDK flags.ts.

Summary

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

evaluate_locally(state, key, distinct_id, attributes)

Deterministic local flag evaluation (spec §D)

get_all_flags(pid, distinct_id, opts \\ [])

Evaluate every known flag for a user.

get_feature_flag(pid, key, distinct_id, opts \\ [])

Get a flag's value for a user. Returns true/false for a simple flag, the variant key string for a multivariate flag, or nil when the flag is unknown.

get_feature_flag_payload(pid, key, distinct_id, opts \\ [])

Get a flag's payload (variant config). Only meaningful under local evaluation. Returns the matched variant's payload, else the flag-level payload, else nil.

is_feature_enabled(pid, key, distinct_id, opts \\ [])

Boolean view of get_feature_flag/4 (a variant string counts as ON).

reload_feature_flag_definitions(pid)

Force a reload of the cached flag definitions (local mode).

set_definitions(pid, defs)

Inject flag definitions directly, bypassing the network. Primarily for tests and for hosts that distribute definitions through their own channel.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

evaluate_locally(state, key, distinct_id, attributes)

@spec evaluate_locally(
  t :: %BilldogEng.Flags{
    api_key: term(),
    definitions: term(),
    definitions_set: term(),
    enable_logging: term(),
    fetched_at: term(),
    local_evaluation: term(),
    transport: term()
  },
  String.t(),
  String.t(),
  map() | nil
) :: boolean() | String.t()

Deterministic local flag evaluation (spec §D):

Missing/inactive → false.
ALL targeting_rules must match attributes, else false.
bucket = murmurhash3("{key}.{distinctId}") % 100; ON iff bucket < rollout.
Multivariate: walk variants by cumulative rollout within the ON bucket.

Returns false (off), true (on, boolean) or the chosen variant key. Exposed for direct use against an explicit definition map.

get_all_flags(pid, distinct_id, opts \\ [])

@spec get_all_flags(pid(), String.t(), keyword()) :: map()

Evaluate every known flag for a user.

get_feature_flag(pid, key, distinct_id, opts \\ [])

@spec get_feature_flag(pid(), String.t(), String.t(), keyword()) ::
  boolean() | String.t() | nil

Get a flag's value for a user. Returns true/false for a simple flag, the variant key string for a multivariate flag, or nil when the flag is unknown.

get_feature_flag_payload(pid, key, distinct_id, opts \\ [])

@spec get_feature_flag_payload(pid(), String.t(), String.t(), keyword()) :: term()

Get a flag's payload (variant config). Only meaningful under local evaluation. Returns the matched variant's payload, else the flag-level payload, else nil.

is_feature_enabled(pid, key, distinct_id, opts \\ [])

@spec is_feature_enabled(pid(), String.t(), String.t(), keyword()) :: boolean()

Boolean view of get_feature_flag/4 (a variant string counts as ON).

reload_feature_flag_definitions(pid)

@spec reload_feature_flag_definitions(pid()) :: :ok

Force a reload of the cached flag definitions (local mode).

set_definitions(pid, defs)

@spec set_definitions(pid(), [map()]) :: :ok

Inject flag definitions directly, bypassing the network. Primarily for tests and for hosts that distribute definitions through their own channel.