shipeasy-sdk 2.3.1 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c724f285483ed9509f862e463c829e8dbba248aa9c7f8affb256d76ce54a7a1
-  data.tar.gz: a021e596201e1492075c1474c5b1a8ce2acb30af7f96120c07fa04cd0ffa0b22
+  metadata.gz: 991e86824a2b5fb735a7d7f53dbff73c635f1a4adb5a3056e3b5c359a164dcbc
+  data.tar.gz: 897872d04e78e03dd76f26b5e82108a5a18ef7eea749cf9657ced843e63843c4
 SHA512:
-  metadata.gz: 6b38d42715ecc331f4efec186c85f22514802790a2aba8671a393ab9fb2f5c2f07121659501182f27fab68b02b0ad464230c69148fca3c7e944b18b3e07d2b21
-  data.tar.gz: 0b05bfd9dd7ab084b5fa40ee5b783395921baf4b3d089c137e42ba91845415a75647ad32c714811a99fa04191270c5d1c6a0f61351d7e1e914e7e70fadc73f16
+  metadata.gz: 540e78bcb95b819ad2a74c8d69387f5ed252b9b6fc9c12ca89f0aa9b1d6ff1653197394721f35931808abb89fa0a4bc002ce7f1c152857e5e80bfd6759bf2c8e
+  data.tar.gz: 36a1275319ef6958380451dd186e0dcd90cbdb04110b0cdf96e59a5e013d8a7a730456672325f9445eae0c4e2ac5f9ace72c936f9d039d9575e0fbd4c5933889

data/lib/shipeasy/client.rb

@@ -34,35 +34,62 @@ module Shipeasy
       @attributes = engine.bind_attributes(mapped)
     end
 
+    # NOTE on fail-safe reads: the engine's runtime methods already never raise
+    # (each is wrapped in Engine#safe_run). The extra defensive rescue here is a
+    # belt-and-braces guard so even an unexpected failure BEFORE the engine call
+    # (e.g. an @attributes deref) still returns the documented safe default
+    # rather than propagating into product code.
+
     def get_flag(name, default: false)
       @engine.get_flag(name, @attributes, default: default)
+    rescue StandardError => e
+      Shipeasy::Logging.error "[shipeasy] Client#get_flag('#{name}') failed — returning default: #{e.message}"
+      default
     end
 
     def get_flag_detail(name)
       @engine.get_flag_detail(name, @attributes)
+    rescue StandardError => e
+      Shipeasy::Logging.error "[shipeasy] Client#get_flag_detail('#{name}') failed — returning safe default: #{e.message}"
+      Shipeasy::Engine::FlagDetail.new(value: false, reason: Shipeasy::Engine::REASON_CLIENT_NOT_READY)
     end
 
     # Configs are not user-scoped, but exposed here for one-stop ergonomics.
     def get_config(name, decode = nil, default: nil)
       @engine.get_config(name, decode, default: default)
+    rescue StandardError => e
+      Shipeasy::Logging.error "[shipeasy] Client#get_config('#{name}') failed — returning default: #{e.message}"
+      default
     end
 
     def get_experiment(name, default_params, decode = nil)
       @engine.get_experiment(name, @attributes, default_params, decode)
+    rescue StandardError => e
+      Shipeasy::Logging.error "[shipeasy] Client#get_experiment('#{name}') failed — returning safe default: #{e.message}"
+      Shipeasy::SDK::Eval::ExperimentResult.new(in_experiment: false, group: "control", params: default_params)
     end
 
     # Killswitches are not user-scoped; forwarded straight to the engine.
     def get_killswitch(name, switch_key = nil)
       @engine.get_killswitch(name, switch_key)
+    rescue StandardError => e
+      Shipeasy::Logging.error "[shipeasy] Client#get_killswitch('#{name}') failed — returning false: #{e.message}"
+      false
     end
 
     def track(event_name, props = {})
       id = @attributes["user_id"] || @attributes["anonymous_id"]
       @engine.track(id, event_name, props)
+    rescue StandardError => e
+      Shipeasy::Logging.error "[shipeasy] Client#track('#{event_name}') failed: #{e.message}"
+      nil
     end
 
     def log_exposure(experiment_name)
       @engine.log_exposure(@attributes, experiment_name)
+    rescue StandardError => e
+      Shipeasy::Logging.error "[shipeasy] Client#log_exposure('#{experiment_name}') failed: #{e.message}"
+      nil
     end
   end
 

data/lib/shipeasy/config.rb

@@ -33,6 +33,14 @@ module Shipeasy
     attr_accessor :env, :disable_telemetry, :telemetry_url,
                   :private_attributes, :sticky_store
 
+    # SDK-wide diagnostic verbosity for the leveled logger (Shipeasy::Logging).
+    # One of :silent, :error, :warn (default), :info, :debug (strings accepted
+    # and downcased; unknown falls back to :warn). Controls the stderr output of
+    # every caught-error diagnostic the SDK emits — the public runtime reads
+    # (get_flag/get_config/…) never raise, so this only tunes how loud they are
+    # about a recovered failure. Threaded into the global Engine by configure.
+    attr_accessor :log_level
+
     # Fetch lifecycle for the global engine `configure` builds:
     #   - init (default true): fire a one-shot fetch fire-and-forget so the first
     #     `Shipeasy::Client.new(user).get_flag(...)` resolves against real rules
@@ -70,6 +78,7 @@ module Shipeasy
       @telemetry_url        = nil
       @private_attributes   = nil
       @sticky_store         = nil
+      @log_level            = :warn
 
       @profile              = "default"
       @default_chunk        = "index"
@@ -147,6 +156,7 @@ module Shipeasy
         telemetry_url:      cfg.telemetry_url,
         private_attributes: cfg.private_attributes,
         sticky_store:       cfg.sticky_store,
+        log_level:          cfg.log_level,
       )
       @engine = engine
       # Capture +engine+ in the closure (not the @engine ivar, which a concurrent
@@ -155,13 +165,13 @@ module Shipeasy
         Thread.new do
           engine.init   # initial fetch + background poll thread
         rescue => e
-          warn "[shipeasy] configure(poll) background poll failed: #{e.message}"
+          Shipeasy::Logging.error "[shipeasy] configure(poll) background poll failed: #{e.message}"
         end
       elsif cfg.init
         Thread.new do
           engine.init_once
         rescue => e
-          warn "[shipeasy] configure() one-shot fetch failed: #{e.message}"
+          Shipeasy::Logging.error "[shipeasy] configure() one-shot fetch failed: #{e.message}"
         end
       end
       engine

data/lib/shipeasy/engine.rb

@@ -3,6 +3,7 @@ require "uri"
 require "json"
 require "thread"
 require "cgi"
+require_relative "logging"
 require_relative "sdk/eval"
 require_relative "sdk/telemetry"
 require_relative "sdk/anon_id"
@@ -33,7 +34,12 @@ module Shipeasy
       # /sdk/i18n/loader.js) — distinct from the edge API the blobs are fetched from.
       DEFAULT_CDN_BASE = "https://cdn.shipeasy.ai"
 
-      def initialize(api_key:, base_url: nil, env: "prod", disable_telemetry: false, telemetry_url: nil, test_mode: false, private_attributes: nil, sticky_store: 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, log_level: nil)
+        # SDK-wide diagnostic verbosity. Set the leveled logger from the passed
+        # level (default :warn; unknown falls back to :warn). The logger is
+        # module-scoped, so the last-built engine wins — mirrors the TS SDK,
+        # where the last configure() sets the level.
+        Shipeasy::Logging.set_level(log_level || Shipeasy::Logging::DEFAULT_LEVEL)
         @api_key     = api_key
         @base_url    = (base_url || DEFAULT_BASE_URL).chomp("/")
         # Read-env tag. Used by telemetry below and stamped onto see() error
@@ -205,6 +211,12 @@ module Shipeasy
       # 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)
+        safe_run("get_flag_detail('#{name}')", FlagDetail.new(value: false, reason: REASON_CLIENT_NOT_READY)) do
+          get_flag_detail_inner(name, user)
+        end
+      end
+
+      def get_flag_detail_inner(name, user)
         key = name.to_s
 
         # 1. Override short-circuits before any telemetry (mirrors get_config).
@@ -233,31 +245,51 @@ module Shipeasy
       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
+        safe_run("get_flag('#{name}')", default) do
+          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
       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
+        safe_run("get_config('#{name}')", default) do
+          key = name.to_s
+          has_override, override = @mutex.synchronize do
+            [@config_overrides.key?(key), @config_overrides[key]]
+          end
+          if has_override
+            begin
+              next(decode ? decode.call(override) : override)
+            rescue => e
+              Shipeasy::Logging.warn "[shipeasy] get_config('#{name}') decode failed: #{e.message}"
+              next default
+            end
+          end
 
-        @telemetry.emit("config", name)
-        entry = @mutex.synchronize { @flags_blob&.dig("configs", name) }
-        return default unless entry
-        value = entry["value"]
-        decode ? decode.call(value) : value
+          @telemetry.emit("config", name)
+          entry = @mutex.synchronize { @flags_blob&.dig("configs", name) }
+          next default unless entry
+          value = entry["value"]
+          begin
+            decode ? decode.call(value) : value
+          rescue => e
+            Shipeasy::Logging.warn "[shipeasy] get_config('#{name}') decode failed: #{e.message}"
+            default
+          end
+        end
       end
 
       def get_experiment(name, user, default_params, decode = nil)
