shipeasy-sdk 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a34364fd54857fe0b04997063d9d2bbb6296e281a3db8b7389efd84c5f1b4a1
-  data.tar.gz: bb1c68285633d2f1a5709286197b9a0aacaf7c78d950908e414f3fde64f44144
+  metadata.gz: 49743db7faf0600dcc8a7cacb3f7a6fc7418c4d3d125efa6fdd1067b24fe4d16
+  data.tar.gz: 031b3acc69308ce512fb67c073b1f7f1894e276e17ab23f5ff3495678c2dab99
 SHA512:
-  metadata.gz: f4f9a1149dabefce47743afb04bec2e3f3e6dceac88c9e1a48a2cdb187b87bce0c5c9853cc68afe3f64f7a521fe8dcb4d5017c679ea362f19f8b598d71b3dbcb
-  data.tar.gz: b82a76824d4d0a90cc481453c5036a53cdb1adb30e74630ac843c6d6582fa294391e440b0d29b044eebf25071eb264bbab3a74491fac3939a815064ca1fd0f92
+  metadata.gz: 479ca3e747f954922315f6bb062b385ba8e7710ac37799d7a732f8da63de87321d5c497b8ee3cc605cb80c66bd9f4ebbceea6acc9486ff7d37d8f0b9c153f628
+  data.tar.gz: 1f9a70f2ccff8c6fcaeb5a9e913657fb88ceac7c37505f21d409880740d1d7af4b952732a3607ee94908a1e8c1921d23e9997852c3622e8a315ab1168a2c2def

data/lib/shipeasy/config.rb

@@ -25,7 +25,18 @@ module Shipeasy
     # Advanced `configure` options — threaded into the global Engine `configure`
     # builds, so callers never construct an Engine themselves:
     #   - env (default "prod"): deployment tag on see() events + usage telemetry.
-    #   - disable_telemetry (default false): opt out of per-eval usage telemetry.
+    #   - is_network_enabled (default: environment-derived): master switch for ALL
+    #     outbound requests (flag/experiment/config fetch, track, exposure logging,
+    #     see() reports, AND telemetry). Defaults ON in production and OFF in every
+    #     other environment, so a dev machine / CI run stays fully offline unless
+    #     you opt in. Explicit true/false always overrides. "Production" is decided
+    #     from SHIPEASY_ENV / RAILS_ENV / RACK_ENV / APP_ENV, then the `env` tag
+    #     (see sdk/env.rb). When off, reads answer from overrides / in-code
+    #     defaults and nothing is sent.
+    #   - disable_telemetry (default: environment-derived — off in prod, i.e.
+    #     telemetry ON in prod / OFF outside prod): opt out of per-eval usage
+    #     telemetry. Explicit true/false overrides; forced off when the network is
+    #     disabled.
     #   - telemetry_url: override the telemetry endpoint (rarely needed).
     #   - private_attributes: attribute keys stripped from every outbound event
     #     before it leaves the process (they still drive targeting locally).
@@ -35,7 +46,7 @@ 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.
-    attr_accessor :env, :disable_telemetry, :telemetry_url,
+    attr_accessor :env, :is_network_enabled, :disable_telemetry, :telemetry_url,
                   :private_attributes, :sticky_store,
                   :disable_internal_error_reporting
 
@@ -80,7 +91,10 @@ module Shipeasy
       @init                 = true
       @poll                 = false
       @env                  = "prod"
-      @disable_telemetry    = false
+      # nil ⇒ environment-derived default (see Engine / sdk/env.rb). An explicit
+      # true/false set in the configure block always overrides.
+      @is_network_enabled   = nil
+      @disable_telemetry    = nil
       @disable_internal_error_reporting = false
       @telemetry_url        = nil
       @private_attributes   = nil
@@ -159,6 +173,7 @@ module Shipeasy
         api_key:            cfg.api_key,
         base_url:           cfg.base_url,
         env:                cfg.env,
+        is_network_enabled: cfg.is_network_enabled,
         disable_telemetry:  cfg.disable_telemetry,
         telemetry_url:      cfg.telemetry_url,
         private_attributes: cfg.private_attributes,
