stream-chat-ruby 3.26.1 → 3.26.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f76091a8b305ba916ed2217c639f46deca24f997c148aaac21dd1cdeb7664482
-  data.tar.gz: bd4e54bd949250094bb2d3ee3c350312f3faebe927c5521733e9ffd6bb08e90a
+  metadata.gz: '019bf5c538cd43fe7a5faef6b980bf00818756ec5cc470d0e61f8e5d610bbf4e'
+  data.tar.gz: 389642e627468500058a1aa007dae4a9b2bda9bcda2e73e5fd30218730e74ce3
 SHA512:
-  metadata.gz: c4352825a7532841cb8667de383e977c6a8ae9908bd2e44dc8de5f714cb8ea6a186d90e7b820b795ce097f78492838bb453dba1e216a7d8284ff6f7347f0b4d4
-  data.tar.gz: f9e18435119dda8be34f8e282004fe9597cee212e34d5a676428d562005c44cdbcee8af19c4c3e2c878268c86beca1120a9173e9fe632341ee46221e6b758d38
+  metadata.gz: c2cbc7e4c1f481fefea8d06ee3a7e4e8c3c0c8e26a068b0754574588c0d65ce262886ffe3ebcee86196085df7d520ad4b1f6234c8b87351ba57d61e8d29132e2
+  data.tar.gz: 92abc3b3c173377ac3d5bc19957221f055fdfb15eabc38d8a64ef302be883b3441db8bbf22da87b937dbbb88f726344430bc5e6a8b2376f9a0f1c90734ff7d0a

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--profile 25

