ld-eventsource 1.0.0

data/lib/ld-eventsource/errors.rb

@@ -0,0 +1,67 @@
+
+module SSE
+  #
+  # Exception classes used by the SSE client.
+  #
+  module Errors
+    #
+    # An exception class representing an HTTP error response. This can be passed to the error
+    # handler specified in {Client#on_error}.
+    #
+    class HTTPStatusError < StandardError
+      def initialize(status, message)
+        @status = status
+        @message = message
+        super("HTTP error #{status}")
+      end
+
+      # The HTTP status code.
+      # @return [Int]
+      attr_reader :status
+
+      # The response body, if any.
+      # @return [String]
+      attr_reader :message
+    end
+
+    #
+    # An exception class representing an invalid HTTP content type. This can be passed to the error
+    # handler specified in {Client#on_error}.
+    #
+    class HTTPContentTypeError < StandardError
+      def initialize(type)
+        @content_type =  type
+        super("invalid content type \"#{type}\"")
+      end
+
+      # The HTTP content type.
+      # @return [String]
+      attr_reader :type
+    end
+
+    #
+    # An exception class indicating that an HTTP proxy server returned an error.
+    #
+    class HTTPProxyError < StandardError
+      def initialize(status)
+        @status = status
+        super("proxy server returned error #{status}")
+      end
+
+      # The HTTP status code.
+      # @return [Int]
+      attr_reader :status
+    end
+
+    #
+    # An exception class indicating that the client dropped the connection due to a read timeout.
+    # This means that the number of seconds specified by `read_timeout` in {Client#initialize}
+    # elapsed without receiving any data from the server.
+    #
+    class ReadTimeoutError < StandardError
+      def initialize(interval)
+        super("no data received in #{interval} seconds")
+      end
+    end
+  end
+end

data/lib/ld-eventsource/events.rb

@@ -0,0 +1,16 @@
+
+module SSE
+  #
+  # Server-Sent Event type used by {Client}. Use {Client#on_event} to receive events.
+  #
+  # @!attribute type
+  #   @return [Symbol] the string that appeared after `event:` in the stream;
+  #     defaults to `:message` if `event:` was not specified, will never be nil
+  # @!attribute data
+  #   @return [String] the string that appeared after `data:` in the stream;
+  #     if there were multiple `data:` lines, they are concatenated with newlines
+  # @!attribute id
+  #   @return [String] the string that appeared after `id:` in the stream if any, or nil
+  #
+  StreamEvent = Struct.new(:type, :data, :id)
+end

data/lib/ld-eventsource/impl/backoff.rb

@@ -0,0 +1,60 @@
+
+module SSE
+  module Impl
+    #
+    # A simple backoff algorithm that can reset itself after a given interval has passed without errors.
+    # A random jitter of up to -50% is applied to each interval.
+    #
+    class Backoff
+      #
+      # Constructs a backoff counter.
+      #
+      # @param [Float] base_interval  the minimum value
+      # @param [Float] max_interval  the maximum value
+      # @param [Float] reconnect_reset_interval  the interval will be reset to the minimum if this number of
+      #   seconds elapses between the last call to {#mark_success} and the next call to {#next_interval}
+      #
+      def initialize(base_interval, max_interval, reconnect_reset_interval: 60)
+        @base_interval = base_interval
+        @max_interval = max_interval
+        @reconnect_reset_interval = reconnect_reset_interval
+        @attempts = 0
+        @last_good_time = nil
+        @jitter_rand = Random.new
+      end
+
+      #
+      # The minimum value for the backoff interval.
+      #
+      attr_accessor :base_interval
+
+      #
+      # Computes the next interval value.
+      #
+      # @return [Float]  the next interval in seconds
+      #
+      def next_interval
+        if !@last_good_time.nil?
+          good_duration = Time.now.to_f - @last_good_time
+          @attempts = 0 if good_duration >= @reconnect_reset_interval
+        end
+        if @attempts == 0
+          @attempts += 1
+          return 0
+        end
+        @last_good_time = nil
+        target = ([@base_interval * (2 ** @attempts), @max_interval].min).to_f
+        @attempts += 1
+        (target / 2) + @jitter_rand.rand(target / 2)
+      end
+
+      #
+      # Marks the current time as being the beginning of a valid connection state, resetting the timer
+      # that measures how long the state has been valid.
+      #
+      def mark_success
+        @last_good_time = Time.now.to_f
+      end
+    end
+  end
+end

data/lib/ld-eventsource/impl/event_parser.rb