@@ -170,13 +185,13 @@ module Shipeasy
       # Capture +engine+ in the closure (not the @engine ivar, which a concurrent
       # reset/reconfigure could nil out before the thread runs).
       if cfg.poll
-        Thread.new do
+        @boot_thread = Thread.new do
           engine.init   # initial fetch + background poll thread
         rescue => e
           Shipeasy::Logging.error "[shipeasy] configure(poll) background poll failed: #{e.message}"
         end
       elsif cfg.init
-        Thread.new do
+        @boot_thread = Thread.new do
           engine.init_once
         rescue => e
           Shipeasy::Logging.error "[shipeasy] configure() one-shot fetch failed: #{e.message}"
@@ -327,6 +342,13 @@ module Shipeasy
 
     # Reset the config back to defaults — primarily for tests.
     def reset_config!
+      # Reap the fire-and-forget boot thread first: it holds its own engine
+      # reference, so left alive it can call init/init_once during the NEXT
+      # test example and trip any_instance expectations armed there.
+      if (t = @boot_thread)
+        t.join(1) || t.kill
+        @boot_thread = nil
+      end
       @config = nil
       @flags_pid = nil
       @flags&.destroy

data/lib/shipeasy/engine.rb

@@ -4,6 +4,7 @@ require "json"
 require "thread"
 require "cgi"
 require_relative "logging"
+require_relative "sdk/env"
 require_relative "sdk/eval"
 require_relative "sdk/telemetry"
 require_relative "sdk/anon_id"
@@ -35,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", disable_telemetry: false, 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)
         # 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,
@@ -59,14 +60,30 @@ module Shipeasy
         # evaluation answers come purely from local overrides. Built via the
         # Engine.for_testing factory; see clear_overrides / override_*.
         @test_mode   = test_mode
-        # Per-evaluation usage telemetry. ON by default; pass
-        # disable_telemetry: true to opt out. See telemetry.rb.
+        # Environment-derived egress default. Both the master network switch and
+        # usage telemetry default ON in production and OFF everywhere else, so an
+        # app that embeds the SDK is quiet by default on a dev machine or in CI.
+        # The production decision consults native env vars first (SHIPEASY_ENV /
+        # RAILS_ENV / RACK_ENV / APP_ENV), then falls back to the configured `env`
+        # tag. See sdk/env.rb.
+        prod = Shipeasy::SDK::Env.is_production_env(env)
+        # Master network gate. test_mode always forces the SDK fully offline;
+        # otherwise honour an explicit is_network_enabled, else default to
+        # prod-on. When @offline, every fetch / track / exposure / see() / poll /
+        # telemetry send is a no-op — reads answer from overrides / in-code
+        # defaults only.
+        network_enabled = @test_mode ? false : (is_network_enabled.nil? ? prod : (is_network_enabled ? true : false))
+        @offline = !network_enabled
+        # Per-evaluation usage telemetry. Honour an explicit disable_telemetry,
+        # else default to prod-on (off outside production). Forced off whenever
+        # the master network switch is off. See telemetry.rb.
+        telemetry_disabled = @offline || (disable_telemetry.nil? ? !prod : (disable_telemetry ? true : false))
         @telemetry = Telemetry.new(
           endpoint: telemetry_url || Telemetry::DEFAULT_TELEMETRY_URL,
           sdk_key: api_key,
           side: "server",
           env: env,
-          disabled: disable_telemetry,
+          disabled: telemetry_disabled,
         )
         @flags_blob  = nil
         @exps_blob   = nil
@@ -103,7 +120,7 @@ module Shipeasy
         Shipeasy::SDK::InternalReport.set_context(
           side: "server",
           sdk_version: Shipeasy::SDK::VERSION,
-          enabled: !test_mode && !disable_internal_error_reporting,
+          enabled: !@offline && !disable_internal_error_reporting,
         )
         # Register as the default client backing the module-level Shipeasy::SDK
         # .see/.see_violation funcs (last constructed wins — the server-SDK
@@ -153,14 +170,14 @@ module Shipeasy
       end
 
       def init
