standard_flags 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/CHANGELOG.md +84 -0
- data/LICENSE +21 -0
- data/README.md +548 -0
- data/Rakefile +6 -0
- data/lib/generators/standard_flags/install/install_generator.rb +40 -0
- data/lib/generators/standard_flags/install/templates/flags.rb.tt +58 -0
- data/lib/generators/standard_flags/install/templates/initializer.rb.tt +43 -0
- data/lib/standard_flags/bucket.rb +61 -0
- data/lib/standard_flags/config.rb +77 -0
- data/lib/standard_flags/context.rb +73 -0
- data/lib/standard_flags/controller.rb +107 -0
- data/lib/standard_flags/definition.rb +285 -0
- data/lib/standard_flags/diagnostics.rb +101 -0
- data/lib/standard_flags/engine.rb +28 -0
- data/lib/standard_flags/env_pin.rb +50 -0
- data/lib/standard_flags/errors.rb +35 -0
- data/lib/standard_flags/evaluation.rb +41 -0
- data/lib/standard_flags/evaluator.rb +58 -0
- data/lib/standard_flags/health_check.rb +50 -0
- data/lib/standard_flags/job.rb +75 -0
- data/lib/standard_flags/memo.rb +57 -0
- data/lib/standard_flags/mode.rb +78 -0
- data/lib/standard_flags/notifiers/logger.rb +49 -0
- data/lib/standard_flags/notifiers/metrics.rb +29 -0
- data/lib/standard_flags/notifiers/sentry.rb +27 -0
- data/lib/standard_flags/parser.rb +36 -0
- data/lib/standard_flags/payload.rb +29 -0
- data/lib/standard_flags/reader.rb +69 -0
- data/lib/standard_flags/reason.rb +34 -0
- data/lib/standard_flags/registry.rb +168 -0
- data/lib/standard_flags/reporting.rb +56 -0
- data/lib/standard_flags/resolvers.rb +103 -0
- data/lib/standard_flags/rspec.rb +58 -0
- data/lib/standard_flags/sensor.rb +77 -0
- data/lib/standard_flags/snapshot.rb +34 -0
- data/lib/standard_flags/subscribers.rb +45 -0
- data/lib/standard_flags/testing.rb +85 -0
- data/lib/standard_flags/tooling.rb +224 -0
- data/lib/standard_flags/version.rb +3 -0
- data/lib/standard_flags.rb +140 -0
- data/lib/tasks/standard_flags.rake +37 -0
- metadata +156 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: 1ed8742c4b0516b2939f0ec26ecd61fd5d133172ec67b0aed28fdc0c76d87e9e
|
|
4
|
+
data.tar.gz: '08e1e0101f9e67874ffb6fbabdc1916795129371cb4d426b2eb1c82390d4b5ae'
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: 43af8495cd0e8f0d4781b1afd3719f3546cf3004179a054e9b79b2c70830506eaf1675c2b33d0a77668f2f60461dfb89915c139f2eb1caf0c353c2ccc1c8d7ab
|
|
7
|
+
data.tar.gz: b3f64247ac6c9c61841dea4ca556b205807b04c255ac200b1a40314b8f32e3ae3d9b111dd8e8629e02c33c6fc43e46c32cd015ee9dddc650863bef19cb889a41
|
data/CHANGELOG.md
ADDED
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [Unreleased]
|
|
9
|
+
|
|
10
|
+
## [0.1.0] - 2026-11-22
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
First release (0.1.0, Phase 1: registry, ENV layer and evaluation API; no
|
|
15
|
+
database tables).
|
|
16
|
+
|
|
17
|
+
- **Registry.** `StandardFlags.define` in `config/flags.rb`, loaded on boot
|
|
18
|
+
and on every code reload. Kinds: `flag`, `kill_switch`, `mode` (presets
|
|
19
|
+
`:sensor`, `:cutover`, `:shadow`, or `values:`), `experiment`, `compat`,
|
|
20
|
+
and `tombstone`. Attributes: `owner:`, `description:`, `default:` (scalar
|
|
21
|
+
or per environment), `env:`, `inverted:`, `forbidden_in:`, `fail:`,
|
|
22
|
+
`expose:`, `unit:`, and `remove_by:` / `final:` (required on `flag`).
|
|
23
|
+
`env_resolver` and `unit` declarations. Define-time validation raises
|
|
24
|
+
`StandardFlags::DefinitionError`, including for a reused tombstoned key.
|
|
25
|
+
- **Resolution** in a fixed order: test override, `forbidden_in` guard, ENV
|
|
26
|
+
pin (`STANDARD_FLAGS_<KEY>`, then legacy `env:` names), code default. One
|
|
27
|
+
strict parser for every ENV value; rejected pins are ignored and reported
|
|
28
|
+
once per process. Per-flag error isolation returns the `fail:` value with
|
|
29
|
+
reason `ERROR`.
|
|
30
|
+
- **OpenFeature-shaped results.** `StandardFlags::Evaluation` with `value`,
|
|
31
|
+
`variant`, `reason`, `error_code`, `rule_id` and `source_env_var`.
|
|
32
|
+
- **Read API.** `on?`, `off?`, `mode` (a `StandardFlags::Mode` with one
|
|
33
|
+
predicate per value), `variant`, `evaluate`, `peek`, `snapshot`, and
|
|
34
|
+
`StandardFlags::Context`. Memoised per unit of work through the Rails
|
|
35
|
+
executor.
|
|
36
|
+
- **Sensor helper** `StandardFlags.sensor` for `preset: :sensor` modes.
|
|
37
|
+
- **Guards.** `StandardFlags::Controller` (`requires_flag`, JSON:API
|
|
38
|
+
`feature_disabled` error, `standard_flags_payload`) and
|
|
39
|
+
`StandardFlags::Job` (`requires_flag ..., retry:`, `StandardFlags::Disabled`).
|
|
40
|
+
- **Client payload.** `StandardFlags.payload(audience)` and `payload_digest`
|
|
41
|
+
for exposed flags only, keyed by wire name.
|
|
42
|
+
- **Bucketing contract.** `StandardFlags::Bucket.v1`, `v2` and the Postgres
|
|
43
|
+
twin `sql_v2`, with fixed test vectors. Not yet used by evaluation.
|
|
44
|
+
- **Conformance fixtures** in `spec/fixtures/conformance/` for evaluators in
|
|
45
|
+
other languages.
|
|
46
|
+
- **Rake tasks.** `flags:list`, `flags:stale`, `flags:refs`,
|
|
47
|
+
`standard_flags:manifest`, `standard_flags:typescript`.
|
|
48
|
+
- **Notifications** `evaluate`, `sensor`, `pin_rejected`, `forbidden` and
|
|
49
|
+
`legacy_env` (`*.standard_flags`), with Logger, Metrics and opt-in Sentry
|
|
50
|
+
subscribers.
|
|
51
|
+
- **Health and diagnostics.** Opt-in `StandardFlags::HealthCheck` for
|
|
52
|
+
standard_health and `StandardFlags::Diagnostics.report`.
|
|
53
|
+
- **Install generator** `rails g standard_flags:install`.
|
|
54
|
+
- **RSpec helpers** (`require "standard_flags/rspec"`): `with_flag`,
|
|
55
|
+
`with_mode`, `with_variant`, `flags:` metadata, automatic reset, strict
|
|
56
|
+
unknown keys.
|
|
57
|
+
- **Permanent flags.** `flag ..., permanent: true` declares a standing
|
|
58
|
+
switch (an environment permission, say) with no `remove_by:` or `final:`
|
|
59
|
+
(both rejected when permanent). It may default off or on, is never stale,
|
|
60
|
+
and shows as permanent in `flags:list`, `Diagnostics.report` and the
|
|
61
|
+
manifest (`"permanent"` on entries of kind `flag`). Conformance fixture
|
|
62
|
+
`permanent_flags.json`.
|
|
63
|
+
- **Per-guard controller responder.** `requires_flag :key, with:` takes a
|
|
64
|
+
callable `(controller, denial)` or a Symbol naming a controller method
|
|
65
|
+
`(denial)`, and overrides `config.controller_responder` for that guard
|
|
66
|
+
only.
|
|
67
|
+
- **Job error class.** `StandardFlags::Job` `requires_flag :key, error:`
|
|
68
|
+
raises an exception class, or what a proc returns, when the flag is off,
|
|
69
|
+
so jobs that already `retry_on` their own error can adopt the guard.
|
|
70
|
+
`error:` always raises: `retry: true` alongside it is redundant and
|
|
71
|
+
`retry: false` is rejected.
|
|
72
|
+
|
|
73
|
+
### Fixed
|
|
74
|
+
|
|
75
|
+
- Rake tasks are defined once. The engine no longer loads
|
|
76
|
+
`lib/tasks/standard_flags.rake` itself on top of Rails::Engine's own
|
|
77
|
+
`lib/tasks` loading, which gave every task two actions (`flags:list`
|
|
78
|
+
printed twice).
|
|
79
|
+
|
|
80
|
+
### Documentation
|
|
81
|
+
|
|
82
|
+
- README and the resolution-order docs state that test overrides (layer 1)
|
|
83
|
+
beat `forbidden_in` guards (layer 2), so a spec proving a guard must use a
|
|
84
|
+
real ENV pin rather than `with_flag`, with the pattern.
|
data/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Rarebit One
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
data/README.md
ADDED
|
@@ -0,0 +1,548 @@
|
|
|
1
|
+
# standard_flags
|
|
2
|
+
|
|
3
|
+
Feature flags, kill switches, staged modes and experiments for Rails apps.
|
|
4
|
+
|
|
5
|
+
StandardFlags is a small Rails engine. Every flag is declared once, in code,
|
|
6
|
+
with an owner. Values come from a fixed, documented chain: test overrides,
|
|
7
|
+
guards, environment pins, then per-environment code defaults. Results have
|
|
8
|
+
the [OpenFeature](https://openfeature.dev) shape (value, variant, reason,
|
|
9
|
+
error code), so "why is this on?" is always a one-line answer.
|
|
10
|
+
|
|
11
|
+
This is version 0.1.0 (Phase 1): registry, ENV layer and evaluation API. It
|
|
12
|
+
needs no database tables. See [Roadmap](#roadmap).
|
|
13
|
+
|
|
14
|
+
- [Install](#install)
|
|
15
|
+
- [Declaring flags](#declaring-flags)
|
|
16
|
+
- [Reading flags](#reading-flags)
|
|
17
|
+
- [How a value is decided](#how-a-value-is-decided)
|
|
18
|
+
- [Environment variables](#environment-variables)
|
|
19
|
+
- [Sensor rollouts](#sensor-rollouts)
|
|
20
|
+
- [Controller and job guards](#controller-and-job-guards)
|
|
21
|
+
- [Client payload](#client-payload)
|
|
22
|
+
- [Rake tasks](#rake-tasks)
|
|
23
|
+
- [Observability](#observability)
|
|
24
|
+
- [Health check and diagnostics](#health-check-and-diagnostics)
|
|
25
|
+
- [Testing](#testing)
|
|
26
|
+
- [Conformance suite](#conformance-suite)
|
|
27
|
+
- [Bucketing](#bucketing)
|
|
28
|
+
- [Roadmap](#roadmap)
|
|
29
|
+
|
|
30
|
+
## Install
|
|
31
|
+
|
|
32
|
+
```ruby
|
|
33
|
+
# Gemfile
|
|
34
|
+
gem "standard_flags"
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
bundle install
|
|
39
|
+
bin/rails g standard_flags:install
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
The generator writes `config/initializers/standard_flags.rb` (runtime
|
|
43
|
+
settings, all commented) and `config/flags.rb` (the registry, with one
|
|
44
|
+
commented example per kind). The engine loads `config/flags.rb` on boot and
|
|
45
|
+
on every code reload.
|
|
46
|
+
|
|
47
|
+
Requires Ruby 4.0+ and Rails 8.1+.
|
|
48
|
+
|
|
49
|
+
## Declaring flags
|
|
50
|
+
|
|
51
|
+
```ruby
|
|
52
|
+
# config/flags.rb
|
|
53
|
+
StandardFlags.define do
|
|
54
|
+
# The logical environment. Pass your own when staging boots with
|
|
55
|
+
# RAILS_ENV=production. Defaults to Rails.env.
|
|
56
|
+
env_resolver -> { ENV.fetch("APP_ENVIRONMENT", Rails.env) }
|
|
57
|
+
|
|
58
|
+
unit :account, from: ->(ctx) { ctx.account }
|
|
59
|
+
|
|
60
|
+
flag :new_checkout,
|
|
61
|
+
owner: "payments",
|
|
62
|
+
description: "Rebuilt checkout flow",
|
|
63
|
+
remove_by: "2027-03-01",
|
|
64
|
+
final: true,
|
|
65
|
+
unit: :account,
|
|
66
|
+
default: { staging: true, production: false },
|
|
67
|
+
expose: { web: :newCheckout }
|
|
68
|
+
|
|
69
|
+
kill_switch :ai_assistant,
|
|
70
|
+
owner: "assistant",
|
|
71
|
+
env: "ACME_LEGACY_DISABLED", inverted: true,
|
|
72
|
+
expose: { web: :assistant, mobile: :assistant }
|
|
73
|
+
|
|
74
|
+
mode :strict_gates, owner: "platform", preset: :sensor
|
|
75
|
+
mode :billing_cutover, owner: "billing", values: %i[off shadow enforce]
|
|
76
|
+
|
|
77
|
+
experiment :home_hero, owner: "growth", variants: %w[control savings privacy]
|
|
78
|
+
|
|
79
|
+
compat :legacy_form_auth, owner: "identity"
|
|
80
|
+
|
|
81
|
+
flag :demo_data, owner: "platform", remove_by: "2027-06-01", final: false,
|
|
82
|
+
forbidden_in: :production
|
|
83
|
+
|
|
84
|
+
flag :demo_pages, owner: "platform", permanent: true,
|
|
85
|
+
default: { development: true, staging: true }, forbidden_in: :production
|
|
86
|
+
|
|
87
|
+
tombstone :manual_entry, removed: "2026-12-01"
|
|
88
|
+
end
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### Kinds
|
|
92
|
+
|
|
93
|
+
| Kind | Values | Default | Use for |
|
|
94
|
+
|------|--------|---------|---------|
|
|
95
|
+
| `flag` | on / off | off | Temporary release flags: `remove_by:` and `final:` are required. With `permanent: true`, a standing switch instead (see below). |
|
|
96
|
+
| `kill_switch` | on / off | on, fails open | Permanent switches that turn a feature off in an emergency. |
|
|
97
|
+
| `mode` | declared values | first value | Staged rollouts. Presets: `:sensor` (off/sensor/on), `:cutover` (off/allowlist/all), `:shadow` (off/shadow/enforce); or `values:`. |
|
|
98
|
+
| `experiment` | declared variants | first variant | Experiments. In 0.1.0 an experiment always resolves to its first variant (list `control` first) unless pinned by ENV. |
|
|
99
|
+
| `compat` | on / off | on | Compatibility shims that stay on until they are removed. |
|
|
100
|
+
| `tombstone` | — | — | A removed key. It can never be declared again. |
|
|
101
|
+
|
|
102
|
+
### Attributes
|
|
103
|
+
|
|
104
|
+
| Attribute | Meaning |
|
|
105
|
+
|-----------|---------|
|
|
106
|
+
| `owner:` | Required on every kind. Who to ask about the flag. |
|
|
107
|
+
| `description:` | What it does. |
|
|
108
|
+
| `default:` | A value, or `{ env_name => value }`. Environments not listed get the kind's default. |
|
|
109
|
+
| `env:` | Legacy environment variable name(s) still honoured. See [Environment variables](#environment-variables). |
|
|
110
|
+
| `inverted:` | The legacy name is a `*_DISABLED` variable: legacy on means flag off. |
|
|
111
|
+
| `forbidden_in:` | Environment name(s) where the flag is forced off. A pin that tries to turn it on is reported once per process. |
|
|
112
|
+
| `fail:` | The value returned if evaluation raises. Kill switches default to on. |
|
|
113
|
+
| `expose:` | `{ audience => wire_name }`, or a list of audiences to use the key. Default: not exposed. |
|
|
114
|
+
| `unit:` | The unit the flag targets. Carried in the context now; used by targeting later. |
|
|
115
|
+
| `remove_by:`, `final:` | On `flag`: the date it should be gone, and the value it settles on. |
|
|
116
|
+
| `permanent:` | On `flag`: `true` for a standing switch with no `remove_by:`/`final:`. |
|
|
117
|
+
|
|
118
|
+
The registry is validated when it loads. `StandardFlags::DefinitionError` is
|
|
119
|
+
raised for a reused tombstoned key, a missing owner, a `flag` without
|
|
120
|
+
`remove_by:`/`final:` (or a `permanent: true` flag with either), a default outside a mode's values, the same wire name
|
|
121
|
+
used twice for one audience, an undeclared unit, or any unknown attribute.
|
|
122
|
+
|
|
123
|
+
### Permanent flags
|
|
124
|
+
|
|
125
|
+
Some switches are never meant to be removed: environment permissions such as
|
|
126
|
+
demo pages, setup screens, or permission to send real messages outside
|
|
127
|
+
production. Declare them as a `flag` with `permanent: true`:
|
|
128
|
+
|
|
129
|
+
```ruby
|
|
130
|
+
flag :demo_pages, owner: "platform", permanent: true,
|
|
131
|
+
default: { development: true, staging: true }, forbidden_in: :production
|
|
132
|
+
flag :outbound_email, owner: "platform", permanent: true, default: true
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
A permanent flag:
|
|
136
|
+
|
|
137
|
+
- takes no `remove_by:` or `final:`; declaring either raises
|
|
138
|
+
`DefinitionError`;
|
|
139
|
+
- defaults off like any `flag`, and may default on, everywhere or per
|
|
140
|
+
environment;
|
|
141
|
+
- evaluates exactly like any other flag: guards, ENV pins and legacy names
|
|
142
|
+
all apply;
|
|
143
|
+
- never appears in `flags:stale` or the health check's stale warnings;
|
|
144
|
+
- shows `permanent` in the `remove_by` column of `flags:list`,
|
|
145
|
+
`permanent: true` in `StandardFlags::Diagnostics.report`, and
|
|
146
|
+
`"permanent": true` in the manifest.
|
|
147
|
+
|
|
148
|
+
Use a `kill_switch` instead when the switch is on by default and exists to
|
|
149
|
+
turn a feature off in an emergency.
|
|
150
|
+
|
|
151
|
+
**Keys are immutable and never reused.** An old key brought back for new
|
|
152
|
+
work can wake up code that was meant to be dead. Remove a flag by replacing
|
|
153
|
+
its declaration with a `tombstone`.
|
|
154
|
+
|
|
155
|
+
## Reading flags
|
|
156
|
+
|
|
157
|
+
```ruby
|
|
158
|
+
StandardFlags.on?(:new_checkout, for: account) # => true
|
|
159
|
+
StandardFlags.off?(:new_checkout, for: account) # => false
|
|
160
|
+
|
|
161
|
+
mode = StandardFlags.mode(:strict_gates) # => #<StandardFlags::Mode :sensor>
|
|
162
|
+
mode.sensor? # => true
|
|
163
|
+
mode.at_least?(:sensor) # => true
|
|
164
|
+
mode.enforce? # NoMethodError: not a declared value
|
|
165
|
+
|
|
166
|
+
StandardFlags.variant(:home_hero, for: visitor) # => "control"
|
|
167
|
+
|
|
168
|
+
StandardFlags.evaluate(:ai_assistant)
|
|
169
|
+
# => #<data StandardFlags::Evaluation key=:ai_assistant, value=false, variant="off",
|
|
170
|
+
# reason="KILL_SWITCH", error_code=nil, rule_id=nil, source_env_var="ACME_LEGACY_DISABLED">
|
|
171
|
+
|
|
172
|
+
StandardFlags.peek(:home_hero) # same as evaluate
|
|
173
|
+
|
|
174
|
+
snap = StandardFlags.snapshot(for: account) # every flag, evaluated once, frozen
|
|
175
|
+
rows.each { |row| import(row) if snap.on?(:new_checkout) }
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
`for:` takes a single target, a hash of actors per unit
|
|
179
|
+
(`{ account: a, organization: o }`), or a `StandardFlags::Context`, which can
|
|
180
|
+
also carry an environment override and client attributes
|
|
181
|
+
(`platform`, `version`, `build`).
|
|
182
|
+
|
|
183
|
+
### Results
|
|
184
|
+
|
|
185
|
+
`StandardFlags::Evaluation` is immutable:
|
|
186
|
+
|
|
187
|
+
- `value`: true/false for on/off kinds, a Symbol for modes, a String for experiments.
|
|
188
|
+
- `variant`: the value as a string (`"on"`/`"off"` for booleans).
|
|
189
|
+
- `reason`: `STATIC`, `DEFAULT`, `TARGETING_MATCH`, `SPLIT`, `DISABLED`, `ERROR`, plus `ENV_PIN` and `KILL_SWITCH`.
|
|
190
|
+
- `error_code`: the OpenFeature set (`FLAG_NOT_FOUND`, `PARSE_ERROR`, `TYPE_MISMATCH`, `TARGETING_KEY_MISSING`, `INVALID_CONTEXT`, `PROVIDER_NOT_READY`, `PROVIDER_FATAL`, `GENERAL`), only when the reason is `ERROR`.
|
|
191
|
+
- `rule_id`: the matching runtime rule. Always nil in 0.1.0.
|
|
192
|
+
- `source_env_var`: the name of the variable that decided the value. Never its contents.
|
|
193
|
+
|
|
194
|
+
### Errors and strictness
|
|
195
|
+
|
|
196
|
+
- **Per-flag isolation.** Anything raised while evaluating one flag returns
|
|
197
|
+
that flag's `fail:` value with reason `ERROR` and error code `GENERAL`,
|
|
198
|
+
reports through `Rails.error` (handled), and leaves every other flag
|
|
199
|
+
alone. The read path never raises in production.
|
|
200
|
+
- **Unknown keys** raise `StandardFlags::UnknownFlag` when `config.strict`
|
|
201
|
+
is on, which is the default everywhere except a production Rails process.
|
|
202
|
+
In production the read fails safe: `on?` is false and `evaluate` returns
|
|
203
|
+
reason `ERROR` with `FLAG_NOT_FOUND`.
|
|
204
|
+
- **Kind mismatches** (`on?` on a mode, say) raise
|
|
205
|
+
`StandardFlags::TypeMismatch` when strict and read as off otherwise.
|
|
206
|
+
|
|
207
|
+
### Memoisation
|
|
208
|
+
|
|
209
|
+
Evaluations are memoised per unit of work through the Rails executor, not
|
|
210
|
+
Rack middleware, so requests, jobs, mailers and console reloads all get a
|
|
211
|
+
consistent answer within one unit and a fresh read of ENV in the next.
|
|
212
|
+
Outside an executor run nothing is memoised.
|
|
213
|
+
|
|
214
|
+
## How a value is decided
|
|
215
|
+
|
|
216
|
+
Each evaluation walks these layers in order and stops at the first one that
|
|
217
|
+
answers. Gates are never OR'd together.
|
|
218
|
+
|
|
219
|
+
1. **Test override.** `with_flag(:x, true)`. Exists only in tests. Reason `STATIC`.
|
|
220
|
+
2. **Guard.** `forbidden_in:` forces the off value. Reason `DISABLED`.
|
|
221
|
+
3. **ENV pin.** `STANDARD_FLAGS_<KEY>`, then legacy `env:` names. Reason
|
|
222
|
+
`ENV_PIN`, or `KILL_SWITCH` when a kill switch is pinned off.
|
|
223
|
+
4. **Code default** for the current environment. Reason `DEFAULT`.
|
|
224
|
+
|
|
225
|
+
Runtime rules arrive between 3 and 4, so an ENV pin keeps beating any
|
|
226
|
+
database rule and keeps working with the database down.
|
|
227
|
+
|
|
228
|
+
**Test overrides beat guards.** Layer 1 answers before layer 2, so
|
|
229
|
+
`with_flag(:demo_pages, true)` turns a `forbidden_in: :production` flag on
|
|
230
|
+
even in production. That is what you want when testing the feature itself,
|
|
231
|
+
but it means a spec cannot prove a guard with `with_flag`. Use a real ENV pin
|
|
232
|
+
instead; see [Testing a guard](#testing-a-guard).
|
|
233
|
+
|
|
234
|
+
## Environment variables
|
|
235
|
+
|
|
236
|
+
Every flag can be pinned with its canonical variable, `STANDARD_FLAGS_<KEY>`
|
|
237
|
+
(the key upcased): `STANDARD_FLAGS_NEW_CHECKOUT=on`.
|
|
238
|
+
|
|
239
|
+
One strict parser reads every value, trimmed and case-insensitive:
|
|
240
|
+
|
|
241
|
+
- on/off kinds: `on`/`off`, `true`/`false`, `1`/`0`, `yes`/`no`;
|
|
242
|
+
- modes: a declared value; experiments: a declared variant.
|
|
243
|
+
|
|
244
|
+
Anything else is ignored and reported once per process per variable, through
|
|
245
|
+
`Rails.error.report(handled: true)` and a `pin_rejected.standard_flags`
|
|
246
|
+
notification. A blank value counts as unset.
|
|
247
|
+
|
|
248
|
+
### Legacy names
|
|
249
|
+
|
|
250
|
+
To adopt the gem without renaming deployed variables, declare the old name:
|
|
251
|
+
|
|
252
|
+
```ruby
|
|
253
|
+
kill_switch :ai_assistant, owner: "assistant", env: "ACME_LEGACY_DISABLED", inverted: true
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
- `env:` takes one name or several; the first that parses wins, in order.
|
|
257
|
+
- The canonical name wins over every legacy name. When both are set, the
|
|
258
|
+
legacy one is reported as shadowed.
|
|
259
|
+
- `inverted: true` flips legacy values only: `ACME_LEGACY_DISABLED=true`
|
|
260
|
+
means the kill switch is off. The canonical variable is never inverted.
|
|
261
|
+
- Using a legacy name emits `legacy_env.standard_flags` once per process,
|
|
262
|
+
and the health check reports it as deprecated. Rename on your own schedule.
|
|
263
|
+
|
|
264
|
+
Moving from hand-written predicates changes one thing on purpose: values the
|
|
265
|
+
strict parser doesn't accept are ignored. A legacy `ENV["X_DISABLED"].present?`
|
|
266
|
+
check treated `X_DISABLED=false` as disabled; with `inverted: true` it now
|
|
267
|
+
means enabled. Call that out when migrating a flag.
|
|
268
|
+
|
|
269
|
+
## Sensor rollouts
|
|
270
|
+
|
|
271
|
+
For a mode declared with `preset: :sensor`:
|
|
272
|
+
|
|
273
|
+
```ruby
|
|
274
|
+
StandardFlags.sensor(:strict_gates, for: run) do |s|
|
|
275
|
+
s.observe { Gates.evaluate(run) } # runs in sensor and on
|
|
276
|
+
s.enforce { |verdict| hold!(run, verdict) } # runs only in on
|
|
277
|
+
end
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
- **off**: neither block runs; returns nil.
|
|
281
|
+
- **sensor**: `observe` runs and its result goes into a
|
|
282
|
+
`sensor.standard_flags` notification; returns the observation. An
|
|
283
|
+
exception in `observe` is reported and swallowed, since sensor mode must
|
|
284
|
+
not change behaviour.
|
|
285
|
+
- **on**: `observe` runs, the notification fires, then `enforce` receives the
|
|
286
|
+
observation; returns `enforce`'s result. Exceptions propagate.
|
|
287
|
+
|
|
288
|
+
## Controller and job guards
|
|
289
|
+
|
|
290
|
+
```ruby
|
|
291
|
+
class ApplicationController < ActionController::Base
|
|
292
|
+
include StandardFlags::Controller
|
|
293
|
+
|
|
294
|
+
private
|
|
295
|
+
|
|
296
|
+
# Who flags are evaluated for in this controller. Defaults to nil.
|
|
297
|
+
def standard_flags_context = Current.account
|
|
298
|
+
end
|
|
299
|
+
|
|
300
|
+
class ReportsController < ApplicationController
|
|
301
|
+
requires_flag :new_reports, except: :index
|
|
302
|
+
requires_flag :legacy_export, error: :not_found # keep an existing 404 contract
|
|
303
|
+
requires_flag :ai_assistant, status: 503
|
|
304
|
+
end
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
A JSON request for a disabled flag gets one JSON:API error:
|
|
308
|
+
|
|
309
|
+
```json
|
|
310
|
+
{"errors":[{"status":"403","code":"feature_disabled","meta":{"feature":"reportsV2"}}]}
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
`meta.feature` is the flag's wire name for `config.default_audience`
|
|
314
|
+
(`:web`), or the key when it has none. `error: :not_found` answers 404 with
|
|
315
|
+
no meta. Other formats get the bare status. A mode counts as enabled once it
|
|
316
|
+
is past its first value. Replace the response everywhere with
|
|
317
|
+
`config.controller_responder = ->(controller, denial) { ... }`.
|
|
318
|
+
|
|
319
|
+
To keep an endpoint's existing error contract, give one guard its own
|
|
320
|
+
responder with `with:`. It overrides `config.controller_responder` for that
|
|
321
|
+
guard only:
|
|
322
|
+
|
|
323
|
+
```ruby
|
|
324
|
+
class Api::ReportsController < ApplicationController
|
|
325
|
+
# A callable takes (controller, denial).
|
|
326
|
+
requires_flag :new_reports,
|
|
327
|
+
with: ->(c, denial) { c.render json: { error_code: "FEATURE_OFF" }, status: 422 }
|
|
328
|
+
|
|
329
|
+
# A Symbol names a controller method that takes (denial).
|
|
330
|
+
requires_flag :report_exports, with: :render_api_error
|
|
331
|
+
|
|
332
|
+
private
|
|
333
|
+
|
|
334
|
+
def render_api_error(denial)
|
|
335
|
+
render json: ApiError.new(:unavailable, feature: denial.feature), status: denial.status
|
|
336
|
+
end
|
|
337
|
+
end
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
The denial carries `key`, `error`, `status` (from `error:`/`status:`),
|
|
341
|
+
`feature` and `body` (the default JSON:API document). The responder must
|
|
342
|
+
render or redirect so the action doesn't run.
|
|
343
|
+
|
|
344
|
+
```ruby
|
|
345
|
+
class ReplyJob < ApplicationJob
|
|
346
|
+
include StandardFlags::Job
|
|
347
|
+
|
|
348
|
+
requires_flag :ai_assistant, retry: true, for: -> { arguments.first }
|
|
349
|
+
retry_on StandardFlags::Disabled, wait: 5.minutes, attempts: 12
|
|
350
|
+
end
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
With `retry: true` a disabled flag raises `StandardFlags::Disabled` so
|
|
354
|
+
`retry_on` can reschedule. Without it the job is discarded unrun.
|
|
355
|
+
|
|
356
|
+
Jobs that already `retry_on` (or `discard_on`) their own exception can
|
|
357
|
+
raise it instead with `error:`, a class or a proc:
|
|
358
|
+
|
|
359
|
+
```ruby
|
|
360
|
+
class SyncJob < ApplicationJob
|
|
361
|
+
include StandardFlags::Job
|
|
362
|
+
|
|
363
|
+
retry_on UpstreamUnavailable, wait: :polynomially_longer, attempts: 10
|
|
364
|
+
|
|
365
|
+
requires_flag :partner_sync, error: UpstreamUnavailable
|
|
366
|
+
# or build the exception in the job instance; the proc may take the key:
|
|
367
|
+
requires_flag :partner_sync, error: ->(key) { UpstreamUnavailable.new("#{key} off for #{arguments.first}") }
|
|
368
|
+
end
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
A class is raised with the message `flag :<key> is disabled`. A proc runs in
|
|
372
|
+
the job instance and returns an exception or an exception class. How the
|
|
373
|
+
options combine:
|
|
374
|
+
|
|
375
|
+
| Options | When the flag is off |
|
|
376
|
+
|---------|----------------------|
|
|
377
|
+
| (none), or `retry: false` | The job is discarded unrun. |
|
|
378
|
+
| `retry: true` | Raises `StandardFlags::Disabled`. |
|
|
379
|
+
| `error: SomeError` | Raises `SomeError`; the job's own `retry_on`/`discard_on` for it applies, and without one the job fails like any other error. |
|
|
380
|
+
| `error:` with `retry: true` | Same as `error:` alone. |
|
|
381
|
+
| `error:` with `retry: false` | `ArgumentError` at declaration: `error:` always raises, so it cannot also discard. |
|
|
382
|
+
|
|
383
|
+
## Client payload
|
|
384
|
+
|
|
385
|
+
Clients see evaluated values only, never rules or the names of flags they
|
|
386
|
+
aren't meant to see:
|
|
387
|
+
|
|
388
|
+
```ruby
|
|
389
|
+
StandardFlags.payload(:web, for: account) # => { "assistant" => true, "newCheckout" => false }
|
|
390
|
+
StandardFlags.payload_digest(:web, for: account) # => "9f3c…" (stable hash of the result)
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
Only flags with `expose:` for that audience appear, keyed by wire name. Wire
|
|
394
|
+
names are separate from keys, so renaming or removing a flag doesn't break a
|
|
395
|
+
shipped client. Booleans stay booleans; modes and variants are strings. The
|
|
396
|
+
digest hashes the evaluated result, so it changes whenever the answers do,
|
|
397
|
+
which makes it a safe ETag.
|
|
398
|
+
|
|
399
|
+
With Inertia:
|
|
400
|
+
|
|
401
|
+
```ruby
|
|
402
|
+
class ApplicationController < ActionController::Base
|
|
403
|
+
include StandardFlags::Controller
|
|
404
|
+
inertia_share features: -> { standard_flags_payload(:web) }
|
|
405
|
+
end
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
## Rake tasks
|
|
409
|
+
|
|
410
|
+
| Task | What it does |
|
|
411
|
+
|------|--------------|
|
|
412
|
+
| `bin/rails flags:list` | Every flag with its value, reason, deciding env var and remove_by (`permanent` for permanent flags). |
|
|
413
|
+
| `bin/rails flags:stale` | Flags past `remove_by`, with the `final:` value to keep. Permanent flags never appear. |
|
|
414
|
+
| `bin/rails flags:refs` | Scans `config.refs_paths` (default `app lib config`) for `on?(:k`, `off?(:k`, `mode(:k`, `variant(:k`, `evaluate(:k`, `requires_flag :k` and string keys. Exits non-zero for undeclared or tombstoned keys; warns for declared flags nothing reads. Run it in CI. |
|
|
415
|
+
| `bin/rails standard_flags:manifest` | Writes `config/flags.manifest.json`: keys, wire names, kinds, values, audiences and defaults (and `permanent` on entries of kind `flag`), deterministically. Commit it. |
|
|
416
|
+
| `bin/rails standard_flags:typescript` | Writes a `.d.ts` with a `Features` interface per audience (`WebFeatures`, `MobileFeatures`, …) keyed by wire name. |
|
|
417
|
+
|
|
418
|
+
## Observability
|
|
419
|
+
|
|
420
|
+
`ActiveSupport::Notifications` events:
|
|
421
|
+
|
|
422
|
+
| Event | When |
|
|
423
|
+
|-------|------|
|
|
424
|
+
| `evaluate.standard_flags` | Sampled evaluations (`config.evaluate_sample_rate`, default 0). |
|
|
425
|
+
| `sensor.standard_flags` | A sensor-mode observation. |
|
|
426
|
+
| `pin_rejected.standard_flags` | An ENV pin that didn't parse. |
|
|
427
|
+
| `forbidden.standard_flags` | A `forbidden_in` flag pinned on where it's forbidden. |
|
|
428
|
+
| `legacy_env.standard_flags` | A legacy env name in use. |
|
|
429
|
+
|
|
430
|
+
Built-in subscribers: **Logger** (always), **Metrics** (`Sentry::Metrics`
|
|
431
|
+
counters when sentry-ruby is loaded) and **Sentry** (handled warnings for
|
|
432
|
+
rejected and forbidden pins). Sentry is off by default because those pins
|
|
433
|
+
already go to `Rails.error`; enable it only when `Rails.error` isn't wired to
|
|
434
|
+
your error tracker. Add your own with
|
|
435
|
+
`config.add_notifier(->(name, payload) { ... })`.
|
|
436
|
+
|
|
437
|
+
## Health check and diagnostics
|
|
438
|
+
|
|
439
|
+
With [standard_health](https://github.com/rarebit-one/standard_health):
|
|
440
|
+
|
|
441
|
+
```ruby
|
|
442
|
+
StandardHealth.configure do |c|
|
|
443
|
+
c.register_check :flags, StandardFlags::HealthCheck
|
|
444
|
+
end
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
The check fails when a `forbidden_in` flag is pinned on, and warns on
|
|
448
|
+
unparseable pins, legacy names in use, flags past `remove_by`, and
|
|
449
|
+
`STANDARD_FLAGS_*` variables that match no flag. standard_health has no
|
|
450
|
+
warning status, so warnings ride on the row (`warnings:`) and the check stays
|
|
451
|
+
`:ok`; pass `warn_as: :fail` to let them degrade the tier. It is non-critical
|
|
452
|
+
by default. There is no dependency on standard_health unless you reference
|
|
453
|
+
the check.
|
|
454
|
+
|
|
455
|
+
`StandardFlags::Diagnostics.report` returns the same picture as a hash for a
|
|
456
|
+
diagnostics page: each flag's value, reason, deciding variable and whether
|
|
457
|
+
it is permanent, plus
|
|
458
|
+
forbidden, rejected, legacy and unknown pins and stale flags. It contains
|
|
459
|
+
variable names only, never raw environment values.
|
|
460
|
+
|
|
461
|
+
## Testing
|
|
462
|
+
|
|
463
|
+
```ruby
|
|
464
|
+
# spec/rails_helper.rb
|
|
465
|
+
require "standard_flags/rspec"
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
```ruby
|
|
469
|
+
with_flag(:new_checkout, true) { ... } # for the block
|
|
470
|
+
with_flag(:new_checkout, true) # for the rest of the example
|
|
471
|
+
with_mode(:strict_gates, :sensor) { ... }
|
|
472
|
+
with_variant(:home_hero, "savings") { ... }
|
|
473
|
+
|
|
474
|
+
it "shows the new checkout", flags: { new_checkout: true } do
|
|
475
|
+
...
|
|
476
|
+
end
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
Overrides are the first evaluation layer, so they beat guards, ENV pins and
|
|
480
|
+
defaults without touching `ENV`. Unknown keys, wrong kinds and undeclared
|
|
481
|
+
values raise; unknown keys raise on read too (strict mode); everything resets
|
|
482
|
+
after each example.
|
|
483
|
+
|
|
484
|
+
### Testing a guard
|
|
485
|
+
|
|
486
|
+
Because overrides beat `forbidden_in:` guards (layer 1 before layer 2), a
|
|
487
|
+
spec that uses `with_flag` to prove a guard passes for the wrong reason: the
|
|
488
|
+
override turns the flag on and the guard never runs. Prove a guard with a
|
|
489
|
+
real ENV pin and an explicit environment:
|
|
490
|
+
|
|
491
|
+
```ruby
|
|
492
|
+
it "never turns demo pages on in production, even when pinned" do
|
|
493
|
+
ENV["STANDARD_FLAGS_DEMO_PAGES"] = "on"
|
|
494
|
+
production = StandardFlags::Context.new(env: "production")
|
|
495
|
+
|
|
496
|
+
expect(StandardFlags.evaluate(:demo_pages, for: production))
|
|
497
|
+
.to have_attributes(value: false, reason: "DISABLED")
|
|
498
|
+
ensure
|
|
499
|
+
ENV.delete("STANDARD_FLAGS_DEMO_PAGES")
|
|
500
|
+
end
|
|
501
|
+
```
|
|
502
|
+
|
|
503
|
+
Pins are read from `config.env_source`, which is `ENV` unless you set it; a
|
|
504
|
+
spec may point it at a Hash instead (`StandardFlags.config.env_source =
|
|
505
|
+
{ "STANDARD_FLAGS_DEMO_PAGES" => "on" }`, and set it back to `ENV` after
|
|
506
|
+
the example). Either
|
|
507
|
+
way the pin goes through the same parser and guard as in production.
|
|
508
|
+
|
|
509
|
+
## Conformance suite
|
|
510
|
+
|
|
511
|
+
`spec/fixtures/conformance/*.json` holds the evaluation contract as data.
|
|
512
|
+
Each file has a registry snippet and cases: environment variables and a
|
|
513
|
+
context in, the expected value, variant, reason, error code and deciding
|
|
514
|
+
variable out. `bucket_vectors.json` pins test vectors for every bucketing
|
|
515
|
+
version. The Ruby suite runs every case. Evaluators in other languages (a
|
|
516
|
+
Kotlin or TypeScript client, say) run the same files, so they cannot drift
|
|
517
|
+
from the server on what a flag evaluates to.
|
|
518
|
+
|
|
519
|
+
## Bucketing
|
|
520
|
+
|
|
521
|
+
`StandardFlags::Bucket` holds the bucketing contract for percentage rollouts
|
|
522
|
+
and experiments. It is not used by evaluation yet.
|
|
523
|
+
|
|
524
|
+
```ruby
|
|
525
|
+
StandardFlags::Bucket.v1(salt, unit_key) # SHA-256("salt:unit_key")[0, 15] hex % 10_000
|
|
526
|
+
StandardFlags::Bucket.v2(:rollout, salt, unit_key) # SHA-256("v2|rollout|salt|unit_key") ...
|
|
527
|
+
StandardFlags::Bucket.v2(:variant, salt, unit_key) # a separate input for variant choice
|
|
528
|
+
StandardFlags::Bucket.sql_v2(column: "devices.id") # the Postgres twin; bind :salt
|
|
529
|
+
```
|
|
530
|
+
|
|
531
|
+
Buckets are basis points (0–9,999). A nil or blank unit key returns nil (the
|
|
532
|
+
caller maps it to `TARGETING_KEY_MISSING`), never a random bucket. These
|
|
533
|
+
functions are permanent: a new algorithm gets a new version and existing
|
|
534
|
+
flags keep theirs.
|
|
535
|
+
|
|
536
|
+
## Roadmap
|
|
537
|
+
|
|
538
|
+
Phase 2 adds runtime rules stored in the database (changes without a
|
|
539
|
+
redeploy, allow and deny lists, cohorts, sticky percentage rollouts with
|
|
540
|
+
per-flag salts), audited write operations and an admin generator. Phase 3
|
|
541
|
+
adds client delivery: an OpenFeature remote-evaluation (OFREP) endpoint,
|
|
542
|
+
client version targeting, a minimum-version endpoint and the manifest
|
|
543
|
+
contract checked in client CI. Phase 4 adds experiment exposure tracking and
|
|
544
|
+
staged rollout plans with automatic halts.
|
|
545
|
+
|
|
546
|
+
## License
|
|
547
|
+
|
|
548
|
+
MIT. See [LICENSE](LICENSE).
|