shipeasy-sdk 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff3dbc0f1f6f19484edafcb75460928392fd43278036b68ed2c8179f9d21ac4d
-  data.tar.gz: 04d7e38426d7be6c00e504749c6a33441d88db79f70e1eae533fa9fc115b94d4
+  metadata.gz: 73c3a9cf2fd1a6fb0a223b9db5bcbe13cd828bfd96a4e901de545ff56d254ce7
+  data.tar.gz: '0489c3e16d16592b1301e888c82fa1d5947c21c08c74adbd9eacb6db86420138'
 SHA512:
-  metadata.gz: 93432ded1ed218653913a2895c0178741c4e4e06671e131722d45672f481d782791243fdc35d16347bd1462b2ea0cc2c8bdacdb7012d983a17f190c208159d9d
-  data.tar.gz: def56c79ef372df20b3a7325e838d8165955c39a2c8221e393546d60b61b9405ee2d5a346e2a467bc771d88c50af8806f116d1bfaac2eaed5db9f2e8f6cbd338
+  metadata.gz: 9f2a91c5482d5eb3baf71e744116b7295ad50b19cea9a96c2ce6b6faa01467a38ca4db91f449ae773de76144156eaeec14052d14d12f3c68a3dc521fa1c6813b
+  data.tar.gz: b8e2512bbc85e404fa4528c411700bff22e7eea40f20be2d6392bd7f59166eb65464cfe17760f8b7a2f56c0eb2c7ca15a42fbc579c0937f04ce61c402824a862

data/lib/shipeasy/sdk/flags_client.rb

@@ -6,6 +6,7 @@ require_relative "eval"
 require_relative "telemetry"
 require_relative "anon_id"
 require_relative "sticky_store"
+require_relative "see"
 
 module Shipeasy
   module SDK
@@ -15,6 +16,9 @@ module Shipeasy
       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("/")
+        # Read-env tag. Used by telemetry below and stamped onto see() error
+        # events so reports are attributable to an environment.
+        @env         = env
         # 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
@@ -55,6 +59,13 @@ module Shipeasy
         # (HTTP 200, not 304). Never fired in test/offline mode. Guarded by
         # @mutex; see on_change / notify_change.
         @change_listeners = []
+        # see() structured error reporting. Per-process spam guard, bound here so
+        # repeated reports of the same issue collapse to one send. See see.rb.
+        @see_limiter = See::Limiter.new
+        # Register as the default client backing the module-level Shipeasy::SDK
+        # .see/.see_violation funcs (last constructed wins — the server-SDK
+        # analog of TS's shipeasy({key}) configure call).
+        Shipeasy::SDK.set_default_client(self)
       end
 
       # Build a no-network, immediately-usable client for tests. Telemetry is
@@ -313,8 +324,58 @@ module Shipeasy
         end
       end
 
+      # ---- see() structured error reporting -------------------------------
+
+      # Report a caught exception (or thrown non-exception). Fire-and-forget;
+      # never blocks or throws into the request path. Terminate with
+      # `.to(outcome)`:
+      #
+      #   client.see(e).causes_the("checkout").to("use cached prices")
+      def see(problem)
+        See::Chain.new(problem, method(:dispatch_see))
+      end
+
+      # Report a non-exception problem. The name is a stable fingerprint key —
+      # put variable data in `.extras`, never in the name.
+      def see_violation(name)
+        See::Chain.new(See::Violation.new(name), method(:dispatch_see))
+      end
+      alias seeViolation see_violation
+
+      # Mark an exception as expected control flow — reports nothing. Returns a
+      # `.because(reason)` tail (with optional `.extras` for local debug only).
+      def control_flow_exception(err)
+        See::ControlFlowChain.new(err)
+      end
+      alias controlFlowException control_flow_exception
+
       private
 
