x-streams 1.0.0

data/lib/x/streams/stopper.rb

@@ -0,0 +1,366 @@
+# frozen_string_literal: true
+
+module X
+  module Streams
+    # Stops the streams a streaming client runs, from any thread, for good
+    #
+    # A stream waits on the API for most of its life, so its block, which runs only when an object arrives, cannot stop
+    # one that delivers nothing. Each stream runs in a thread the stopper knows, and stop raises Stopped in each, which
+    # is delivered as the stream next blocks, mostly as it waits on the API, ending a read, a connection, or a wait to
+    # reconnect, but never in the block of the stream, the on_response or on_reconnect of its client, or the
+    # save_tokens a refresh is reported to, which guard runs, so that what each does is never cut short. A stopper
+    # that was stopped stays stopped, so a stream that had not begun when stop was called, as one a thread started
+    # just before it may not have, never begins.
+    #
+    # Internal to x-streams: StreamingClient#stop stops the streams it runs with it.
+    #
+    # @api private
+    class Stopper
+      # Raised in the thread of a stream that stop stops, or by a run that reads the stopper was stopped; each stopper
+      # raises a subclass of its own, which only its run rescues to return nil
+      #
+      # It is not a StandardError, as Timeout::ExitException is not, so that a callback the stream runs where a stop is
+      # delivered, as an object_class whose from_response looks something up or a load_tokens that reads a store, cannot
+      # rescue it, and raise an error of its own or let the stream go on, rather than return nil.
+      class Stopped < Exception; end # rubocop:disable Lint/InheritException
+      private_constant :Stopped
+
+      # A stream a stopper runs: the thread it runs in, whether it runs in a fiber a Fiber scheduler runs, and whether a
+      # guarded block of it is running
+      class Stream
+        # The thread the stream runs in
+        # @api private
+        # @return [Thread] the thread
+        attr_reader :thread
+
+        # Whether a Fiber scheduler runs the non-blocking fiber of the stream
+        #
+        # It does for a stream in an Async task.
+        #
+        # Such a stream waits on the API in the scheduler, not in a read of its own, so a stop raised in its thread
+        # would end the scheduler rather than the stream; stop raises in no such stream, which is stopped once its
+        # block returns.
+        #
+        # @api private
+        # @return [Boolean] true if a Fiber scheduler runs the fiber of the stream
+        attr_reader :scheduled
+
+        # Whether a guarded block of the stream is running
+        # @api private
+        # @return [Boolean] true while a guarded block of the stream runs
+        attr_accessor :guarded
+
+        # Initialize a stream that runs in the current fiber
+        #
+        # No guarded block of it is running.
+        #
+        # @api private
+        # @return [Stream] a new stream
+        def initialize
+          @thread = Thread.current
+          @scheduled = !Fiber.blocking? && !Fiber.scheduler.nil?
+          @guarded = false
+        end
+
+        # Whether stop raises in the stream
+        #
+        # It does if no guarded block of the stream runs, and no Fiber scheduler runs it.
+        #
+        # @api private
+        # @return [Boolean] true if stop raises in the thread of the stream
+        def interruptible? = !guarded && !scheduled
+      end
+      private_constant :Stream
+
+      # The key of the fiber-local variable that holds the stopper and the stream that run in the current fiber
+      CURRENT = :__x_streams_stopper_current__
+      private_constant :CURRENT
+
+      # Run a block that stop does not cut short, deferring a stop until it returns
+      #
+      # No stop is held back in the thread while a guarded block of a stream runs, and stop raises in no stream whose
+      # guarded block runs, so a stream whose block is held, as in a Fiber an Enumerator iterates, is not stopped in
+      # the place of another stream of the same thread. A stop held back as the block began is discarded, and once the
+      # block returns, a stream whose stopper was stopped is stopped the next time it waits on the API, as one stop
+      # raises in is. A block that ends by raising, throwing, or breaking ends the stream as it does, since no stop was
+      # held back to end the stream in its place as it unwinds.
+      #
+      # @api private
+      # @yield the block
+      # @return [Object] what the block returns
+      # @example Pass an object to the block of a stream
+      #   X::Streams::Stopper.guard { block.call(post) }
+      def self.guard(&)
+        stopper, stream = Thread.current[CURRENT]
+        return Thread.handle_interrupt(Stopped => :never, &) unless stream
+
+        result = guarding_stream(stream, &)
+        stopper.__send__(:stop_returned, stream)
+        result
+      end
+
+      # Run a block with a stream marked as running a guarded block
+      #
+      # The mark the stream had is restored after. The stream is marked before a stop held back as the block begins
+      # is discarded, so that stop, which raises in no stream so marked, raises in it either before the discard or
+      # not at all, and none is held back while the block runs. The stream is stopped once the block returns.
+      #
+      # @api private
+      # @param stream [Stream] the stream
+      # @yield the block
+      # @return [Object] what the block returns
+      def self.guarding_stream(stream)
+        outer = stream.guarded
+        begin
+          stream.guarded = true
+          discard_stop
+          yield
+        ensure
+          stream.guarded = outer
+        end
+      end
+      private_class_method :guarding_stream
+
+      # Discard every stop held back in the current thread
+      #
+      # Each call of stop raises in a stream that is reading, and Ruby holds each back on its own, so a stream stopped
+      # more than once holds back as many; each is discarded in turn until none is left, so that none cuts a block short
+      # or reaches the caller once the stream returns.
+      #
+      # @api private
+      # @return [nil]
+      def self.discard_stop
+        Thread.handle_interrupt(Stopped => :immediate) {}
+      rescue Stopped
+        retry
+      end
+      private_class_method :discard_stop
+
+      # A callable that calls another, then stops its stream if it was stopped
+      #
+      # A stream calls it for each keep-alive, so a stream a Fiber scheduler runs, which stop raises in no read of,
+      # is stopped at the next keep-alive X sends, within 20 seconds, though it delivers no object.
+      #
+      # @api private
+      # @param callable [#call] the callable
+      # @return [Proc] the callable that calls it and then stops the stream
+      # @example Stop a stream at a keep-alive
+      #   X::Streams::Stopper.checking(alive)
+      def self.checking(callable)
+        lambda do
+          callable.call
+          stopper, stream = Thread.current[CURRENT]
+          stopper&.__send__(:stop_returned, stream)
+        end
+      end
+
+      # The most seconds a stream a Fiber scheduler runs waits to reconnect before it checks whether it was stopped
+      PAUSE = 1
+      private_constant :PAUSE
+
+      # Wait to reconnect, yielding the seconds to sleep, and stop the stream if stopped
+      #
+      # A stream a Fiber scheduler runs, which stop raises in no wait of, waits a second at a time, and is stopped
+      # before each second and before it reconnects, so a stream that cannot connect, or that X answers with an error,
+      # is stopped within a second, though it delivers no object and reads no keep-alive. Any other stream waits the
+      # seconds at once, which stop cuts short.
+      #
+      # @api private
+      # @param seconds [Integer, Float] the seconds to wait
+      # @yieldparam seconds [Integer, Float] the seconds to sleep
+      # @return [void]
+      # @example Wait to reconnect
+      #   X::Streams::Stopper.pausing(5) { |seconds| sleep(seconds) }
+      def self.pausing(seconds)
+        stopper, stream = Thread.current[CURRENT]
+        return yield(seconds) unless stream&.scheduled
+
+        while seconds.positive?
+          stopper.__send__(:stop_returned, stream)
+          yield [seconds, PAUSE].min
+          seconds -= PAUSE
+        end
+        stopper.__send__(:stop_returned, stream)
+      end
+
+      # A callable that calls another with guard, or nil for no callable
+      #
+      # stop does not cut short the callable it calls, as it does not the block of guard.
+      #
+      # @api private
+      # @param callable [#call, nil] the callable
+      # @return [Proc, nil] the callable that guards it, or nil if it is nil
+      # @example Guard the on_response of a client
+      #   X::Streams::Stopper.guarding(client.on_response)
+      def self.guarding(callable) = callable && ->(*arguments) { guard { callable.call(*arguments) } }
+
+      # Initialize a stopper that knows no stream, and was not stopped
+      #
+      # @api private
+      # @return [Stopper] a new stopper
+      def initialize
+        @streams = [] #: Array[Stream]
+        @lock = Mutex.new
+        @stopped = false
+        @stop = Class.new(Stopped) #: singleton(Stopped)
+      end
+
+      # Whether the stopper was stopped
+      #
+      # @api private
+      # @return [Boolean] true once stop was called
+      # @example Check whether the streams of a streaming client were stopped
+      #   stopper.stopped? # => false
+      def stopped? = @stopped
+
+      # Run a stream that stop stops, unless the stopper was stopped
+      #
+      # The stream is known to stop while it runs alone, under the lock stop raises under, so stop raises in no
+      # thread that is not running a stream. Whether the stopper was stopped is read under that lock too, and stop
+      # marks it before it takes the lock, so either the stream is known by the time stop raises, or it reads that
+      # the stopper was stopped and never begins. A stop that arrives as the stream ends is discarded once the stream
+      # is no longer known to stop, so it never reaches the caller. Only a stop of this stopper is rescued, so one
+      # of another, as for a stream that runs in the block of this one, ends the stream it stops.
+      #
+      # @api private
+      # @yield runs the stream
+      # @return [Object, nil] what the stream returned, or nil if stop stopped it, or was called before it began
+      # @example Run a stream that stop stops
+      #   stopper.run { reconnect_handler.handle(consumer) { |deliver, alive| read(deliver, alive) } }
+      def run(&)
+        Thread.handle_interrupt(Stopped => :never) do
+          stream = Stream.new
+          raise @stop unless @lock.synchronize { @streams << stream unless stopped? }
+
+          running(stream, &)
+        end
+      rescue @stop
+        nil
+      end
+
+      # Stop every stream the stopper runs, and every one it is asked to run later
+      #
+      # It may be called from the trap of a signal, where no lock can be waited for, and where the thread that holds
+      # the lock may be the one the trap interrupted, so it marks the stopper stopped without the lock, and raises in
+      # the streams under the lock only if it takes it at once. Otherwise a thread of its own waits for the lock and
+      # raises in them, which it does not wait for, since the thread that holds the lock may be waiting for it to
+      # return. A thread of its own raises in them too when it is called in the thread of a stream that is reading,
+      # as from a trap that interrupts a stream on the main thread as it reads, since Stopped raised in the thread
+      # that raises it is held back until the read the trap interrupted returns, which may be never. It raises in no
+      # stream whose guarded block is running, which guard stops as the block returns.
+      #
+      # @api private
+      # @return [nil]
+      # @example Stop the streams of a streaming client
+      #   stopper.stop # => nil
+      def stop
+        @stopped = true
+        (!reading_here? && lock_at_once) ? interrupt_and_unlock : Thread.new { @lock.synchronize { interrupt } }
+        nil
+      end
+
+      private
+
+      # Run a stream the stopper knows as the stream of the current fiber
+      #
+      # The save_tokens of a refresh the stream makes is run under guard too, as its block is, so that a stop waits for
+      # it to store the tokens rather than cut it short and leave the store with a refresh token X no longer accepts.
+      #
+      # @api private
+      # @param stream [Stream] the stream
+      # @yield runs the stream
+      # @return [Object] what the stream returned
+      def running(stream)
+        outer = Thread.current[CURRENT] #: [Stopper, Stream]?
+        begin
+          Thread.current[CURRENT] = [self, stream]
+          RefreshReportGuard.around(self.class.public_method(:guard)) { Thread.handle_interrupt(Stopped => :on_blocking) { yield } }
+        ensure
+          Thread.current[CURRENT] = outer
+          @lock.synchronize { @streams.delete_if { |known| known.equal?(stream) } }
+          self.class.__send__(:discard_stop)
+        end
+      end
+
+      # Hold a stop back for a stream whose guarded block returned once it was stopped
+      #
+      # A stream a Fiber scheduler runs is stopped at once instead, since a stop held back in its thread would be
+      # delivered as the scheduler waits, ending the scheduler rather than the stream. Each keep-alive read before
+      # the stream next waits on the API holds back one more, which the stream discards with the rest as it ends.
+      #
+      # @api private
+      # @param stream [Stream] the stream
+      # @return [void]
+      # @raise [Stopped] if the stopper was stopped and a Fiber scheduler runs the stream
+      def stop_returned(stream)
+        return unless stopped? && !stream.guarded
+        raise @stop if stream.scheduled
+
+        Thread.current.raise(@stop)
+      end
+
+      # Whether a stream the stopper runs is reading in the current thread
+      #
+      # It is as a trap that interrupts the read of a stream on its own thread runs.
+      #
+      # @api private
+      # @return [Boolean] true if a stream runs in the current thread and no guarded block of it is running
+      def reading_here? = @streams.any? { |stream| stream.thread.equal?(Thread.current) && stream.interruptible? }
+
+      # Take the lock if no thread holds it, without waiting for it
+      #
+      # @api private
+      # @return [Boolean] true if it took the lock, or false if a thread holds it, or it cannot be taken here
+      def lock_at_once
+        @lock.try_lock
+      rescue ThreadError
+        false
+      end
+
+      # Raise Stopped in each stream the stopper runs, and release the lock this took
+      # @api private
+      # @return [void]
+      def interrupt_and_unlock
+        interrupt
+      ensure
+        @lock.unlock
+      end
+
+      # Raise Stopped in each stream that is interruptible, under the lock
+      # @api private
+      # @return [void]
+      def interrupt = @streams.each { |stream| stream.thread.raise(@stop) if stream.interruptible? }
+    end
+    private_constant :Stopper
+
+    # Runs the save_tokens of a refresh a stream makes inside the guard of the stream
+    #
+    # x-core runs the callables a refresh reports to inside the callable under this fiber-local key, if one is set,
+    # so that a stop waits for save_tokens to store the tokens rather than cut it short and leave the store with a
+    # refresh token X no longer accepts.
+    #
+    # @api private
+    module RefreshReportGuard
+      # The fiber-local key x-core reads the guard from
+      KEY = :x_core_refresh_report_guard
+
+      # Run a block with a guard set for its refreshes, then set the one before again
+      # @api private
+      # @param guard [#call] the guard, which is passed a block to run
+      # @yield runs the stream
+      # @return [Object] what the block returns
+      # @example Guard the refreshes of a stream
+      #   RefreshReportGuard.around(Stopper.method(:guard)) { stream }
+      def self.around(guard)
+        outer = Thread.current[KEY]
+        begin
+          Thread.current[KEY] = guard
+          yield
+        ensure
+          Thread.current[KEY] = outer
+        end
+      end
+    end
+    private_constant :RefreshReportGuard
+  end
+end

