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

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

checksums.yaml +4 -4
data/README.md +138 -0
data/lib/shipeasy/sdk/eval.rb +38 -3
data/lib/shipeasy/sdk/flags_client.rb +251 -9
data/lib/shipeasy/sdk/openfeature.rb +204 -0
data/lib/shipeasy/sdk/sticky_store.rb +39 -0
data/lib/shipeasy/sdk/version.rb +1 -1
data/lib/shipeasy-sdk.rb +1 -0
metadata +4 -2

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6987470d45b6349d50b279a94bc0fb356812c23f354a743c3c052433dc5759aa
-  data.tar.gz: 34d847b481a67fd8876c5e7dfc1351dab1e832fa41f97053324cffb19e24a4c0
+  metadata.gz: ff3dbc0f1f6f19484edafcb75460928392fd43278036b68ed2c8179f9d21ac4d
+  data.tar.gz: 04d7e38426d7be6c00e504749c6a33441d88db79f70e1eae533fa9fc115b94d4
 SHA512:
-  metadata.gz: 4a3899f6938f09b3e84f0de89f37aab45caca5ae1449157d9e6efd45274a0b224fadbbcfa54505ee84ff760a3b8309fa5545227b0f41cb2650bf83c48d7cfe1f
-  data.tar.gz: c5ea14a6d5e53fe124bb8fbb7de06ed3930975b764964698e4c3dbc771f8e68d1766062777fe527f57b8cbd59924b94b864e8f4ed5d7574aa86b066cd9c6d896
+  metadata.gz: 93432ded1ed218653913a2895c0178741c4e4e06671e131722d45672f481d782791243fdc35d16347bd1462b2ea0cc2c8bdacdb7012d983a17f190c208159d9d
+  data.tar.gz: def56c79ef372df20b3a7325e838d8165955c39a2c8221e393546d60b61b9405ee2d5a346e2a467bc771d88c50af8806f116d1bfaac2eaed5db9f2e8f6cbd338

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/eval.rb CHANGED Viewed

@@ -57,6 +57,19 @@ module Shipeasy
         end
       end
+      # Pick the bucketing identifier. When bucket_by is set and the user
+      # carries that attribute as a non-empty string (or any number, stringified),
+      # bucket on it — so a whole company/org lands on one variant. Otherwise fall
+      # back to user_id, then anonymous_id. Mirrors core's pickIdentifier.
+      def self.pick_identifier(user, bucket_by)
+        if bucket_by && !bucket_by.to_s.empty?
+          v = user[bucket_by] || user[bucket_by.to_sym]
+          return v if v.is_a?(String) && !v.empty?
+          return v.to_s if v.is_a?(Numeric)
+        end
+        user["user_id"] || user[:user_id] || user["anonymous_id"] || user[:anonymous_id]
+      end
       def self.eval_gate(gate, user)
         return false if enabled?(gate["killswitch"])
         return false unless enabled?(gate["enabled"])
@@ -79,7 +92,14 @@ module Shipeasy
       ExperimentResult = Struct.new(:in_experiment, :group, :params, keyword_init: true)
-      def self.eval_experiment(exp, flags_blob, exps_blob, user)
+      # exp_name + sticky_store are optional so existing callers stay deterministic.
+      # When a sticky_store is passed, an enrolled unit whose stored salt prefix
+      # still matches skips the allocation gate (so a shrinking allocation keeps
+      # it in) and returns the stored group without re-running the pick. A fresh
+      # pick is persisted via store.set; a salt mismatch / missing stored group
+      # falls through to re-bucket + overwrite. Mirrors the TS reference
+      # (doc 20 §2). exp_name is the key under which the entry is stored.
+      def self.eval_experiment(exp, flags_blob, exps_blob, user, exp_name: nil, sticky_store: nil)
         not_in = ExperimentResult.new(in_experiment: false, group: "control", params: nil)
         return not_in unless exp && exp["status"] == "running"
@@ -90,7 +110,8 @@ module Shipeasy
           return not_in unless gate && eval_gate(gate, user)
         end