+      # 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)
+        return if @test_mode
+
+        ev = See.build_event(
+          built.problem,
+          built.subject,
+          built.outcome,
+          strip_private(built.extras),
+          sdk_version: Shipeasy::SDK::VERSION,
+          env: @env,
+        )
+        return unless @see_limiter.should_send?(ev)
+
+        payload = JSON.generate({ events: [ev] })
+        Thread.new do
+          post("/collect", payload)
+        rescue => e
+          warn "[shipeasy] see() send failed: #{e.message}"
+        end
+      rescue => e
+        warn "[shipeasy] see() failed: #{e.message}"
+      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/see.rb

@@ -0,0 +1,284 @@
+# see — shipeasy error. Structured error reporting for the server SDK.
+#
+# Mirrors `@shipeasy/sdk` (packages/ts-sdk/src/see/core.ts) and the Python
+# reference (packages/server-sdks/sdk-python/shipeasy/_see.py). Every handled
+# exception documents its product *consequence*, not just its stack:
+#
+#   begin
+#     charge_card(order)
+#   rescue => e
+#     Shipeasy::SDK.see(e).causes_the("checkout").to("use the backup processor")
+#   end
+#
+# Dispatch model (differs from TS, which uses a microtask): `.to(outcome)` is
+# the terminal — it builds the wire event and fire-and-forgets the POST to
+# /collect. `causes_the` and `extras` are chainable setters that may be called
+# in any order *before* `.to`:
+#
+#   client.see(e).causes_the("checkout").to("use cached prices")
+#   client.see(e).causes_the("checkout").extras({ order_id: oid }).to("use cached prices")
+#
+# If you don't know the consequence of an exception, don't catch it.
+
+require "thread"
+require "json"
+require_relative "version"
+
+module Shipeasy
+  module SDK
+    module See
+      # ---- Limits (mirror core.ts; kept in sync with the worker's /collect) ----
+      SEE_MAX_MESSAGE     = 500
+      SEE_MAX_STACK       = 8000
+      SEE_MAX_SUBJECT     = 200 # used for subject, outcome, error_type
+      SEE_MAX_EXTRA_VALUE = 200
+      SEE_MAX_EXTRA_KEYS  = 20
+      SEE_DEDUP_WINDOW_MS = 30_000
+      SEE_MAX_PER_PROCESS = 25
+
+      # Default consequence parts when a chain omits them.
+      DEFAULT_SUBJECT = "app".freeze
+      DEFAULT_OUTCOME = "hit an error".freeze
+
+      # Marker attribute stamped onto an exception by control_flow_exception().
+      EXPECTED_IVAR = :@__shipeasy_see_expected
+
+      module_function
+
+      def truncate(str, limit)
+        s = str.to_s
+        s.length <= limit ? s : s[0, limit]
+      end
+
+      # Drop nil values, keep only String/Numeric(finite)/boolean, truncate
+      # string values to 200 chars, cap at 20 keys (insertion order). Returns
+      # nil if nothing is kept. Keys are stringified.
+      def sanitize_extras(extras)
+        return nil unless extras.is_a?(Hash)
+        return nil if extras.empty?
+
+        out = {}
+        extras.each do |k, v|
+          break if out.size >= SEE_MAX_EXTRA_KEYS
+          next if v.nil?
+
+          case v
+          when true, false
+            out[k.to_s] = v
+          when String
+            out[k.to_s] = truncate(v, SEE_MAX_EXTRA_VALUE)
+          when Numeric
+            # Reject NaN / Infinity (not representable in JSON).
+            next if v.respond_to?(:finite?) && !v.finite?
+
+            out[k.to_s] = v
+          else
+            next
+          end
+        end
+        out.empty? ? nil : out
+      end
+
+      # Best-effort stamp marking an exception as expected control flow.
+      def mark_expected(err, because, extras = nil)
+        mark = { "because" => because.to_s }
+        clean = sanitize_extras(extras)
+        mark["extras"] = clean if clean
+        err.instance_variable_set(EXPECTED_IVAR, mark)
+      rescue StandardError
+        # Frozen / builtin objects that reject ivars: best effort only.
+        nil
+      end
+
+      def expected?(err)
+        err.instance_variable_defined?(EXPECTED_IVAR) &&
+          !err.instance_variable_get(EXPECTED_IVAR).nil?
+      rescue StandardError
+        false
+      end
+
+      # A non-exception problem. The name is a stable fingerprint key — put
+      # variable data in `.extras`, never in the name.
+      class Violation
+        attr_reader :name
+
+        def initialize(name)
+          @name = name.to_s
+        end
+      end
+
+      # ---- Wire event construction ----
+
+      # Build the type:"error" event accepted by POST /collect.
+      def build_event(problem, subject, outcome, extras, sdk_version:, env:)
+        stack = nil
+
+        if problem.is_a?(Violation)
+          error_type = problem.name
+          message    = problem.name
+          kind       = "violation"
+        elsif problem.is_a?(Exception)
+          error_type = problem.class.name || "Error"
+          message    = (problem.message.to_s.empty? ? error_type : problem.message)
+          bt = problem.backtrace
+          stack = bt.join("\n") if bt && !bt.empty?
+          kind = "caught"
+        else
+          error_type = "Error"
+          message    = problem.to_s
+          kind       = "caught"
+        end
+
+        ev = {
+          "type"        => "error",
+          "kind"        => kind,
+          "error_type"  => truncate(error_type, SEE_MAX_SUBJECT),
+          "message"     => truncate(message, SEE_MAX_MESSAGE),
+          "subject"     => truncate(subject, SEE_MAX_SUBJECT),
+          "outcome"     => truncate(outcome, SEE_MAX_SUBJECT),
+          "side"        => "server",
+          "sdk_version" => sdk_version,
+          "ts"          => (Time.now.to_f * 1000).to_i,
+        }
+        ev["stack"] = truncate(stack, SEE_MAX_STACK) if stack
+        clean = sanitize_extras(extras)
+        ev["extras"] = clean if clean
+        ev["env"] = env if env && !env.to_s.empty?
+        ev
+      end
+
+      # ---- Spam limiter (mirror SeeLimiter) ----
+
+      # Per-process spam guard: identical events within 30s collapse to one
+      # send; a hard cap bounds total sends. Thread-safe. The worker dedupes by
+      # fingerprint anyway — this only bounds network chatter from a hot loop.
+      class Limiter
+        def initialize(max_per_process: SEE_MAX_PER_PROCESS, dedup_window_ms: SEE_DEDUP_WINDOW_MS)
+          @max    = max_per_process
+          @window = dedup_window_ms
+          @last   = {}
+          @sent   = 0
+          @mutex  = Mutex.new
+        end
+
+        def should_send?(ev)
+          @mutex.synchronize do
+            return false if @sent >= @max
+
+            key = [
+              ev["kind"],
+              ev["error_type"],
+              ev["message"].to_s[0, 200],
+              See.top_stack_line(ev["stack"]),
+            ].join("|")
+            now = (Time.now.to_f * 1000).to_i
+            prev = @last[key]
+            return false if prev && (now - prev) < @window
+
+            @last[key] = now
+            @sent += 1
+            true
+          end
+        end
+      end
+
+      def top_stack_line(stack)
+        return "" if stack.nil? || stack.empty?
+
+        stack.each_line do |line|
+          s = line.strip
+          return s[0, 200] if s.start_with?("File ") || s.start_with?("at ") || s.include?("line ") || s.include?(":in ")
+        end
+        ""
+      end
+
+      # ---- Fluent chains ----
+
+      # Accumulates consequence + extras; `.to(outcome)` dispatches once.
+      class Chain
+        def initialize(problem, dispatch)
+          @problem  = problem
+          @dispatch = dispatch
+          @subject  = nil
+          @outcome  = nil
+          @extras   = nil
+          @done     = false
+        end
+
+        def causes_the(subject)
+          @subject = subject.to_s
+          self
+        end
+        alias causesThe causes_the
+
+        def extras(extras)
+          if extras.is_a?(Hash) && !extras.empty?
+            @extras = (@extras || {}).merge(extras)
+          end
+          self
+        end
+
+        # Terminal: build the event and fire-and-forget the report. Idempotent.
+        def to(outcome)
+          return if @done
+
+          @done = true
+          @outcome = outcome.to_s
+          begin
+            @dispatch.call(
+              Built.new(@problem, @subject || DEFAULT_SUBJECT, @outcome.empty? ? DEFAULT_OUTCOME : @outcome, @extras)
+            )
+          rescue StandardError
+            # Reporting must never raise into caller code.
+            nil
+          end
+        end
+      end
+
+      # Plain carrier of a finalized chain handed to the client dispatcher.
+      Built = Struct.new(:problem, :subject, :outcome, :extras)
+
+      # `control_flow_exception(e).because("because ...")` — marks the exception
+      # expected and reports NOTHING. `.extras` is stored for local debugging
+      # only (an expected exception is never transmitted).
+      class ControlFlowChain
+        def initialize(err)
+          @err = err
+        end
+
+        def because(reason)
+          See.mark_expected(@err, reason)
+          ControlFlowTail.new(@err, reason)
+        end
+      end
+
+      class ControlFlowTail
+        def initialize(err, reason)
+          @err = err
+          @reason = reason
+        end
+
+        def extras(extras)
+          See.mark_expected(@err, @reason, extras)
+          self
+        end
+      end
+
+      # A no-op chain returned by the module-level see() when no client exists.
+      class NullChain
+        def causes_the(_subject)
+          self
+        end
+        alias causesThe causes_the
+
+        def extras(_extras)
+          self
+        end
+
+        def to(_outcome)
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/shipeasy/sdk/version.rb

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