-        return if @test_mode
+        return if @offline
         fetch_all
         @initialized = true
         start_poll
       end
 
       def init_once
-        return if @test_mode
+        return if @offline
         return if @initialized
         fetch_all
         @initialized = true
@@ -470,7 +487,7 @@ module Shipeasy
 
       def track(user_id, event_name, props = {})
         safe_run("track('#{event_name}')", nil) do
-          next if @test_mode
+          next if @offline
 
           safe_props = strip_private(props)
 
@@ -583,7 +600,7 @@ module Shipeasy
       # spam /collect. Fire-and-forget; no-op in test mode. This is how
       # assign_universe auto-logs — the browser's auto-exposure parity for SSR.
       def post_exposure(user, experiment, group)
-        return if @test_mode
+        return if @offline
         u = user.transform_keys(&:to_s)
         uid = u["user_id"] || u["anonymous_id"]
         dedup_key = "#{uid}:#{experiment}:#{group}"
@@ -614,7 +631,7 @@ module Shipeasy
       # 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
+        return if @offline
 
         ev = See.build_event(
           built.problem,

data/lib/shipeasy/sdk/env.rb

@@ -0,0 +1,55 @@
+module Shipeasy
+  module SDK
+    # Native runtime-environment detection.
+    #
+    # Used ONLY to pick the DEFAULT for outbound egress when the caller does not
+    # set it explicitly:
+    #   - is the SDK allowed to make network requests at all (is_network_enabled)?
+    #   - is per-evaluation usage telemetry allowed (disable_telemetry)?
+    #
+    # Both default to ON in production and OFF everywhere else, so a local/dev/CI
+    # run of an app that embeds the SDK never phones home unless it explicitly
+    # opts in.
+    #
+    # Precedence for the production decision (mirrors the TS SDK's src/env.ts):
+    #   1. A native runtime env var — SHIPEASY_ENV, then RAILS_ENV, then RACK_ENV,
+    #      then APP_ENV. A value of "production"/"prod" (case-insensitive) ⇒ prod;
+    #      anything else present ("development"/"staging"/"test"/…) ⇒ not prod.
+    #   2. When no native env var is set (e.g. serverless / some containers), fall
+    #      back to the SDK's OWN configured `env` option, which the caller sets and
+    #      which itself defaults to "prod". This keeps a real production deploy
+    #      "on" by default while an `env: "dev"` config stays quiet.
+    #
+    # The env option is always present (it defaults to "prod"), so the production
+    # decision is always inferrable — the SDK never has to make the field required.
+    module Env
+      # Native env vars consulted, in precedence order.
+      NATIVE_ENV_VARS = %w[SHIPEASY_ENV RAILS_ENV RACK_ENV APP_ENV].freeze
+
+      module_function
+
+      # True when the host runtime looks like a production deployment.
+      # +configured_env+ is the SDK's own `env` option (dev/staging/prod); it is
+      # consulted ONLY when no native runtime env var is set.
+      def is_production_env(configured_env = nil)
+        native = read_native_env
+        return native == "production" || native == "prod" unless native.nil?
+
+        (configured_env || "prod").to_s.strip.downcase == "prod"
+      end
+
+      # Read the first present native env var (lowercased, trimmed), or nil when
+      # none of them is set to a non-empty value.
+      def read_native_env
+        NATIVE_ENV_VARS.each do |name|
+          raw = ENV[name]
+          next if raw.nil?
+
+          v = raw.strip.downcase
+          return v unless v.empty?
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/shipeasy/sdk/version.rb

@@ -1,5 +1,5 @@
 module Shipeasy
   module SDK
-    VERSION = "3.0.0"
+    VERSION = "3.1.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shipeasy-sdk
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Shipeasy, Inc.
@@ -142,6 +142,7 @@ files:
 - lib/shipeasy/i18n/view_helpers.rb
 - lib/shipeasy/logging.rb
 - lib/shipeasy/sdk/anon_id.rb
+- lib/shipeasy/sdk/env.rb
 - lib/shipeasy/sdk/eval.rb
 - lib/shipeasy/sdk/internal_report.rb
 - lib/shipeasy/sdk/murmur3.rb