ld-eventsource 2.3.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56eca88c610f3aa1f572426034422f66f343ce30553c9d2e281462c4f3efe831
-  data.tar.gz: a9719f1e29695c0468c8b745239feb71041d5735e32f071fd77873866518bad5
+  metadata.gz: 3ba844140cea3837caa7a02aa4676af7483faa11230a353da421e435932553b3
+  data.tar.gz: 30619609829908038a63d8302cefdbe8bda6935dc691ceaaabff225f2747da8c
 SHA512:
-  metadata.gz: 2daad080ae032ab394dd4700e6bc22d20d167aca0e0a7ba9f74b41544ff0c5232cb0d34b6803fdc09342d95608732bea6c9ee7cef87bc912fef9a8ab10ccfb26
-  data.tar.gz: 520224cf097791d2942ed0662dc29d94bff02c979fdebde479186efb21dbfa052aa80eee62779be723db2c918a9dd34a19ab4eea343453b7e114524a3dc23eb5
+  metadata.gz: 6b0ffc7be77854b053bc561d1389c3cb6327290066697ca40e6d7a96e29ad9192013b733e9b2973d0b1ebcb5aee66e0eb530066f6bbc3762f95fa80d28183b33
+  data.tar.gz: 7efe744ebf4c9cb9b4302fbbf5d2348a31a3f99f45de8cbd54346d2ac5eed8de8c8e79d5120888a2103d712afaf71035ebeec712664a797c229694a561b7dbe9

data/lib/ld-eventsource/client.rb

@@ -162,8 +162,9 @@ module SSE
         reconnect_reset_interval: reconnect_reset_interval)
       @first_attempt = true
 
-      @on = { event: ->(_) {}, error: ->(_) {} }
+      @on = { event: ->(_) {}, error: ->(_) {}, connect: ->(_) {} }
       @last_id = last_event_id
+      @query_params_callback = nil
 
       yield self if block_given?
 
@@ -206,6 +207,56 @@ module SSE
       @on[:error] = action
     end
 
+    #
+    # Specifies a block or Proc to be called when a successful connection is established. This will
+    # be called with a single parameter containing the HTTP response headers. It is called
+    # from the same worker thread that reads the stream, so no more events will be dispatched until
+    # it returns.
+    #
+    # This is called every time a connection is successfully established, including on reconnections
+    # after a failure. It allows you to inspect server response headers such as rate limits, custom
+    # metadata, or fallback directives (e.g., `X-LD-FD-FALLBACK`).
+    #
+    # Any previously specified connect handler will be replaced.
+    #
+    # @yieldparam headers [Hash, nil] the HTTP response headers from the successful connection,
+    #   or nil if not available. The headers object uses case-insensitive keys (via the http gem's
+    #   HTTP::Headers).
+    #
+    def on_connect(&action)
+      @on[:connect] = action
+    end
+
+    #
+    # Specifies a block or Proc to generate query parameters dynamically. This will be called before
+    # each connection attempt (both initial connection and reconnections), allowing you to update
+    # query parameters based on the current client state.
+    #
+    # The block should return a Hash with string keys and string values, which will be merged with
+    # any existing query parameters in the base URI. If the callback raises an exception, it will be
+    # logged and the connection will proceed with the base URI's query parameters (or no query
+    # parameters if none were present).
+    #
+    # This is useful for scenarios where query parameters need to reflect the current state of the
+    # client, such as sending a "basis" parameter that represents what data the client already has.
+    #
+    # @example Using dynamic query parameters
+    #     client = SSE::Client.new(base_uri) do |c|
+    #       c.query_params do
+    #         {
+    #           "basis" => (selector.state if selector.defined?),
+    #           "filter" => filter_key
+    #         }.compact
+    #       end
+    #       c.on_event { |event| handle_event(event) }
+    #     end
+    #
+    # @yieldreturn [Hash<String, String>] a hash of query parameter names to values
+    #
+    def query_params(&action)
+      @query_params_callback = action
+    end
+
     #
     # Permanently shuts down the client and its connection. No further events will be dispatched. This
     # has no effect if called a second time.
