shopcircle-orbit 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea60f7805d0aa67d6d2748586dc5342bc88e12f2b4b61b4aab4c8cd1ca5519f1
-  data.tar.gz: 87bf73def7abdfac9818392a21b80a161f67b5ecbcdd6c64df5dc37d4ebcd838
+  metadata.gz: fc9150b18fb5fafd2bfffa30c16ab606e828e430e0a256f8bf7b26b99b6b9b24
+  data.tar.gz: 5f80e5a8c9c68835749e856191903c165d8f4ce7dfaf8f6b2be037b935d348e1
 SHA512:
-  metadata.gz: '067937e4dc01ec32494a35cfdba85fb923a6c0c10e4730a03bdbf5c5368d38773d46af351c36b73cbee9efa8491df6eed787afe97e67de1008e5400d52defb23'
-  data.tar.gz: 3379decabf5a9596d9a21fe7be34d30f7c0af5045d2e4917e5f12f165ebb27bcb1a8d00fa16b4d2bb9baaab9ad295d035346ce3cfdf51961ec2509fee51b0bd5
+  metadata.gz: 29e8608f43338f1f5fceaf2b059c1cf9b70ce93368d609a5406dda26e418c3d207ee44043fd9b3d99c67e43b9b71bab4755714fa6dc58d0552a63507939da2b3
+  data.tar.gz: d479a929d7d21e3759f09a0324014ba2aaf811ab9dceb5105e4841faca25322a767ee00c11f01bb249066c1d316f61520675819e1859ad9a2b6692485e65f213

data/lib/shopcircle/orbit/client.rb

@@ -9,8 +9,7 @@ module ShopCircle
         @config = resolve_config(config, options)
         @config.validate!
 
-        @profile_id = nil
-        @device_id  = @config.device_id
+        @default_device_id = @config.device_id
         @queue      = Thread::Queue.new
         @mutex      = Mutex.new
         @shutdown   = false
@@ -52,9 +51,9 @@ module ShopCircle
       #   first_name / firstName, last_name / lastName
       #
       def identify(profile_id, traits = {})
-        raise ArgumentError, "profile_id is required" if profile_id.nil? || profile_id.to_s.strip.empty?
+        raise ValidationError, "profile_id is required" if profile_id.nil? || profile_id.to_s.strip.empty?
 
-        @mutex.synchronize { @profile_id = profile_id.to_s }
+        Thread.current[:shopcircle_orbit_profile_id] = profile_id.to_s
 
         traits = traits.dup
         first_name = traits.delete(:first_name) || traits.delete(:firstName)
@@ -76,13 +75,14 @@ module ShopCircle
 
       # Clear current profile association (e.g. on logout).
       def reset!
-        @mutex.synchronize { @profile_id = nil }
+        Thread.current[:shopcircle_orbit_profile_id] = nil
+        Thread.current[:shopcircle_orbit_device_id] = nil
       end
 
       # Set or update the device identifier at runtime.
       def set_device_id(device_id)
         Validation.validate_device_id!(device_id)
-        @mutex.synchronize { @device_id = device_id&.to_s }
+        Thread.current[:shopcircle_orbit_device_id] = device_id&.to_s
       end
 
       # Force an immediate flush of queued events.
@@ -94,6 +94,7 @@ module ShopCircle
       def shutdown!
         @mutex.synchronize { @shutdown = true }
         @worker.stop
+        @worker.transport.shutdown if @worker.transport.respond_to?(:shutdown)
       end
 
       # Returns recorded events (stub mode only).
@@ -105,22 +106,24 @@ module ShopCircle
       private
 
       def enqueue(event)
-        return if @mutex.synchronize { @shutdown }
+        @mutex.synchronize do
+          return if @shutdown
 
-        # Drop oldest if at capacity
-        if @queue.size >= @config.max_queue_size
-          @queue.pop(true) rescue nil
-        end
+          if @queue.size >= @config.max_queue_size
+            @queue.pop(true) rescue nil
+            @config.resolved_logger&.warn("[shopcircle-orbit] Event queue full (#{@config.max_queue_size}), dropping oldest event")
+          end
 