-        uid = user["user_id"] || user[:user_id] || user["anonymous_id"] || user[:anonymous_id]
+        bucket_by = exp["bucketBy"] || exp[:bucketBy]
+        uid = pick_identifier(user, bucket_by)
         return not_in unless uid
         universe_name = exp["universe"]
@@ -103,14 +124,28 @@ module Shipeasy
         salt          = exp["salt"]
         allocation_pct = exp["allocationPct"] || 0
+        groups = exp["groups"] || []
+        salt8 = (salt || "")[0, 8]
+        # Sticky short-circuit: an enrolled unit whose stored salt prefix still
+        # matches skips allocation and returns the stored group. If the stored
+        # group no longer exists, fall through to re-bucket + overwrite.
+        if sticky_store && exp_name
+          entry = (sticky_store.get(uid) || {})[exp_name]
+          if entry && entry["s"] == salt8
+            g = groups.find { |x| x["name"] == entry["g"] }
+            return ExperimentResult.new(in_experiment: true, group: g["name"], params: g["params"]) if g
+          end
+        end
         return not_in if murmur3("#{salt}:alloc:#{uid}") % 10000 >= allocation_pct
         group_hash = murmur3("#{salt}:group:#{uid}") % 10000
         cumulative = 0
-        groups = exp["groups"] || []
         groups.each_with_index do |g, i|
           cumulative += g["weight"]
           if group_hash < cumulative || i == groups.length - 1
+            sticky_store.set(uid, exp_name, { "g" => g["name"], "s" => salt8 }) if sticky_store && exp_name
             return ExperimentResult.new(in_experiment: true, group: g["name"], params: g["params"])
           end
         end

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

@@ -5,15 +5,29 @@ require "thread"
 require_relative "eval"
 require_relative "telemetry"
 require_relative "anon_id"
+require_relative "sticky_store"
 module Shipeasy
   module SDK
     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, private_attributes: nil, sticky_store: nil)
         @api_key     = api_key
         @base_url    = (base_url || DEFAULT_BASE_URL).chomp("/")
+        # Attribute names usable for targeting but stripped from every outbound
+        # /collect payload (LD/Statsig privateAttributes). The server evaluates
+        # locally so private attrs never leave for evaluation; the only egress is
+        # track(), where the listed keys are dropped from the props bag.
+        @private_attributes = (private_attributes || []).map(&:to_s)
+        # Pluggable sticky-bucketing store (doc 20 §2). Absent ⇒ deterministic.
+        # Threaded into get_experiment so an enrolled unit locks to its first
+        # assigned variant. Built-in: InMemoryStickyStore.
+        @sticky_store = sticky_store
+        # 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,45 +45,203 @@ 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_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)
+      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)
-        result = Eval.eval_experiment(exp, flags_blob, exps_blob, with_anon_id(user))
+        result = Eval.eval_experiment(
+          exp, flags_blob, exps_blob, with_anon_id(user),
+          exp_name: name.to_s, sticky_store: @sticky_store,
+        )
         result.params ||= default_params
         if result.in_experiment && decode
@@ -89,13 +261,17 @@ module Shipeasy
       end
       def track(user_id, event_name, props = {})
+        return if @test_mode
+        safe_props = strip_private(props)
         payload = JSON.generate({
           events: [{
             type: "metric",
             event_name: event_name,
             user_id: user_id.to_s,
             ts: (Time.now.to_f * 1000).to_i,
-            **(props.empty? ? {} : { properties: props }),
+            **(safe_props.empty? ? {} : { properties: safe_props }),
           }],
         })
@@ -106,8 +282,72 @@ module Shipeasy
         end
       end
