getstream-ruby 9.0.0 → 10.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95df1de0290331e3d4c2040f9afbadb7f0ee6fa5cc931cbef126c2f244672632
-  data.tar.gz: 484cd5ddc8b072644bbc8f0808c87f4f3e933b936fb114fb49b23c3e32327329
+  metadata.gz: f7c2582f037fa1be220f8b72647c0a87254d0eeb42af2b5046cdb410852f25d7
+  data.tar.gz: a880f9c77e414fe74ee4dd7d82631c927b5af8b4c8b0dca6fca5d00386ff08cf
 SHA512:
-  metadata.gz: c577cceb9a470b2835b48eb1bb5554e3f955227d63b595786c1516f7e6ea0f56e1bc5d452486e3ff4e0b1b7bda34d49b6d5e7c5f14e746b8d972f899034a55c3
-  data.tar.gz: 0c616c6ad3ac9ebd6701f049e2d0432b0cb3309363fbd2dd5da8bfc75e787f0f0e44628363f1f9a40a97a97b07861af4e05c366d50f09f6783d06397d8695c54
+  metadata.gz: 10ad2c2ba0fb122b5a0048136d605eba7de662c86c7cd62123b8e84ad17f96a88750e0dc416764208e42106dab904d5127f711b36aab9083d637e8684582dd26
+  data.tar.gz: b1bffe4b14da26fb2761eb596c78b3337f8bd7f4600869e1be0792b4c581bea79108990bd7ab5898c083826b66a8b68a054eda8c2e4d93c94d75a9007735af67

data/README.md

@@ -163,6 +163,42 @@ rescue GetStreamRuby::APIError => e
 end
 ```
 
+## Retries
+
+Retries are opt-in via `retry_config:` and disabled by default (the client makes exactly one attempt; errors surface unchanged). When enabled, only `GET`/`HEAD` requests are retried, and only when they fail with HTTP 429 (unless the error is marked `unrecoverable`) or a transport-level error (connection reset, timeout, DNS failure, TLS handshake failure). Writes, 5xx responses, and other 4xx responses are never retried.
+
+```ruby
+client = GetStreamRuby::Client.new(
+  api_key: '...', api_secret: '...',
+  retry_config: GetStreamRuby::RetryConfig.new(enabled: true, max_attempts: 3, max_backoff: 30.0)
+)
+```
+
+`max_attempts` caps the total number of attempts (default 3). `max_backoff` caps the wait between attempts (default 30.0 seconds). A 429 with a `Retry-After` header waits exactly that long, clamped to `max_backoff`, with no jitter. Otherwise the wait is full jitter: a random delay between 0 and `min(max_backoff, 2**attempt)` seconds.
+
+## Logging
+
+Pass a stdlib `Logger` via `logger:` to get structured, single-line log events. With no `logger:`, the SDK produces zero output; the SDK never sets the logger's level either, that's the caller's call.
+
+```ruby
+require 'logger'
+
+client = GetStreamRuby.manual(
+  api_key: "your_api_key",
+  api_secret: "your_api_secret",
+  logger: Logger.new($stdout)
+)
+```
+
+Four events are emitted:
+
+- `client.initialized` (INFO, once at construction): SDK version and the effective client config (pool size, timeouts, gzip, whether a custom `http_client`/`log_bodies` is set).
+- `http.request.sent` (DEBUG, before each request).
+- `http.response.received` (DEBUG, after any response including 4xx/5xx — those are just data, not a failure).
+- `http.request.failed` (ERROR, transport failure only: no HTTP response was received at all, e.g. connection reset, timeout, DNS failure, TLS handshake failure). When [retries](#retries) are enabled, each retried attempt also emits `http.request.failed` at DEBUG with a `retry.attempt` field (1-indexed) before its backoff sleep; a 429 retry omits `error.type` (the paired `http.response.received` already recorded the status), a transport-error retry includes it.
+
+Query values for `api_key`/`api_secret`/`token` are always redacted to `<redacted>`, and the same keys are redacted (shallowly, top-level only) in JSON body logging. No headers are ever logged. Request/response bodies are not logged by default; pass `log_bodies: true` to opt in (values for the keys above are still redacted). Enabling it emits one WARN at construction as a reminder that your logs will now contain body content.
+
 ## Development
 
 ### Quick Start

data/lib/getstream_ruby/client.rb

@@ -2,7 +2,6 @@
 
 require 'faraday'
 require 'faraday/gzip'
-require 'faraday/retry'
 require 'faraday/multipart'
 require 'faraday/net_http_persistent'
 require 'logger'
@@ -20,11 +19,15 @@ require_relative 'generated/webhook'
 require_relative 'generated/models/api_error'
 require_relative 'stream_response'
 require_relative 'error_mapping'
+require_relative 'log_redaction'
+require_relative 'request_logging'
 
 module GetStreamRuby
 
   class Client
 
+    include RequestLogging
+
     # Backdate the JWT `iat` claim by this many seconds.
     #
     # JWT timestamps are whole-second (RFC 7519 NumericDate), so `Time.now.to_i`
@@ -38,20 +41,23 @@ module GetStreamRuby
     attr_reader :configuration
 
     def initialize(config = nil, api_key: nil, api_secret: nil, **options)
-      @configuration = config || GetStreamRuby.configuration
-
-      # Create new configuration with overrides if any parameters provided
-      if api_key || api_secret || !options.empty?
-        @configuration = Configuration.with_overrides(
-          api_key: api_key,
-          api_secret: api_secret,
-          **options,
-        )
-      end
+      # Overrides win over an explicit config, matching prior behavior. Only
+      # fall back to GetStreamRuby.configuration when neither is given, so
+      # that path (currently unimplemented) isn't evaluated needlessly.
+      @configuration = if api_key || api_secret || !options.empty?
+                         Configuration.with_overrides(
+                           api_key: api_key,
+                           api_secret: api_secret,
+                           **options,
+                         )
+                       else
+                         config || GetStreamRuby.configuration
+                       end
 
       @configuration.validate!
       @connection = build_connection
       @configuration.log_pool_config_to(@configuration.logger)
+      warn_log_bodies_enabled
     end
 
     def feed_resource
@@ -209,21 +215,76 @@ module GetStreamRuby
       # Check if this is a file upload request that needs multipart
       return make_multipart_request(method, path, query_params, data) if multipart_request?(data)
 
-      response = @connection.send(method) do |req|
+      body_json = data.to_json
+      attempt = 0
 
-        req.url path, query_params
-        req.headers['Authorization'] = generate_auth_header
-        req.headers['Content-Type'] = 'application/json'
-        req.headers['stream-auth-type'] = 'jwt'
-        req.headers['X-Stream-Client'] = user_agent
-        req.body = data.to_json
-        req.options.timeout = request_timeout if request_timeout
+      begin
+        started = monotonic_now
+        log_request_sent(method, path, query_params, body_json)
+
+        response = @connection.send(method) do |req|
+
+          req.url path, query_params
+          req.headers['Authorization'] = generate_auth_header
+          req.headers['Content-Type'] = 'application/json'
+          req.headers['stream-auth-type'] = 'jwt'
+          req.headers['X-Stream-Client'] = user_agent
+          req.body = body_json
+          req.options.timeout = request_timeout if request_timeout
+
+        end
 
+        log_response_received(response, started)
+        handle_response(response)
+      rescue Faraday::Error => e
+        error = TransportError.new("Request failed: #{e.message}", error_type: ErrorMapping.classify_faraday_error(e))
+        if retry_eligible?(method, error, attempt)
+          wait_before_retry(method, path, error, attempt, started)
+          attempt += 1
+          retry
+        end
+        log_request_failed(method, path, e, started)
+        raise error
+      rescue RateLimitError => e
+        if retry_eligible?(method, e, attempt)
+          wait_before_retry(method, path, e, attempt, started)
+          attempt += 1
+          retry
+        end
+        raise
       end
+    end
 
-      handle_response(response)
-    rescue Faraday::Error => e
-      raise TransportError.new("Request failed: #{e.message}", error_type: ErrorMapping.classify_faraday_error(e))
+    # True when the opt-in retry policy (GetStreamRuby::RetryConfig) allows
+    # another attempt for this failure: disabled by default (single attempt,
+    # errors surface unchanged); enabled only retries idempotent GET/HEAD
+    # requests that failed with a recoverable RateLimitError or a
+    # TransportError, and only while attempts remain.
+    def retry_eligible?(method, error, attempt)
+      config = @configuration.retry_config
+      return false unless config&.enabled?
+      return false unless %i[get head].include?(method)
+      return false if error.is_a?(RateLimitError) && error.unrecoverable
+      return false unless attempt + 1 < config.max_attempts
+
+      true
+    end
+
+    # Emits the retry-attempt log, then blocks for the backoff delay:
+    # RateLimitError#retry_after (if positive) capped at max_backoff, no
+    # jitter; otherwise full jitter over 2**attempt capped at max_backoff.
+    # `sleep` is called on self so specs can stub it.
+    def wait_before_retry(method, path, error, attempt, started)
+      log_retry_attempt(method, path, error, attempt, started)
+      config = @configuration.retry_config
+      delay =
+        if error.is_a?(RateLimitError) && error.retry_after&.positive?
+          [error.retry_after, config.max_backoff].min
+        else
+          ceiling = [config.max_backoff, 2.0**attempt].min
+          ceiling <= 0 ? 0.0 : rand * ceiling
+        end
+      sleep(delay)
     end
 
     def build_connection
@@ -234,13 +295,10 @@ module GetStreamRuby
       Faraday.new(url: @configuration.base_url) do |conn|
 
         conn.request :multipart
-        conn.request :retry, {
-          max: 3,
-          interval: 0.05,
-          interval_randomness: 0.5,
-          backoff_factor: 2,
-        }
-        conn.response :json, content_type: /\bjson$/
+        # preserve_raw: true keeps the wire string in env[:raw_body] alongside
+        # the parsed body, so response logging can report size/content
+        # without re-serializing an already-parsed Hash.
+        conn.response :json, content_type: /\bjson$/, preserve_raw: true
         # :gzip must come after :json (Faraday runs response middleware in reverse).
         conn.request :gzip
         configure_adapter(conn)
@@ -277,8 +335,6 @@ module GetStreamRuby
       # A fallback silently disables pooling, so always WARN (never swallow).
       @configuration.warn_pool_fallback(Faraday.default_adapter, e)
       connection.adapter Faraday.default_adapter
-      # Record the adapter actually built so the INFO log reports it accurately.
-      @configuration.effective_adapter = Faraday.default_adapter.to_s
     end
 
     def generate_auth_header
@@ -346,6 +402,9 @@ module GetStreamRuby
         payload[:upload_sizes] = upload_sizes_json
       end
 
+      started = monotonic_now
+      log_request_sent(method, path, query_params)
+
       response = @connection.send(method) do |req|
 
         req.url path, query_params
@@ -356,8 +415,10 @@ module GetStreamRuby
 
       end
 
+      log_response_received(response, started)
       handle_response(response)
     rescue Faraday::Error => e
+      log_request_failed(method, path, e, started)
       raise TransportError.new("Request failed: #{e.message}", error_type: ErrorMapping.classify_faraday_error(e))
     end
 

data/lib/getstream_ruby/configuration.rb

@@ -8,7 +8,7 @@ module GetStreamRuby
 
     attr_accessor :api_key, :api_secret, :base_url, :timeout, :logger, :faraday_adapter, :faraday_adapter_options,
                   :connection_keep_alive, :max_conns_per_host, :idle_timeout, :connect_timeout,
-                  :request_timeout, :http_client, :effective_adapter
+                  :request_timeout, :http_client, :log_bodies, :retry_config
 
     def initialize(api_key: nil, api_secret: nil, use_env: true, **options)
       http_options = options[:http_options] || {}
@@ -22,6 +22,8 @@ module GetStreamRuby
       @timeout = @request_timeout
       @http_client = options[:http_client]
       @logger = options[:logger]
+      @log_bodies = options[:log_bodies] || false
+      @retry_config = options[:retry_config] || RetryConfig.new
     end
 
     def valid?
@@ -48,41 +50,36 @@ module GetStreamRuby
         faraday_adapter_options: @faraday_adapter_options.dup,
         connection_keep_alive: @connection_keep_alive,
         logger: @logger,
+        log_bodies: @log_bodies,
+        retry_config: @retry_config,
       )
     end
 
-    # Emit a single INFO line listing the 5 effective pool knobs plus the active escape hatch (CHA-2956).
-    # If no logger is supplied, a default $stdout INFO logger is used.
-    # The faraday_adapter label reflects the adapter actually built
-    # (effective_adapter, set by Client#configure_adapter) so a silent fallback
-    # to the default adapter is never misreported as the requested adapter.
+    # Emit the `client.initialized` INFO event once at construction (structured
+    # logging spec §6.1). A no-op when no logger is configured: unlike
+    # `warn_pool_fallback` below, a quiet start-up here is expected, not a
+    # silently-swallowed problem, so there is no $stdout fallback.
     def log_pool_config_to(logger)
-      logger ||= Logger.new($stdout).tap { |l| l.level = Logger::INFO }
-      flag = @http_client ? 'user_http_client=true' : 'user_http_client=false'
-      adapter_label = if @http_client
-                        'user-supplied'
-                      elsif @effective_adapter
-                        @effective_adapter
-                      elsif @faraday_adapter
-                        @faraday_adapter.to_s
-                      else
-                        'default'
-                      end
-      fmt = 'connection pool: max_conns_per_host=%<m>d idle_timeout=%<i>d ' \
-            'connect_timeout=%<c>d request_timeout=%<r>d %<flag>s faraday_adapter=%<a>s'
-      logger.info(
-        format(
-          fmt,
-          m: @max_conns_per_host, i: @idle_timeout, c: @connect_timeout,
-          r: @request_timeout, flag: flag, a: adapter_label
-        ),
-      )
+      return if logger.nil?
+
+      fields = {
+        'stream.sdk.name' => 'getstream-ruby',
+        'stream.sdk.version' => VERSION,
+        'stream.client.max_conns_per_host' => @max_conns_per_host,
+        'stream.client.idle_timeout_seconds' => @idle_timeout,
+        'stream.client.connect_timeout_seconds' => @connect_timeout,
+        'stream.client.request_timeout_seconds' => @request_timeout,
+        'stream.client.gzip_enabled' => true,
+        'stream.client.user_http_client' => !@http_client.nil?,
+        'stream.client.log_bodies' => @log_bodies,
+      }
+      logger.info { "client.initialized #{fields.map { |k, v| "#{k}=#{v}" }.join(' ')}" }
     end
 
     # Emit a WARNING that the requested adapter could not be built and pooling
-    # is disabled (CHA-2956). A fallback must never be silent, so when no logger
-    # is configured this uses a default $stdout logger, exactly like
-    # log_pool_config_to.
+    # is disabled (CHA-2956). A fallback must never be silent, so unlike the
+    # structured-logging events below, this uses a default $stdout logger when
+    # none is configured.
     def warn_pool_fallback(fallback_adapter, error)
       warn_logger = @logger || Logger.new($stdout).tap { |l| l.level = Logger::WARN }
       warn_logger.warn(

data/lib/getstream_ruby/log_redaction.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module GetStreamRuby
+
+  # Redaction helpers for the SDK's structured log events. Shallow by design.
+  module LogRedaction
+
+    REDACTED = '<redacted>'
+    QUERY_PARAMS = %w[api_key api_secret token].freeze
+    BODY_KEYS = %w[api_secret token password].freeze
+    # Matches `key=value` for the secret query params wherever they appear in a
+    # free-form string (e.g. a transport error message that embeds the request
+    # URL), value runs up to the next `&`, whitespace, or end of string.
+    MESSAGE_SECRET_PATTERN = /\b(#{QUERY_PARAMS.join('|')})=[^&\s]*/i.freeze
+
+    module_function
+
+    def redact_query(params)
+      return params if params.nil? || params.empty?
+
+      params.to_h { |k, v| [k, QUERY_PARAMS.include?(k.to_s.downcase) ? REDACTED : v] }
+    end
+
+    def redact_json_body(body)
+      return body if body.nil? || body.empty?
+
+      data = JSON.parse(body)
+      return body unless data.is_a?(Hash)
+
+      changed = false
+      BODY_KEYS.each do |key|
+
+        if data.key?(key)
+          data[key] = REDACTED
+          changed = true
+        end
+
+      end
+      changed ? JSON.generate(data) : body
+    rescue JSON::ParserError
+      body
+    end
+
+    # Redacts secret query-parameter values wherever they appear in a free
+    # string (e.g. `error.message` from a transport exception, which may embed
+    # the full request URL). Case-insensitive on the key; the value is
+    # replaced regardless of its own case.
+    def redact_message(string)
+      return string if string.nil? || string.empty?
+
+      string.gsub(MESSAGE_SECRET_PATTERN) { "#{Regexp.last_match(1)}=#{REDACTED}" }
+    end
+
+  end
+
+end

data/lib/getstream_ruby/request_logging.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module GetStreamRuby
+
+  # Structured-logging event emission mixed into Client (kept in its own file
+  # to stay under Metrics/ClassLength; these methods rely on Client's
+  # @configuration/monotonic_now same as if they lived on the class directly).
+  module RequestLogging
+
+    private
+
+    # One-shot WARN at construction so a log_bodies: true deployment can't miss
+    # that bodies (secrets key-redacted, but otherwise verbatim) are now being
+    # written to its logs.
+    def warn_log_bodies_enabled
+      return unless @configuration.log_bodies && @configuration.logger
+
+      @configuration.logger.warn do
+
+        'HTTP request/response bodies will be logged. Auth headers and ' \
+          'known-secret fields are still redacted, but other sensitive ' \
+          'data (messages, PII) may appear in logs. Disable for production.'
+
+      end
+    end
+
+    def log_request_sent(method, path, query_params, body_json = nil)
+      logger = @configuration.logger
+      return unless logger
+
+      query = LogRedaction.redact_query(query_params).map { |k, v| "#{k}=#{v}" }.join('&')
+      line = +"http.request.sent http.request.method=#{method} url.path=#{path} url.query=#{query}"
+      line << " http.request.body=#{LogRedaction.redact_json_body(body_json)}" if @configuration.log_bodies && body_json
+      logger.debug { line }
+    end
+
+    def log_response_received(response, started)
+      logger = @configuration.logger
+      return unless logger
+
+      raw_body = raw_response_body(response)
+      line = +"http.response.received http.response.status_code=#{response.status} " \
+              "http.response.body.size=#{raw_body.bytesize} duration_ms=#{elapsed_ms(started)}"
+      line << " http.response.body=#{LogRedaction.redact_json_body(raw_body)}" if @configuration.log_bodies
+      logger.debug { line }
+    end
+
+    def log_request_failed(method, path, error, started)
+      logger = @configuration.logger
+      return unless logger
+
+      error_type = ErrorMapping.classify_faraday_error(error)
+      message = LogRedaction.redact_message(error.message)
+      logger.error do
+
+        "http.request.failed http.request.method=#{method} url.path=#{path} " \
+          "error.type=#{error_type} error.message=#{message} duration_ms=#{elapsed_ms(started)}"
+
+      end
+    end
+
+    # DEBUG-level counterpart to `log_request_failed`, emitted before each
+    # retry backoff sleep (opt-in RetryConfig). `error.type` is the closed
+    # transport-classifier enum (see ErrorMapping.classify_faraday_error /
+    # TRANSPORT_ERROR_TYPES) and is only meaningful for TransportError; a 429
+    # retry omits it rather than invent a value; the paired
+    # http.response.received log already recorded the 429 status.
+    def log_retry_attempt(method, path, error, attempt, started)
+      logger = @configuration.logger
+      return unless logger
+
+      message = LogRedaction.redact_message(error.message)
+      line = +"http.request.failed http.request.method=#{method} url.path=#{path} retry.attempt=#{attempt + 1}"
+      line << " error.type=#{error.error_type}" if error.is_a?(TransportError)
+      line << " error.message=#{message} duration_ms=#{elapsed_ms(started)}"
+      logger.debug { line }
+    end
+
+    def elapsed_ms(started)
+      ((monotonic_now - started) * 1000).round
+    end
+
+    # The `:json` response middleware parses env[:body] in place once its
+    # content type matches, so the raw wire string only survives via
+    # `preserve_raw:` (see Client#build_connection). Falls back to
+    # `response.body` itself when it was never parsed (non-JSON content type,
+    # or no body).
+    def raw_response_body(response)
+      raw = response.env[:raw_body]
+      return raw unless raw.nil?
+
+      response.body.to_s
+    end
+
+  end
+
+end

data/lib/getstream_ruby/retry_config.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module GetStreamRuby
+
+  # Opt-in auto-retry policy. Disabled by default: the client performs exactly
+  # one attempt and surfaces errors unchanged. When enabled, only GET/HEAD
+  # requests failing with HTTP 429 or a transport error are retried.
+  class RetryConfig
+
+    attr_reader :max_attempts, :max_backoff
+
+    def initialize(enabled: false, max_attempts: 3, max_backoff: 30.0)
+      raise ArgumentError, 'max_attempts must be >= 1' if max_attempts < 1
+      raise ArgumentError, 'max_backoff must be >= 0' if max_backoff.negative?
+
+      @enabled = enabled
+      @max_attempts = max_attempts
+      @max_backoff = max_backoff.to_f
+    end
+
+    def enabled?
+      @enabled
+    end
+
+  end
+
+end

data/lib/getstream_ruby/version.rb

@@ -2,6 +2,6 @@
 
 module GetStreamRuby
 
-  VERSION = '9.0.0'
+  VERSION = '10.0.0'
 
 end

data/lib/getstream_ruby.rb

@@ -2,6 +2,8 @@
 
 # Only load dotenv for .env method, not for system env method
 require 'getstream_ruby/version'
+require 'getstream_ruby/log_redaction'
+require 'getstream_ruby/retry_config'
 require 'getstream_ruby/client'
 require 'getstream_ruby/configuration'
 require 'getstream_ruby/errors'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: getstream-ruby
 version: !ruby/object:Gem::Version
-  version: 9.0.0
+  version: 10.0.0
 platform: ruby
 authors:
 - GetStream
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-15 00:00:00.000000000 Z
+date: 2026-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dotenv
@@ -80,20 +80,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.3'
-- !ruby/object:Gem::Dependency
-  name: faraday-retry
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
@@ -1534,7 +1520,10 @@ files:
 - lib/getstream_ruby/generated/moderation_client.rb
 - lib/getstream_ruby/generated/video_client.rb
 - lib/getstream_ruby/generated/webhook.rb
+- lib/getstream_ruby/log_redaction.rb
+- lib/getstream_ruby/request_logging.rb
 - lib/getstream_ruby/resources/feed.rb
+- lib/getstream_ruby/retry_config.rb
 - lib/getstream_ruby/stream_response.rb
 - lib/getstream_ruby/version.rb
 homepage: https://getstream.io
@@ -1556,7 +1545,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
+rubygems_version: 3.3.3
 signing_key:
 specification_version: 4
 summary: Ruby SDK for GetStream