data/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [3.26.2](https://github.com/GetStream/stream-chat-ruby/compare/v3.26.1...v3.26.2) (2026-06-30)
+
+
+### Features
+
+* **webhooks:** verify_and_parse_* API for compressed payloads (CHA-3071) ([#211](https://github.com/GetStream/stream-chat-ruby/issues/211)) ([dd76c8f](https://github.com/GetStream/stream-chat-ruby/commit/dd76c8f39d0fae98c3d2c331635e9369b40e3696))
+
+
+### Bug Fixes
+
+* guard StreamAPIException against empty and non-integer error bodies ([#217](https://github.com/GetStream/stream-chat-ruby/issues/217)) ([415f6c0](https://github.com/GetStream/stream-chat-ruby/commit/415f6c0bd7b51b87631c5a1e8f821e50a5def2ec))
+
+
+### Other
+
+* before-message-send hook attempt timeout (CHA-3267) ([#216](https://github.com/GetStream/stream-chat-ruby/issues/216)) ([e721776](https://github.com/GetStream/stream-chat-ruby/commit/e721776376c064b434485bd4cb4188762f9f3c2b)), closes [GetStream/chat#13541](https://github.com/GetStream/chat/issues/13541)
+* **spec:** clean fellowship sediment + retry commands eventually ([#212](https://github.com/GetStream/stream-chat-ruby/issues/212)) ([f3c8f5b](https://github.com/GetStream/stream-chat-ruby/commit/f3c8f5be841f95c2e0e399d3d180d7565d80fd6a))
+
 ### [3.26.1](https://github.com/GetStream/stream-chat-ruby/compare/v3.25.0...v3.26.1) (2026-04-29)
 
 

data/lib/stream-chat/client.rb

@@ -1,7 +1,11 @@
 # typed: strict
 # frozen_string_literal: true
 
+require 'base64'
 require 'open-uri'
+require 'openssl'
+require 'stringio'
+require 'zlib'
 require 'faraday'
 require 'faraday/multipart'
 require 'faraday/net_http_persistent'
@@ -18,6 +22,7 @@ require 'stream-chat/util'
 require 'stream-chat/types'
 require 'stream-chat/moderation'
 require 'stream-chat/channel_batch_updater'
+require 'stream-chat/webhook'
 
 module StreamChat
   DEFAULT_BLOCKLIST = 'profanity'
@@ -698,11 +703,57 @@ module StreamChat
       get('rate_limits', params: params)
     end
 
-    # Verify the signature added to a webhook event.
+    # Verify the signature on a webhook event using the client's API secret.
+    #
+    # Backward-compatible boolean helper. New integrations should call
+    # {#verify_and_parse_webhook} (or the SQS / SNS variants), which also handle
+    # gzip payload compression and return the parsed event.
     sig { params(request_body: String, x_signature: String).returns(T::Boolean) }
     def verify_webhook(request_body, x_signature)
-      signature = OpenSSL::HMAC.hexdigest('SHA256', @api_secret, request_body)
-      signature == x_signature
+      StreamChat::Webhook.verify_signature(request_body, x_signature, @api_secret)
+    end
+
+    # Verify and parse an HTTP webhook event.
+    #
+    # Decompresses `body` when gzipped (detected from the body bytes), verifies
+    # the `X-Signature` header against the client's API secret, and returns the
+    # parsed event as a `Hash`. Typed event classes are planned for a future
+    # release.
+    #
+    # @param body [String, Array<Integer>] Raw HTTP request body bytes Stream
+    #   signed.
+    # @param signature [String] Value of the `X-Signature` header.
+    # @return [Hash] The parsed event.
+    # @raise [InvalidWebhookError] When the signature does not match or the
+    #   gzip envelope is malformed.
+    sig do
+      params(
+        body: T.any(String, T::Array[Integer]),
+        signature: String
+      ).returns(T::Hash[String, T.untyped])
+    end
+    def verify_and_parse_webhook(body, signature)
+      StreamChat::Webhook.verify_and_parse_webhook(body, signature, @api_secret)
+    end
+
+    # Parse an SQS-delivered webhook event (decode only; Stream does not HMAC-sign SQS bodies).
+    #
+    # @param message_body [String] SQS message `Body` string.
+    # @return [Hash] The parsed event.
+    # @raise [InvalidWebhookError] on malformed base64 or gzip envelope
+    sig { params(message_body: String).returns(T::Hash[String, T.untyped]) }
+    def parse_sqs(message_body)
+      StreamChat::Webhook.parse_sqs(message_body)
+    end
+
+    # Parse an SNS-delivered webhook event (unwraps envelope JSON when needed).
+    #
+    # @param message [String] Raw SNS POST body or pre-extracted Message string.
+    # @return [Hash] The parsed event.
+    # @raise [InvalidWebhookError] on decode failures
+    sig { params(message: String).returns(T::Hash[String, T.untyped]) }
+    def parse_sns(message)
+      StreamChat::Webhook.parse_sns(message)
     end
 
     # Allows you to send custom events to a connected user.

data/lib/stream-chat/errors.rb

@@ -21,14 +21,28 @@ module StreamChat
     def initialize(response)
       super()
       @response = response
+
+      # Seed defaults first so the typed readers never return nil. A 5xx can
+      # arrive with an empty or non-JSON body (e.g. a load balancer emitting a
+      # bare 503), and an error envelope may omit "code"/"message" or send a
+      # non-integer "code". Without these defaults, reading error_code on such
+      # an exception raised a Sorbet TypeError that masked the real HTTP error.
+      @json_response = T.let(false, T::Boolean)
+      @error_code = T.let(-1, Integer)
+      @error_message = T.let('unknown', String)
+
       begin
         parsed_response = JSON.parse(response.body)
-        @json_response = T.let(true, T::Boolean)
-        @error_code = T.let(parsed_response.fetch('code', 'unknown'), Integer)
-        @error_message = T.let(parsed_response.fetch('message', 'unknown'), String)
       rescue JSON::ParserError
-        @json_response = false
+        return
       end
+      return unless parsed_response.is_a?(Hash)
+
+      @json_response = true
+      code = parsed_response['code']
+      @error_code = code if code.is_a?(Integer)
+      msg = parsed_response['message']
+      @error_message = msg if msg.is_a?(String)
     end
 
     sig { returns(String) }
@@ -47,4 +61,15 @@ module StreamChat
   end
 
   class StreamChannelException < StandardError; end
+
+  # Raised by webhook verify/parse helpers when the HMAC does not match or a
+  # gzip/base64/JSON envelope cannot be decoded. The message identifies which
+  # failure mode fired; the class-level constants below are the canonical
+  # strings for callers that prefer exact-match filtering over substring.
+  class InvalidWebhookError < StandardError
+    SIGNATURE_MISMATCH = 'signature mismatch'
+    INVALID_BASE64 = 'invalid base64 encoding'
+    GZIP_FAILED = 'gzip decompression failed'
+    INVALID_JSON = 'invalid JSON payload'
+  end
 end

data/lib/stream-chat/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module StreamChat
-  VERSION = '3.26.1'
+  VERSION = '3.26.2'
 end

data/lib/stream-chat/webhook.rb

@@ -0,0 +1,206 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+require 'openssl'
+require 'sorbet-runtime'
+require 'stringio'
+require 'zlib'
+
+require 'stream-chat/errors'
+
+module StreamChat
+  # Stateless helpers implementing the cross-SDK webhook contract documented at
+  # https://getstream.io/chat/docs/node/webhooks_overview/.
+  #
+  # The composite functions (`verify_and_parse_webhook`, `parse_sqs`,
+  # `parse_sns`) are the recommended entry points. The primitives
+  # they compose (`gunzip_payload`, `decode_sqs_payload`, `decode_sns_payload`,
+  # `verify_signature`, `parse_event`) are exposed so callers can build custom
+  # flows or run individual steps in isolation.
+  #
+  # The Ruby SDK currently returns the parsed JSON as a `Hash`; typed event
+  # classes will land in a future release.
+  module Webhook # rubocop:disable Metrics/ModuleLength
+    extend T::Sig
+
+    GZIP_MAGIC = T.let("\x1f\x8b".b.freeze, String)
+
+    # Coerces the webhook body into a binary `String` regardless of whether
+    # the caller hands us a `String` (HTTP `request.raw_post`) or an array of
+    # bytes (which is what some Ruby SQS clients yield when the message body
+    # is binary safe).
+    sig { params(body: T.any(String, T::Array[Integer])).returns(String) }
+    def self.normalize_body(body)
+      raw =
+        if body.is_a?(Array)
+          body.pack('C*')
+        else
+          String.new(body)
+        end
+      raw.force_encoding(Encoding::ASCII_8BIT)
+    end
+
+    # Returns `body` unchanged unless it starts with the gzip magic
+    # (`1f 8b`, per RFC 1952), in which case the gzip stream is inflated and
+    # the decompressed bytes are returned.
+    #
+    # Magic-byte detection (rather than relying on a header) keeps the same
+    # handler correct when middleware - Rack, Rails - auto-decompresses the
+    # request before your code sees it.
+    sig { params(body: T.any(String, T::Array[Integer])).returns(String) }
+    def self.gunzip_payload(body)
+      raw = normalize_body(body)
+      return raw unless raw.start_with?(GZIP_MAGIC)
+
+      begin
+        Zlib::GzipReader.new(StringIO.new(raw)).read.force_encoding(Encoding::ASCII_8BIT)
+      rescue Zlib::Error
+        raise InvalidWebhookError, InvalidWebhookError::GZIP_FAILED
+      end
+    end
+
+    # Reverses the SQS firehose envelope: the message `Body` is base64-decoded
+    # and, when the result begins with the gzip magic, gzip-decompressed. The
+    # same call works whether or not Stream is currently compressing payloads.
+    sig { params(body: String).returns(String) }
+    def self.decode_sqs_payload(body)
+      decoded =
+        begin
+          Base64.strict_decode64(body)
+        rescue ArgumentError
+          raise InvalidWebhookError, InvalidWebhookError::INVALID_BASE64
+        end
+      gunzip_payload(decoded)
+    end
+
+    # Reverses an SNS HTTP notification envelope. When `notification_body` is a
+    # JSON envelope (`{"Type":"Notification","Message":"..."}`), the inner
+    # `Message` field is extracted and run through the SQS pipeline
+    # (base64-decode, then gzip-if-magic). When the input is not a JSON
+    # envelope it is treated as the already-extracted `Message` string, so
+    # call sites that pre-unwrap continue to work.
+    sig { params(notification_body: String).returns(String) }
+    def self.decode_sns_payload(notification_body)
+      inner = extract_sns_message(notification_body)
+      decode_sqs_payload(inner.nil? ? notification_body : inner)
+    end
+
+    sig { params(notification_body: String).returns(T.nilable(String)) }
+    def self.extract_sns_message(notification_body)
+      trimmed = notification_body.to_s.lstrip
+      return nil unless trimmed.start_with?('{')
+
+      begin
+        parsed = JSON.parse(trimmed)
+      rescue JSON::ParserError
+        return nil
+      end
+      return nil unless parsed.is_a?(Hash)
+
+      message = parsed['Message']
+      message.is_a?(String) ? message : nil
+    end
+    private_class_method :extract_sns_message
+
+    # Constant-time HMAC-SHA256 verification of `signature` against the digest
+    # of `body` keyed by `secret`.
+    #
+    # The signature is always computed over the **uncompressed** JSON bytes,
+    # so callers that decoded a gzipped or base64-wrapped payload must pass
+    # the inflated bytes here.
+    sig do
+      params(
+        body: T.any(String, T::Array[Integer]),
+        signature: String,
+        secret: String
+      ).returns(T::Boolean)
+    end
+    def self.verify_signature(body, signature, secret)
+      raw = normalize_body(body)
+      expected = OpenSSL::HMAC.hexdigest('SHA256', secret, raw)
+      constant_time_equal?(expected, signature)
+    end
+
+    # Parse a JSON-encoded webhook event into a `Hash`.
+    #
+    # The Ruby SDK currently returns the parsed JSON as a `Hash`; typed event
+    # classes will land in a future release. The function name matches the
+    # documented primitive so callers can swap in a typed parser later without
+    # changing call sites.
+    sig { params(payload: String).returns(T::Hash[String, T.untyped]) }
+    def self.parse_event(payload)
+      result =
+        begin
+          JSON.parse(payload)
+        rescue JSON::ParserError
+          raise InvalidWebhookError, InvalidWebhookError::INVALID_JSON
+        end
+      raise InvalidWebhookError, InvalidWebhookError::INVALID_JSON unless result.is_a?(Hash)
+
+      result
+    end
+
+    sig do
+      params(
+        payload: String,
+        signature: String,
+        secret: String
+      ).returns(T::Hash[String, T.untyped])
+    end
+    def self.verify_and_parse_internal(payload, signature, secret)
+      raise InvalidWebhookError, InvalidWebhookError::SIGNATURE_MISMATCH unless verify_signature(payload, signature, secret)
+
+      parse_event(payload)
+    end
+    private_class_method :verify_and_parse_internal
+
+    # Decompress `body` when gzipped, verify the HMAC `signature`, and return
+    # the parsed event.
+    sig do
+      params(
+        body: T.any(String, T::Array[Integer]),
+        signature: String,
+        secret: String
+      ).returns(T::Hash[String, T.untyped])
+    end
+    def self.verify_and_parse_webhook(body, signature, secret)
+      verify_and_parse_internal(gunzip_payload(body), signature, secret)
+    end
+
+    # Decode the SQS `Body` (base64, then gzip-if-magic) and return the parsed
+    # event JSON. Stream does not ship an application-level signature on SQS payloads.
+    sig { params(message_body: String).returns(T::Hash[String, T.untyped]) }
+    def self.parse_sqs(message_body)
+      parse_event(decode_sqs_payload(message_body))
+    end
+
+    # Decode SNS (unwrap envelope when needed) and return the parsed event JSON.
+    sig { params(message: String).returns(T::Hash[String, T.untyped]) }
+    def self.parse_sns(message)
+      parse_event(decode_sns_payload(message))
+    end
+
+    # Timing-safe equality check used to compare the locally computed HMAC
+    # with the `X-Signature` header. Prefers the OpenSSL primitive when the
+    # Ruby build exposes it, otherwise falls back to a manual byte XOR loop
+    # that does not short-circuit on the first mismatch.
+    sig { params(left: String, right: String).returns(T::Boolean) }
+    def self.constant_time_equal?(left, right)
+      a = left.b
+      b = right.b
+      return false unless a.bytesize == b.bytesize
+
+      if OpenSSL.respond_to?(:fixed_length_secure_compare)
+        OpenSSL.fixed_length_secure_compare(a, b)
+      else
+        a_bytes = a.bytes
+        b_bytes = b.bytes
+        diff = 0
+        a_bytes.each_with_index { |byte, i| diff |= byte ^ b_bytes[i] }
+        diff.zero?
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stream-chat-ruby
 version: !ruby/object:Gem::Version
-  version: 3.26.1
+  version: 3.26.2
 platform: ruby
 authors:
 - getstream.io
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-29 00:00:00.000000000 Z
+date: 2026-06-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -113,6 +113,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".rspec"
 - ".rubocop.yml"
 - ".versionrc.js"
 - CHANGELOG.md
@@ -136,6 +137,7 @@ files:
 - lib/stream-chat/types.rb
 - lib/stream-chat/util.rb
 - lib/stream-chat/version.rb
+- lib/stream-chat/webhook.rb
 - stream-chat.gemspec
 homepage: http://github.com/GetStream/stream-chat-ruby
 licenses: []