+      # Emit an exposure event for an experiment at the server-side decision
+      # point (parity with the browser's auto-exposure). The server is stateless
+      # and never auto-logs, so call this when you actually present the
+      # treatment. Re-evaluates the experiment for the user (a bare user_id
+      # string is wrapped as { "user_id" => id }); if enrolled, POSTs a single
+      # exposure to /collect. No-op in test mode or when the user isn't enrolled.
+      def log_exposure(user_or_user_id, experiment_name)
+        return if @test_mode
+        user = user_or_user_id.is_a?(Hash) ? user_or_user_id : { "user_id" => user_or_user_id.to_s }
+        result = get_experiment(experiment_name, user, {})
+        return unless result.in_experiment
+        u = user.transform_keys(&:to_s)
+        payload = JSON.generate({
+          events: [{
+            type: "exposure",
+            experiment: experiment_name.to_s,
+            group: result.group,
+            user_id: (u["user_id"] || u["anonymous_id"]).to_s,
+            ts: (Time.now.to_f * 1000).to_i,
+          }],
+        })
+        Thread.new do
+          post("/collect", payload)
+        rescue => e
+          warn "[shipeasy] log_exposure failed: #{e.message}"
+        end
+      end
       private
+      # Drop caller-marked private attributes from an outbound props bag. Handles
+      # both string and symbol keys against the stringified private list.
+      def strip_private(props)
+        return props if props.nil? || props.empty? || @private_attributes.empty?
+        props.reject { |k, _| @private_attributes.include?(k.to_s) }
+      end
+      # 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 +402,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/openfeature.rb ADDED Viewed

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+# OpenFeature provider for Shipeasy (server paradigm).
+#
+# Lets apps standardized on the CNCF OpenFeature API plug Shipeasy in as the
+# backing provider. This file is intentionally NOT required by the main
+# `shipeasy-sdk` entrypoint — `openfeature-sdk` is an optional development
+# dependency, so the provider is loaded lazily and the gem is required from
+# inside this file. Require it explicitly when you want the provider:
+#
+#   require "open_feature/sdk"
+#   require "shipeasy/sdk/openfeature"
+#
+#   client = Shipeasy::SDK::FlagsClient.new(api_key: ENV.fetch("SHIPEASY_SERVER_KEY"))
+#   client.init
+#
+#   OpenFeature::SDK.configure do |config|
+#     config.set_provider(Shipeasy::OpenFeature::Provider.new(client))
+#   end
+#
+#   of = OpenFeature::SDK.build_client
+#   on = of.fetch_boolean_value(flag_key: "new_checkout", default_value: false,
+#                               evaluation_context: OpenFeature::SDK::EvaluationContext.new(targeting_key: "u1"))
+#
+# Pure adapter over `FlagsClient` — no change to evaluation. Boolean values map
+# onto gates (`get_flag_detail`); string/number/integer/float/object map onto
+# dynamic configs (`get_config`).
+# `openfeature-sdk` (module `OpenFeature::SDK::Provider`) is an optional dep.
+# Require it lazily so the main SDK never pulls it in; surface a clear error if
+# the consumer forgot to add it.
+begin
+  require "open_feature/sdk"
+rescue LoadError => e
+  raise LoadError, "shipeasy/sdk/openfeature requires the `openfeature-sdk` gem " \
+                   "(module OpenFeature::SDK::Provider). Add it to your Gemfile: " \
+                   "gem \"openfeature-sdk\". (#{e.message})"
+end
+require_relative "flags_client"
+module Shipeasy
+  module OpenFeature
+    # Shipeasy OpenFeature provider (server paradigm). Wraps a
+    # `Shipeasy::SDK::FlagsClient`; evaluation is local against the cached blob,
+    # so resolution is effectively synchronous.
+    class Provider
+      OF = ::OpenFeature::SDK::Provider
+      # Shipeasy `FlagDetail#reason` → [OpenFeature reason, optional error_code].
+      # Per the cross-SDK contract (doc 20):
+      #   RULE_MATCH       → TARGETING_MATCH
+      #   DEFAULT          → DEFAULT
+      #   OFF              → DISABLED
+      #   OVERRIDE         → STATIC
+      #   FLAG_NOT_FOUND   → ERROR (error_code FLAG_NOT_FOUND)
+      #   CLIENT_NOT_READY → ERROR (error_code PROVIDER_NOT_READY)
+      REASON_MAP = {
+        Shipeasy::SDK::FlagsClient::REASON_RULE_MATCH       => [OF::Reason::TARGETING_MATCH, nil],
+        Shipeasy::SDK::FlagsClient::REASON_DEFAULT          => [OF::Reason::DEFAULT, nil],
+        Shipeasy::SDK::FlagsClient::REASON_OFF              => [OF::Reason::DISABLED, nil],
+        Shipeasy::SDK::FlagsClient::REASON_OVERRIDE         => [OF::Reason::STATIC, nil],
+        Shipeasy::SDK::FlagsClient::REASON_FLAG_NOT_FOUND   => [OF::Reason::ERROR, OF::ErrorCode::FLAG_NOT_FOUND],
+        Shipeasy::SDK::FlagsClient::REASON_CLIENT_NOT_READY => [OF::Reason::ERROR, OF::ErrorCode::PROVIDER_NOT_READY],
+      }.freeze
+      attr_reader :metadata
+      def initialize(client)
+        @client = client
+        @metadata = OF::ProviderMetadata.new(name: "shipeasy").freeze
+      end
+      # OpenFeature lifecycle (optional but supported): fetch the blob once and
+      # tear down the poll thread on shutdown.
+      def init(_evaluation_context = nil)
+        @client.init_once
+      end
+      def shutdown
+        @client.destroy
+      end
+      # --- Boolean → gate ------------------------------------------------------
+      def fetch_boolean_value(flag_key:, default_value:, evaluation_context: nil)
+        user = to_user(evaluation_context)
+        detail = @client.get_flag_detail(flag_key, user)
+        of_reason, error_code = REASON_MAP.fetch(detail.reason, [OF::Reason::UNKNOWN, nil])
+        if error_code
+          OF::ResolutionDetails.new(value: default_value, reason: of_reason, error_code: error_code)
+        else
+          OF::ResolutionDetails.new(value: detail.value, reason: of_reason)
+        end
+      rescue => e
+        OF::ResolutionDetails.new(
+          value: default_value, reason: OF::Reason::ERROR,
+          error_code: OF::ErrorCode::GENERAL, error_message: e.message,
+        )
+      end
+      # --- String / number / integer / float / object → dynamic config --------
+      def fetch_string_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve_config(flag_key, default_value) { |v| v.is_a?(String) }
+      end
+      def fetch_number_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve_config(flag_key, default_value) { |v| numeric?(v) }
+      end
+      def fetch_integer_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve_config(flag_key, default_value) { |v| v.is_a?(Integer) }
+      end
+      def fetch_float_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve_config(flag_key, default_value) { |v| numeric?(v) }
+      end
+      def fetch_object_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve_config(flag_key, default_value) { |v| v.is_a?(Hash) || v.is_a?(Array) }
+      end
+      # OpenFeature `track()` → Shipeasy `track()`. No-ops without a targeting key.
+      def track(tracking_event_name, evaluation_context: nil, details: {})
+        ctx = normalize_context(evaluation_context)
+        user_id = ctx["targeting_key"] || ctx["user_id"]
+        return if user_id.nil? || user_id.to_s.empty?
+        props = details.is_a?(Hash) ? details : {}
+        @client.track(user_id, tracking_event_name, props)
+      end
+      private
+      # A sentinel distinct from any legitimate config value so we can tell an
+      # absent key (→ DEFAULT) from a present-but-nil value.
+      ABSENT = Object.new
+      private_constant :ABSENT
+      # Resolve a dynamic config and type-check it. Absent key → DEFAULT;
+      # present but failing the type predicate → TYPE_MISMATCH; otherwise
+      # TARGETING_MATCH with the value. Both return the default for the value.
+      def resolve_config(flag_key, default_value)
+        raw = @client.get_config(flag_key, nil, default: ABSENT)
+        if raw.equal?(ABSENT)
+          return OF::ResolutionDetails.new(value: default_value, reason: OF::Reason::DEFAULT)
+        end
+        unless yield(raw)
+          return OF::ResolutionDetails.new(
+            value: default_value, reason: OF::Reason::ERROR,
+            error_code: OF::ErrorCode::TYPE_MISMATCH,
+            error_message: "config value #{raw.inspect} does not match the requested type",
+          )
+        end
+        OF::ResolutionDetails.new(value: raw, reason: OF::Reason::TARGETING_MATCH)
+      rescue => e
+        OF::ResolutionDetails.new(
+          value: default_value, reason: OF::Reason::ERROR,
+          error_code: OF::ErrorCode::GENERAL, error_message: e.message,
+        )
+      end
+      def numeric?(value)
+        # Booleans are Integers' cousins in some langs but not Ruby; exclude
+        # them explicitly so `true` never satisfies a number/float request.
+        return false if value == true || value == false
+        value.is_a?(Numeric)
+      end
+      # Build a Shipeasy user hash from an OpenFeature EvaluationContext:
+      # `targeting_key` → `user_id`; every other field carried through verbatim
+      # for targeting. Accepts a real EvaluationContext, a plain Hash, or nil.
+      def to_user(evaluation_context)
+        ctx = normalize_context(evaluation_context)
+        targeting_key = ctx["targeting_key"]
+        rest = ctx.reject { |k, _| k == "targeting_key" }
+        user = rest
+        if targeting_key.is_a?(String) && !targeting_key.empty?
+          user = user.merge("user_id" => targeting_key)
+        end
+        user
+      end
+      # Coerce any of {EvaluationContext, Hash, nil} into a string-keyed Hash.
+      def normalize_context(evaluation_context)
+        return {} if evaluation_context.nil?
+        if evaluation_context.respond_to?(:fields)
+          evaluation_context.fields.transform_keys(&:to_s)
+        elsif evaluation_context.is_a?(Hash)
+          evaluation_context.transform_keys(&:to_s)
+        else
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/shipeasy/sdk/sticky_store.rb ADDED Viewed

