RubyGems - shipeasy-sdk - Versions diffs - 1.3.0 → 1.4.0 - Mend

shipeasy-sdk 1.3.0 → 1.4.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 (5) hide show

checksums.yaml +4 -4
data/README.md +138 -0
data/lib/shipeasy/sdk/flags_client.rb +196 -7
data/lib/shipeasy/sdk/version.rb +1 -1
metadata +2 -2

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6987470d45b6349d50b279a94bc0fb356812c23f354a743c3c052433dc5759aa
-  data.tar.gz: 34d847b481a67fd8876c5e7dfc1351dab1e832fa41f97053324cffb19e24a4c0
+  metadata.gz: bacc8b94c722361a53df3156e4dc63159c75b0657e2c1f6ae246593e90cf7c12
+  data.tar.gz: 4450034aaee670f04015f396a960646fff27e5195e13ebd93ace4c032a82f023
 SHA512:
-  metadata.gz: 4a3899f6938f09b3e84f0de89f37aab45caca5ae1449157d9e6efd45274a0b224fadbbcfa54505ee84ff760a3b8309fa5545227b0f41cb2650bf83c48d7cfe1f
-  data.tar.gz: c5ea14a6d5e53fe124bb8fbb7de06ed3930975b764964698e4c3dbc771f8e68d1766062777fe527f57b8cbd59924b94b864e8f4ed5d7574aa86b066cd9c6d896
+  metadata.gz: cff2bbf433472f1e2be585ccbf5deb12d420e29130bb8f09961f2b277135a0c1726c1318a0f1b7b57fce511b114b6fcde982cc0735b884bb946de46016638c52
+  data.tar.gz: 1ff69897f3b0501e6c4e41fa5eb386017fc4d714a0a5423871ec867b969bea2d1097fda01fb3902b1a57bc37a0490aaf433169e9d829f11739f3ac63cbcabb56

data/README.md CHANGED Viewed

