cru-flags 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ddbe75a3b8dd51184b5c884571040346e4f33e96bd0301e7dc845a290b8bb10b
-  data.tar.gz: c3bf794d63aaae3a521f9916bd5c00d0c620bdc363b1aa08fd850a3b31a1c136
+  metadata.gz: 4eab9de685d2ede692ce24cf2b1db8d939b9f316e3ede26c6d4ef4796bee6ffe
+  data.tar.gz: 2db33c91a5571087296900d9edf2ec012c397aa6bab028d731bfefde372d2c81
 SHA512:
-  metadata.gz: 9415e6972df83cb2c45d4a7b7de065ad99a47f884f507a057cc7550c96b1c9f4143be31eca001826d34393e0304ebaea4808a39580ec924df6f337a466296f82
-  data.tar.gz: f2f12796650212518e932577bc789f1bbf25746fbe2aea574654e7ddad8e37f91badfdb73879f46d9dd871a1a556bc477b364d20aa54b195ba749112224277a3
+  metadata.gz: 131419c9830fafc66f0a169cf756f2ea0017e635dd877a3b0d50f2227973aa6f6e4462af2dae4bec516b45bee9e5399800a8f72daa331daf439122cca3fea41a
+  data.tar.gz: 3fa93d5e3b293f540e8f354b0bf091737e76b19ebdace9ad3a610d7444f41203661f2bf4d384c5162cf084b7149ed519b45a16082eaedb5280b45c93fc86ec3c

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.1.1](https://github.com/CruGlobal/cru-flags-ruby/compare/cru-flags/v0.1.0...cru-flags/v0.1.1) (2026-08-24)
+
+
+### Bug Fixes
+
+* 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))
+
 ## 0.1.0 (2026-08-24)
 
 
