cru-flags 0.2.0 → 0.3.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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: f7095f1356c7bbd71e37d86dbcd3b2bd4b3fdfd8eab1596f72f4b3d0e7aced11
4
- data.tar.gz: 0b7ad1b83c3346b6cf4e4ab1e6c471e7ee7c2ae19e2c1baa7fc752b08e40a3b4
3
+ metadata.gz: 8e30bb4a6976f3c9260a037567d36b7dcde5cd1b6c56f3fc05a42a5be1cb6175
4
+ data.tar.gz: d52a60b18efc70a89df960782102443151c68353467cb90ee77d83dee9739821
5
5
  SHA512:
6
- metadata.gz: 57b7ca9b139f2880951c8365c86dcfe613c52cc4f287ba3e4960da4057df4cb159789506ff48726e2c3bbab70e2aeca1be0d2df9e59b94996ddd43c017b088bd
7
- data.tar.gz: 0d657b212c65ade4858620199c18ca91bae2e810d9382cedf67ef1ba00798aaf3933dd31f2ffaef6907a51263a11fba8bfc8f3c17662ac42761025c979a3a52f
6
+ metadata.gz: bafcdb45473f2e45fc363626a52ab3d6d04d821d116975a0d1c602e7df096acfa2d9a74b0ea62cd8837d2ebed332c31860e319e6770a9b4ed77270c9eb3096fd
7
+ data.tar.gz: 307d96a180cb094892bae38b17a040eeb2e9014e5e69cfa9fb713362b00274b748d460b818c031c41d607c707626f87c6bdca4c7e79d71f086a6c02b6753c064
data/CHANGELOG.md CHANGED
@@ -1,34 +1,20 @@
1
1
  # Changelog
2
2
 
3
- ## [0.2.0](https://github.com/CruGlobal/cru-flags-ruby/compare/cru-flags/v0.1.2...cru-flags/v0.2.0) (2026-10-29)
3
+ ## [0.3.0](https://github.com/CruGlobal/cru-flags/compare/v0.2.0...v0.3.0) (2026-11-10)
4
4
 
5
5
 
6
- ### Features
6
+ ### Added
7
7
 