-        @queue.push(event)
+          @queue.push(event)
+        end
       end
 
       def current_profile_id
-        @mutex.synchronize { @profile_id }
+        Thread.current[:shopcircle_orbit_profile_id]
       end
 
       def current_device_id
-        @mutex.synchronize { @device_id }
+        Thread.current[:shopcircle_orbit_device_id] || @default_device_id
       end
 
       def register_at_exit_hook
@@ -140,7 +143,7 @@ module ShopCircle
             build_config(options)
           end
         else
-          raise ArgumentError, "Expected Configuration, Hash, or keyword arguments"
+          raise ConfigurationError, "Expected Configuration, Hash, or keyword arguments"
         end
       end
 
@@ -148,7 +151,11 @@ module ShopCircle
         c = Configuration.new
         hash.each do |k, v|
           setter = :"#{k}="
-          c.public_send(setter, v) if c.respond_to?(setter)
+          if c.respond_to?(setter)
+            c.public_send(setter, v)
+          else
+            c.resolved_logger.warn("[shopcircle-orbit] Unknown configuration key: #{k}")
+          end
         end
         c
       end

data/lib/shopcircle/orbit/configuration.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "uri"
+
 module ShopCircle
   module Orbit
     class Configuration
@@ -15,7 +17,9 @@ module ShopCircle
                     :request_timeout,
                     :logger,
                     :stub,
-                    :on_error
+                    :on_error,
+                    :redact_pii,
+                    :exclude_paths
 
       def initialize
         @client_id       = nil
@@ -31,20 +35,55 @@ module ShopCircle
         @logger          = nil
         @stub            = false
         @on_error        = nil
+        @redact_pii      = true
+        @exclude_paths   = []
       end
 
       def validate!
-        raise ArgumentError, "client_id is required" if @client_id.nil? || @client_id.to_s.empty?
-        raise ArgumentError, "api_url is required" if @api_url.nil? || @api_url.to_s.empty?
-        raise ArgumentError, "device_id max 128 chars" if @device_id && @device_id.to_s.length > 128
+        raise ConfigurationError, "client_id is required" if @client_id.nil? || @client_id.to_s.empty?
+        raise ConfigurationError, "api_url is required" if @api_url.nil? || @api_url.to_s.empty?
+        raise ConfigurationError, "device_id max 128 chars" if @device_id && @device_id.to_s.length > 128
+
+        validate_positive!(:flush_interval, @flush_interval)
+        validate_positive!(:max_batch_size, @max_batch_size)
+        validate_positive!(:max_queue_size, @max_queue_size)
+        validate_positive!(:request_timeout, @request_timeout)
+        validate_positive!(:base_retry_delay, @base_retry_delay)
+        raise ConfigurationError, "max_retries must be >= 0" if !@max_retries.is_a?(Numeric) || @max_retries < 0
+
+        uri = URI.parse(@api_url.to_s)
+        unless uri.scheme == "https" || ENV["ORBIT_ALLOW_HTTP"] == "1"
+          raise ConfigurationError, "api_url must use https:// in production. Set ORBIT_ALLOW_HTTP=1 for local development."
+        end
+        if uri.scheme != "https"
+          resolved_logger.warn("[shopcircle-orbit] WARNING: Sending data over plaintext HTTP. Do not use in production.")
+        end
       end
 
       def resolved_logger
         @logger || default_logger
       end
 
+      # Redact sensitive fields from inspect output to prevent
+      # accidental credential leakage in logs/debugging.
+      def inspect
+        redacted = instance_variables.each_with_object({}) do |var, hash|
+          val = instance_variable_get(var)
+          hash[var] = if var == :@client_secret && val
+                        "[REDACTED]"
+                      else
+                        val
+                      end
+        end
+        "#<#{self.class} #{redacted.map { |k, v| "#{k}=#{v.inspect}" }.join(', ')}>"
+      end
+
       private
 
+      def validate_positive!(name, value)
+        raise ConfigurationError, "#{name} must be a positive number" if !value.is_a?(Numeric) || value <= 0
+      end
+
       def default_logger
         @default_logger ||= begin
           require "logger"

data/lib/shopcircle/orbit/errors.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ShopCircle
+  module Orbit
+    # Base error for all SDK errors. Rescue this to catch everything.
+    class Error < StandardError; end
+
+    # Raised when configuration is invalid (missing keys, bad URLs, etc.)
+    class ConfigurationError < Error; end
+
+    # Raised when input validation fails (event names, properties, etc.)
+    class ValidationError < Error; end
+
+    # Raised on 401 responses.
+    class AuthenticationError < Error; end
+
+    # Raised on 403 responses.
+    class AuthorizationError < Error; end
+
+    # Raised on 429 responses.
+    class RateLimitError < Error; end
+
+    # Raised on 4xx responses not covered above.
+    class ClientError < Error
+      attr_reader :status
+
+      def initialize(message, status: nil)
+        @status = status
+        super(message)
+      end
+    end
+
+    # Raised on 5xx responses.
+    class APIError < Error
+      attr_reader :status
+
+      def initialize(message, status: nil)
+        @status = status
+        super(message)
+      end
+    end
+
+    # Raised on network failures (connection refused, reset, etc.)
+    class ConnectionError < Error; end
+
+    # Raised on request timeouts.
+    class TimeoutError < ConnectionError; end
+  end
+end

data/lib/shopcircle/orbit/rails/middleware.rb

@@ -20,22 +20,27 @@ module ShopCircle
 
         def call(env)
           status, headers, response = @app.call(env)
-
-          if trackable?(env, status)
-            request = Rack::Request.new(env)
-            ShopCircle::Orbit.track("page_view", {
-              path: request.path,
-              method: request.request_method,
-              status: status,
-              user_agent: request.user_agent,
-              ip: request.ip,
-              referrer: request.referrer
-            })
+          begin
+            if trackable?(env, status)
+              request = Rack::Request.new(env)
+              props = {
+                path: request.path,
+                method: request.request_method,
+                status: status
+              }
+              unless ShopCircle::Orbit.configuration.redact_pii
+                props[:user_agent] = request.user_agent
+                props[:ip] = request.ip
+                props[:referrer] = request.referrer
+              end
+              ShopCircle::Orbit.track("page_view", props)
+            end
+          rescue StandardError => e
+            ShopCircle::Orbit.configuration.resolved_logger.warn("[shopcircle-orbit] Tracking error: #{e.message}")
+          ensure
+            Thread.current[:shopcircle_orbit_profile_id] = nil
+            Thread.current[:shopcircle_orbit_device_id] = nil
           end
-
-          [status, headers, response]
-        rescue StandardError
-          # Never break the request due to tracking errors
           [status, headers, response]
         end
 
@@ -48,6 +53,10 @@ module ShopCircle
           path = env["PATH_INFO"].to_s
           return false if SKIP_PREFIXES.any? { |p| path.start_with?(p) }
 
+          # User-configurable path exclusions
+          config_excludes = ShopCircle::Orbit.configuration.exclude_paths
+          return false if config_excludes.any? { |p| path.start_with?(p) }
+
           # Skip XHR / fetch requests
           return false if env["HTTP_X_REQUESTED_WITH"] == "XMLHttpRequest"
           return false if env["HTTP_ACCEPT"]&.include?("application/json")

data/lib/shopcircle/orbit/transport.rb

@@ -3,6 +3,7 @@
 require "net/http"
 require "uri"
 require "json"
+require "openssl"
 
 module ShopCircle
   module Orbit
@@ -12,6 +13,8 @@ module ShopCircle
       def initialize(config)
         @config  = config
         @api_uri = URI.parse(config.api_url.to_s.chomp("/"))
+        @http    = nil
+        @mutex   = Mutex.new
       end
 
       def send_single(event)
@@ -24,66 +27,116 @@ module ShopCircle
           events: events.map(&:to_payload),
           clientId: @config.client_id,
           sdkName: SDK_NAME,
-          sdkVersion: ShopCircle::Orbit::VERSION,
-          deviceId: events.first&.device_id
+          sdkVersion: ShopCircle::Orbit::VERSION
         })
         post("/api/track/batch", body)
       end
 
