Skip to content

About feature toggles

In a server, a feature toggle picks a code path. In a command-line tool it also decides the interface, including whether --quic exists, whether admin is a command, what --help lists, what completion offers, and whether a config key is valid. A toggle that only guards an if in Run leaves the flag visible and accepted while the code behind it is switched off.

CONGA separates two things. A feature is a named value the user sets, declared as a field of conga.Features[T]. A gated member is a flag or subcommand whose feature:"..." expression decides whether it exists for this run. One feature can gate many members, gate none (and be read only in code), or gate a member while switched off, as !strict-tls does for a plaintext escape hatch.

How to gate flags and subcommands behind features shows the steps, and Struct tags lists the tags.

Struct-declared toggles versus dynamic registries

Section titled “Struct-declared toggles versus dynamic registries”

Many programs check features by name at run time, through a string-keyed registry or an environment lookup:

// A lookup by name, as many feature-flag libraries do it
if featureManager.IsEnabled("http3") { ... }

String lookups are easy to start with and hard to maintain. A misspelled name such as "htttp3" compiles, runs, and quietly returns the default. Code that checks a toggle removed months ago still compiles. Names, descriptions, and defaults end up spread across handlers and config parsers, so no one place says which toggles exist.

CONGA instead declares every feature once, as a field of the struct T in conga.Features[T] on the root command:

type Experiments struct {
HTTP3 bool `stage:"alpha" help:"Experimental HTTP/3 listener"`
SyntaxV2 int `stage:"beta" enum:"1,2" help:"Syntax version (0 = off)"`
}
type Server struct {
Features conga.Features[Experiments] `flag:"feature-gates" env:"SERVER_FEATURES" config:"features"`
}

Handlers read features as struct fields (c.Features.Get().HTTP3), so renaming or removing a feature breaks the build instead of a run. The struct is the one list of names, stages, levels, and defaults, and the help screen, completion, --why, and conga-lint all read from it. The engine checks the struct when the application starts, before it reads any user input, so a malformed declaration never reaches a user.

Features often come from several sources at once. A shared config file might turn on experimental features for a whole team, an environment variable might change one of them, and a flag might change another for a single run.

A scalar or slice flag takes its value from the single source that wins, so a value on the command line discards the environment’s and the config file’s. Features can’t work that way. A user who runs with --feature-gates http3=true wants http3 on, and still wants the ten other features the team’s config file turned on.

CONGA instead merges features one by one, across all four sources:

Struct Defaults < Configuration Files < Environment Variables < CLI Flags

The struct’s field types and default tags give every feature a starting value. Config, then environment, then command line each lay name=value pairs over it, and each changes only the names it mentions. A higher source can turn a feature off or change its level, but it cannot make a lower source’s setting disappear. A feature no source names keeps its default.

Each place a feature can be set has its own naming convention. Command-line flags use kebab-case (--feature-gates gentle-force=true), environment variables use upper snake case (GENTLE_FORCE), and the Go field is camelCase (GentleForce).

On the command line and in the environment, CONGA maps every spelling to the declared feature name before merging, so GENTLE_FORCE in an environment variable and gentle_force=true on the command line set the same feature. Precedence follows the source, never the spelling.

A config file is the exception. Its feature section takes the feature name spelled in the app’s config key casing (gentle-force by default), as every config key is, and another spelling is an unknown key.

The environment source reaches features through one of two exclusive shapes, one combined map variable (the container’s env tag) or one variable per feature (the container’s envprefix tag). A container can’t use both, because two shapes writing the same keys would need an arbitrary precedence rule between them, and the --why report could not say which variable won.

The application-level EnvPrefix(...) never reaches features. It namespaces normal flags. Features bind their environment explicitly, so an ambient prefix cannot silently turn feature names into flag overrides.