@@ -289,15 +340,18 @@ module SSE
         end
         cxn = nil
         begin
-          @logger.info { "Connecting to event stream at #{@uri}" }
-          cxn = @http_client.request(@method, @uri, build_opts)
+          uri = build_uri_with_query_params
+          @logger.info { "Connecting to event stream at #{uri}" }
+          cxn = @http_client.request(@method, uri, build_opts)
+          headers = cxn.headers
           if cxn.status.code == 200
             content_type = cxn.content_type.mime_type
             if content_type && content_type.start_with?("text/event-stream")
+              @on[:connect].call(headers)  # Notify connect callback with headers
               return cxn  # we're good to proceed
             else
               reset_http
-              err = Errors::HTTPContentTypeError.new(content_type)
+              err = Errors::HTTPContentTypeError.new(content_type, headers)
               @on[:error].call(err)
               @logger.warn { "Event source returned unexpected content type '#{content_type}'" }
             end
@@ -305,7 +359,7 @@ module SSE
             body = cxn.to_s  # grab the whole response body in case it has error details
             reset_http
             @logger.info { "Server returned error status #{cxn.status.code}" }
-            err = Errors::HTTPStatusError.new(cxn.status.code, body)
+            err = Errors::HTTPStatusError.new(cxn.status.code, body, headers)
             @on[:error].call(err)
           end
         rescue
@@ -397,5 +451,27 @@ module SSE
         {headers: build_headers, body: resolved_payload.to_s}
       end
     end
+
+    def build_uri_with_query_params
+      uri = @uri.dup
+
+      if @query_params_callback
+        begin
+          dynamic_params = @query_params_callback.call
+          if dynamic_params.is_a?(Hash) && !dynamic_params.empty?
+            existing_params = uri.query ? URI.decode_www_form(uri.query).to_h : {}
+            merged_params = existing_params.merge(dynamic_params)
+            uri.query = URI.encode_www_form(merged_params)
+          elsif !dynamic_params.is_a?(Hash)
+            @logger.warn { "query_params callback returned non-Hash value: #{dynamic_params.class}, ignoring" }
+          end
+        rescue StandardError => e
+          @logger.warn { "query_params callback raised an exception: #{e.inspect}, proceeding with base URI" }
+          @logger.debug { "Exception trace: #{e.backtrace}" }
+        end
+      end
+
+      uri
+    end
   end
 end

data/lib/ld-eventsource/errors.rb

@@ -9,9 +9,10 @@ module SSE
     # handler specified in {Client#on_error}.
     #
     class HTTPStatusError < StandardError
-      def initialize(status, message)
+      def initialize(status, message, headers = nil)
         @status = status
         @message = message
+        @headers = headers
         super("HTTP error #{status}")
       end
 
@@ -22,6 +23,13 @@ module SSE
       # The response body, if any.
       # @return [String]
       attr_reader :message
+
+      # The HTTP response headers, if any.
+      #
+      # The headers object uses case-insensitive keys (via the http gem's HTTP::Headers).
+      #
+      # @return [Hash, nil] the response headers, or nil if not available
+      attr_reader :headers
     end
 
     #
@@ -29,14 +37,22 @@ module SSE
     # handler specified in {Client#on_error}.
     #
     class HTTPContentTypeError < StandardError
-      def initialize(type)
+      def initialize(type, headers = nil)
         @content_type = type
+        @headers = headers
         super("invalid content type \"#{type}\"")
       end
 
       # The HTTP content type.
       # @return [String]
       attr_reader :type
+
+      # The HTTP response headers, if any.
+      #
+      # The headers object uses case-insensitive keys (via the http gem's HTTP::Headers).
+      #
+      # @return [Hash, nil] the response headers, or nil if not available
+      attr_reader :headers
     end
 
     #

data/lib/ld-eventsource/version.rb

@@ -1,3 +1,3 @@
 module SSE
-  VERSION = "2.3.0" # x-release-please-version
+  VERSION = "2.5.0" # x-release-please-version
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ld-eventsource
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.5.0
 platform: ruby
 authors:
 - LaunchDarkly
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-09-04 00:00:00.000000000 Z
+date: 2026-01-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger