shipeasy-sdk 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 434e056f9f0849c73316e812f9ff8918ad838d9161283db0b3a8c9c7450b1077
-  data.tar.gz: beb6a893abc08ec7463a64fb2ec22f7df014f4da147b824a5f7b8d70ed3f34a0
+  metadata.gz: 991e86824a2b5fb735a7d7f53dbff73c635f1a4adb5a3056e3b5c359a164dcbc
+  data.tar.gz: 897872d04e78e03dd76f26b5e82108a5a18ef7eea749cf9657ced843e63843c4
 SHA512:
-  metadata.gz: 17339d55c4ed50599d3cc2cfa04f2f5a53e57a5478fb626bbf999ac6297da3a35a47e9a139150b4cfcce209c6e29f1b033180c9f5cc64923f106f5c1379adff8
-  data.tar.gz: 57fb7a408683111fd2f0aee2b389c97f5de038b22b2b6bbf0ff757c193220740a766951a7cda8baa59c58fc83bc26ea7e1103a07944e9206555a22970d071b19
+  metadata.gz: 540e78bcb95b819ad2a74c8d69387f5ed252b9b6fc9c12ca89f0aa9b1d6ff1653197394721f35931808abb89fa0a4bc002ce7f1c152857e5e80bfd6759bf2c8e
+  data.tar.gz: 36a1275319ef6958380451dd186e0dcd90cbdb04110b0cdf96e59a5e013d8a7a730456672325f9445eae0c4e2ac5f9ace72c936f9d039d9575e0fbd4c5933889

data/lib/shipeasy/admin.rb

@@ -37,23 +37,29 @@ module Shipeasy
   module Admin
     # Programmatic client for the Shipeasy Admin REST API. Each resource group is
     # a lazily-constructed, memoized reader whose methods map 1:1 to the OpenAPI
-    # operations: #gates, #configs, #killswitches, #experiments, #universes,
-    # #metrics, #events, #alert_rules, #attributes, #projects, #ops, #i18n.
+    # operations: #flags, #configs, #killswitch, #experiments, #universes,
+    # #attributes, #metrics, #events, #ops, #alerts, #projects, #profiles, #keys,
+    # #drafts, #errors, #connectors, #api_keys.
     class Client
       # Friendly reader name => generated Api class.
       APIS = {
-        gates: Generated::GatesApi,
+        flags: Generated::FlagsApi,
         configs: Generated::ConfigsApi,
-        killswitches: Generated::KillswitchesApi,
+        killswitch: Generated::KillswitchApi,
         experiments: Generated::ExperimentsApi,
         universes: Generated::UniversesApi,
+        attributes: Generated::AttributesApi,
         metrics: Generated::MetricsApi,
         events: Generated::EventsApi,
-        alert_rules: Generated::AlertRulesApi,
-        attributes: Generated::AttributesApi,
-        projects: Generated::ProjectsApi,
         ops: Generated::OpsApi,
-        i18n: Generated::I18nApi,
+        alerts: Generated::AlertsApi,
+        projects: Generated::ProjectsApi,
+        profiles: Generated::ProfilesApi,
+        keys: Generated::KeysApi,
+        drafts: Generated::DraftsApi,
+        errors: Generated::ErrorsApi,
+        connectors: Generated::ConnectorsApi,
+        api_keys: Generated::APIKeysApi,
       }.freeze
 
       # @param api_key [String] admin SDK key, sent as `Authorization: Bearer <api_key>`.

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.0"
+    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)