buzz/crates/buzz-feature-flags/README.md

buzz-feature-flags

Provider-neutral, typed feature-flag contracts for Buzz server crates.

This crate is infrastructure-only. It defines a small API for flag evaluation, plus a static evaluator and an optional LaunchDarkly adapter behind a compile feature.

Purpose

buzz-feature-flags centralizes typed flag evaluation so server crates can use flags without importing vendor SDK types.

Provider-neutral types:

• BooleanFlag
• IntegerFlag (i64, including negative values)
• EvaluationContext (a CommunityId with an optional actor PublicKey, or for_process() for process-wide settings such as concurrency caps)
• FlagEvaluator (typed evaluate_bool and evaluate_int)
• StaticEvaluator (always returns declared defaults)
• EnvironmentEvaluator (process-wide immutable environment snapshot)
• EnvironmentDiagnostic (sanitized malformed-value report)

LaunchDarkly support is optional and compile-gated behind buzz-feature-flags/launchdarkly.

EnvironmentEvaluator is provider-neutral and always available (no Cargo feature and no external dependency).

Environment Variable Naming

EnvironmentEvaluator reads only the fixed namespace BUZZ_FEATURE_FLAG_.

For each flag key:

• uppercase ASCII letters,
• replace each run of non-ASCII-alphanumeric characters with _,
• trim leading/trailing _,
• prepend BUZZ_FEATURE_FLAG_.

Example: relay.feature.query-v2 → BUZZ_FEATURE_FLAG_RELAY_FEATURE_QUERY_V2.

Normalized names must be unique across declared flags. Collisions (for example a-b and a_b) intentionally map to the same environment variable. Enforcing uniqueness belongs in a future flag registry; this crate does not add a registry yet.

Relay Provider Selection

buzz-relay builds exactly one evaluator at startup, chosen by BUZZ_FEATURE_FLAGS_PROVIDER (outside the BUZZ_FEATURE_FLAG_ namespace, so it can never be read as a flag):

Value	Evaluator
unset, static	StaticEvaluator
environment	EnvironmentEvaluator::from_process_environment()
launchdarkly	LaunchDarklyEvaluator, from BUZZ_LAUNCHDARKLY_SDK_KEY and the optional Relay Proxy URL BUZZ_LAUNCHDARKLY_RELAY_PROXY_URL

The value is parsed into one provider; there is no stacking, no precedence and no fallback from one provider to another, and the evaluator never changes for the life of the process. Every relay build carries the LaunchDarkly adapter (buzz-feature-flags/launchdarkly), which stays inert unless selected, so one published artifact serves every deployment and the deployment's configuration pins its provider.

The composition root lives in crates/buzz-relay/src/feature_flags.rs. It constructs the evaluator once and hands consumers the shared Arc<dyn FlagEvaluator>, keeping the concrete owner to drain environment diagnostics and to call LaunchDarkly's close() at shutdown.

Startup fails on a local configuration error: an unknown provider, launchdarkly without an SDK key, or a malformed Relay Proxy URL. It does not fail when LaunchDarkly is unreachable: the relay waits briefly for flag data, then serves declared defaults while the SDK keeps connecting, and buzz_feature_flags_ready{provider} reports whether the provider has initialized. Once initialized, LaunchDarkly serves its last-known values through a later outage, so the gauge stays 1 and flag values do not revert to defaults until the SDK reconnects and receives new data.

buzz-db Boundary (approved correction)

buzz-db may evaluate flags internally when choosing between equivalent query implementations. It should depend on buzz-feature-flags without enabling the LaunchDarkly feature, and it should never construct or import provider types.

Concise example (query path selection only):

use buzz_core::CommunityId;
use std::sync::Arc;

use buzz_feature_flags::{EvaluationContext, FlagEvaluator, IntegerFlag};

pub struct Db {
    feature_flags: Arc<dyn FlagEvaluator>,
}

