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.
Files changed (43) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +84 -0
  3. data/LICENSE +21 -0
  4. data/README.md +548 -0
  5. data/Rakefile +6 -0
  6. data/lib/generators/standard_flags/install/install_generator.rb +40 -0
  7. data/lib/generators/standard_flags/install/templates/flags.rb.tt +58 -0
  8. data/lib/generators/standard_flags/install/templates/initializer.rb.tt +43 -0
  9. data/lib/standard_flags/bucket.rb +61 -0
  10. data/lib/standard_flags/config.rb +77 -0
  11. data/lib/standard_flags/context.rb +73 -0
  12. data/lib/standard_flags/controller.rb +107 -0
  13. data/lib/standard_flags/definition.rb +285 -0
  14. data/lib/standard_flags/diagnostics.rb +101 -0
  15. data/lib/standard_flags/engine.rb +28 -0
  16. data/lib/standard_flags/env_pin.rb +50 -0
  17. data/lib/standard_flags/errors.rb +35 -0
  18. data/lib/standard_flags/evaluation.rb +41 -0
  19. data/lib/standard_flags/evaluator.rb +58 -0
  20. data/lib/standard_flags/health_check.rb +50 -0
  21. data/lib/standard_flags/job.rb +75 -0
  22. data/lib/standard_flags/memo.rb +57 -0
  23. data/lib/standard_flags/mode.rb +78 -0
  24. data/lib/standard_flags/notifiers/logger.rb +49 -0
  25. data/lib/standard_flags/notifiers/metrics.rb +29 -0
  26. data/lib/standard_flags/notifiers/sentry.rb +27 -0
  27. data/lib/standard_flags/parser.rb +36 -0
  28. data/lib/standard_flags/payload.rb +29 -0
  29. data/lib/standard_flags/reader.rb +69 -0
  30. data/lib/standard_flags/reason.rb +34 -0
  31. data/lib/standard_flags/registry.rb +168 -0
  32. data/lib/standard_flags/reporting.rb +56 -0
  33. data/lib/standard_flags/resolvers.rb +103 -0
  34. data/lib/standard_flags/rspec.rb +58 -0
  35. data/lib/standard_flags/sensor.rb +77 -0
  36. data/lib/standard_flags/snapshot.rb +34 -0
  37. data/lib/standard_flags/subscribers.rb +45 -0
  38. data/lib/standard_flags/testing.rb +85 -0
  39. data/lib/standard_flags/tooling.rb +224 -0
  40. data/lib/standard_flags/version.rb +3 -0
  41. data/lib/standard_flags.rb +140 -0
  42. data/lib/tasks/standard_flags.rake +37 -0
  43. 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).
data/Rakefile ADDED
@@ -0,0 +1,6 @@
1
+ require "bundler/gem_tasks"
2
+ require "rspec/core/rake_task"
3
+
4
+ RSpec::Core::RakeTask.new(:spec)
5
+
6
+ task default: :spec