@@ -11,5 +18,3 @@
 ### Miscellaneous Chores
 
 * release 0.1.0 ([2ed0e67](https://github.com/CruGlobal/cru-flags-ruby/commit/2ed0e67e0ce0441d80ba8d1dc6559a9d8995de17))
-
-## Changelog

data/docs/design.md

@@ -317,8 +317,15 @@ that, in an 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
+  i.e. only when we cannot tell that anybody chose it. `FLIPPER_STRICT` is
+  always honored when set. An app-set `config.flipper.strict` is honored too,
+  **except when it happens to equal the environment's own flipper default**
+  (`:warn` in development, `false` elsewhere) — that case is
+  indistinguishable from nobody setting it, and is quieted. Reading the value
+  is the only signal available; distinguishing it would mean hooking the
+  assignment itself, which is not worth the coupling for a case whose
+  observable effect is the value the app asked for anyway in every
+  environment but development. 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.
@@ -421,17 +428,26 @@ 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,
+2. One-shot `Net::HTTP.start(hostname, 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
+   pooling; the right trade for one request per 30 seconds. `URI#hostname`,
+   not `URI#host`: the latter keeps the brackets an IPv6 literal carries in
+   a URL (`[::1]`), which `getaddrinfo` cannot resolve. **No retries
+   within a tick** — the next tick is the retry, and Net::HTTP's own
+   `max_retries` (default 1) is set to 0 explicitly, since its default would
+   silently re-issue the failed GET inside the same tick. 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`.
+   and the response body is capped at `MAX_BODY_BYTES` (1 MiB) **as it
+   streams** — read chunk by chunk with a running byte count, ending the
+   read the moment the cap is passed — so an oversized or endless body never
+   reaches the heap whole. A `200` that overruns fails the tick (a truncated
+   document must never be parsed); on any other status the body is only ever
+   an excerpt or unused, so the overrun just ends the read and the status's
+   own outcome stands. Both guards fail the tick rather than handing an
+   attacker-controlled value to `Net::HTTP` or `JSON.parse`.
 3. Outcomes:
 
    | Outcome | Action | Health |
@@ -504,11 +520,19 @@ re-running the suite on 3.2 / 3.3 / 3.4.
   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.)
+- Runtime dependencies: **`flipper` (`~> 1.4`), plus a floor on the stdlib
+  gem `json` (`>= 2.4`).** The client core uses stdlib exclusively; the
+  Flipper adapter and Railtie are the gem's reason to have `flipper`, 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.) The `json` entry is a **version floor on a default gem, not a
+  new dependency** — but it must not be removed: `JSON.parse(..., freeze:
+  true)` is what makes the published document deep-frozen, and json below
+  2.4 **silently ignores** `freeze:` rather than erroring. On an older json
+  the snapshot would quietly become mutable and §6's frozen-snapshot
+  invariant — the whole reason readers can dig into the live document
+  without a lock — would be false with no symptom until something mutated
+  it.
 - 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

data/lib/cru_flags/client.rb

@@ -11,13 +11,23 @@ module CruFlags
     VALID_SCHEMES = %w[http https].freeze
     MODES = %w[background on-demand].freeze
 
+    # The one place CRU_FLAGS_URL is read and normalized (design doc §3:
+    # `url: nil` means "read CRU_FLAGS_URL on first use"). It lives on the
+    # Client, not on the module singleton, so a directly-constructed Client
+    # honors the documented contract instead of being silently inert; the
+    # module singleton gets the same normalization by construction.
+    def self.url_from_env
+      value = ENV[ENV_VAR].to_s.strip
+      value.empty? ? nil : value
+    end
+
     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
+      @url = url || self.class.url_from_env
       @document = nil
       @etag = nil
       @healthy = true
@@ -294,7 +304,9 @@ module CruFlags
       return if @url.nil?
       uri = URI(@url.to_s)
       invalid_scheme = !VALID_SCHEMES.include?(uri.scheme)
-      no_host = uri.host.to_s.empty?
+      # hostname, matching the fetcher: the unbracketed form is what actually
+      # gets resolved, so it is what "has a host" must be judged on.
+      no_host = uri.hostname.to_s.empty?
       if invalid_scheme || no_host
         reason = invalid_scheme ? "scheme #{uri.scheme.inspect} is not http(s)" : "has no host"
         @url = nil

data/lib/cru_flags/fetcher.rb

@@ -9,6 +9,12 @@ module CruFlags
   module Fetcher
     Outcome = Struct.new(:kind, :document, :etag, :error)
 
+    # The parts of a Net::HTTPResponse this module uses, captured while the
+    # connection is still open. The body is read (and size-capped) inside the
+    # request block rather than buffered by Net::HTTP, so nothing here holds
+    # a live socket.
+    Response = Struct.new(:code, :body, :etag, :location)
+
     REDIRECT_LIMIT = 3
     REDIRECT_CODES = %w[301 302 303 307 308].freeze
     VALID_SCHEMES = %w[http https].freeze
@@ -21,14 +27,10 @@ module CruFlags
       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
+        # The MAX_BODY_BYTES cap already tripped during the read if it was
+        # going to (see read_capped_body); reaching here means the body fits.
+        document = Document.parse(response.body.to_s)
+        Outcome.new(kind: :document, document:, etag: response.etag)
       when "304" then Outcome.new(kind: :not_modified)
       when "404" then Outcome.new(kind: :missing)
       else
@@ -61,7 +63,7 @@ module CruFlags
           raise FetchError.new("flag fetch exceeded #{REDIRECT_LIMIT} redirects",
             code: :http, status: Integer(response.code))
         end
-        uri = uri.merge(response["location"].to_s)
+        uri = uri.merge(response.location.to_s)
         validate_redirect_uri!(uri)
       end
     end
@@ -71,8 +73,8 @@ module CruFlags
     # 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})",
+      return if VALID_SCHEMES.include?(uri.scheme) && !uri.hostname.to_s.empty?
+      raise FetchError.new("flag fetch redirected to an invalid URI (scheme #{uri.scheme.inspect}, host #{uri.hostname.inspect})",
         code: :network)
     end
 
@@ -80,13 +82,48 @@ module CruFlags
       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",
+      # hostname, not host: URI#host keeps the brackets an IPv6 literal must
+      # carry inside a URL ("[::1]"), which getaddrinfo cannot resolve.
+      Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https",
         open_timeout: timeout, read_timeout: timeout, write_timeout: timeout) do |http|
-        http.get(uri.request_uri, headers)
+        # Design doc §8: no retries within a tick — the next tick is the
+        # retry. Net::HTTP's default max_retries of 1 silently re-issues a
+        # failed idempotent GET, doubling both the blocking bound the client
+        # promises and the load a struggling flag service sees.
+        http.max_retries = 0
+        http.request(Net::HTTP::Get.new(uri.request_uri, headers)) do |response|
+          return Response.new(code: response.code, etag: response["etag"],
+            location: response["location"], body: read_capped_body(response))
+        end
+      end
+    end
+
+    # Design doc §8's 1 MiB cap, enforced WHILE the body streams in rather
+    # than after Net::HTTP has already buffered it: reading stops the moment
+    # the cap is passed, so an oversized (or endless) body never reaches the
+    # heap whole. A 304 — and any other bodyless response — yields nothing
+    # and comes back as "".
+    #
+    # Only a 200 turns the overrun into the tick's failure: that body IS the
+    # document, and a truncated document must never be parsed. Every other
+    # status uses the body as at most a BODY_EXCERPT-sized error excerpt, or
+    # ignores it entirely, so overrunning there just ends the read rather
+    # than relabeling a legible HTTP outcome as a size error.
+    def read_capped_body(response)
+      body = +""
+      response.read_body do |chunk|
+        body << chunk
+        next if body.bytesize <= MAX_BODY_BYTES
+        if response.code == "200"
+          raise FetchError.new("flag fetch body exceeds #{MAX_BODY_BYTES} bytes", code: :parse)
+        end
+        break
       end
+      body
     end
 
     def failed(error) = Outcome.new(kind: :failed, error:)
-    private_class_method :get_following_redirects, :validate_redirect_uri!, :get, :failed
+    private_class_method :get_following_redirects, :validate_redirect_uri!, :get,
+      :read_capped_body, :failed
   end
 end

data/lib/cru_flags/railtie.rb

@@ -22,7 +22,10 @@ module CruFlags
     # (: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.
+    # Flipper's own computed default. An app that explicitly sets the value
+    # its environment already defaults to is therefore indistinguishable
+    # from an app that set nothing, and gets quieted; the value is the only
+    # signal available without hooking the assignment (design doc §5.1).
     def self.quiet_strict?(current:, env_var:, rails_env:)
       return false unless env_var.nil?
       flipper_default = (rails_env == "development") ? :warn : false

data/lib/cru_flags/version.rb

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

data/lib/cru_flags.rb

@@ -17,8 +17,11 @@ module CruFlags
   @flipper_adapter = nil
 
   class << self
+    # The env read happens inside Client (Client.url_from_env), so the
+    # singleton and a hand-rolled `Client.new` share one normalization
+    # rather than two copies that can drift.
     def client
-      @client || @client_mutex.synchronize { @client ||= Client.new(url: url_from_env) }
+      @client || @client_mutex.synchronize { @client ||= Client.new }
     end
 
     def enabled?(name) = client.enabled?(name)
@@ -29,7 +32,11 @@ module CruFlags
 
     def refresh(force: false) = client.refresh(force:)
 
-    def close = client.close
+    # Nil-safe on the ivar, like reset!: going through the memoizing reader
+    # would BUILD (and validate) a singleton just to close it, leaving a
+    # permanently-closed client memoized — and emitting the invalid-URL
+    # warning at shutdown for an app that never used flags at all.
+    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
@@ -52,13 +59,6 @@ module CruFlags
       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
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cru-flags
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Cru