+        safe_run("get_experiment('#{name}')", Eval::ExperimentResult.new(in_experiment: false, group: "control", params: default_params)) do
+          get_experiment_inner(name, user, default_params, decode)
+        end
+      end
+
+      def get_experiment_inner(name, user, default_params, decode = nil)
         key = name.to_s
         override = @mutex.synchronize { @exp_overrides[key] }
         if override
@@ -287,7 +319,7 @@ module Shipeasy
               params: decode.call(result.params),
             )
           rescue => e
-            warn "[shipeasy] get_experiment('#{name}') decode failed: #{e.message}"
+            Shipeasy::Logging.warn "[shipeasy] get_experiment('#{name}') decode failed: #{e.message}"
             return Eval::ExperimentResult.new(in_experiment: false, group: "control", params: default_params)
           end
         end
@@ -309,16 +341,18 @@ module Shipeasy
       # value (so an unconfigured key behaves exactly like the no-key call).
       # Unknown killswitches return false. Not user-scoped.
       def get_killswitch(name, switch_key = nil)
-        @telemetry.emit("ks", name)
-        ks = @mutex.synchronize { @flags_blob&.dig("killswitches", name.to_s) }
-        return false unless ks
-        unless switch_key.nil?
-          switches = ks["switches"] || {}
-          key = switch_key.to_s
-          return Eval.enabled?(switches[key]) if switches.key?(key)
-          # key not configured → fall through to the top-level value
+        safe_run("get_killswitch('#{name}')", false) do
+          @telemetry.emit("ks", name)
+          ks = @mutex.synchronize { @flags_blob&.dig("killswitches", name.to_s) }
+          next false unless ks
+          unless switch_key.nil?
+            switches = ks["switches"] || {}
+            key = switch_key.to_s
+            next Eval.enabled?(switches[key]) if switches.key?(key)
+            # key not configured → fall through to the top-level value
+          end
+          Eval.enabled?(ks["killed"])
         end
-        Eval.enabled?(ks["killed"])
       end
 
       # Batch-evaluate every loaded gate, config and experiment for +user+ into
@@ -387,24 +421,27 @@ 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,
-            **(safe_props.empty? ? {} : { properties: safe_props }),
-          }],
-        })
-
-        Thread.new do
-          post("/collect", payload)
-        rescue => e
-          warn "[shipeasy] track failed: #{e.message}"
+        safe_run("track('#{event_name}')", nil) do
+          next 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,
+              **(safe_props.empty? ? {} : { properties: safe_props }),
+            }],
+          })
+
+          Thread.new do
+            post("/collect", payload)
+          rescue => e
+            Shipeasy::Logging.warn "[shipeasy] track failed: #{e.message}"
+          end
+          nil
         end
       end
 
@@ -415,27 +452,30 @@ module Shipeasy
       # 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,
-          }],
-        })
+        safe_run("log_exposure('#{experiment_name}')", nil) do
+          next 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, {})
+          next 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}"
+          Thread.new do
+            post("/collect", payload)
+          rescue => e
+            Shipeasy::Logging.warn "[shipeasy] log_exposure failed: #{e.message}"
+          end
+          nil
         end
       end
 
@@ -466,6 +506,19 @@ module Shipeasy
 
       private
 
+      # Last-resort guard that makes a public RUNTIME method (get_flag /
+      # get_config / get_experiment / get_killswitch / track / log_exposure)
+      # unable to raise into product code, even if an internal invariant is
+      # violated. Runs the block; on any StandardError it logs at :error and
+      # returns +fallback+ (the method's documented safe default). +label+ names
+      # the method for the log line.
+      def safe_run(label, fallback)
+        yield
+      rescue StandardError => e
+        Shipeasy::Logging.error "[shipeasy] #{label} failed — returning safe default: #{e.message}"
+        fallback
+      end
+
       # Build the wire event and fire-and-forget POST it to /collect. No-op in
       # test mode (mirrors track). Spam-guarded. Never raises into caller code.
       def dispatch_see(built)
@@ -485,10 +538,10 @@ module Shipeasy
         Thread.new do
           post("/collect", payload)
         rescue => e
-          warn "[shipeasy] see() send failed: #{e.message}"
+          Shipeasy::Logging.warn "[shipeasy] see() send failed: #{e.message}"
         end
       rescue => e
-        warn "[shipeasy] see() failed: #{e.message}"
+        Shipeasy::Logging.error "[shipeasy] see() failed: #{e.message}"
       end
 
       # Drop caller-marked private attributes from an outbound props bag. Handles
@@ -519,7 +572,7 @@ module Shipeasy
           begin
             listener.call
           rescue => e
-            warn "[shipeasy] on_change listener raised: #{e.message}"
+            Shipeasy::Logging.warn "[shipeasy] on_change listener raised: #{e.message}"
           end
         end
       end
