shipeasy-sdk 3.4.0 → 3.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1b1f478bea3279f979e85e04476381f719d3db27aa29ffb23447768ceefc560
-  data.tar.gz: c0d4f8f1ca49a6a1b34ac3b1198a3788dc115f640eb5845fb388a66175e1384c
+  metadata.gz: 936c7071cc2d4302c9523145eaa5ee80b184167bea8047ee7be9f539d2a3538e
+  data.tar.gz: ae302e9e648ed16fcf4687ad90668779434a9fda602266e0a4d7fc6a319bda81
 SHA512:
-  metadata.gz: 94790b0a88b1524f35faf706245339db83908565b5adec3a7f8b9f5775d476cb703ce00ac55a697d79a343a1abe0c94145c2fd693538c1aecbdab81385525148
-  data.tar.gz: f35b460dd560167674a1a278c1e76600fd59040016ad06b3129ee77c5dd95d68d57d0c7695ca06dee7f7870f15489655ee20ca644b6d1a24d416fdf280c2daf7
+  metadata.gz: eab22b5a957b8be557fd605f3e19024872217179b43d27d1356caec5f1c6829f2049a6ca4663bf53f58ff31dfc92bdacdbf183655b160fc653aa74d916d81304
+  data.tar.gz: 3a79b37580852b152b783dc3265232ebd123aac3176ea82b8d5a3acdd3c1285ff2163d2b682180f20005ccf0d702d862b2c7bf1cc5c6a4dcc3ac739613d527ff

data/docs/skill/SKILL.md

@@ -155,6 +155,7 @@ the loader tag (public client key).
 - Anon bucketing: `Shipeasy::SDK::RackMiddleware` mints the shared `__se_anon_id`
   cookie (Rails Railtie auto-mounts it); anonymous `get_flag` then just works.
 - `c.private_attributes = ["email"]` strips keys from outbound events.
+- `c.clean_backtrace` (default on) filters `see()` stacks to app frames via `Rails.backtrace_cleaner`; set `false` for raw backtraces.
 - `c.sticky_store = Shipeasy::SDK::InMemoryStickyStore.new` pins experiment assignment.
 - SSR: `Shipeasy.bootstrap_script_tag(user)` + `Shipeasy.i18n_script_tag(client_key, "en:prod")`.
 - `Shipeasy.on_change { ... }` (requires `c.poll = true`) fires after a poll fetches new data.

data/lib/shipeasy/config.rb

@@ -46,9 +46,14 @@ module Shipeasy
     #     swallows one of its OWN internal errors it normally ships a structured
     #     see event to Shipeasy's own project (NOT yours) so the SDK team can
     #     track SDK bugs; set true to disable that entirely.
+    #   - clean_backtrace (default true): pass see() error backtraces through the
+    #     host framework's own backtrace cleaner so reports carry only your
+    #     application frames (gem/framework noise stripped). We do not invent the
+    #     filtering rules — this leverages `Rails.backtrace_cleaner` and is a
+    #     no-op outside Rails. Set false to always report the raw backtrace.
     attr_accessor :env, :is_network_enabled, :disable_telemetry, :telemetry_url,
                   :private_attributes, :sticky_store,
-                  :disable_internal_error_reporting
+                  :disable_internal_error_reporting, :clean_backtrace
 
     # SDK-wide diagnostic verbosity for the leveled logger (Shipeasy::Logging).
     # One of :silent, :error, :warn (default), :info, :debug (strings accepted
@@ -103,6 +108,7 @@ module Shipeasy
       @is_network_enabled   = nil
       @disable_telemetry    = nil
       @disable_internal_error_reporting = false
+      @clean_backtrace      = true
       @telemetry_url        = nil
       @private_attributes   = nil
       @sticky_store         = nil
@@ -197,6 +203,7 @@ module Shipeasy
         sticky_store:       cfg.sticky_store,
         log_level:          cfg.log_level,
         disable_internal_error_reporting: cfg.disable_internal_error_reporting,
+        clean_backtrace:    cfg.clean_backtrace,
       )
       @engine = engine
       # Capture +engine+ in the closure (not the @engine ivar, which a concurrent

data/lib/shipeasy/engine.rb

@@ -36,7 +36,7 @@ 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", is_network_enabled: nil, disable_telemetry: nil, telemetry_url: nil, test_mode: false, private_attributes: nil, sticky_store: nil, log_level: nil, disable_internal_error_reporting: false)
+      def initialize(api_key:, base_url: nil, env: "prod", is_network_enabled: nil, disable_telemetry: nil, telemetry_url: nil, test_mode: false, private_attributes: nil, sticky_store: nil, log_level: nil, disable_internal_error_reporting: false, clean_backtrace: true)
         # 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,
@@ -52,6 +52,13 @@ module Shipeasy
         # 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)