@@ -0,0 +1,81 @@
+require "ld-eventsource/events"
+
+module SSE
+  module Impl
+    #
+    # Indicates that the SSE server sent a `retry:` field to override the client's reconnection
+    # interval. You will only see this class if you use {EventParser} directly; {Client} will
+    # consume it and not pass it on.
+    #
+    # @!attribute milliseconds
+    #   @return [Int] the new reconnect interval in milliseconds
+    #
+    SetRetryInterval = Struct.new(:milliseconds)
+
+    #
+    # Accepts lines of text via an enumerator, and parses them into SSE messages. You will not need
+    # to use this directly if you are using {Client}, but it may be useful for testing.
+    #
+    class EventParser
+      #
+      # Constructs an instance of EventParser.
+      #
+      # @param [Enumerator] lines  an enumerator that will yield one line of text at a time
+      #
+      def initialize(lines)
+        @lines = lines
+        reset_buffers
+      end
+
+      # Generator that parses the input iterator and returns instances of {StreamEvent} or {SetRetryInterval}.
+      def items
+        Enumerator.new do |gen|
+          @lines.each do |line|
+            line.chomp!
+            if line.empty?
+              event = maybe_create_event
+              reset_buffers
+              gen.yield event if !event.nil?
+            else
+              case line
+                when /^(\w+): ?(.*)$/
+                  item = process_field($1, $2)
+                  gen.yield item if !item.nil?
+              end
+            end
+          end
+        end
+      end
+
+      private
+
+      def reset_buffers
+        @id = nil
+        @type = nil
+        @data = ""
+      end
+
+      def process_field(name, value)
+        case name
+          when "event"
+            @type = value.to_sym
+          when "data"
+            @data << "\n" if !@data.empty?
+            @data << value
+          when "id"
+            @id = value
+          when "retry"
+            if /^(?<num>\d+)$/ =~ value
+              return SetRetryInterval.new(num.to_i)
+            end
+        end
+        nil
+      end
+
+      def maybe_create_event
+        return nil if @data.empty?
+        StreamEvent.new(@type || :message, @data, @id)
+      end
+    end
+  end
+end

data/lib/ld-eventsource/impl/streaming_http.rb

@@ -0,0 +1,222 @@
+require "ld-eventsource/errors"
+
+require "concurrent/atomics"
+require "http_tools"
+require "socketry"
+
+module SSE
+  module Impl
+    #
+    # Wrapper around a socket providing a simplified HTTP request-response cycle including streaming.
+    # The socket is created and managed by Socketry, which we use so that we can have a read timeout.
+    #
+    class StreamingHTTPConnection
+      attr_reader :status, :headers
+
+      #
+      # Opens a new connection.
+      #
+      # @param [String] uri  the URI to connect o
+      # @param [String] proxy  the proxy server URI, if any
+      # @param [Hash] headers  request headers
+      # @param [Float] connect_timeout  connection timeout
+      # @param [Float] read_timeout  read timeout
+      #
+      def initialize(uri, proxy: nil, headers: {}, connect_timeout: nil, read_timeout: nil)
+        @socket = HTTPConnectionFactory.connect(uri, proxy, connect_timeout, read_timeout)
+        @socket.write(build_request(uri, headers))
+        @reader = HTTPResponseReader.new(@socket, read_timeout)
+        @status = @reader.status
+        @headers = @reader.headers
+        @closed = Concurrent::AtomicBoolean.new(false)
+      end
+
+      #
+      # Closes the connection.
+      #
+      def close
+        if @closed.make_true
+          @socket.close if @socket
+          @socket = nil
+        end
+      end
+      
+      #
+      # Generator that returns one line of the response body at a time (delimited by \r, \n,
+      # or \r\n) until the response is fully consumed or the socket is closed.
+      #
+      def read_lines
+        @reader.read_lines
+      end
+
+      #
+      # Consumes the entire response body and returns it.
+      #
+      # @return [String]  the response body
+      #
+      def read_all
+        @reader.read_all
+      end
+
+      private
+
+      # Build an HTTP request line and headers.
+      def build_request(uri, headers)
+        ret = "GET #{uri.request_uri} HTTP/1.1\r\n"
+        ret << "Host: #{uri.host}\r\n"
+        headers.each { |k, v|
+          ret << "#{k}: #{v}\r\n"
+        }
+        ret + "\r\n"
+      end
+    end
+
+    #
+    # Used internally to send the HTTP request, including the proxy dialogue if necessary.
+    # @private
+    #
+    class HTTPConnectionFactory
+      def self.connect(uri, proxy, connect_timeout, read_timeout)
+        if !proxy
+          return open_socket(uri, connect_timeout)
+        end
+
+        socket = open_socket(proxy, connect_timeout)
+        socket.write(build_proxy_request(uri, proxy))
+
+        # temporarily create a reader just for the proxy connect response
+        proxy_reader = HTTPResponseReader.new(socket, read_timeout)
+        if proxy_reader.status != 200
+          raise Errors::HTTPProxyError.new(proxy_reader.status)
+        end
+
+        # start using TLS at this point if appropriate
+        if uri.scheme.downcase == 'https'
+          wrap_socket_in_ssl_socket(socket)
+        else
+          socket
+        end
+      end
+
+      private
+
+      def self.open_socket(uri, connect_timeout)
+        if uri.scheme.downcase == 'https'
+          Socketry::SSL::Socket.connect(uri.host, uri.port, timeout: connect_timeout)
+        else
+          Socketry::TCP::Socket.connect(uri.host, uri.port, timeout: connect_timeout)
+        end
+      end
+
+      # Build a proxy connection header.
+      def self.build_proxy_request(uri, proxy)
+        ret = "CONNECT #{uri.host}:#{uri.port} HTTP/1.1\r\n"
+        ret << "Host: #{uri.host}:#{uri.port}\r\n"
+        if proxy.user || proxy.password
+          encoded_credentials = Base64.strict_encode64([proxy.user || '', proxy.password || ''].join(":"))
+          ret << "Proxy-Authorization: Basic #{encoded_credentials}\r\n"
+        end
+        ret << "\r\n"
+        ret
+      end
+
+      def self.wrap_socket_in_ssl_socket(socket)
+        io = IO.try_convert(socket)
+        ssl_sock = OpenSSL::SSL::SSLSocket.new(io, OpenSSL::SSL::SSLContext.new)
+        ssl_sock.connect
+        Socketry::SSL::Socket.new.from_socket(ssl_sock)
+      end
+    end
+
+    #
+    # Used internally to read the HTTP response, either all at once or as a stream of text lines.
+    # Incoming data is fed into an instance of HTTPTools::Parser, which gives us the header and
+    # chunks of the body via callbacks.
+    # @private
+    #
+    class HTTPResponseReader
+      DEFAULT_CHUNK_SIZE = 10000
+
+      attr_reader :status, :headers
+
+      def initialize(socket, read_timeout)
+        @socket = socket
+        @read_timeout = read_timeout
+        @parser = HTTPTools::Parser.new
+        @buffer = ""
+        @done = false
+        @lock = Mutex.new
+
+        # Provide callbacks for the Parser to give us the headers and body. This has to be done
+        # before we start piping any data into the parser.
+        have_headers = false
+        @parser.on(:header) do
+          have_headers = true
+        end
+        @parser.on(:stream) do |data|
+          @lock.synchronize { @buffer << data }  # synchronize because we're called from another thread in Socketry
+        end
+        @parser.on(:finish) do
+          @lock.synchronize { @done = true }
+        end
+
+        # Block until the status code and headers have been successfully read.
+        while !have_headers
+          raise EOFError if !read_chunk_into_buffer
+        end
+        @headers = Hash[@parser.header.map { |k,v| [k.downcase, v] }]
+        @status = @parser.status_code
+      end
+
+      def read_lines
+        Enumerator.new do |gen|
+          loop do
+            line = read_line
+            break if line.nil?
+            gen.yield line
+          end
+        end
+      end
+
+      def read_all
+        while read_chunk_into_buffer
+        end
+        @buffer
+      end
+
+      private
+
+      # Attempt to read some more data from the socket. Return true if successful, false if EOF.
+      # A read timeout will result in an exception from Socketry's readpartial method.
+      def read_chunk_into_buffer
+        # If @done is set, it means the Parser has signaled end of response body
+        @lock.synchronize { return false if @done }
+        begin
+          data = @socket.readpartial(DEFAULT_CHUNK_SIZE, timeout: @read_timeout)
+        rescue Socketry::TimeoutError
+          # We rethrow this as our own type so the caller doesn't have to know the Socketry API
+          raise Errors::ReadTimeoutError.new(@read_timeout)
+        end
+        return false if data == :eof
+        @parser << data
+        # We are piping the content through the parser so that it can handle things like chunked
+        # encoding for us. The content ends up being appended to @buffer via our callback.
+        true
+      end
+
+      # Extract the next line of text from the read buffer, refilling the buffer as needed.
+      def read_line
+        loop do
+          @lock.synchronize do
+            i = @buffer.index(/[\r\n]/)
+            if !i.nil?
+              i += 1 if (@buffer[i] == "\r" && i < @buffer.length - 1 && @buffer[i + 1] == "\n")
+              return @buffer.slice!(0, i + 1).force_encoding(Encoding::UTF_8)
+            end
+          end
+          return nil if !read_chunk_into_buffer
+        end
+      end
+    end
+  end
+end