@@ -557,7 +610,7 @@ module Shipeasy
             begin
               fetch_all
             rescue => e
-              warn "[shipeasy] background poll failed: #{e.message}"
+              Shipeasy::Logging.error "[shipeasy] background poll failed: #{e.message}"
             end
           end
         end

data/lib/shipeasy/logging.rb

@@ -0,0 +1,79 @@
+# Leveled logger shared by the whole gem.
+#
+# Every diagnostic the SDK emits from a *caught* error goes through here, so a
+# single `log_level` config option (default :warn) controls the SDK's stderr
+# output. The contract for the SDK's public RUNTIME methods (get_flag,
+# get_config, get_experiment, get_killswitch, track, log_exposure, see, …) is
+# that they NEVER raise into product code — so logging itself is best-effort
+# too: a broken/throwing $stderr can never take down a flag read.
+#
+# Level ordering (a message at level L is emitted iff the configured level is at
+# least as verbose as L):
+#   silent < error < warn < info < debug
+# :warn (the default) therefore emits `error` + `warn` and suppresses the
+# informational `info` / `debug` chatter.
+
+module Shipeasy
+  module Logging
+    # All accepted levels, in increasing verbosity.
+    LEVELS = %i[silent error warn info debug].freeze
+
+    RANK = { silent: 0, error: 1, warn: 2, info: 3, debug: 4 }.freeze
+
+    DEFAULT_LEVEL = :warn
+
+    class << self
+      # Set the SDK-wide log level. Accepts a symbol or string (case-insensitive);
+      # an unrecognised value falls back to the default :warn so a bad config value
+      # can never silence a genuine error unexpectedly.
+      def set_level(level)
+        @level = normalize(level)
+      end
+
+      # The current SDK-wide log level (defaults to :warn until set).
+      def level
+        @level || DEFAULT_LEVEL
+      end
+
+      # Normalise any input to a known level symbol; unknown → DEFAULT_LEVEL.
+      def normalize(level)
+        sym =
+          case level
+          when Symbol then level.to_s.downcase.to_sym
+          when String then level.downcase.to_sym
+          else nil
+          end
+        RANK.key?(sym) ? sym : DEFAULT_LEVEL
+      end
+
+      def error(msg)
+        emit(:error, msg)
+      end
+
+      def warn(msg)
+        emit(:warn, msg)
+      end
+
+      def info(msg)
+        emit(:info, msg)
+      end
+
+      def debug(msg)
+        emit(:debug, msg)
+      end
+
+      private
+
+      # Gate on the configured level, then write to $stderr exactly as the old
+      # bare `warn "[shipeasy] …"` calls did (Kernel#warn → $stderr). Never
+      # raises: a broken stream is swallowed.
+      def emit(msg_level, msg)
+        return if RANK[level] < RANK[msg_level]
+
+        Kernel.warn(msg)
+      rescue StandardError
+        # logging must never raise into product code
+      end
+    end
+  end
+end

data/lib/shipeasy/sdk/version.rb

@@ -1,5 +1,5 @@
 module Shipeasy
   module SDK
-    VERSION = "2.3.1"
+    VERSION = "2.4.0"
   end
 end

data/lib/shipeasy-sdk.rb

@@ -1,4 +1,5 @@
 require_relative "shipeasy/sdk/version"
+require_relative "shipeasy/logging"
 require_relative "shipeasy/config"
 require_relative "shipeasy/sdk/murmur3"
 require_relative "shipeasy/sdk/eval"
@@ -54,7 +55,7 @@ module Shipeasy
     def self.see(problem)
       client = default_client
       if client.nil?
-        warn "[shipeasy] see() called before a client was created — error dropped"
+        Shipeasy::Logging.warn "[shipeasy] see() called before a client was created — error dropped"
         return See::NullChain.new
       end
       client.see(problem)
@@ -64,7 +65,7 @@ module Shipeasy
     def self.see_violation(name)
       client = default_client
       if client.nil?
-        warn "[shipeasy] see_violation() called before a client was created — error dropped"
+        Shipeasy::Logging.warn "[shipeasy] see_violation() called before a client was created — error dropped"
         return See::NullChain.new
       end
       client.see_violation(name)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shipeasy-sdk
 version: !ruby/object:Gem::Version
-  version: 2.3.1
+  version: 2.4.0
 platform: ruby
 authors:
 - Shipeasy, Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-29 00:00:00.000000000 Z
+date: 2026-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -140,6 +140,7 @@ files:
 - lib/shipeasy/i18n/label_fetcher.rb
 - lib/shipeasy/i18n/railtie.rb
 - lib/shipeasy/i18n/view_helpers.rb
+- lib/shipeasy/logging.rb
 - lib/shipeasy/sdk/anon_id.rb
 - lib/shipeasy/sdk/eval.rb
 - lib/shipeasy/sdk/murmur3.rb