+        # When true (default), see() error stacks are passed through the host
+        # framework's own backtrace cleaner so a report carries only application
+        # frames (gem/framework noise stripped). We never invent the filtering —
+        # today this leverages Rails.backtrace_cleaner and is a no-op outside
+        # Rails. Set false to always send the raw backtrace. See
+        # see_backtrace_cleaner.
+        @clean_backtrace = clean_backtrace != false
         # Pluggable sticky-bucketing store (doc 20 §2). Absent ⇒ deterministic.
         # Threaded into experiment eval so an enrolled unit locks to its first
         # assigned variant. Built-in: InMemoryStickyStore.
@@ -645,6 +652,7 @@ module Shipeasy
           strip_private(built.extras),
           sdk_version: Shipeasy::SDK::VERSION,
           env: @env,
+          backtrace_cleaner: see_backtrace_cleaner,
         )
         return unless @see_limiter.should_send?(ev)
 
@@ -658,6 +666,26 @@ module Shipeasy
         Shipeasy::Logging.error "[shipeasy] see() failed: #{e.message}"
       end
 
+      # The framework-provided backtrace cleaner used to strip gem/framework
+      # frames from see() stacks, or nil to send the raw backtrace. Resolved
+      # lazily (not memoized) because Rails installs its cleaner during boot,
+      # which can finish after Shipeasy.configure runs. Today the only supported
+      # cleaner is Rails' own `ActiveSupport::BacktraceCleaner` — we leverage it
+      # rather than reimplementing the app-vs-gem frame rules ourselves. Returns
+      # nil when disabled or when not running under Rails.
+      def see_backtrace_cleaner
+        return nil unless @clean_backtrace
+        return nil unless defined?(::Rails) && ::Rails.respond_to?(:backtrace_cleaner)
+
+        cleaner = ::Rails.backtrace_cleaner
+        return nil unless cleaner.respond_to?(:clean)
+
+        ->(bt) { cleaner.clean(bt) }
+      rescue StandardError
+        # Rails present but the cleaner blew up while resolving: fall back to raw.
+        nil
+      end
+
       # 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)

data/lib/shipeasy/sdk/eval.rb

@@ -70,10 +70,102 @@ module Shipeasy
         user["user_id"] || user[:user_id] || user["anonymous_id"] || user[:anonymous_id]
       end
 
+      def self.clamp_pct(n)
+        return 0 if n < 0
+        return 10000 if n > 10000
+        n
+      end
+
+      # Effective rollout % for a stack entry at time +now+ (epoch ms). A
+      # condition with no explicit rolloutPct defaults to 100% (match => pass); a
+      # rollout to 0%. A ramp linearly interpolates from=>to over
+      # [startAt, startAt + durationMs] via truncating-toward-zero division — the
+      # cross-SDK contract (experiment-platform/04-evaluation.md). Mirrors core's
+      # effectivePct.
+      def self.effective_pct(entry, now)
+        type = entry["type"] || entry[:type]
+        raw  = entry["rolloutPct"] || entry[:rolloutPct]
+        base = raw.nil? ? (type == "condition" ? 10000 : 0) : raw
+        ramp = entry["ramp"] || entry[:ramp]
+        return base unless ramp
+
+        from      = ramp["from"] || ramp[:from]
+        to        = ramp["to"] || ramp[:to]
+        start_at  = ramp["startAt"] || ramp[:startAt]
+        duration  = ramp["durationMs"] || ramp[:durationMs]
+        return from if now <= start_at
+        return to if now >= start_at + duration
+
+        delta   = to - from # signed
+        elapsed = now - start_at
+        # .to_i on the float quotient truncates toward zero (works for a negative
+        # ramp-down delta, unlike Ruby's floor-division integer `/`).
+        clamp_pct(from + (delta * elapsed).fdiv(duration).to_i)
+      end
+
+      # Hash the caller into [0, 10000) and test against +pct+. No-unit contract
+      # (experiment-platform/18): a fully-rolled bucket is on for everyone without
+      # a unit id; a fractional one needs a stable unit, so it is off. Mirrors
+      # core's bucketHit.
+      def self.bucket_hit(pct, uid, salt)
+        return false if pct <= 0
+        return pct >= 10000 if uid.nil? || uid.to_s.empty?
+        return true if pct >= 10000
+        murmur3("#{salt}:#{uid}") % 10000 < pct
+      end
+
+      # Evaluate one gatekeeper stack entry. A `condition` gates on its rules
+      # (pass: "all" | "any") then buckets at its own rollout % (default 100%); a
+      # `rollout` buckets everyone who reached it (default 0%). A condition's
+      # default bucketing salt is its own id so each step buckets independently;
+      # a rollout falls back to the gate salt so existing entries don't re-bucket.
+      # Mirrors core's evalStackEntry.
+      def self.eval_stack_entry(entry, user, fallback_salt, now)
+        type = entry["type"] || entry[:type]
+        bucket_by = entry["bucketBy"] || entry[:bucketBy]
+        entry_salt = entry["salt"] || entry[:salt]
+
+        if type == "condition"
+          rules = entry["rules"] || entry[:rules] || []
+          return false if rules.empty?
+
+          mode = entry["pass"] || entry[:pass] || "all"
+          matched =
+            if mode == "any"
+              rules.any? { |r| match_rule(r, user) }
+            else
+              rules.all? { |r| match_rule(r, user) }
+            end
+          return false unless matched
+
+          salt = (entry_salt && !entry_salt.to_s.empty?) ? entry_salt : (entry["id"] || entry[:id] || fallback_salt)
+          bucket_hit(effective_pct(entry, now), pick_identifier(user, bucket_by), salt)
+        else
+          salt = (entry_salt && !entry_salt.to_s.empty?) ? entry_salt : fallback_salt
+          bucket_hit(effective_pct(entry, now), pick_identifier(user, bucket_by), salt)
+        end
+      end
+
       def self.eval_gate(gate, user)
         return false if enabled?(gate["killswitch"])
         return false unless enabled?(gate["enabled"])
 