Display follows the same split. The combined-map variable is documented on the synthesized flag, where the container help tag may inline it with {{env}}. Per-feature variables are documented next to the feature they bind, in the help screen’s Features section, because the synthesized flag cannot present them meaningfully when it is hidden. The two locations never list the same variable.

For the same reason, schema build rejects two features bound to one variable. The reference lists the rules.

A flag for an unreleased feature that still shows up in --help invites users to try it, and leaves them guessing why it does nothing. So when a member’s feature expression does not hold, CONGA removes the member for that run. It is missing from Flags: and Commands: in help, from completion candidates, and from the --why table. The interface a user sees therefore matches what will run.

When a source names a feature that doesn’t exist, or a gated member that is inactive for the run, the result depends on the source.

The command line is what the user typed for this run, so an unknown feature name, or a flag whose feature is off, is a mistake to report to them. The run stops before any hook with a usage error (exit code 2) that names the missing feature and shows the usage.

Configuration files and feature variables (exit code 1)

Section titled “Configuration files and feature variables (exit code 1)”

A config file holds settings that outlast any one run, and an environment variable arrives from the shell, CI, or a container. Both are data rather than a command line, so an unknown feature name or a bad value from either source is a config error (ErrConfig, exit code 1). Both errors name their source. A bad value names the key or variable, and an unknown name names the variable or the file and section, with the same “did you mean” hint as on the command line. A file that sets a flag an inactive feature removed is also ErrConfig, unless the command line or an environment variable turned that feature off. A higher source overrides the file for that run, so CONGA ignores the key.

Terminal window
$ feature-toggles --config-file features.yaml
Error:feature-toggles: error: invalid value "maybe" for feature "http3" (from config key "features.http3"): must be true or false (or 1 or 0)
Terminal window
$ API_FEATURES=http3=maybe feature-toggles
Error:feature-toggles: error: invalid value "maybe" for feature "http3" (from environment variable API_FEATURES): must be true or false (or 1 or 0)

An unknown name gets a hint when the spelling is close:

Terminal window
$ API_FEATURES=htt3=true feature-toggles
Error:feature-toggles: error: unknown feature "htt3" (from environment variable API_FEATURES) (did you mean "http3"?)

Variables for gated flags (silently ignored)

Section titled “Variables for gated flags (silently ignored)”

Environment variables leak in from parent shells, CI runners, and container orchestrators. If API_QUIC=true is left over in a shell where http3 is off, failing would break a run the variable was never meant for, so CONGA ignores variables that set inactive gated flags. Feature variables such as API_FEATURES or API_FEATURE_HTTP3 are always validated, because they exist only to set features.

Feature support means expression parsing, name canonicalization, per-feature merging, and provenance tracking. A small tool that never declares a feature shouldn’t carry that code, so features are opt-in through app.EnableFeatures(). Without the call the linker drops the feature code entirely. A struct that declares features without the call fails at startup, and conga-lint reports it earlier, so the opt-in can’t be forgotten silently.

CONGA models feature maturity through the stage struct tag:

Stage Intended meaning
alpha Early development, usually off by default, and may change incompatibly.
beta Functionally complete and being tested in real use, and may be on by default.
ga Generally available, with stable and permanent behavior.
deprecated Marked for removal in a future release.

The meanings are guidance for the author. A stage decides only whether the feature is listed in the help screen’s Features: section, and never sets its default.

Declaring feature stages is optional. However, when any field on T declares a stage tag, every field on T must declare one, and schema build rejects a mix with ErrSchema. This rule prevents ambiguous help listings, where staged and unstaged features would sit side by side with no way to tell whether a missing label means stable or forgotten.

Mature features leave the Features section

Section titled “Mature features leave the Features section”

As in Kubernetes, the automatic Features: section on the root help screen displays only experimental toggles (alpha and beta).

Once a feature reaches ga or deprecated, it drops out of the help screen’s Features: table. A GA feature is expected to stay on, and a deprecated one shouldn’t be advertised to new users. Features at either stage still work, validate, and complete, and --why still shows their state.