@@ -0,0 +1,39 @@
+require "thread"
+module Shipeasy
+  module SDK
+    # Pluggable sticky-bucketing store for the server (doc 20 §2). Duck-typed:
+    # any object responding to the two methods below works.
+    #
+    #   get(unit) -> { exp_name => { "g" => group, "s" => salt8 } } or nil
+    #   set(unit, exp_name, entry)   # entry = { "g" => group, "s" => salt8 }
+    #
+    # Keyed by the bucketing unit (pick_identifier-resolved id). When threaded
+    # into experiment eval, an enrolled unit locks to its first-assigned variant
+    # — changing allocation % or weights won't re-bucket it; changing the
+    # experiment salt is the reshuffle lever. Absent ⇒ deterministic behavior.
+    class InMemoryStickyStore
+      # Optionally seed with { unit => { exp => { "g"=>.., "s"=>.. } } }.
+      def initialize(seed = nil)
+        @mutex = Mutex.new
+        @data  = {}
+        if seed
+          seed.each { |unit, exps| @data[unit.to_s] = exps.dup }
+        end
+      end
+      # Return this unit's per-experiment assignments, or nil if none.
+      def get(unit)
+        @mutex.synchronize { @data[unit.to_s] }
+      end
+      # Persist one assignment for (unit, exp).
+      def set(unit, exp, entry)
+        @mutex.synchronize do
+          (@data[unit.to_s] ||= {})[exp] = entry
+        end
+        nil
+      end
+    end
+  end
+end

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

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

data/lib/shipeasy-sdk.rb CHANGED Viewed

@@ -2,6 +2,7 @@ require_relative "shipeasy/sdk/version"
 require_relative "shipeasy/config"
 require_relative "shipeasy/sdk/murmur3"
 require_relative "shipeasy/sdk/eval"
+require_relative "shipeasy/sdk/sticky_store"
 require_relative "shipeasy/sdk/flags_client"
 require_relative "shipeasy/sdk/anon_id"
 require_relative "shipeasy/sdk/rack_middleware"

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.5.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
@@ -73,8 +73,10 @@ files:
 - lib/shipeasy/sdk/eval.rb
 - lib/shipeasy/sdk/flags_client.rb
 - lib/shipeasy/sdk/murmur3.rb
+- lib/shipeasy/sdk/openfeature.rb
 - lib/shipeasy/sdk/rack_middleware.rb
 - lib/shipeasy/sdk/railtie.rb
+- lib/shipeasy/sdk/sticky_store.rb
 - lib/shipeasy/sdk/telemetry.rb
 - lib/shipeasy/sdk/version.rb
 homepage: https://github.com/shipeasy-ai/sdk-ruby