+        # Modern gatekeepers ship an ordered `stack`; evaluate it top-to-bottom and
+        # pass on the first entry whose rules match AND whose bucket hits. This is
+        # the canonical model — the flat `rules`/`rolloutPct` below are a lossy
+        # approximation (a whitelist condition at 100% collapses to `rolloutPct: 0`
+        # once the public rollout is 0%, which the flat path would wrongly read as
+        # "never"). Mirrors @shipeasy/core evalGatekeeper — keep the two in sync.
+        stack = gate["stack"] || gate[:stack]
+        if stack.is_a?(Array) && !stack.empty?
+          now = (Time.now.to_f * 1000).to_i
+          gate_salt = gate["salt"] || gate[:salt]
+          stack.each do |entry|
+            return true if eval_stack_entry(entry, user, gate_salt, now)
+          end
+          return false
+        end
+
         (gate["rules"] || []).each do |rule|
           return false unless match_rule(rule, user)
         end

data/lib/shipeasy/sdk/see.rb

@@ -121,7 +121,15 @@ module Shipeasy
       # ---- Wire event construction ----
 
       # Build the type:"error" event accepted by POST /collect.
-      def build_event(problem, subject, outcome, extras, sdk_version:, env:)
+      #
+      # `backtrace_cleaner` (optional) is a callable that takes the raw backtrace
+      # array and returns an application-only subset (framework/gem frames
+      # stripped) — e.g. `->(bt) { Rails.backtrace_cleaner.clean(bt) }`. It is
+      # applied before the stack is joined; if it strips every frame (a stack
+      # that is purely framework/gem code) we fall back to the raw backtrace so
+      # an error is never left with an empty stack. We never invent the filtering
+      # rules — the callable is supplied by the framework's own cleaner.
+      def build_event(problem, subject, outcome, extras, sdk_version:, env:, backtrace_cleaner: nil)
         stack = nil
 
         if problem.is_a?(Violation)
@@ -131,7 +139,7 @@ module Shipeasy
         elsif problem.is_a?(Exception)
           error_type = problem.class.name || "Error"
           message    = (problem.message.to_s.empty? ? error_type : problem.message)
-          bt = problem.backtrace
+          bt = clean_backtrace(problem.backtrace, backtrace_cleaner)
           stack = bt.join("\n") if bt && !bt.empty?
           kind = "caught"
         else
@@ -158,6 +166,21 @@ module Shipeasy
         ev
       end
 
+      # Apply the framework-provided backtrace cleaner to a raw backtrace,
+      # returning an application-only frame array. No cleaner (or no backtrace)
+      # ⇒ the input is returned untouched. If the cleaner raises, or strips every
+      # frame, fall back to the raw backtrace — a cleaned-to-empty stack would
+      # lose all debugging signal for an error that lives entirely in framework
+      # code. Never raises.
+      def clean_backtrace(bt, cleaner)
+        return bt if cleaner.nil? || bt.nil? || bt.empty?
+
+        cleaned = cleaner.call(bt)
+        cleaned && !cleaned.empty? ? cleaned : bt
+      rescue StandardError
+        bt
+      end
+
       # ---- Spam limiter (mirror SeeLimiter) ----
 
       # Per-process spam guard: identical events within 30s collapse to one

data/lib/shipeasy/sdk/version.rb

@@ -1,5 +1,5 @@
 module Shipeasy
   module SDK
-    VERSION = "3.4.0"
+    VERSION = "3.5.1"
   end
 end

metadata

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