+      def shutdown
+        @mutex.synchronize do
+          @http&.finish rescue nil
+          @http = nil
+        end
+      end
+
       private
 
-      def post(path, body, attempt = 0)
-        uri = @api_uri.dup
-        uri.path = path
-
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl = (uri.scheme == "https")
-        http.open_timeout = @config.request_timeout
-        http.read_timeout = @config.request_timeout
-        http.write_timeout = @config.request_timeout if http.respond_to?(:write_timeout=)
-
-        request = Net::HTTP::Post.new(uri.path)
-        request["Content-Type"]             = "application/json"
-        request["shopcircle-client-id"]     = @config.client_id
-        request["shopcircle-sdk-name"]      = SDK_NAME
-        request["shopcircle-sdk-version"]   = ShopCircle::Orbit::VERSION
-        request["shopcircle-client-secret"] = @config.client_secret if @config.client_secret
-        request.body = body
-
-        response = http.request(request)
-        status = response.code.to_i
-
-        return if status >= 200 && status < 300
-
-        # 4xx except 429: client error, don't retry
-        if status >= 400 && status < 500 && status != 429
-          log_error("HTTP #{status}", response.body)
-          return
+      def ensure_connection
+        if @http.nil? || !@http.started?
+          @http = Net::HTTP.new(@api_uri.host, @api_uri.port)
+          @http.use_ssl = (@api_uri.scheme == "https")
+          @http.verify_mode = OpenSSL::SSL::VERIFY_PEER if @http.use_ssl?
+          @http.open_timeout = @config.request_timeout
+          @http.read_timeout = @config.request_timeout
+          @http.write_timeout = @config.request_timeout if @http.respond_to?(:write_timeout=)
+          @http.keep_alive_timeout = 30
+          @http.start
         end
+      end
 
-        # 429, 5xx: retryable
-        maybe_retry(path, body, attempt, status, response.body)
-      rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout,
-             Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EPIPE,
-             SocketError, IOError => e
-        maybe_retry(path, body, attempt, nil, e.message)
-      ensure
-        http&.finish rescue nil
+      def close_connection
+        @http&.finish rescue nil
+        @http = nil
       end
 
-      def maybe_retry(path, body, attempt, status, message)
-        if attempt < @config.max_retries
-          delay = @config.base_retry_delay * (2**attempt)
-          sleep(delay)
-          post(path, body, attempt + 1)
-        else
-          log_error("Failed after #{@config.max_retries + 1} attempts (status=#{status})", message)
+      def post(path, body)
+        attempt = 0
+
+        @mutex.synchronize do
+          loop do
+            ensure_connection
+
+            request = Net::HTTP::Post.new(path)
+            request["Content-Type"]           = "application/json"
+            request["shopcircle-client-id"]   = @config.client_id
+            request["shopcircle-sdk-name"]    = SDK_NAME
+            request["shopcircle-sdk-version"] = ShopCircle::Orbit::VERSION
+            request["Authorization"]          = "Bearer #{@config.client_secret}" if @config.client_secret
+            request.body = body
+
+            response = @http.request(request)
+            status = response.code.to_i
+
+            # 2xx/3xx: success
+            return if status >= 200 && status < 400
+
+            # 4xx except 429: client error, don't retry
+            if status >= 400 && status < 500 && status != 429
+              log_error("HTTP #{status}", response.body)
+              return
+            end
+
+            # 429 or 5xx: retryable
+            if attempt < @config.max_retries
+              delay = retry_delay(attempt, response)
+              sleep(delay)
+              attempt += 1
+            else
+              log_error("Failed after #{@config.max_retries + 1} attempts (status=#{status})", response.body)
+              return
+            end
+
+          rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout => e
+            close_connection
+            if attempt < @config.max_retries
+              sleep(retry_delay(attempt))
+              attempt += 1
+            else
+              log_error("Timeout after #{@config.max_retries + 1} attempts", e.message)
+              return
+            end
+
+          rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EPIPE,
+                 SocketError, IOError => e
+            close_connection
+            if attempt < @config.max_retries
+              sleep(retry_delay(attempt))
+              attempt += 1
+            else
+              log_error("Connection error after #{@config.max_retries + 1} attempts", e.message)
+              return
+            end
+          end
+        end
+      end
+
+      # Exponential backoff with jitter.
+      # Respects Retry-After header when present (429 responses).
+      def retry_delay(attempt, response = nil)
+        if response
+          retry_after = response["Retry-After"]
+          return retry_after.to_f if retry_after && retry_after.match?(/\A\d+(\.\d+)?\z/)
         end
+
+        base = @config.base_retry_delay * (2**attempt)
+        # Full jitter: random value between 50%-100% of base delay
+        base * (0.5 + rand * 0.5)
       end
 
       def log_error(msg, detail)
-        @config.on_error&.call(msg, detail)
-        @config.resolved_logger.warn("[shopcircle-orbit] #{msg}: #{detail}")
+        safe_detail = detail.to_s[0, 200]
+        @config.on_error&.call(msg, safe_detail)
+        @config.resolved_logger.warn("[shopcircle-orbit] #{msg}: #{safe_detail}")
       rescue StandardError
         # Never crash the worker thread due to logging/callback errors
       end

data/lib/shopcircle/orbit/validation.rb

@@ -12,23 +12,39 @@ module ShopCircle
 
       class << self
         def validate_event_name!(name)
-          raise ArgumentError, "event name is required" if name.nil? || name.to_s.strip.empty?
-          raise ArgumentError, "event name max #{MAX_EVENT_NAME_LENGTH} chars" if name.to_s.length > MAX_EVENT_NAME_LENGTH
-          raise ArgumentError, "event name '#{name}' is reserved" if RESERVED_NAMES.include?(name.to_s)
+          raise ValidationError, "event name is required" if name.nil? || name.to_s.strip.empty?
+          raise ValidationError, "event name max #{MAX_EVENT_NAME_LENGTH} chars" if name.to_s.length > MAX_EVENT_NAME_LENGTH
+          raise ValidationError, "event name '#{name}' is reserved" if RESERVED_NAMES.include?(name.to_s)
         end
 
         def validate_properties!(props)
           return if props.nil? || props.empty?
 
-          json = JSON.generate(props)
-          if json.bytesize > MAX_PROPERTIES_BYTES
-            raise ArgumentError, "properties too large (#{json.bytesize} bytes, max #{MAX_PROPERTIES_BYTES})"
+          size = estimate_byte_size(props)
+          if size > MAX_PROPERTIES_BYTES
+            raise ValidationError, "properties too large (~#{size} bytes, max #{MAX_PROPERTIES_BYTES})"
           end
         end
 
         def validate_device_id!(device_id)
           return if device_id.nil?
-          raise ArgumentError, "device_id max #{MAX_DEVICE_ID_LENGTH} chars" if device_id.to_s.length > MAX_DEVICE_ID_LENGTH
+          raise ValidationError, "device_id max #{MAX_DEVICE_ID_LENGTH} chars" if device_id.to_s.length > MAX_DEVICE_ID_LENGTH
+        end
+
+        private
+
+        def estimate_byte_size(obj)
+          case obj
+          when Hash
+            2 + obj.sum { |k, v| k.to_s.bytesize + estimate_byte_size(v) + 4 }
+          when Array
+            2 + obj.sum { |v| estimate_byte_size(v) + 1 }
+          when String then obj.bytesize + 2
+          when Numeric then obj.to_s.bytesize
+          when TrueClass, FalseClass then obj.to_s.bytesize
+          when NilClass then 4
+          else obj.to_s.bytesize + 2
+          end
         end
       end
     end

data/lib/shopcircle/orbit/version.rb

@@ -2,6 +2,6 @@
 
 module ShopCircle
   module Orbit
-    VERSION = "1.0.0"
+    VERSION = "1.1.0"
   end
 end

data/lib/shopcircle/orbit/worker.rb

@@ -5,6 +5,9 @@ module ShopCircle
     class Worker
       attr_reader :transport
 