@@ -115,6 +115,84 @@ client.init
 at_exit { client.destroy }
 ```
+## Default values
+`get_flag` and `get_config` take an optional `default:` returned **only when the
+value cannot be resolved** — never when a flag genuinely evaluates to `false`.
+```ruby
+# Flag: default is returned only when the client isn't ready yet (no blob
+# fetched) or the gate doesn't exist. A gate that evaluates to false (disabled,
+# or outside its rollout) returns false, NOT the default.
+Shipeasy.flags.get_flag("new_checkout", user, default: true)
+# Config: default is returned when the config key is absent. A decode proc still
+# runs on a present value.
+Shipeasy.flags.get_config("button_color", default: "blue")
+Shipeasy.flags.get_config("limits", ->(v) { v["max"] }, default: 0)
+```
+## Evaluation detail
+`get_flag_detail(name, user)` returns the boolean **and the reason** it was
+reached, as a `FlagDetail` struct (`.value`, `.reason`). `get_flag` is built on
+top of it. The reason is one of the `REASON_*` constants:
+| Reason             | Meaning                                              |
+| ------------------ | --------------------------------------------------- |
+| `OVERRIDE`         | answered by a local `override_flag` (no telemetry)  |
+| `CLIENT_NOT_READY` | no flag blob fetched/loaded yet                     |
+| `FLAG_NOT_FOUND`   | blob present, but this gate isn't in it             |
+| `OFF`              | gate present but disabled or killswitched           |
+| `RULE_MATCH`       | evaluated to `true`                                 |
+| `DEFAULT`          | evaluated to `false` (rollout/rule)                 |
+```ruby
+detail = Shipeasy.flags.get_flag_detail("new_checkout", user)
+detail.value   # => true / false
+detail.reason  # => "RULE_MATCH" / "DEFAULT" / "OFF" / ...
+```
+The `gate` usage beacon fires exactly once per `get_flag_detail` call (never on
+the `OVERRIDE` short-circuit).
+## Change listeners
+`on_change` registers a callback fired after a background poll fetches **new**
+flag/config data (HTTP 200, not a 304). It accepts a block or any callable and
+returns an unsubscribe proc. Listeners never fire in test/offline mode (there is
+no poll thread). A raising listener is isolated and logged, not propagated.
+```ruby
+unsubscribe = Shipeasy.flags.on_change { reload_local_cache! }
+# ... later
+unsubscribe.call
+```
+## Offline snapshot
+For CI, air-gapped runs, or reproducing a production decision from a captured
+blob, build a **no-network** client that still runs the real evaluator against a
+snapshot. The snapshot JSON holds the raw response bodies of the two SDK
+endpoints:
+```json
+{ "flags": <body of /sdk/flags>, "experiments": <body of /sdk/experiments> }
+```
+```ruby
+client = Shipeasy::SDK::FlagsClient.from_file("snapshot.json")
+# or, from already-parsed blobs:
+client = Shipeasy::SDK::FlagsClient.from_snapshot(flags: flags_body, experiments: exps_body)
+client.get_flag("new_checkout", user)        # real evaluation, no network
+client.get_experiment("checkout_cta", user, {})
+```
+`init` / `init_once` / `track` are no-ops and telemetry is off (it reuses the
+`for_testing` plumbing). Local `override_*` setters still apply on top of the
+snapshot.
 ## Evaluation details
 - **Gates** — rules matched in order; rollout bucket =
@@ -128,6 +206,66 @@ at_exit { client.destroy }
 - **Poll interval** — defaults to 30 s; overridden by the
   `X-Poll-Interval` header from the flags endpoint.
+## Testing
+For unit/integration tests you want a client that does **zero network** and
+returns exactly the values you seed — no api_key, no fetch, no poll thread, no
+telemetry, no metric ingestion. Build one with `FlagsClient.for_testing` and
+seed each entity with the `override_*` setters (Statsig-style local overrides).
+An override always wins over the fetched blob, so the getters answer
+deterministically:
+```ruby
+require "shipeasy-sdk"
+client = Shipeasy::SDK::FlagsClient.for_testing
+# init / init_once are no-ops here — nothing is ever fetched.
+# Flags (boolean)
+client.override_flag("new_checkout", true)
+client.get_flag("new_checkout", { user_id: "u_1" })   # => true
+# Configs (any value; an optional decode proc still runs)
+client.override_config("button_color", "blue")
+client.get_config("button_color")                     # => "blue"
+client.override_config("limits", { "max" => 10 })
+client.get_config("limits", ->(v) { v["max"] })       # => 10
+# Experiments — returns an in-experiment Eval::ExperimentResult
+client.override_experiment("checkout_cta", "treatment", { label: "Buy now" })
+r = client.get_experiment("checkout_cta", { user_id: "u_1" }, { label: "default" })
+r.in_experiment   # => true
+r.group           # => "treatment"
+r.params          # => { label: "Buy now" }
+# track is a no-op (no thread, no network) — assert call counts without stubbing.
+client.track("u_1", "checkout_completed", { revenue: 49.99 })  # => nil
+# Reset between examples
+client.clear_overrides
+```
+The same `override_flag` / `override_config` / `override_experiment` /
+`clear_overrides` setters also work on a **normal** live client (built with
+`FlagsClient.new(...)`), so you can pin one value in local development while the
+rest comes from the fetched blob.
+### Rails singleton
+`Shipeasy.flags` is a process-wide singleton that fetches over the network, so
+in tests prefer a `for_testing` client. If a code path reaches through
+`Shipeasy.flags` directly, stub the singleton to the test client in your test
+setup:
+```ruby
+# RSpec
+before do
+  test_client = Shipeasy::SDK::FlagsClient.for_testing
+  test_client.override_flag("new_checkout", true)
+  allow(Shipeasy).to receive(:flags).and_return(test_client)
+end
+```
 ## Configuration
 | Parameter  | Default                   | Description                         |

data/lib/shipeasy/sdk/flags_client.rb CHANGED Viewed

@@ -11,9 +11,13 @@ module Shipeasy
     class FlagsClient
       DEFAULT_BASE_URL = "https://edge.shipeasy.dev"
-      def initialize(api_key:, base_url: nil, env: "prod", disable_telemetry: false, telemetry_url: nil)
+      def initialize(api_key:, base_url: nil, env: "prod", disable_telemetry: false, telemetry_url: nil, test_mode: false)
         @api_key     = api_key
         @base_url    = (base_url || DEFAULT_BASE_URL).chomp("/")
+        # Test mode: no network, ever. init/init_once/track become no-ops and
+        # evaluation answers come purely from local overrides. Built via the
+        # FlagsClient.for_testing factory; see clear_overrides / override_*.
+        @test_mode   = test_mode
         # Per-evaluation usage telemetry. ON by default; pass
         # disable_telemetry: true to opt out. See telemetry.rb.
         @telemetry = Telemetry.new(
@@ -31,41 +35,196 @@ module Shipeasy
         @mutex       = Mutex.new
         @timer       = nil
         @initialized = false
+        # Statsig-style local overrides. Keyed by resource name; an override,
+        # when present, short-circuits the corresponding getter. Usable on any
+        # client (test or live) for deterministic tests / local development.
+        @flag_overrides   = {}
+        @config_overrides = {}
+        @exp_overrides    = {}
+        # Change listeners — fired after a background poll returns NEW data
+        # (HTTP 200, not 304). Never fired in test/offline mode. Guarded by
+        # @mutex; see on_change / notify_change.
+        @change_listeners = []
+      end
+      # Build a no-network, immediately-usable client for tests. Telemetry is
+      # disabled, init/init_once/track are no-ops (never fetch), and no api_key
+      # is required. Seed it with override_flag / override_config /
+      # override_experiment, then call the normal getters.
+      def self.for_testing(env: "prod")
+        new(
+          api_key: "test",
+          env: env,
+          disable_telemetry: true,
+          test_mode: true,
+        )
+      end
+      # Build an offline client from a JSON snapshot file. The file holds the
+      # raw response bodies of the two SDK endpoints under "flags" and
+      # "experiments" keys:
+      #
+      #   { "flags": <body of /sdk/flags>, "experiments": <body of /sdk/experiments> }
+      #
+      # The returned client does ZERO network (reuses test_mode plumbing:
+      # init/init_once/track are no-ops, telemetry off) but, unlike a bare
+      # for_testing client, runs the REAL evaluator against the loaded blobs.
+      # Local overrides still apply on top. Handy for CI, air-gapped runs, and
+      # reproducing a production decision from a captured blob.
+      def self.from_file(path, env: "prod")
+        data = JSON.parse(File.read(path))
+        from_snapshot(flags: data["flags"], experiments: data["experiments"], env: env)
+      end
+      # Build an offline client directly from already-parsed blobs (same shape
+      # as the /sdk/flags and /sdk/experiments response bodies). See from_file.
+      def self.from_snapshot(flags: nil, experiments: nil, env: "prod")
+        client = for_testing(env: env)
+        client.send(:load_snapshot, flags, experiments)
+        client
       end
       def init
+        return if @test_mode
         fetch_all
         @initialized = true
         start_poll
       end
       def init_once
+        return if @test_mode
         return if @initialized
         fetch_all
         @initialized = true
       end
+      # --- Local overrides -------------------------------------------------
+      # An override wins over the fetched blob in the matching getter. Setters
+      # are mutex-guarded so they're safe to call alongside background polling
+      # on a live client.
+      def override_flag(name, value)
+        @mutex.synchronize { @flag_overrides[name.to_s] = (value ? true : false) }
+        self
+      end
+      def override_config(name, value)
+        @mutex.synchronize { @config_overrides[name.to_s] = value }
+        self
+      end
+      def override_experiment(name, group, params)
+        @mutex.synchronize do
+          @exp_overrides[name.to_s] = { group: group, params: params }
+        end
+        self
+      end
+      def clear_overrides
+        @mutex.synchronize do
+          @flag_overrides.clear
+          @config_overrides.clear
+          @exp_overrides.clear
+        end
+        self
+      end
+      # Register a listener fired after a background poll fetches NEW flag/config
+      # data (HTTP 200, not 304). Accepts either a block or any callable (an
+      # object responding to #call). Returns an unsubscribe proc — call it to
+      # remove the listener. Never fires in test/offline mode (no poll thread).
+      def on_change(callable = nil, &block)
+        listener = callable || block
+        raise ArgumentError, "on_change requires a block or callable" unless listener.respond_to?(:call)
+        @mutex.synchronize { @change_listeners << listener }
+        proc { @mutex.synchronize { @change_listeners.delete(listener) } }
+      end
       def destroy
         @timer&.kill
         @timer = nil
       end
-      def get_flag(name, user)
+      # Flag evaluation with the reason the value was reached. :value is the
+      # boolean result; :reason is one of the REASON_* constants below.
+      FlagDetail = Struct.new(:value, :reason, keyword_init: true)
+      # Reason constants for FlagDetail#reason / get_flag_detail.
+      REASON_CLIENT_NOT_READY = "CLIENT_NOT_READY" # no blob fetched/loaded yet
+      REASON_FLAG_NOT_FOUND   = "FLAG_NOT_FOUND"   # blob present, gate absent
+      REASON_OFF              = "OFF"              # gate present but disabled/killed
+      REASON_OVERRIDE         = "OVERRIDE"         # answered by a local override
+      REASON_RULE_MATCH       = "RULE_MATCH"       # evaluated true
+      REASON_DEFAULT          = "DEFAULT"          # evaluated false (rollout/rule)
+      # Evaluate a flag and return why. Telemetry ("gate" beacon) is emitted
+      # exactly once here (steps 2–5), never on the OVERRIDE short-circuit.
+      def get_flag_detail(name, user)
+        key = name.to_s
+        # 1. Override short-circuits before any telemetry (mirrors get_config).
+        override = @mutex.synchronize { @flag_overrides[key] if @flag_overrides.key?(key) }
+        return FlagDetail.new(value: override, reason: REASON_OVERRIDE) unless override.nil?
         @telemetry.emit("gate", name)
-        gate = @mutex.synchronize { @flags_blob&.dig("gates", name) }
-        return false unless gate
-        Eval.eval_gate(gate, with_anon_id(user))
+        flags_blob, gate = @mutex.synchronize { [@flags_blob, @flags_blob&.dig("gates", name)] }
+        # 2. Not initialized — no blob fetched or loaded yet.
+        return FlagDetail.new(value: false, reason: REASON_CLIENT_NOT_READY) if flags_blob.nil?
+        # 3. Blob present but this gate isn't in it.
+        return FlagDetail.new(value: false, reason: REASON_FLAG_NOT_FOUND) unless gate
+        # 4. Gate present but disabled (or killswitched) — eval_gate would also
+        #    return false here, but the reason is OFF, not a rollout DEFAULT.
+        if Eval.enabled?(gate["killswitch"]) || !Eval.enabled?(gate["enabled"])
+          return FlagDetail.new(value: false, reason: REASON_OFF)
+        end
+        # 5. Run the canonical evaluator; reason follows the boolean result.
+        result = Eval.eval_gate(gate, with_anon_id(user))
+        FlagDetail.new(value: result, reason: result ? REASON_RULE_MATCH : REASON_DEFAULT)
       end
-      def get_config(name, decode = nil)
+      def get_flag(name, user, default: false)
+        detail = get_flag_detail(name, user)
+        if detail.reason == REASON_CLIENT_NOT_READY || detail.reason == REASON_FLAG_NOT_FOUND
+          default
+        else
+          detail.value
+        end
+      end
+      def get_config(name, decode = nil, default: nil)
+        key = name.to_s
+        has_override, override = @mutex.synchronize do
+          [@config_overrides.key?(key), @config_overrides[key]]
+        end
+        if has_override
+          return decode ? decode.call(override) : override
+        end
         @telemetry.emit("config", name)
         entry = @mutex.synchronize { @flags_blob&.dig("configs", name) }
-        return nil unless entry
+        return default unless entry
         value = entry["value"]
         decode ? decode.call(value) : value
       end
       def get_experiment(name, user, default_params, decode = nil)
+        key = name.to_s
+        override = @mutex.synchronize { @exp_overrides[key] }
+        if override
+          params = override[:params]
+          params = decode.call(params) if decode
+          return Eval::ExperimentResult.new(
+            in_experiment: true,
+            group: override[:group],
+            params: params,
+          )
+        end
         @telemetry.emit("experiment", name)
         flags_blob, exps_blob = @mutex.synchronize { [@flags_blob, @exps_blob] }
         exp = exps_blob&.dig("experiments", name)
@@ -89,6 +248,8 @@ module Shipeasy
       end
       def track(user_id, event_name, props = {})
+        return if @test_mode
         payload = JSON.generate({
           events: [{
             type: "metric",
@@ -108,6 +269,32 @@ module Shipeasy
       private
+      # Load a parsed snapshot into the local blobs and mark the client ready,
+      # without any network. Used by from_snapshot / from_file on a test_mode
+      # client so the real evaluator runs against captured data.
+      def load_snapshot(flags, experiments)
+        @mutex.synchronize do
+          @flags_blob = flags
+          @exps_blob  = experiments
+        end
+        @initialized = true
+        self
+      end
+      # Fire each change listener, snapshotting the array under the mutex so a
+      # listener that unsubscribes mid-callback doesn't mutate the list we're
+      # iterating. Listener errors are isolated (warn, never propagate).
+      def notify_change
+        listeners = @mutex.synchronize { @change_listeners.dup }
+        listeners.each do |listener|
+          begin
+            listener.call
+          rescue => e
+            warn "[shipeasy] on_change listener raised: #{e.message}"
+          end
+        end
+      end
       # Normalise the user hash to string keys and, when the caller passed no
       # explicit unit, default anonymous_id to the request's __se_anon_id (set by
       # RackMiddleware). Lets `get_flag("x", {})` bucket anonymous traffic with
@@ -162,6 +349,8 @@ module Shipeasy
           @flags_etag = etag if etag
           @flags_blob = blob
         end
+        # New data arrived (200, not the 304 returned above) — notify listeners.
+        notify_change
         interval
       end

data/lib/shipeasy/sdk/version.rb CHANGED Viewed

@@ -1,5 +1,5 @@
 module Shipeasy
   module SDK
-    VERSION = "1.3.0"
+    VERSION = "1.4.0"
   end
 end

metadata CHANGED Viewed

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shipeasy-sdk
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Shipeasy, Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-13 00:00:00.000000000 Z
+date: 2026-06-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec