getstream-ruby 8.0.2 → 10.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9147f9cf1a12d531292d5b4e226e6e7c249a618e2b00f1a60e82148878d80524
-  data.tar.gz: 47ba7a4df6a3720660c2485877255010a553ae02b1b807294dcc73582d837263
+  metadata.gz: f7c2582f037fa1be220f8b72647c0a87254d0eeb42af2b5046cdb410852f25d7
+  data.tar.gz: a880f9c77e414fe74ee4dd7d82631c927b5af8b4c8b0dca6fca5d00386ff08cf
 SHA512:
-  metadata.gz: 54a465d565efc229cec95322f5975b3aa212198f9e75ce6de338f0dbd01930f79aac2f5fa3b412af57d8b24583e68c4dc7477a8fcf949800349b95dced779d0a
-  data.tar.gz: 48344c6287f4a46e94262b7d2ef51a96a9265fac15f4733f502e5dcd345cfcfff00c9e923b6ce69db949c5992575df3a6f95542d083e05d685af60aaf0e27767
+  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/generated/chat_client.rb

@@ -297,6 +297,35 @@ module GetStream
         )
       end
 
+      # Returns a channel by its CID without creating it. Responds with 404 when the channel does not exist, so it doubles as an existence check. Pass state=true to also load messages, read state and watchers.
+      #
+      # @param _type [String]
+      # @param _id [String]
+      # @param state [Boolean]
+      # @param messages_limit [Integer]
+      # @param members_limit [Integer]
+      # @param watchers_limit [Integer]
+      # @return [Models::ChannelStateResponse]
+      def get_channel(_type, _id, state = nil, messages_limit = nil, members_limit = nil, watchers_limit = nil)
+        path = '/api/v2/chat/channels/{type}/{id}'
+        # Replace path parameters
+        path = path.gsub('{type}', _type.to_s)
+        path = path.gsub('{id}', _id.to_s)
+        # Build query parameters
+        query_params = {}
+        query_params['state'] = state unless state.nil?
+        query_params['messages_limit'] = messages_limit unless messages_limit.nil?
+        query_params['members_limit'] = members_limit unless members_limit.nil?
+        query_params['watchers_limit'] = watchers_limit unless watchers_limit.nil?
+
+        # Make the API request
+        @client.make_request(
+          :get,
+          path,
+          query_params: query_params
+        )
+      end
+
       # Updates certain fields of the channelSends events:- channel.updated
       #
       # @param _type [String]

data/lib/getstream_ruby/generated/feed.rb

@@ -32,11 +32,17 @@ module GetStream
       # Create a single feed for a given feed group
       #
       # @param get_or_create_feed_request [GetOrCreateFeedRequest]
+      # @param language [String]
+      # @param translate_text [Boolean]
       # @return [Models::GetOrCreateFeedResponse]
-      def get_or_create_feed(get_or_create_feed_request)
+      def get_or_create_feed(get_or_create_feed_request, language = nil, translate_text = nil)
+        # Build query parameters
+        query_params = {}
+        query_params['language'] = language unless language.nil?
+        query_params['translate_text'] = translate_text unless translate_text.nil?
 
         # Delegate to the FeedsClient
-        @client.feeds.get_or_create_feed(@feed_group_id, @feed_id, get_or_create_feed_request)
+        @client.feeds.get_or_create_feed(@feed_group_id, @feed_id, get_or_create_feed_request, query_params)
       end
 
       # Update an existing feed
@@ -139,11 +145,17 @@ module GetStream
       # Query pinned activities for a feed with filter query
       #
       # @param query_pinned_activities_request [QueryPinnedActivitiesRequest]
+      # @param language [String]
+      # @param translate_text [Boolean]
       # @return [Models::QueryPinnedActivitiesResponse]
-      def query_pinned_activities(query_pinned_activities_request)
+      def query_pinned_activities(query_pinned_activities_request, language = nil, translate_text = nil)
+        # Build query parameters
+        query_params = {}
+        query_params['language'] = language unless language.nil?
+        query_params['translate_text'] = translate_text unless translate_text.nil?
 
         # Delegate to the FeedsClient
-        @client.feeds.query_pinned_activities(@feed_group_id, @feed_id, query_pinned_activities_request)
+        @client.feeds.query_pinned_activities(@feed_group_id, @feed_id, query_pinned_activities_request, query_params)
       end
 
     end