data/lib/shipeasy-sdk.rb

@@ -25,5 +25,54 @@ module Shipeasy
     def self.new_client(api_key: Shipeasy.config.api_key, base_url: Shipeasy.config.base_url)
       FlagsClient.new(api_key: api_key, base_url: base_url)
     end
+
+    # ---- see() module-level facade --------------------------------------
+    #
+    # Backed by a default client, registered when a FlagsClient is constructed
+    # (last constructed wins). Mirrors the package-level see() in the TS/Python
+    # SDKs so callers can `Shipeasy::SDK.see(e).causes_the(...).to(...)` without
+    # threading a client reference through every call site. A call before any
+    # client exists warns and returns a no-op chain (NEVER raises).
+
+    @see_default_client = nil
+    @see_default_mutex  = Mutex.new
+
+    # Register the client backing the module-level see() funcs. Called
+    # automatically from FlagsClient#initialize; also exposed for explicit use.
+    def self.set_default_client(client)
+      @see_default_mutex.synchronize { @see_default_client = client }
+      client
+    end
+
+    def self.default_client
+      @see_default_mutex.synchronize { @see_default_client }
+    end
+
+    # Report a caught exception via the default client. Use client.see to
+    # target a specific client.
+    def self.see(problem)
+      client = default_client
+      if client.nil?
+        warn "[shipeasy] see() called before a client was created — error dropped"
+        return See::NullChain.new
+      end
+      client.see(problem)
+    end
+
+    # Report a non-exception problem via the default client.
+    def self.see_violation(name)
+      client = default_client
+      if client.nil?
+        warn "[shipeasy] see_violation() called before a client was created — error dropped"
+        return See::NullChain.new
+      end
+      client.see_violation(name)
+    end
+
+    # Mark an exception as expected control flow (reports nothing). Works
+    # without a client — it only stamps the exception object.
+    def self.control_flow_exception(err)
+      See::ControlFlowChain.new(err)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shipeasy-sdk
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Shipeasy, Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-19 00:00:00.000000000 Z
+date: 2026-06-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -76,6 +76,7 @@ files:
 - lib/shipeasy/sdk/openfeature.rb
 - lib/shipeasy/sdk/rack_middleware.rb
 - lib/shipeasy/sdk/railtie.rb
+- lib/shipeasy/sdk/see.rb
 - lib/shipeasy/sdk/sticky_store.rb
 - lib/shipeasy/sdk/telemetry.rb
 - lib/shipeasy/sdk/version.rb