impl Db {
    pub async fn list_events(
        &self,
        community: CommunityId,
    ) -> anyhow::Result<Vec<EventRow>> {
        let context = EvaluationContext::for_community(community);

        let query_version = self.feature_flags.evaluate_int(
            IntegerFlag::new("db.events.query-version", 1),
            &context,
        );

        if query_version >= 2 {
            self.list_events_v2_sql(community).await
        } else {
            self.list_events_v1_sql(community).await
        }
    }
}

SQL details are intentionally omitted in this example; the key point is that public Db methods accept only domain inputs, while feature-flag evaluator wiring remains internal to Db construction.

EvaluationContext::for_actor is appropriate only when the existing DB operation already receives an authoritative authenticated actor for domain behavior. Feature targeting must not add actor/pubkey parameters to otherwise actor-free DB APIs.

For LaunchDarkly, a community evaluation always includes kind community plus optional global kind pubkey; a process evaluation is a single kind relay context keyed relay. Percentage rollouts must explicitly choose a kind present in evaluation: rollouts must set contextKind to a kind present in evaluation (community or pubkey) when they are intended to bucket Buzz traffic. LaunchDarkly rollouts where configuration omits contextKind defaults to user; Buzz does not synthesize a user alias, so those rollouts bucket as zero and pick the first positive-weight variation.

Guardrails

• Evaluation context inputs are authoritative server-resolved values (community, optional actor), not client-supplied targeting attributes.
• Flags may choose between equivalent implementations only, with one exception: an operational limit (a concurrency cap) may be set by a flag when the flag can only tighten it. The consumer clamps the value to a ceiling fixed at startup, and a missing, non-positive or unavailable value means the ceiling. Shedding under such a limit must be retryable.
• Flags must not weaken authorization, tenant isolation, ordering guarantees, transaction/consistency behavior, or schema invariants.
• Declared defaults choose the established safe path.
• Integer values must be validated at the consumer boundary before affecting behavior.

Fallback, Startup, and Lifecycle

• StaticEvaluator always returns each flag's declared default.
• EnvironmentEvaluator returns declared defaults when values are missing, empty, invalid, non-Unicode, or the normalized flag key is unusable. Present malformed values also produce a sanitized diagnostic; missing values do not.
• LaunchDarkly adapter returns declared defaults when a flag is missing, wrong type, or evaluation fails.
• LaunchDarkly numbers are SDK f64 values. Integer evaluation accepts only mathematically integral values that convert to i64 exactly from that f64 representation; otherwise it returns each flag's declared default.
• Startup chooses one evaluator from configuration (StaticEvaluator, EnvironmentEvaluator, or LaunchDarkly); provider precedence/stacking is out of scope.
• If LaunchDarkly is used, call evaluator close() during process shutdown. close() blocks the calling thread while it flushes analytics and has no deadline of its own, so async shutdown code should run it off the runtime and bound the wait (the relay gives it a detached thread and 2 s).
• Safety invariants must never rely on remote-flag availability.

Build and Test Expectations

Build modes:

# Provider-neutral (default): no LaunchDarkly dependency activated
cargo build -p buzz-feature-flags

# Provider-neutral environment evaluator is included in the default build
cargo test -p buzz-feature-flags --test environment_evaluator

# LaunchDarkly adapter enabled
cargo build -p buzz-feature-flags --features launchdarkly

Dependency-graph expectation checks:

# Default graph should exclude launchdarkly-server-sdk
cargo tree -p buzz-feature-flags

# Feature graph should include launchdarkly-server-sdk
cargo tree -p buzz-feature-flags --features launchdarkly

Testing expectations:

• Run provider-neutral tests and LaunchDarkly-feature tests for this crate.
• When buzz-db adopts flag-gated query selection, add parity tests proving old/new query paths return equivalent rows, ordering, and transactional behavior for the same inputs.

References

• ARCHITECTURE.md
• docs/multi-tenant-relay.md