+      FLUSH_TIMEOUT = 5
+      MAX_CONSECUTIVE_ERRORS = 5
+
       def initialize(queue:, config:, transport:)
         @queue     = queue
         @config    = config
@@ -13,6 +16,8 @@ module ShopCircle
         @mutex     = Mutex.new
         @condvar   = ConditionVariable.new
         @running   = false
+        @flush_waiters = []
+        @consecutive_errors = 0
       end
 
       def start
@@ -30,14 +35,30 @@ module ShopCircle
           @running = false
           @condvar.signal
         end
-        flush_all
         @thread&.join(5)
+        flush_all
+        notify_all_waiters
       end
 
       def flush
-        @mutex.synchronize { @condvar.signal }
-        # Give worker thread a moment to process
-        sleep(0.05)
+        return unless running?
+
+        done = Queue.new
+        @mutex.synchronize do
+          @flush_waiters << done
+          @condvar.signal
+        end
+
+        # Poll with short sleeps instead of Timeout (which uses Thread.raise)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + FLUSH_TIMEOUT
+        loop do
+          return done.pop(true) if !done.empty?
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+            @mutex.synchronize { @flush_waiters.delete(done) }
+            return nil
+          end
+          sleep(0.01)
+        end
       end
 
       private
@@ -48,9 +69,22 @@ module ShopCircle
             @condvar.wait(@mutex, @config.flush_interval)
           end
           flush_all
+          @consecutive_errors = 0
+          notify_all_waiters
         end
       rescue StandardError => e
+        @consecutive_errors += 1
         @config.resolved_logger.error("[shopcircle-orbit] Worker error: #{e.message}")
+        notify_all_waiters
+
+        if @consecutive_errors >= MAX_CONSECUTIVE_ERRORS
+          @config.resolved_logger.error("[shopcircle-orbit] Worker stopped after #{MAX_CONSECUTIVE_ERRORS} consecutive errors")
+          @mutex.synchronize { @running = false }
+          return
+        end
+
+        backoff = [2**@consecutive_errors, 30].min
+        sleep(backoff)
         retry if running?
       end
 
@@ -58,6 +92,15 @@ module ShopCircle
         @mutex.synchronize { @running }
       end
 
+      def notify_all_waiters
+        @mutex.synchronize do
+          @flush_waiters.each { |q| q.push(true) }
+          @flush_waiters.clear
+        end
+      rescue StandardError
+        # Never crash the worker thread due to notification errors
+      end
+
       def flush_all
         batch = drain_queue
         return if batch.empty?

data/lib/shopcircle_orbit.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "shopcircle/orbit/version"
+require_relative "shopcircle/orbit/errors"
 require_relative "shopcircle/orbit/configuration"
 require_relative "shopcircle/orbit/validation"
 require_relative "shopcircle/orbit/event"
@@ -10,6 +11,8 @@ require_relative "shopcircle/orbit/client"
 
 module ShopCircle
   module Orbit
+    @client_mutex = Mutex.new
+
     class << self
       attr_writer :configuration
 
@@ -30,7 +33,11 @@ module ShopCircle
 
       # Lazily initialized singleton client.
       def client
-        @client ||= Client.new(configuration)
+        return @client if @client
+
+        @client_mutex.synchronize do
+          @client ||= Client.new(configuration)
+        end
       end
 
       # Track a custom event.
@@ -68,9 +75,11 @@ module ShopCircle
 
       # Flush and stop the singleton client.
       def shutdown!
-        return unless @client
-        @client.shutdown!
-        @client = nil
+        @client_mutex.synchronize do
+          return unless @client
+          @client.shutdown!
+          @client = nil
+        end
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shopcircle-orbit
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - ShopCircle
@@ -64,6 +64,7 @@ files:
 - README.md
 - lib/shopcircle/orbit/client.rb
 - lib/shopcircle/orbit/configuration.rb
+- lib/shopcircle/orbit/errors.rb
 - lib/shopcircle/orbit/event.rb
 - lib/shopcircle/orbit/rails/generators/install_generator.rb
 - lib/shopcircle/orbit/rails/middleware.rb