shipeasy-sdk 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bacc8b94c722361a53df3156e4dc63159c75b0657e2c1f6ae246593e90cf7c12
-  data.tar.gz: 4450034aaee670f04015f396a960646fff27e5195e13ebd93ace4c032a82f023
+  metadata.gz: ff3dbc0f1f6f19484edafcb75460928392fd43278036b68ed2c8179f9d21ac4d
+  data.tar.gz: 04d7e38426d7be6c00e504749c6a33441d88db79f70e1eae533fa9fc115b94d4
 SHA512:
-  metadata.gz: cff2bbf433472f1e2be585ccbf5deb12d420e29130bb8f09961f2b277135a0c1726c1318a0f1b7b57fce511b114b6fcde982cc0735b884bb946de46016638c52
-  data.tar.gz: 1ff69897f3b0501e6c4e41fa5eb386017fc4d714a0a5423871ec867b969bea2d1097fda01fb3902b1a57bc37a0490aaf433169e9d829f11739f3ac63cbcabb56
+  metadata.gz: 93432ded1ed218653913a2895c0178741c4e4e06671e131722d45672f481d782791243fdc35d16347bd1462b2ea0cc2c8bdacdb7012d983a17f190c208159d9d
+  data.tar.gz: def56c79ef372df20b3a7325e838d8165955c39a2c8221e393546d60b61b9405ee2d5a346e2a467bc771d88c50af8806f116d1bfaac2eaed5db9f2e8f6cbd338

data/lib/shipeasy/sdk/eval.rb

@@ -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

@@ -5,15 +5,25 @@ 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, test_mode: false)
+      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_*.
@@ -228,7 +238,10 @@ module Shipeasy
         @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
@@ -250,13 +263,15 @@ module Shipeasy
       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 }),
           }],
         })
 
@@ -267,8 +282,46 @@ 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.

data/lib/shipeasy/sdk/openfeature.rb

@@ -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

@@ -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

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

data/lib/shipeasy-sdk.rb

@@ -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

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shipeasy-sdk
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Shipeasy, Inc.
@@ -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