data/lib/x/streams/stream_error.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "x/core"
+require_relative "error"
+
+module X
+  module Streams
+    # Raised for a line of a stream that holds errors and no data
+    #
+    # A stream sends the problems it has in a line of their own, such as the operational-disconnect X sends before it
+    # closes a stream. The line is not an object the stream delivers, so the stream raises this error in place of
+    # passing it to its block, whether the objects are Hashes or are built by an object_class.
+    #
+    # A stream reconnects after a line that holds operational-disconnects alone, as it does after a connection that
+    # dropped, and raises this error once it has no reconnects left. After any other problems it stops, and the error
+    # reaches the caller, who decides whether to open the stream again. The message names the request, and each
+    # problem, and {#problems} holds them, as X::HTTPError#problems holds those of a response the API refused.
+    # {#http_method} and {#uri} are the request of the stream.
+    #
+    # @api public
+    # @example Report the problems that stopped a stream
+    #   begin
+    #     client.streaming.stream("tweets/search/stream") { |post| handle(post) }
+    #   rescue X::StreamError => e
+    #     warn e.problems.map(&:title).join(", ")
+    #   end
+    class ::X::StreamError < Streams::Error
+      # The HTTP method the request of the stream was sent with
+      #
+      # @api public
+      # @return [Symbol, nil] the method, as :get, or nil for an error built without one, such as one a test built
+      # @example Read the method of the stream
+      #   error.http_method # => :get
+      attr_reader :http_method
+
+      # The URI the request of the stream was sent to
+      #
+      # @api public
+      # @return [URI::Generic, nil] the URI, or nil for an error built without one
+      # @example Read the path of the stream
+      #   error.uri.path # => "/2/tweets/search/stream"
+      attr_reader :uri
+
+      # The problems the line of the stream held
+      #
+      # @api public
+      # @return [Array<Problem>] the problems, frozen, in the order the line held them
+      # @example Read the title of each problem
+      #   error.problems.map(&:title) # => ["operational-disconnect"]
+      attr_reader :problems
+
+      # Initialize a new StreamError
+      #
+      # Public, so that code that rescues a StreamError can be tested with one built by hand, as StreamParser builds one
+      # for a line of a stream, and raised with a message alone, as any exception is. The message is the one given, or
+      # else the title and detail of each problem, and names the request, when given its method and URI, as the errors
+      # of x-core name the request that raised them.
+      #
+      # @api public
+      # @param message [String, nil] the message, or nil for the one the problems give
+      # @param problems [Array<Problem>] the problems the line held
+      # @param http_method [Symbol, String, nil] the method of the request of the stream, in any case
+      # @param uri [URI::Generic, nil] the URI of the request of the stream
+      # @return [StreamError] a new instance
+      # @example Create an error
+      #   error = X::StreamError.new(problems: X::Problem.all_from(body), http_method: :get, uri: stream_uri)
+      # @example Raise the error with a message alone, as a test stub may
+      #   raise X::StreamError, "The stream dropped"
+      def initialize(message = nil, problems: [], http_method: nil, uri: nil)
+        @problems = problems.dup.freeze
+        @http_method = http_method&.downcase&.to_sym
+        @uri = uri
+        super(naming_request(message || describe(problems)))
+      end
+
+      private
+
+      # The message, led by the method and path of the request it names, if any
+      #
+      # It names the request as an error of x-core does, as "GET /2/tweets/search/stream: operational-disconnect". An
+      # error that says nothing of what went wrong names no request, so that its message is the name of its class, as
+      # that of any exception raised with no message is.
+      #
+      # @api private
+      # @param message [String, nil] what went wrong, or nil for nothing
+      # @return [String, nil] the message, or nil for none
+      def naming_request(message)
+        http_method, uri = @http_method, @uri
+        return message unless http_method && uri && message
+
+        path = uri.path #: String
+        "#{http_method.upcase} #{path.empty? ? "/" : path}: #{message}"
+      end
+    end
+  end
+end

data/lib/x/streams/stream_parser.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "json"
+require "x/core"
+require_relative "callback_error"
+require_relative "stream_error"
+
+module X
+  module Streams
+    # Reads the lines of a stream the API answered, and decodes each into the object it delivers
+    #
+    # Internal to x-streams: StreamingClient reads streams with it.
+    #
+    # @api private
+    class StreamParser
+      # Line delimiter for streaming responses
+      LINE_DELIMITER = "\r\n"
+
+      # Read a stream the API answered, and yield each object it delivers
+      #
+      # The request of the stream, which its errors name, is the one the response answers, a GET of its URI.
+      #
+      # @api private
+      # @param response [StreamResponse] the successful response of the stream, whose body is not yet read
+      # @param array_class [Class] the class for parsing JSON arrays
+      # @param object_class [Class, #from_response] the class for parsing JSON objects, or one that builds each object
+      #   from the whole line
+      # @param client [Client] the client of the stream, which from_response is passed
+      # @param on_line [#call] a callable passed each line of JSON before it is decoded
+      # @param on_keep_alive [#call] a callable called for each keep-alive, the empty line X sends a quiet stream
+      # @yield [Object] each decoded JSON document from the stream
+      # @return [void]
+      # @raise [InvalidResponse] if a line of the stream is not JSON, which the error holds as its body
+      # @raise [StreamError] if a line holds errors and no data
+      # @raise [CallbackError] if on_line, or the object_class that builds each object, raises, so that the error is
+      #   not taken for one of the stream
+      # @example Process a streaming response
+      #   parser.process(response:, array_class: Array, object_class: Hash, client:, on_line: ->(_) {}, on_keep_alive: -> {}) { |json| puts json }
+      def process(response:, array_class:, object_class:, client:, on_line:, on_keep_alive:, &block)
+        decode = lambda do |line|
+          tagging_callback_errors { on_line.call(line) }
+          body = parse_line(line, response:)
+          tagging_callback_errors { build(body, array_class:, object_class:, client:) }
+        end
+        read_lines(response:, decode:, on_keep_alive:, &block)
+      end
+
+      private
+
+      # Parse a line of the stream, raising for one not JSON or holding errors alone
+      #
+      # A line that holds errors and no data, such as the operational-disconnect X sends before it closes a stream,
+      # is not an object the stream delivers, so it raises StreamError, which holds the problems, whatever the
+      # objects are built as, rather than reach the block as a Hash that holds no data, or build nothing of it with
+      # an object_class that responds to from_response.
+      #
+      # Only this parse is the stream's own, so only a line it cannot parse raises InvalidResponse, which a stream
+      # reconnects after: a JSON::ParserError of on_line or of the object_class is theirs, and stops the stream.
+      #
+      # @api private
+      # @param line [String] the line, tagged UTF-8
+      # @param response [StreamResponse] the response of the stream, whose request the errors name
+      # @return [Object] the parsed line
+      # @raise [InvalidResponse] if the line is not JSON, which the error holds as its body
+      # @raise [StreamError] if the line holds errors and no data
+      def parse_line(line, response:)
+        body = JSON.parse(line)
+        problems = (Hash === body && !body.key?("data")) ? Problem.all_from(body) : [] #: Array[Problem]
+        raise StreamError.new(problems:, http_method: :get, uri: response.uri) unless problems.empty?
+
+        body
+      rescue JSON::ParserError
+        raise InvalidResponse.new(http_response: response.http_response, body: line, http_method: :get, uri: response.uri)
+      end
+
+      # Build the object a line delivers, as the body of a request is decoded
+      #
+      # The line was parsed once already, into Hashes and Arrays, so it is built from what that parse gave rather than
+      # parsed again.
+      #
+      # @api private
+      # @param body [Object] the line, parsed
+      # @param array_class [Class] the class for parsing JSON arrays
+      # @param object_class [Class, #from_response] the class for parsing JSON objects, or one that builds each object
+      #   from the whole line
+      # @param client [Client] the client of the stream, which from_response is passed
+      # @return [Object] the object
+      def build(body, array_class:, object_class:, client:)
+        return object_class.from_response(body, client:) if object_class.respond_to?(:from_response)
+
+        rebuild(body, array_class:, object_class:)
+      end
+
+      # Build a parsed value into the array_class and object_class given
+      #
+      # Each is built as JSON.parse builds it: an object into a new object_class, which is given each of its pairs with
+      # []=, in order, and an array into a new array_class, which is given each of its elements with <<, in order,
+      # each built in turn. Any other value is what the parse gave.
+      #
+      # @api private
+      # @param value [Object] the parsed value
+      # @param array_class [Class] the class for parsing JSON arrays
+      # @param object_class [Class] the class for parsing JSON objects
+      # @return [Object] the value, built
+      def rebuild(value, array_class:, object_class:)
+        case value
+        when Hash then value.each_with_object(object_class.new) { |(key, item), object| object[key] = rebuild(item, array_class:, object_class:) }
+        when Array then value.each_with_object(array_class.new) { |item, array| array << rebuild(item, array_class:, object_class:) }
+        else value
+        end
+      end
+
+      # Run a callback of a line, tagging the error it raises
+      #
+      # The errors a socket raises are the errors a stream reconnects after, as is the InvalidResponse of a line that
+      # is not JSON, so a callback that raises one of them, or a JSON::ParserError of its own, is told apart from a
+      # connection that dropped.
+      #
+      # @api private
+      # @yield [] runs the callback
+      # @return [Object] what the callback returned
+      # @raise [CallbackError] if the callback raised an error
+      def tagging_callback_errors
+        yield
+      rescue => e
+        raise CallbackError, e
+      end
+
+      # Read the body in chunks and yield each line as it completes
+      #
+      # X ends each line it sends, so what is left when the stream ends without a line ending is a line the stream was
+      # cut off within, as when the server closes the connection mid-line. It is dropped rather than parsed, which would
+      # raise InvalidResponse, and back off as from a server error, for a stream that ended, and it is not passed to
+      # on_line, which would report it as an object the API bills: the stream ends as a dropped stream does.
+      #
+      # @api private
+      # @param response [StreamResponse] the response of the stream
+      # @param decode [Proc] the lambda that decodes a line
+      # @param on_keep_alive [#call] a callable called for each empty line
+      # @yield [Object] each decoded JSON document
+      # @return [void]
+      def read_lines(response:, decode:, on_keep_alive:, &)
+        buffer = +""
+        response.read_body do |chunk|
+          buffer << chunk
+          process_buffer(buffer:, decode:, on_keep_alive:, &)
+        end
+      end
+
+      # Process complete lines from the buffer
+      # @api private
+      # @param buffer [String] the accumulated data buffer
+      # @param decode [Proc] decodes a line of JSON
+      # @param on_keep_alive [#call] a callable called for each empty line
+      # @yield [Object] each decoded JSON document
+      # @return [void]
+      def process_buffer(buffer:, decode:, on_keep_alive:, &)
+        while (line_end = buffer.index(LINE_DELIMITER))
+          line = buffer.slice!(0, line_end) # : String
+          buffer.delete_prefix!(LINE_DELIMITER)
+          line.empty? ? on_keep_alive.call : yield_json(line:, decode:, &)
+        end
+      end
+
+      # Decode a line of JSON and yield the result
+      #
+      # The body of a stream arrives in binary chunks, and a chunk can end within a character, so each line
+      # is tagged UTF-8 once it is whole, before on_line, the decoder, or an error reads it. A line that is not valid
+      # UTF-8 keeps its bytes, as the body of a request does.
+      #
+      # @api private
+      # @param line [String] the JSON line to decode
+      # @param decode [Proc] decodes a line of JSON
+      # @yield [Object] the decoded JSON document
+      # @return [void]
+      def yield_json(line:, decode:)
+        yield decode.call(line.force_encoding(Encoding::UTF_8))
+      end
+    end
+    private_constant :StreamParser
+  end
+end