cru-flags 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ddbe75a3b8dd51184b5c884571040346e4f33e96bd0301e7dc845a290b8bb10b
+  data.tar.gz: c3bf794d63aaae3a521f9916bd5c00d0c620bdc363b1aa08fd850a3b31a1c136
+SHA512:
+  metadata.gz: 9415e6972df83cb2c45d4a7b7de065ad99a47f884f507a057cc7550c96b1c9f4143be31eca001826d34393e0304ebaea4808a39580ec924df6f337a466296f82
+  data.tar.gz: f2f12796650212518e932577bc789f1bbf25746fbe2aea574654e7ddad8e37f91badfdb73879f46d9dd871a1a556bc477b364d20aa54b195ba749112224277a3

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 (2026-08-24)
+
+
+### Features
+
+* the cru-flags client — sibling contract + Flipper adapter ([#1](https://github.com/CruGlobal/cru-flags-ruby/issues/1)) ([02dfa26](https://github.com/CruGlobal/cru-flags-ruby/commit/02dfa264a68c48ccdce6055893aef5fe50fe8473))
+
+
+### Miscellaneous Chores
+
+* release 0.1.0 ([2ed0e67](https://github.com/CruGlobal/cru-flags-ruby/commit/2ed0e67e0ce0441d80ba8d1dc6559a9d8995de17))
+
+## Changelog

data/LICENSE

@@ -0,0 +1,30 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Cru
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from this
+   software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,35 @@
+# cru-flags
+
+> **Status: AI-generated, not actively maintained by a human team.** This
+> library was authored primarily by an AI assistant against the specification
+> in [docs/design.md](docs/design.md), reviewed and operated by the Cru Rails
+> team. Read the design doc before changing behavior — drift between the
+> design doc and the code is a bug, and the doc wins.
+
+The official Ruby client for Cru's pipeline feature-flag service, and the
+third sibling of [cru-flags-node](https://github.com/CruGlobal/cru-flags-node)
+and [cru-flags-python](https://github.com/CruGlobal/cru-flags-python) — plus a
+read-only Flipper adapter so the Rails fleet's existing `Flipper.enabled?`
+call sites work unchanged.
+
+```ruby
+# In a Rails app: add the gem, done. The Railtie wires Flipper for you.
+Flipper.enabled?(:checkout_v2)
+
+# Anywhere else:
+require "cru_flags"
+CruFlags.enabled?("checkout_v2")
+```
+
+Configuration is one environment variable: `CRU_FLAGS_URL`, the full document
+URL (`https://deploys.cru.org/flags/<project>/<environment>`). Unset means
+every flag is off and nothing starts — no thread, no socket, no warning.
+
+Semantics in one paragraph: the client polls the document in a background
+thread (30s ± 20% jitter, 2s timeouts, conditional GETs via ETag) and answers
+reads from a frozen in-memory snapshot. **Fail-static**: all flags are off
+until the first successful fetch; after that, an outage means flags stop
+changing — never that they turn off. Reads never raise and never do I/O.
+Health transitions (and only transitions) are logged.
+
+CRuby >= 3.2 only. See [docs/design.md](docs/design.md) for everything else.

data/docs/design.md

@@ -0,0 +1,535 @@
+# cru-flags-ruby — Design Document
+
+> ADL-35. Drafted 2026-08-21 against cru-flags-python's docs/design.md (the
+> most complete sibling spec) and the recon in adl-35-cru-flags-ruby-recon.md.
+> When the CruGlobal/cru-flags-ruby repo is created this file moves in as
+> `docs/design.md` and inherits the siblings' rule: drift between the design
+> doc and the code is a bug, and the doc wins.
+
+## 1. Purpose & Scope
+
+`cru-flags` is the official Ruby client for Cru's pipeline feature-flag
+service, and the third sibling of `@cruglobal/flags` (Node) and `cru-flags`
+(Python). It answers exactly one question, as cheaply and as safely as
+possible:
+
+```ruby
+Flipper.enabled?(:checkout_v2)   # the fleet's existing call sites, unchanged
+CruFlags.enabled?("checkout_v2") # the sibling-parity API, same answer
+```
+
+The flag service publishes one JSON document per (project, environment) at a
+public HTTP endpoint. This library polls that document in the background and
+answers reads from an in-memory snapshot. It is a **read-only client**: flags
+are authored elsewhere (cru-cli / the deploys.cru.org dashboard), never by
+this library.
+
+The Ruby client differs from its siblings in one deliberate way: it ships a
+**Flipper adapter** that answers Flipper's read API from the same in-memory
+snapshot. The ~20 Rails apps already call `Flipper.enabled?` (ADL-9's
+ratified standard; ararat's hand-rolled `flipper.rb` is the current
+reference), so the gem keeps that API working while replacing everything
+underneath it. What it replaces, and why, is §4.
+
+### In scope for v0.x
+
+- Read `CRU_FLAGS_URL` from the environment; poll that URL in a background
+  thread; answer `enabled?(name)` from the last document received.
+- Conditional requests (`If-None-Match` / `ETag`) so steady-state polling
+  costs one 304 per interval.
+- An opt-in `refresh_mode: "on-demand"` that drops the thread and refreshes
+  synchronously on the reading thread, for runtimes that freeze between
+  requests (§7.1) — included for contract parity with the siblings.
+- **Fail-static** semantics: a flag lookup never raises, never blocks (in
+  background mode), and never changes answer because the network broke.
+- A read-only `CruFlags::FlipperAdapter` over the snapshot, plus a Railtie
+  that wires it into Flipper with zero app code.
+- Stdlib-only client core (`net/http`, `json`, `thread`); Ruby >= 3.2.
+
+### Out of scope
+
+- **Writing** flags, or any authentication. The flag documents are public,
+  read-only URLs.
+- Per-actor / group / percentage targeting, variants, or non-boolean flag
+  values. The service models a flag as a boolean with metadata; so does this
+  client. The Flipper adapter exposes **only the boolean gate**.
+- Local flag overrides, file-based sources, streaming, or a daemon/sidecar.
+- The service's `/flipper/{project}/{env}/features` protocol endpoints. Stock
+  Flipper's HTTP adapter needed them; ours reads the snapshot, so the
+  collection/single-feature asymmetries documented in the recon simply never
+  come into play.
+
+### Non-goals
+
+- We do **not** try to be a general feature-flag SDK. There is one document
+  shape, defined by our own service, and this client is allowed to know it.
+- We do **not** raise on misconfiguration. An application missing
+  `CRU_FLAGS_URL` must still boot and serve traffic, with every flag off —
+  exactly ararat's current Memory-adapter fallback posture.
+- We do **not** cache in `Rails.cache`. The snapshot is process-local memory;
+  there is no TTL, no Marshal round-trip, and therefore no TTL cliff and no
+  default_proc trap (§4).
+
+---
+
+## 2. Wire contract
+
+Identical to the siblings'. The live document (a real response from
+`https://deploys.cru.org/flags/ararat/release-candidate`):
+
+```json
+{
+  "Project": "ararat",
+  "Environment": "release-candidate",
+  "Version": 3,
+  "NotifySlack": true,
+  "Flags": {
+    "pilot_banner": {
+      "Enabled": true,
+      "Description": "Pilot: flag-gated banner proving the flag service end-to-end (ararat#198)",
+      "CreatedAt": "2026-07-31T14:09:01.119Z",
+      "UpdatedAt": "2026-07-31T14:09:08.777Z",
+      "UpdatedBy": "Omicron7"
+    }
+  }
+}
+```
+
+Load-bearing properties:
+
+| Property | Contract |
+| --- | --- |
+| Top level | JSON object with `Project`, `Environment`, `Version`, `NotifySlack`, `Flags`. PascalCase keys. |
+| `Flags` | Object keyed by flag name. Each value is an object with at least `Enabled: bool`; other keys are metadata. |
+| Unknown keys | **Additive.** New top-level and per-flag keys may appear at any time; the client ignores what it does not understand and never validates beyond "is a JSON object". |
+| `ETag` | Present on `200`, currently the stringified `Version`. Opaque to the client — store and echo it, never parse it. |
+| `304 Not Modified` | Returned when `If-None-Match` matches. Body empty; the previous snapshot stays in force. |
+| `404 Not Found` | A *valid* answer meaning "no document exists yet", not a failure. |
+| `400 Bad Request` | The URL names an environment that does not exist (only `release-candidate` and `production` are real). This *is* a failure: the caller's configuration is wrong and someone should see it. |
+
+`enabled?(name)` is defined precisely as:
+
+```ruby
+document.dig("Flags", name, "Enabled") == true
+```
+
+The `== true` identity check (not truthiness) is deliberate: a flag whose
+`Enabled` is the *string* `"true"`, or `1`, or `null` is a malformed
+document, and the safe reading of a malformed document is "off".
+
+---
+
+## 3. Public API
+
+```ruby
+CruFlags.enabled?("checkout_v2")  # -> bool, never raises
+CruFlags.ready(timeout: 3.0)      # -> bool, never raises
+CruFlags.snapshot                 # -> Hash, plain JSON-serializable deep copy
+CruFlags.refresh(force: false)    # -> bool, refresh now on this thread
+CruFlags.close                    # -> nil, stop refreshing (mostly for tests)
+CruFlags.flipper_adapter          # -> the read-only Flipper adapter (§5)
+
+CruFlags::Client.new(
+  url: nil,            # nil -> read CRU_FLAGS_URL on first use
+  poll_seconds: 30.0,  # refresh interval, ±20% jitter
+  fetch_timeout: 2.0,  # per-request open AND read timeout
+  on_error: nil,       # nil -> log to the "cru_flags" logger (§3.6)
+  refresh_mode: nil    # nil -> read CRU_FLAGS_REFRESH_MODE, else "background"
+)
+```
+
+### 3.1 `CruFlags` module methods
+
+The module methods delegate to a lazily-constructed process-wide
+`CruFlags::Client` singleton — the 99% path, mirroring the siblings'
+module-level `flags`. Requiring the gem does **nothing**: no environment
+read, no socket, no thread (§7). The singleton is constructed on first use,
+so tests and dotenv can set `CRU_FLAGS_URL` any time before the first lookup.
+
+### 3.2 `enabled?(name) -> bool`
+
+Non-blocking read of the current snapshot (in on-demand mode it may refresh
+first; §7.1). **Never raises** — the entire body is rescued so no bug in this
+library, no malformed document, and no shutdown race can take down a caller's
+request path. Anything unexpected answers `false`. Accepts a String or
+Symbol; Symbols are converted with `to_s` (the document's keys are strings;
+Flipper call sites pass symbols).
+
+Unknown flag, unset flag, no document yet, no `CRU_FLAGS_URL`, service down
+before the first success — all `false`.
+
+### 3.3 `ready(timeout: nil) -> bool`
+
+Blocks until the **first fetch attempt completes** — success *or* failure —
+and returns whether it completed within `timeout`. Returns `true` after a
+failed first attempt (the attempt did complete, and "all off" is the final
+answer until the next poll). Returns `false` immediately, without blocking,
+when the client is inert (no URL) — there is no attempt to wait for and never
+will be. In on-demand mode `ready` *performs* the first attempt like any
+other read, so `timeout:` is unused there — the call is bounded by the fetch
+timeouts (up to ~2s by default) regardless of a smaller `timeout:` value,
+exactly as the python client documents. Never raises.
+
+### 3.4 `snapshot -> Hash`
+
+A plain, deep-copied, JSON-serializable Hash of the last document received
+(`{}` before the first success). `JSON.generate(CruFlags.snapshot)`
+round-trips to exactly what the service sent. The copy exists so a caller
+cannot mutate library state; the internally stored snapshot is genuinely
+frozen (§6).
+
+### 3.5 `refresh(force: false) -> bool`
+
+Fetches on the *calling* thread and returns whether the snapshot is fresh (an
+attempt has completed and the most recent one succeeded). Without `force` it
+is a no-op while the last attempt is younger than `poll_seconds`. Blocks for
+at most the fetch timeouts. Never raises. This is the refresh primitive in
+on-demand mode, and an out-of-band poke in background mode — where, per the
+Node contract, concurrent `refresh` calls and a concurrent poller tick all
+**share one in-flight request** rather than stacking simultaneous fetches.
+
+### 3.6 `on_error`
+
+A callable invoked **only on health transitions**:
+
+- ok → failing: called with the exception that broke the poll.
+- failing → ok: called with `nil` (recovery).
+
+Never called per-poll while a failure persists, and never for `304` or `404`.
+The default logs both transitions at WARN — to `Rails.logger` when Rails is
+loaded, else to a `Logger` on `$stderr` tagged `cru_flags`. This is the
+structural replacement for ararat's `LoggedFlagFetches` delegator: the two
+2026-07-31 outages that motivated it were invisible precisely because
+failures were swallowed silently; transition logging makes an outage exactly
+two log lines (one down, one up) instead of zero or thousands. Exceptions
+raised *by* `on_error` are swallowed: a broken error handler must not kill
+the poller.
+
+### 3.7 `close`
+
+Stops refreshing, in either mode. Terminal: a closed client never refreshes
+again, and closing before the first lookup leaves the client permanently
+inert. The last snapshot stays readable. Mostly useful in tests.
+
+---
+
+## 4. Why fail-static (and what this replaces)
+
+The design constraint is inverted relative to a normal HTTP client: **the
+flag client is allowed to be wrong, but never allowed to be loud, slow, or
+fatal.**
+
+1. **`enabled?` performs no I/O** in the default background mode: one ivar
+   read and two Hash lookups. No lock on the read path, so a slow network can
+   never become a slow request. It also performs the fork/liveness guard (a
+   `Process.pid` check plus `Thread#alive?`) that lazily re-arms a dead or
+   post-fork poller, still lock-free and network-free — the guard only takes
+   a lock on the (rare) path where it actually needs to respawn.
+2. **All flags are `false` until the first successful fetch.** A flag guards
+   *new* behaviour; the safe answer while ignorant is the old behaviour.
+3. **Last-known-good persists indefinitely. There is no TTL.** This is the
+   failure-mode semantic §6 of the fleet's original flags design doc (the
+   Google-Doc-era spec, snapshotted as cru-flags-design-doc.md) promised and
+   the current fleet recipe does not deliver: ararat composes `Flipper::Adapters::Failsafe` outside a
+   30-second `ActiveSupportCacheStore`, so 30 seconds into any flag-service
+   outage every flag snaps to `false` — a synchronised, fleet-wide behaviour
+   change caused by exactly the outage a flag client should ride through.
+   Holding the last deliberately-published configuration is the whole reason
+   this gem exists. Freshness is a monitoring question (the transition log,
+   `ready`, `snapshot["Version"]`), never a silent behaviour flip.
+4. **404 is data, not an error.** "This project has no flags yet" is the
+   normal state of every project on day one.
+5. **Nothing raises.** `enabled?` and `ready` rescue `StandardError` —
+   `Interrupt`, `SystemExit`, and other non-StandardError exceptions still
+   propagate.
+
+The stock-Flipper traps this architecture retires by construction (all
+verified live in the recon):
+
+- Flipper's Rails engine installs a **Memoizer middleware that preloads
+  `get_all` on every request** — with a network adapter underneath, Failsafe
+  is load-bearing and any gap 500s the whole app. Our adapter's `get_all` is
+  a frozen-Hash read; the preload becomes free and Failsafe has nothing to
+  guard.
+- `Flipper::Adapters::Http` must be given `max_retries: 0` **explicitly**
+  (its internal default never applies) and leaves open/read timeouts at
+  Net::HTTP's ~60s unless set. Our HTTP layer sets 2s/2s explicitly and never
+  sits on a request path.
+- The `default_proc` that Marshal — and therefore any Marshal-backed
+  `Rails.cache` — cannot serialize (ararat's `MarshalableFlipperReads`
+  incident) is added by `Flipper::Adapters::Memoizable#get_all`
+  (memoizable.rb:103 in 1.4.2), **which wraps ANY adapter the DSL is given,
+  including ours** — not by the Http adapter as ararat's comments suggest.
+  With no `Rails.cache` layer nothing ever Marshals the result, so the trap
+  is gone — but Memoizable's mutation constrains our adapter's return values;
+  see the hard rule in §5.
+
+---
+
+## 5. The Flipper adapter
+
+`CruFlags::FlipperAdapter` — a read-only adapter over the client's frozen
+snapshot, so every existing `Flipper.enabled?(:name)` call site works
+unchanged.
+
+- `features` → the Set of flag names in the current document.
+- `get(feature)` / `get_multi` / `get_all` → gate-value hashes shaped by
+  `Flipper::Adapter.default_config` (which in 1.4 includes the `expression`
+  gate key alongside boolean/actors/groups/percentages), with **only the
+  boolean gate** populated: `true` when the flag's `Enabled == true`, off
+  otherwise. The service is boolean-only.
+- **HARD RULE: `get`, `get_multi`, and `get_all` must return freshly-built,
+  UNFROZEN top-level Hashes on every call** (their nested gate values may
+  reference frozen snapshot data; the top-level containers may not be
+  frozen and may not be memoized/shared). Flipper's DSL wraps every adapter
+  in `Adapters::Memoizable` by default, and its `get_all` **mutates the
+  returned Hash in place** (`response.default_proc = ...`,
+  memoizable.rb:103) on every Memoizer-preloaded request — a frozen or
+  shared return value raises `FrozenError` on every request in production,
+  a stricter recurrence of the very failure mode §4 retires. The suite
+  pins this with a test that calls the adapter through
+  `Flipper::Adapters::Memoizable` under memoization.
+- `add` / `remove` / `clear` / `enable` / `disable` →
+  raise `CruFlags::ReadOnlyError`. The CLI and dashboard are the only
+  writers; this preserves the behavior of ararat's
+  `Flipper::Adapters::ReadOnly` wrapper (whose own error class is
+  `ReadOnly::WriteAttempted`) without another wrapper layer.
+- The adapter holds no state of its own and takes no locks — it reads
+  whatever frozen document the client currently publishes, so a Memoizer
+  preload, a console `Flipper.enabled?`, and a background job all see the
+  same atomically-swapped snapshot.
+
+### 5.1 Railtie
+
+`require "cru_flags"` in a Rails app (via the Gemfile) installs a Railtie
+that, in an initializer:
+
+- registers the adapter via `Flipper.configure { |c| c.adapter { CruFlags.flipper_adapter } }`
+  in an ordinary initializer — safe against ordering because Flipper's engine
+  resolves `config.adapter` LAZILY on first `Flipper.instance` access (its
+  `flipper.default` block calls it at invocation time, not at boot), and the
+  last `AdapterBuilder#store` wins, so an app's own `Flipper.configure` in
+  `config/initializers` still overrides ours;
+- quiets strict mode for the no-flag-document case, **but not with a naive
+  "unless the app set it" check** — Flipper's engine populates
+  `config.flipper.strict` in `config.before_configuration` (`:warn` in
+  development, `false` in production), which runs before ANY gem initializer,
+  so the value is always already set when we look. Instead the Railtie sets
+  `config.flipper.strict = false` only when `ENV["FLIPPER_STRICT"].nil?` AND
+  the current value equals Flipper's own computed default for this Rails env —
+  i.e. only when we can prove nobody chose it. `FLIPPER_STRICT=warn` (or any
+  app-set value) is always honored. Rationale: local dev and brand-new
+  projects legitimately have no flag document, and `Flipper.add` is never
+  called by app code (flags are born in the service), so dev-mode `:warn`
+  would fire on every check.
+
+With `CRU_FLAGS_URL` unset the client is inert, the snapshot is empty, and
+every flag reads `false` — byte-for-byte ararat's current Memory-adapter
+fallback, with zero configuration branching. An app that wants different
+wiring (a test adapter, Flipper UI in development) configures Flipper itself;
+the Railtie only supplies the default.
+
+Non-Rails Ruby (plain scripts, sidekiq-less workers) skips the Railtie and
+uses `CruFlags.enabled?` directly.
+
+---
+
+## 6. Snapshot storage & atomicity
+
+The parsed document is **deep-frozen** before it is published — via
+`JSON.parse(body, freeze: true)` (json >= 2.4, which also interns repeated
+strings) rather than a hand-rolled recursive walk. The frozen tree is then
+assigned to a single instance variable — one atomic reference swap — while
+holding a mutex that only *writers* contend for. Readers never take the lock.
+
+The lock-free read depends on CRuby's GVL making a single reference store
+observable atomically; **the gem supports CRuby only** (the entire fleet is
+CRuby; JRuby/TruffleRuby have no GVL and would need a read barrier we have no
+consumer for). The gemspec/README say so.
+
+Why frozen rather than "a hash we promise not to mutate": the snapshot is
+shared across every thread in the process, and one accidental
+`snapshot["Flags"]["x"]["Enabled"] = true` in caller code would be an
+un-debuggable, cross-thread, non-reproducible bug. Freezing makes it a
+`FrozenError` at the point of the mistake. `CruFlags.snapshot` hands back a
+thawed deep copy so the public API stays ordinary Ruby.
+
+Consistency guarantee: a reader sees either the whole old document or the
+whole new one, never a half-applied update.
+
+---
+
+## 7. Threading model
+
+- **One background Thread per active client**, `Thread#name` set to
+  `"cru-flags-poller"`, `abort_on_exception` left false, `report_on_exception`
+  set false (the loop rescues everything; a teardown race must not spam
+  stderr).
+- **Started lazily** on the first `enabled?` / `ready` call, never at
+  require. Requiring a gem must not start threads: it breaks preloading
+  forking servers (Puma workers, Spring) that require before forking, and
+  makes `require "cru_flags"` in a test suite a side-effecting act. **After
+  `fork`, the child re-starts its own poller lazily on first read** — the
+  client detects a PID change and discards the parent's dead thread state
+  (Puma's `fork_worker` and Spring both make this a first-class case in
+  Rails, where the siblings could treat forking as exotic).
+- **Never delays exit.** Ruby threads other than the main thread die with
+  the process — no daemon flag needed — but the loop also sleeps
+  interruptibly (a `Queue#pop` with timeout / `ConditionVariable#wait`), so
+  `close` returns promptly instead of waiting out a poll interval.
+- **Jitter**: each sleep is `poll_seconds * rand(0.8..1.2)`. Fleet pods boot
+  together; without jitter they synchronise into a thundering herd against
+  the flag service. ±20% de-phases them within a couple of intervals.
+- **Inert clients start nothing.** No `CRU_FLAGS_URL` and no explicit `url:`
+  means no thread, no socket, no warning — just `false`.
+
+### 7.1 On-demand refresh (`refresh_mode: "on-demand"`)
+
+Contract-identical to the siblings' mode (python design §5.1): no poller
+thread at all; every read fetches first when the last **attempt** is
+`poll_seconds` or older, else answers from cache. Concurrent readers coalesce
+on one mutex — a burst of N readers is one request. Staleness anchors on the
+last attempt, not the last success, so a dead service costs one failed
+request per interval, not one per read. No jitter (real traffic de-phases
+itself). The cost is the read-path guarantee: `enabled?` can block up to the
+fetch timeouts, once per interval.
+
+Selecting it: `Client.new(refresh_mode: "on-demand")` or
+`CRU_FLAGS_REFRESH_MODE=on-demand`. The constructor argument wins. An
+unrecognised *environment* value warns through `on_error` and falls back to
+background (misconfiguration must never stop boot); an unrecognised
+*constructor* argument raises `ArgumentError` (that is a typo in code).
+
+Why it ships at all: the Rails fleet is long-running ECS and will use
+background mode everywhere — but the three clients advertise one contract,
+the mode is ~100 lines plus ported tests, and the first Cloud-Run-shaped
+Ruby consumer gets it for free instead of forking the gem.
+
+### 7.2 Environment resolution
+
+`CRU_FLAGS_URL` and `CRU_FLAGS_REFRESH_MODE` are read once, at first use, and
+cached. Empty or whitespace-only counts as unset. Only `http`/`https` URLs
+are accepted; anything else makes the client inert with one warning through
+`on_error`.
+
+---
+
+## 8. Fetch algorithm
+
+One tick:
+
+1. Build a `Net::HTTP::Get` with `Accept: application/json`, a `User-Agent`
+   of `cru-flags-ruby/<version>`, and `If-None-Match: <etag>` when an ETag is
+   stored.
+2. One-shot `Net::HTTP.start(host, port, use_ssl:, open_timeout: t,
+   read_timeout: t, write_timeout: t)` — no keep-alive, no connection
+   pooling; the right trade for one request per 30 seconds. **No retries
+   within a tick** — the next tick is the retry. Redirects are followed to a
+   fixed limit of **3** (Net::HTTP does not follow them itself; the siblings
+   inherit auto-follow from `fetch`/`urllib`). Ruby-first hardening the
+   siblings may want to adopt: each redirect hop's merged URI is
+   re-validated (http/https scheme, non-empty host) before it is followed,
+   and the response body is capped at `MAX_BODY_BYTES` (1 MiB) before
+   parsing, both failing the tick rather than handing an attacker-controlled
+   value to `Net::HTTP` or `JSON.parse`.
+3. Outcomes:
+
+   | Outcome | Action | Health |
+   | --- | --- | --- |
+   | `200` + JSON object | Freeze and publish; **then** store `ETag` | ok |
+   | `304` | Keep snapshot and ETag | ok |
+   | `404` | Publish empty snapshot; clear ETag | ok |
+   | Other status (`400`, `5xx`, …) | Keep snapshot | failing |
+   | Timeout / DNS / connection error | Keep snapshot | failing |
+   | Body not JSON, or not a JSON object | Keep snapshot | failing |
+
+   Document-before-ETag ordering is load-bearing (inherited from the Node
+   client): a body that fails to parse must never get its ETag stored, or
+   the client would pin itself to the bad response via endless 304s.
+
+4. Report the health transition (§3.6), if any.
+
+Parsing is lenient exactly like the siblings, with the Node client's §6.1
+rules as the reference: missing/`null` `Flags` becomes `{}`, but `Flags`
+**present with the wrong type** (a string, number, or array) fails the whole
+document (health → failing) — leniency is for absence, not for malformation.
+Individual non-Hash flag *entries* are dropped without failing the document;
+all unknown keys are preserved verbatim. (§2's "never validates beyond is-a-
+JSON-object" is scoped by these rules, same as the siblings' docs.)
+
+---
+
+## 9. Testing strategy
+
+Every line of the behavioural contract is a test, in the python client's
+organisation: contract tests grouped by design-doc section, against **a real
+local HTTP server** (a minimal programmable responder on a stdlib
+`TCPServer` at `127.0.0.1:0` — WEBrick is no longer a default gem and the
+responder needs ~60 lines), recording inbound headers so the ETag echo, 304,
+404, 500, slow-response, and malformed-body paths exercise real `Net::HTTP`
+behaviour rather than a mock's idea of it.
+
+Plus, ported from the siblings and ararat:
+
+- Subprocess tests: `require "cru_flags"` starts no threads even with
+  `CRU_FLAGS_URL` set; a running poller never delays interpreter exit.
+- A fork test: parent warms the client, child forks, child's reads work and
+  spawn the child's own poller (§7's PID-change case).
+- Jitter distribution; a concurrency hammer on `enabled?` across snapshot
+  swaps; `JSON.generate`/`parse` round-trip of `snapshot`.
+- Flipper conformance: `Flipper.new(CruFlags.flipper_adapter)` answering
+  `enabled?` end-to-end against the local server, the Memoizer preload path,
+  writes raising `ReadOnlyError`, and — the regression ararat paid for —
+  `Marshal.dump(Rails.cache-shaped round trip)` of everything `get_all`
+  returns.
+- On-demand mode: its own section (coalescing, one-fetch-per-interval while
+  down, no thread).
+- `test/verify_live.rb`, opt-in and networked, against the real public
+  endpoint (document parses; second conditional fetch is 304). Not in CI.
+
+Framework: minitest (the fleet standard), `filterwarnings`-equivalent
+strictness via `Warning[:deprecated] = true` and a test that the suite emits
+no warnings. CI: one required check running lint (standardrb, the fleet
+direction per AP-7) + the suite on the `.tool-versions` Ruby, plus a matrix
+re-running the suite on 3.2 / 3.3 / 3.4.
+
+---
+
+## 10. Packaging & distribution
+
+- Gem `cru-flags`, require path `cru_flags`, module `CruFlags`, repo
+  `CruGlobal/cru-flags-ruby`. Version lives in `lib/cru_flags/version.rb`,
+  bumped by release-please (`release-type: ruby` **with an explicit
+  `"version-file": "lib/cru_flags/version.rb"`** — release-please's default
+  path derivation turns the hyphenated name into `lib/cru/flags/version.rb`
+  and would silently bump a file that doesn't exist).
+- `required_ruby_version = ">= 3.2"` — the fleet floor.
+- Runtime dependency: **`flipper` (`~> 1.4`) only.** The client core uses
+  stdlib exclusively; the Flipper adapter and Railtie are the gem's reason to
+  have its one dependency, and every consumer already carries it. (If a
+  flipper-less consumer ever appears, splitting a zero-dep core gem out is a
+  follow-up, not a v0 concern.)
+- Publishing via **RubyGems Trusted Publishing** (OIDC) from
+  `.github/workflows/release.yml` — the PyPI pattern; no API key in the
+  repo. First publish uses RubyGems' pending-publisher flow since the gem
+  name is unclaimed.
+- Repo onboarding matches the fleet standard from day one: security-only
+  `dependabot.yml` (bundler + github-actions lanes per the ADL-32 template),
+  a `dependabot-auto-merge` gate is NOT installed (review-tier repo), README
+  status banner and CLAUDE.md same-PR-doc rule copied from the siblings.
+
+---
+
+## 11. Rollout (out of scope for the gem, recorded for sequencing)
+
+1. Gem ships and publishes v0.1.0.
+2. ararat cuts over: Gemfile swap, delete `config/initializers/flipper.rb`
+   and its two regression tests (their scenarios live in the gem's suite
+   now). ararat is the proving ground exactly as it was for the hand-rolled
+   version.
+3. devops-claude-skills onboarding skill Stage 4 changes from "copy ararat's
+   flipper.rb" to "add the cru-flags gem".
+4. The remaining fleet picks it up as apps onboard to v2 (no mass retrofit —
+   only ararat and clm are on v2 today).
+
+Each step is its own PR with its own review; none blocks the gem.

data/lib/cru_flags/client.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+require "json"
+require "logger"
+require "uri"
+
+module CruFlags
+  # The polling flag client (design doc §3–§8). One instance per process in
+  # normal use, via the CruFlags module singleton.
+  class Client
+    VALID_SCHEMES = %w[http https].freeze
+    MODES = %w[background on-demand].freeze
+
+    def initialize(url: nil, poll_seconds: 30.0, fetch_timeout: 2.0,
+      on_error: nil, refresh_mode: nil)
+      @poll_seconds = positive(poll_seconds, 30.0)
+      @fetch_timeout = positive(fetch_timeout, 2.0)
+      @on_error = on_error || default_on_error
+      @refresh_mode = resolve_mode(refresh_mode)
+      @url = url
+      @document = nil
+      @etag = nil
+      @healthy = true
+      @attempted = false
+      @last_attempt_at = nil
+      @last_attempt_ok = false
+      @closed = false
+      @write_mutex = Mutex.new
+      @fetch_mutex = Mutex.new
+      @ready_mutex = Mutex.new
+      @ready_cv = ConditionVariable.new
+      @wake = Queue.new
+      @thread = nil
+      @pid = nil
+      validate_url!
+    end
+
+    def inert? = @url.nil?
+
+    def enabled?(name)
+      read_path_touch
+      doc = @document
+      doc&.dig("Flags", name.to_s, "Enabled") == true
+    rescue
+      false
+    end
+
+    def snapshot
+      read_path_touch
+      doc = @document
+      doc ? JSON.parse(JSON.generate(doc)) : {}
+    rescue
+      {}
+    end
+
+    # The Flipper adapter's read primitive: the frozen Flags hash (or {}),
+    # through the same read path as enabled? (lazy start / on-demand
+    # refresh).
+    def flags_for_adapter
+      read_path_touch
+      @document&.fetch("Flags", nil) || {}
+    rescue
+      {}
+    end
+
+    # Blocks until the first fetch attempt completes (success or failure) and
+    # returns whether it did within timeout. Immediately false for inert
+    # clients (design doc §3.3, §7).
+    def ready(timeout: nil)
+      return false if inert? || (@closed && !@attempted)
+      ensure_started
+      return on_demand_ready if on_demand?
+      @ready_mutex.synchronize do
+        deadline = timeout && Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        until @attempted
+          ensure_started # self-heals a poller that died mid-wait, rather than waiting on it forever
+          remaining = deadline && deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          return false if remaining && remaining <= 0
+          @ready_cv.wait(@ready_mutex, remaining || 1.0)
+          return false if @closed && !@attempted
+        end
+        true
+      end
+    rescue
+      false
+    end
+
+    def refresh(force: false)
+      return false if inert? || @closed
+      waited_from = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      begin
+        @fetch_mutex.synchronize do
+          if force
+            attempt_fetch unless @last_attempt_at && @last_attempt_at >= waited_from
+          elsif stale?
+            attempt_fetch
+          end
+        end
+      ensure
+        signal_ready
+      end
+      @attempted && @last_attempt_ok
+    rescue
+      false
+    end
+
+    def close
+      @closed = true
+      @wake.push(:stop)
+      @ready_mutex.synchronize { @ready_cv.broadcast }
+      begin
+        @thread&.join(0.1)
+      rescue
+        nil # close called from the poller thread itself must not raise ThreadError
+      end
+      nil
+    end
+
+    private
+
+    # The pre-read hook shared by enabled?/snapshot/flags_for_adapter: lazily
+    # arms the background poller (a no-op once running) and, in on-demand
+    # mode, performs the coalesced fetch before the read.
+    def read_path_touch
+      ensure_started
+      refresh_on_demand
+    end
+
+    # refresh_mode resolution (design doc §7.1, §7.2): constructor argument
+    # wins over ENV["CRU_FLAGS_REFRESH_MODE"], which wins over the
+    # "background" default. An unrecognized constructor value is a caller
+    # typo -> ArgumentError. An unrecognized ENV value is misconfiguration
+    # that must never stop boot -> one on_error warning, then background.
+    # @on_error is already assigned by the time this runs, so the warning
+    # can be reported inline.
+    def resolve_mode(arg)
+      if arg
+        raise ArgumentError, "refresh_mode must be one of #{MODES.join(", ")}" unless MODES.include?(arg)
+        return arg
+      end
+      env = ENV["CRU_FLAGS_REFRESH_MODE"].to_s.strip
+      return "background" if env.empty?
+      return env if MODES.include?(env)
+      report(FetchError.new("CRU_FLAGS_REFRESH_MODE=#{env.inspect} is not recognized; using background",
+        code: :network))
+      "background"
+    end
+
+    # On-demand mode has no poller thread at all (design doc §7.1).
+    def on_demand?
+      @refresh_mode == "on-demand"
+    end
+
+    # The on-demand read-path hook: every enabled?/snapshot/ready call
+    # attempts a coalesced, attempt-anchored fetch before reading. A no-op
+    # in background mode, for inert clients, and once closed.
+    def refresh_on_demand
+      return unless on_demand?
+      return if inert? || @closed
+      begin
+        attempt_fetch_coalesced(force: false)
+      ensure
+        signal_ready # deliberate: kept for symmetry with the background poller's signal, even though on-demand's own ready() never waits on this CV
+      end
+    end
+
+    # ready in on-demand mode performs the read-path refresh itself rather
+    # than waiting on the ready CV (there is no poller to signal it); the
+    # timeout: argument is unused there, bounded instead by the fetch
+    # timeouts (design doc §3.3, §7.1).
+    def on_demand_ready
+      refresh_on_demand
+      @attempted
+    end
+
+    # Lazily arms the background poller on the first enabled?/ready/snapshot
+    # call. A no-op for inert, closed, or on-demand clients. Self-healing: a
+    # dead poller (killed by an unanticipated bug) is detected via
+    # Thread#alive? and respawned rather than leaving flags frozen forever.
+    # Fork-safe: a PID change discards the dead parent thread's state
+    # (including the ready CV, whose wait queue may reference parent
+    # threads) so the child re-arms its own poller on its own next read
+    # (design doc §7).
+    def ensure_started
+      return if inert? || @closed || on_demand?
+      return if @thread&.alive? && Process.pid == @pid
+      @write_mutex.synchronize do
+        return if @closed
+        if @thread && Process.pid != @pid
+          @thread = nil
+          @wake = Queue.new
+          @ready_mutex = Mutex.new
+          @ready_cv = ConditionVariable.new
+        end
+        spawn_poller unless @thread&.alive?
+      end
+    end
+
+    def spawn_poller
+      @pid = Process.pid
+      @thread = Thread.new do
+        Thread.current.name = "cru-flags-poller"
+        Thread.current.report_on_exception = false
+        until @closed
+          begin
+            attempt_fetch_coalesced(force: true)
+          rescue
+            nil # a bug here must not silently kill the poller (design doc §7)
+          ensure
+            signal_ready
+          end
+          begin
+            @wake.pop(timeout: @poll_seconds * rand(0.8..1.2))
+          rescue
+            # Non-spinning: a broken wake queue must not turn into a busy
+            # loop hammering the flag service.
+            sleep(@poll_seconds)
+          end
+        end
+      end
+    end
+
+    def attempt_fetch_coalesced(force:)
+      @fetch_mutex.synchronize do
+        attempt_fetch if force || stale?
+      end
+    end
+
+    def signal_ready
+      return unless @attempted
+      @ready_mutex.synchronize { @ready_cv.broadcast }
+    end
+
+    def stale?
+      @last_attempt_at.nil? ||
+        (Process.clock_gettime(Process::CLOCK_MONOTONIC) - @last_attempt_at) >= @poll_seconds
+    end
+
+    def attempt_fetch
+      outcome = Fetcher.call(url: @url, etag: @etag, timeout: @fetch_timeout)
+      apply(outcome)
+    ensure
+      @attempted = true
+      @last_attempt_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def apply(outcome)
+      case outcome.kind
+      when :document
+        @document = outcome.document # document BEFORE etag (design doc §8)
+        @etag = outcome.etag
+        became(healthy: true)
+      when :not_modified
+        became(healthy: true)
+      when :missing
+        @document = Document::EMPTY
+        @etag = nil
+        became(healthy: true)
+      when :failed
+        became(healthy: false, error: outcome.error)
+      end
+      @last_attempt_ok = outcome.kind != :failed
+    end
+
+    def became(healthy:, error: nil)
+      return if healthy == @healthy
+      @healthy = healthy
+      report(healthy ? nil : error)
+    end
+
+    def report(error)
+      @on_error.call(error)
+    rescue
+      nil # a broken error handler must not kill the poller
+    end
+
+    def default_on_error
+      lambda do |error|
+        logger = defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger ||
+          (@fallback_logger ||= Logger.new($stderr, progname: "cru_flags"))
+        if error
+          logger.warn("flag fetches failing: #{error.class}: #{error.message}")
+        else
+          logger.warn("flag fetches recovered")
+        end
+      end
+    end
+
+    def positive(value, fallback)
+      (value.is_a?(Numeric) && value.finite? && value.positive?) ? value.to_f : fallback
+    end
+
+    def validate_url!
+      return if @url.nil?
+      uri = URI(@url.to_s)
+      invalid_scheme = !VALID_SCHEMES.include?(uri.scheme)
+      no_host = uri.host.to_s.empty?
+      if invalid_scheme || no_host
+        reason = invalid_scheme ? "scheme #{uri.scheme.inspect} is not http(s)" : "has no host"
+        @url = nil
+        report(FetchError.new("CRU_FLAGS_URL #{reason}; client is inert", code: :network))
+      end
+    rescue URI::InvalidURIError
+      @url = nil
+      report(FetchError.new("CRU_FLAGS_URL is not a valid URL; client is inert", code: :network))
+    end
+  end
+end

data/lib/cru_flags/document.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "json"
+
+module CruFlags
+  module Document
+    EMPTY = {"Flags" => {}.freeze}.freeze
+
+    module_function
+
+    # Parse and deep-freeze one flag document. Leniency is for ABSENCE, not
+    # malformation: a missing Flags key is an empty document, a wrong-typed
+    # one is a broken document (design doc §8).
+    def parse(body)
+      parsed = JSON.parse(body, freeze: true)
+      raise ParseError, "document is not a JSON object" unless parsed.is_a?(Hash)
+
+      normalize_flags(parsed)
+    rescue JSON::ParserError => e
+      raise ParseError, "document is not JSON: #{e.message}"
+    end
+
+    def normalize_flags(parsed)
+      flags = parsed["Flags"]
+      case flags
+      when nil
+        rebuild(parsed, {}.freeze)
+      when Hash
+        clean = flags.select { |_name, entry| entry.is_a?(Hash) }
+        (clean.size == flags.size) ? parsed : rebuild(parsed, clean.freeze)
+      else
+        raise ParseError, "Flags is #{flags.class}, expected an object"
+      end
+    end
+
+    def rebuild(parsed, flags)
+      parsed.except("Flags").merge("Flags" => flags).freeze
+    end
+    private_class_method :normalize_flags, :rebuild
+  end
+end

data/lib/cru_flags/errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CruFlags
+  class Error < StandardError; end
+
+  class ParseError < Error; end
+
+  # Normalized fetch failure. code is :http, :network, :timeout, or :parse;
+  # status is set only for :http.
+  class FetchError < Error
+    attr_reader :code, :status
+
+    def initialize(message, code:, status: nil)
+      super(message)
+      @code = code
+      @status = status
+    end
+  end
+
+  class ReadOnlyError < Error; end
+end

data/lib/cru_flags/fetcher.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module CruFlags
+  # One conditional GET of the flag document. Stateless; the Client owns the
+  # etag and the snapshot. Never raises — every failure is an Outcome.
+  module Fetcher
+    Outcome = Struct.new(:kind, :document, :etag, :error)
+
+    REDIRECT_LIMIT = 3
+    REDIRECT_CODES = %w[301 302 303 307 308].freeze
+    VALID_SCHEMES = %w[http https].freeze
+    BODY_EXCERPT = 200
+    MAX_BODY_BYTES = 1_048_576
+
+    module_function
+
+    def call(url:, etag: nil, timeout: 2.0)
+      response = get_following_redirects(URI(url), etag:, timeout:)
+      case response.code
+      when "200"
+        body = response.body.to_s
+        if body.bytesize > MAX_BODY_BYTES
+          failed(FetchError.new("flag fetch body exceeds #{MAX_BODY_BYTES} bytes (#{body.bytesize})",
+            code: :parse))
+        else
+          document = Document.parse(body)
+          Outcome.new(kind: :document, document:, etag: response["etag"])
+        end
+      when "304" then Outcome.new(kind: :not_modified)
+      when "404" then Outcome.new(kind: :missing)
+      else
+        excerpt = response.body.to_s.strip.gsub(/\s+/, " ")[0, BODY_EXCERPT]
+        failed(FetchError.new("flag fetch failed with HTTP #{response.code}: #{excerpt}",
+          code: :http, status: Integer(response.code)))
+      end
+    rescue FetchError => e
+      failed(e)
+    rescue ParseError => e
+      failed(FetchError.new(e.message, code: :parse))
+    rescue Timeout::Error => e
+      failed(FetchError.new("flag fetch timed out: #{e.message}", code: :timeout))
+    rescue SystemCallError, SocketError, IOError, OpenSSL::SSL::SSLError,
+      URI::Error, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError => e
+      failed(FetchError.new("flag fetch failed: #{e.message}", code: :network))
+    rescue => e
+      # Floor, not enumeration: "call never raises" must hold by construction.
+      # Mirrors the sibling clients' contract (node's toFlagsError) — any
+      # exception type we didn't anticipate still normalizes to :network
+      # rather than escaping as a raise.
+      failed(FetchError.new("flag fetch failed: #{e.message}", code: :network))
+    end
+
+    def get_following_redirects(uri, etag:, timeout:)
+      REDIRECT_LIMIT.downto(0) do |hops_left|
+        response = get(uri, etag:, timeout:)
+        return response unless REDIRECT_CODES.include?(response.code)
+        if hops_left.zero?
+          raise FetchError.new("flag fetch exceeded #{REDIRECT_LIMIT} redirects",
+            code: :http, status: Integer(response.code))
+        end
+        uri = uri.merge(response["location"].to_s)
+        validate_redirect_uri!(uri)
+      end
+    end
+
+    # Guards each redirect hop (design doc §8): a Location header pointing at
+    # a non-http(s) scheme or a hostless URI must not be handed to Net::HTTP,
+    # which would otherwise raise something less legible than a plain :failed
+    # :network outcome.
+    def validate_redirect_uri!(uri)
+      return if VALID_SCHEMES.include?(uri.scheme) && !uri.host.to_s.empty?
+      raise FetchError.new("flag fetch redirected to an invalid URI (scheme #{uri.scheme.inspect}, host #{uri.host.inspect})",
+        code: :network)
+    end
+
+    def get(uri, etag:, timeout:)
+      headers = {"Accept" => "application/json",
+                 "User-Agent" => "cru-flags-ruby/#{VERSION}"}
+      headers["If-None-Match"] = etag if etag
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+        open_timeout: timeout, read_timeout: timeout, write_timeout: timeout) do |http|
+        http.get(uri.request_uri, headers)
+      end
+    end
+
+    def failed(error) = Outcome.new(kind: :failed, error:)
+    private_class_method :get_following_redirects, :validate_redirect_uri!, :get, :failed
+  end
+end

data/lib/cru_flags/flipper_adapter.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "flipper"
+
+module CruFlags
+  # Read-only Flipper adapter over the client's frozen snapshot (design doc
+  # §5). HARD RULE: get/get_multi/get_all build fresh, UNFROZEN top-level
+  # hashes on every call — Flipper::Adapters::Memoizable mutates the Hash we
+  # return (response.default_proc =, memoizable.rb:103), so a frozen or
+  # shared return value would raise FrozenError on every memoized request.
+  class FlipperAdapter
+    include Flipper::Adapter
+
+    def initialize(client)
+      @client = client
+    end
+
+    def name = :cru_flags
+
+    def read_only? = true
+
+    def features
+      @client.flags_for_adapter.keys.to_set
+    end
+
+    def get(feature)
+      gates_for(feature.key)
+    end
+
+    def get_multi(features)
+      flags = @client.flags_for_adapter
+      features.to_h { |feature| [feature.key, gates_for(feature.key, flags)] }
+    end
+
+    def get_all
+      flags = @client.flags_for_adapter
+      flags.keys.to_h { |name| [name, gates_for(name, flags)] }
+    end
+
+    def add(_feature) = write_refused
+
+    def remove(_feature) = write_refused
+
+    def clear(_feature) = write_refused
+
+    def enable(_feature, _gate, _thing) = write_refused
+
+    def disable(_feature, _gate, _thing) = write_refused
+
+    private
+
+    def gates_for(name, flags = @client.flags_for_adapter)
+      gates = self.class.default_config.dup
+      gates[:boolean] = true if flags.dig(name, "Enabled") == true
+      gates
+    end
+
+    def write_refused
+      raise ReadOnlyError, "flags are written by cru-cli and the deploys.cru.org dashboard, never by the app"
+    end
+  end
+end

data/lib/cru_flags/railtie.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Loaded at file scope, not inside the initializer: Rails::Application
+# computes its initializer collection ONCE, by walking Rails::Railtie's
+# currently-defined subclasses, before running any of them. If "flipper"
+# were required for the first time from inside our own initializer's body,
+# Flipper::Engine would not exist yet when that walk happens, so its own
+# initializers (Strict wrapping, ActorLimit, the Memoizer middleware) would
+# never join the collection at all — not run late, just silently absent.
+# This file only loads under Rails (see the guarded require in
+# lib/cru_flags.rb), so requiring "flipper" here does not touch the
+# no-bundler / non-Rails path.
+require "flipper"
+
+module CruFlags
+  # Zero-config Rails wiring (design doc §5.1). Registration is ordering-safe
+  # because Flipper's engine resolves config.adapter LAZILY on first
+  # Flipper.instance access, and the last-registered adapter block wins — an
+  # app's own Flipper.configure in config/initializers still overrides ours.
+  class Railtie < Rails::Railtie
+    # Flipper's engine assigns config.flipper.strict in before_configuration
+    # (:warn in development, false elsewhere) — BEFORE any gem initializer —
+    # so "did the app set it" cannot be read off the config value alone. We
+    # quiet strict only when the env var is unset AND the value still equals
+    # Flipper's own computed default, i.e. only when nobody chose it.
+    def self.quiet_strict?(current:, env_var:, rails_env:)
+      return false unless env_var.nil?
+      flipper_default = (rails_env == "development") ? :warn : false
+      current == flipper_default
+    end
+
+    initializer "cru_flags.flipper" do |app|
+      Flipper.configure { |config| config.adapter { CruFlags.flipper_adapter } }
+
+      if app.config.respond_to?(:flipper) &&
+          Railtie.quiet_strict?(current: app.config.flipper.strict,
+            env_var: ENV["FLIPPER_STRICT"], rails_env: Rails.env.to_s)
+        app.config.flipper.strict = false
+      end
+    end
+  end
+end

data/lib/cru_flags/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CruFlags
+  VERSION = "0.1.0"
+end

data/lib/cru_flags.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "cru_flags/version"
+require_relative "cru_flags/errors"
+require_relative "cru_flags/document"
+require_relative "cru_flags/fetcher"
+require_relative "cru_flags/client"
+
+# Module-level singleton — the 99% path (design doc §3.1). Requiring this
+# file does nothing: no env read, no socket, no thread.
+module CruFlags
+  ENV_VAR = "CRU_FLAGS_URL"
+
+  @client_mutex = Mutex.new
+  @client = nil
+  @flipper_adapter_mutex = Mutex.new
+  @flipper_adapter = nil
+
+  class << self
+    def client
+      @client || @client_mutex.synchronize { @client ||= Client.new(url: url_from_env) }
+    end
+
+    def enabled?(name) = client.enabled?(name)
+
+    def ready(timeout: nil) = client.ready(timeout:)
+
+    def snapshot = client.snapshot
+
+    def refresh(force: false) = client.refresh(force:)
+
+    def close = client.close
+
+    # The read-only Flipper adapter (design doc §5), memoized and bound to
+    # the singleton client. `flipper` is required lazily here (not at the
+    # top of this file) so requiring "cru_flags" alone stays flipper-free.
+    def flipper_adapter
+      @flipper_adapter || @flipper_adapter_mutex.synchronize do
+        @flipper_adapter ||= begin
+          require_relative "cru_flags/flipper_adapter"
+          FlipperAdapter.new(client)
+        end
+      end
+    end
+
+    # Test hook, not public API: closes and discards the singleton so the
+    # next call re-reads the environment.
+    def reset!
+      @client_mutex.synchronize do
+        @client&.close
+        @client = nil
+      end
+      @flipper_adapter_mutex.synchronize { @flipper_adapter = nil }
+    end
+
+    private
+
+    def url_from_env
+      value = ENV[ENV_VAR].to_s.strip
+      value.empty? ? nil : value
+    end
+  end
+end
+
+require_relative "cru_flags/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: cru-flags
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Cru
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: flipper
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+description: Polls the flag service's per-(project, environment) JSON document, answers
+  reads from a frozen in-memory snapshot with fail-static semantics, and ships a read-only
+  Flipper adapter for the Rails fleet. CRuby only. See docs/design.md.
+email:
+- apps@cru.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- docs/design.md
+- lib/cru_flags.rb
+- lib/cru_flags/client.rb
+- lib/cru_flags/document.rb
+- lib/cru_flags/errors.rb
+- lib/cru_flags/fetcher.rb
+- lib/cru_flags/flipper_adapter.rb
+- lib/cru_flags/railtie.rb
+- lib/cru_flags/version.rb
+homepage: https://github.com/CruGlobal/cru-flags-ruby
+licenses:
+- BSD-3-Clause
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/CruGlobal/cru-flags-ruby
+  changelog_uri: https://github.com/CruGlobal/cru-flags-ruby/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Official Ruby client for Cru's pipeline feature-flag service
+test_files: []