8
- * keep a fallback copy of the flag document in Rails.cache ([#12](https://github.com/CruGlobal/cru-flags-ruby/issues/12)) ([cf03f02](https://github.com/CruGlobal/cru-flags-ruby/commit/cf03f02adf998774ae1b258af5685ddb668140d5))
8
+ * add the Go client ([#10](https://github.com/CruGlobal/cru-flags/issues/10)) ([67e98e3](https://github.com/CruGlobal/cru-flags/commit/67e98e34dd38dab2757b58cc8b9a98e4ef1de4c2))
9
9
 
10
- ## [0.1.2](https://github.com/CruGlobal/cru-flags-ruby/compare/cru-flags/v0.1.1...cru-flags/v0.1.2) (2026-08-24)
10
+ ## Before 0.3.0
11
11
 
12
+ Until 0.3.0 the clients lived in three repositories, each with its own
13
+ version line. Their changelogs moved here unchanged:
12
14
 
13
- ### Bug Fixes
15
+ - Node, `@cruglobal/flags` 0.1.0 to 0.1.3: [docs/node/CHANGELOG.md](docs/node/CHANGELOG.md)
16
+ - Python, `cru-flags` 0.1.0 to 0.1.3: [docs/python/CHANGELOG.md](docs/python/CHANGELOG.md)
17
+ - Ruby, `cru-flags` gem 0.1.0 to 0.2.0: [docs/ruby/CHANGELOG.md](docs/ruby/CHANGELOG.md)
14
18
 
15
- * gem "cru-flags" with no require: now actually loads the gem ([#9](https://github.com/CruGlobal/cru-flags-ruby/issues/9)) ([05ce44c](https://github.com/CruGlobal/cru-flags-ruby/commit/05ce44c1b68673487d07d669e96f191c701658d7))
16
-
17
- ## [0.1.1](https://github.com/CruGlobal/cru-flags-ruby/compare/cru-flags/v0.1.0...cru-flags/v0.1.1) (2026-08-24)
18
-
19
-
20
- ### Bug Fixes
21
-
22
- * single-attempt fetches, Client env fallback, streaming body cap, IPv6 hosts ([#7](https://github.com/CruGlobal/cru-flags-ruby/issues/7)) ([f0710b1](https://github.com/CruGlobal/cru-flags-ruby/commit/f0710b1e0ea79ef9e6ee44be972834575127173c))
23
-
24
- ## 0.1.0 (2026-08-24)
25
-
26
-
27
- ### Features
28
-
29
- * 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))
30
-
31
-
32
- ### Miscellaneous Chores
33
-
34
- * release 0.1.0 ([2ed0e67](https://github.com/CruGlobal/cru-flags-ruby/commit/2ed0e67e0ce0441d80ba8d1dc6559a9d8995de17))
19
+ From 0.3.0 on, all four packages, Go included, release together under one
20
+ version.
data/LICENSE CHANGED
@@ -1,30 +1,28 @@
1
1
  BSD 3-Clause License
2
2
 
3
3
  Copyright (c) 2026, Cru
4
- All rights reserved.
5
4
 
6
5
  Redistribution and use in source and binary forms, with or without
7
6
  modification, are permitted provided that the following conditions are met:
8
7
 
9
- 1. Redistributions of source code must retain the above copyright notice,
10
- this list of conditions and the following disclaimer.
8
+ 1. Redistributions of source code must retain the above copyright notice, this
9
+ list of conditions and the following disclaimer.
11
10
 
12
11
  2. Redistributions in binary form must reproduce the above copyright notice,
13
12
  this list of conditions and the following disclaimer in the documentation
14
13
  and/or other materials provided with the distribution.
15
14
 
16
15
  3. Neither the name of the copyright holder nor the names of its
17
- contributors may be used to endorse or promote products derived from this
18
- software without specific prior written permission.
16
+ contributors may be used to endorse or promote products derived from
17
+ this software without specific prior written permission.
19
18
 
20
19
  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21
20
  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23
- ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
24
- LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
25
- CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
26
- SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27
- INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
28
- CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
29
- ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30
- POSSIBILITY OF SUCH DAMAGE.
21
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
23
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
25
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
data/README.md CHANGED
@@ -1,41 +1,145 @@
1
1
  # cru-flags
2
2
 
3
- > **Status: AI-generated, not actively maintained by a human team.** This
4
- > library was authored primarily by an AI assistant against the specification
5
- > in [docs/design.md](docs/design.md), reviewed and operated by the Cru Rails
6
- > team. Read the design doc before changing behavior — drift between the
7
- > design doc and the code is a bug, and the doc wins.
8
-
9
- The official Ruby client for Cru's pipeline feature-flag service, and the
10
- third sibling of [cru-flags-node](https://github.com/CruGlobal/cru-flags-node)
11
- and [cru-flags-python](https://github.com/CruGlobal/cru-flags-python) — plus a
12
- read-only Flipper adapter so the Rails fleet's existing `Flipper.enabled?`
13
- call sites work unchanged.
3
+ Clients for **Cru's pipeline feature-flag service**, one per language, in one
4
+ repository. Each one reads `CRU_FLAGS_URL`, polls that one JSON document with
5
+ `ETag` revalidation, keeps the last good copy through any outage, and answers
6
+ "is this flag on?" from memory without ever raising:
7
+
8
+ | Language | Package | Install | Read a flag |
9
+ | ---------- | ------------------------------------------------------------------ | --------------------------------------- | ------------------------------------------ |
10
+ | Go | [`github.com/CruGlobal/cru-flags`][go-pkg] | `go get github.com/CruGlobal/cru-flags` | `cruflags.Enabled("checkout_v2")` |
11
+ | TypeScript | [`@cruglobal/flags`](https://www.npmjs.com/package/@cruglobal/flags) | `npm install @cruglobal/flags` | `flags.enabled("checkout_v2")` |
12
+ | Python | [`cru-flags`](https://pypi.org/project/cru-flags/) | `pip install cru-flags` | `flags.enabled("checkout_v2")` |
13
+ | Ruby | [`cru-flags`](https://rubygems.org/gems/cru-flags) | `gem "cru-flags"` | `Flipper.enabled?(:checkout_v2)` (Rails) |
14
+
15
+ All four have zero runtime dependencies (the gem's one exception is `flipper`,
16
+ for its read-only Flipper adapter), share one version number, and release
17
+ together.
18
+
19
+ How flags are created and flipped (`cru app flags`), and how they fit the
20
+ merge-dark / demo-on-stage / launch-in-production workflow, is in the
21
+ [pipeline guide](https://github.com/CruGlobal/cru-deploy/blob/main/docs/pipeline-v2.md#feature-flags).
22
+
23
+ > **Status: AI-generated, maintained on a best-effort basis.** These libraries
24
+ > were authored primarily by an AI assistant against the design documents
25
+ > linked below. Dependabot keeps tooling current; feature work and fixes
26
+ > happen as needed. Issues and pull requests are welcome.
27
+
28
+ [go-pkg]: https://pkg.go.dev/github.com/CruGlobal/cru-flags
29
+
30
+ ## The contract every client keeps
31
+
32
+ - **`CRU_FLAGS_URL` unset means every flag is off**, silently. Local
33
+ development, CI, preview and lab environments have no flag document, and
34
+ that is a normal state, not a configuration error.
35
+ - **Unknown flags read off.** Only a literal `"Enabled": true` turns a flag on.
36
+ - **A flag read never fetches, never blocks and never raises.** It is a memory
37
+ lookup.
38
+ - **Poll every 30 seconds, plus or minus 20% jitter,** sending `If-None-Match`
39
+ so an unchanged document costs a `304`.
40
+ - **Keep last-known-good.** A failed poll (timeout, `5xx`, a malformed body)
41
+ changes nothing, forever. Flags never fall back to off on error. A `404`
42
+ means "this app has no flags yet" and is not an error.
43
+ - **Fetch once at startup** (`Ready`) so the first requests after a deploy see
44
+ real flags.
45
+ - **Log health transitions only**: once when polling starts failing, once when
46
+ it recovers.
47
+
48
+ The [conformance suite](conformance/) encodes these rules as cases, and every
49
+ client's test suite runs them against the same test server.
50
+
51
+ ## Quick start
52
+
53
+ ### Go
54
+
55
+ ```go
56
+ import cruflags "github.com/CruGlobal/cru-flags"
57
+
58
+ func main() {
59
+ ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
60
+ cruflags.Ready(ctx) // optional: wait for the first fetch before serving
61
+ cancel()
62
+
63
+ if cruflags.Enabled("checkout_v2") {
64
+ // ...
65
+ }
66
+ }
67
+ ```
68
+
69
+ Details: [docs/go/README.md](https://github.com/CruGlobal/cru-flags/blob/main/docs/go/README.md).
70
+
71
+ ### TypeScript / Node.js
72
+
73
+ ```ts
74
+ import { flags } from "@cruglobal/flags";
75
+
76
+ await flags.ready(); // optional warmup
77
+ if (flags.enabled("checkout_v2")) {
78
+ // ...
79
+ }
80
+ ```
81
+
82
+ Details: [docs/node/README.md](https://github.com/CruGlobal/cru-flags/blob/main/docs/node/README.md).
83
+
84
+ ### Python
85
+
86
+ ```python
87
+ from cru_flags import flags
88
+
89
+ flags.ready(timeout=3.0) # optional warmup
90
+ if flags.enabled("checkout_v2"):
91
+ ...
92
+ ```
93
+
94
+ Details: [docs/python/README.md](https://github.com/CruGlobal/cru-flags/blob/main/docs/python/README.md).
95
+
96
+ ### Ruby
14
97
 
15
98
  ```ruby
16
- # In a Rails app: add the gem, done. The Railtie wires Flipper for you.
99
+ # Gemfile
100
+ gem "cru-flags"
101
+
102
+ # In Rails the Railtie wires Flipper for you:
17
103
  Flipper.enabled?(:checkout_v2)
18
104
 
19
105
  # Anywhere else:
20
- require "cru_flags"
21
106
  CruFlags.enabled?("checkout_v2")
22
107
  ```
23
108
 
24
- Configuration is one environment variable: `CRU_FLAGS_URL`, the full document
25
- URL (`https://deploys.cru.org/flags/<project>/<environment>`). Unset means
26
- every flag is off and nothing starts — no thread, no socket, no warning.
109
+ Details: [docs/ruby/README.md](https://github.com/CruGlobal/cru-flags/blob/main/docs/ruby/README.md).
110
+
111
+ ### Lambda and Cloud Run
112
+
113
+ On runtimes that freeze the process between requests, a background poll timer
114
+ does not tick. Set `CRU_FLAGS_REFRESH_MODE=on-demand` and every client drops
115
+ the timer and refreshes from the read path instead, at most once per poll
116
+ interval. Call `Ready` during init so the first invocation sees real flags.
117
+
118
+ ## Repository layout
119
+
120
+ | Path | What |
121
+ | ---------------------------------------------------- | ----------------------------------------------------------- |
122
+ | `*.go`, `go.mod` | Go package `cruflags` |
123
+ | `src/`, `test/*.ts`, `package.json` | TypeScript package `@cruglobal/flags` |
124
+ | `cru_flags/`, `tests/`, `pyproject.toml` | Python package `cru-flags` |
125
+ | `lib/`, `test/*.rb`, `cru-flags.gemspec` | Ruby gem `cru-flags` |
126
+ | `conformance/` | Shared cases and the test server every client runs against |
127
+ | `docs/<language>/` | Each client's README, design document and old changelog |
128
+
129
+ Each language's design document (`docs/<language>/design.md`) is the
130
+ authoritative specification for that client. See
131
+ [CONTRIBUTING.md](https://github.com/CruGlobal/cru-flags/blob/main/CONTRIBUTING.md)
132
+ to work on them.
133
+
134
+ ## Releasing
27
135
 
28
- Semantics in one paragraph: the client polls the document in a background
29
- thread (30s ± 20% jitter, 2s timeouts, conditional GETs via ETag) and answers
30
- reads from a frozen in-memory snapshot. **Fail-static**: all flags are off
31
- until the first successful fetch; after that, an outage means flags stop
32
- changing — never that they turn off. Reads never raise and never do I/O.
33
- Health transitions (and only transitions) are logged.
136
+ [release-please](https://github.com/googleapis/release-please) keeps a release
137
+ pull request open on `main`, built from Conventional Commit subjects. Merging
138
+ it bumps every version file, writes `CHANGELOG.md`, tags `vX.Y.Z` and
139
+ publishes a GitHub Release. The release workflow then publishes to npm, PyPI
140
+ and RubyGems through trusted publishing (no registry tokens live in this
141
+ repository). The Go module needs no publish step: the tag is the release.
34
142
 
35
- In Rails, the client also keeps a copy of the last good document in
36
- `Rails.cache` (no expiry). A process that boots while the flag service is down
37
- serves that copy instead of every flag off. To opt out, set
38
- `CruFlags.fallback_store = nil` anywhere in your app's config (application,
39
- environment file, or initializer).
143
+ ## License
40
144
 
41
- CRuby >= 3.2 only. See [docs/design.md](docs/design.md) for everything else.
145
+ [BSD-3-Clause](LICENSE).
@@ -1,10 +1,10 @@
1
- # cru-flags-ruby — Design Document
1
+ # Ruby client (`cru-flags` gem) — Design Document
2
2
 
3
3
  > ADL-35. Drafted 2026-08-21 against cru-flags-python's docs/design.md (the
4
4
  > most complete sibling spec) and the recon in adl-35-cru-flags-ruby-recon.md.
5
- > When the CruGlobal/cru-flags-ruby repo is created this file moves in as
6
- > `docs/design.md` and inherits the siblings' rule: drift between the design
7
- > doc and the code is a bug, and the doc wins.
5
+ > It now lives at `docs/ruby/design.md` in CruGlobal/cru-flags, beside the
6
+ > other clients' design docs, and follows their rule: drift between the
7
+ > design doc and the code is a bug, and the doc wins.
8
8
 
9
9
  ## 1. Purpose & Scope
10
10
 
@@ -620,11 +620,11 @@ re-running the suite on 3.2 / 3.3 / 3.4.
620
620
  ## 10. Packaging & distribution
621
621
 
622
622
  - Gem `cru-flags`, require path `cru_flags`, module `CruFlags`, repo
623
- `CruGlobal/cru-flags-ruby`. Version lives in `lib/cru_flags/version.rb`,
624
- bumped by release-please (`release-type: ruby` **with an explicit
625
- `"version-file": "lib/cru_flags/version.rb"`** — release-please's default
626
- path derivation turns the hyphenated name into `lib/cru/flags/version.rb`
627
- and would silently bump a file that doesn't exist).
623
+ `CruGlobal/cru-flags` (shared with the Node, Python and Go clients). Version
624
+ lives in `lib/cru_flags/version.rb` and moves in lockstep with the other
625
+ three packages: release-please's root `node` release bumps it through an
626
+ `extra-files` entry that rewrites the line carrying the
627
+ `x-release-please-version` annotation.
628
628
  - `required_ruby_version = ">= 3.2"` — the fleet floor.
629
629
  - Runtime dependencies: **`flipper` (`~> 1.4`), plus a floor on the stdlib
630
630
  gem `json` (`>= 2.4`).** The client core uses stdlib exclusively; the
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module CruFlags
4
- VERSION = "0.2.0"
4
+ VERSION = "0.3.0" # x-release-please-version
5
5
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: cru-flags
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.0
4
+ version: 0.3.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Cru
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2026-10-29 00:00:00.000000000 Z
11
+ date: 2026-11-10 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: flipper
@@ -40,7 +40,7 @@ dependencies:
40
40
  version: '2.4'
41
41
  description: Polls the flag service's per-(project, environment) JSON document, answers
42
42
  reads from a frozen in-memory snapshot with fail-static semantics, and ships a read-only
43
- Flipper adapter for the Rails fleet. CRuby only. See docs/design.md.
43
+ Flipper adapter for the Rails fleet. CRuby only. See docs/ruby/design.md.
44
44
  email:
45
45
  - apps@cru.org
46
46
  executables: []
@@ -50,7 +50,7 @@ files:
50
50
  - CHANGELOG.md
51
51
  - LICENSE
52
52
  - README.md
53
- - docs/design.md
53
+ - docs/ruby/design.md
54
54
  - lib/cru-flags.rb
55
55
  - lib/cru_flags.rb
56
56
  - lib/cru_flags/client.rb
@@ -60,13 +60,13 @@ files:
60
60
  - lib/cru_flags/flipper_adapter.rb
61
61
  - lib/cru_flags/railtie.rb
62
62
  - lib/cru_flags/version.rb
63
- homepage: https://github.com/CruGlobal/cru-flags-ruby
63
+ homepage: https://github.com/CruGlobal/cru-flags
64
64
  licenses:
65
65
  - BSD-3-Clause
66
66
  metadata:
67
67
  rubygems_mfa_required: 'true'
68
- source_code_uri: https://github.com/CruGlobal/cru-flags-ruby
69
- changelog_uri: https://github.com/CruGlobal/cru-flags-ruby/blob/main/CHANGELOG.md
68
+ source_code_uri: https://github.com/CruGlobal/cru-flags
69
+ changelog_uri: https://github.com/CruGlobal/cru-flags/blob/main/CHANGELOG.md
70
70
  post_install_message:
71
71
  rdoc_options: []
72
72
  require_paths: