ld-eventsource 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 294a32bc78de81b8f7c5ffa0a8b9ffc25847b0ecd20eee8f27caea576ae2b6fc
+  data.tar.gz: 5c0bb7736f090364098525477ec192b89ee02b96e0d12542bf72f08112180ba2
+SHA512:
+  metadata.gz: b6466b0b4c060b681640e2b47cc1844bb93a9588076fbcc901a5922be303860538d6e064d1f9ea897062ffeafcb86690e68e26e0c28d6f795ea68bb41dc7d364
+  data.tar.gz: 67a62d448f673893e9fc397cb536ad6ba4194292e3f8c3058d96bcc39b0f8bf3ce6bf12b1bdeb8e843ff962e3324505b9cddc3e42486cdb915456dbe1dba4dcc

data/.circleci/config.yml

@@ -0,0 +1,90 @@
+version: 2
+
+workflows:
+  version: 2
+  test:
+    jobs:
+      - test-misc-rubies
+      - test-2.2
+      - test-2.3
+      - test-2.4
+      - test-2.5
+      - test-jruby-9.2
+
+ruby-docker-template: &ruby-docker-template
+  steps:
+    - checkout
+    - run: |
+        if [[ $CIRCLE_JOB == test-jruby* ]]; then
+          gem install jruby-openssl; # required by bundler, no effect on Ruby MRI
+        fi
+    - run: ruby -v
+    - run: gem install bundler -v "~> 1.17"
+    - run: bundle install
+    - run: mkdir ./rspec
+    - run: bundle exec rspec --format progress --format RspecJunitFormatter -o ./rspec/rspec.xml spec
+    - store_test_results:
+        path: ./rspec
+    - store_artifacts:
+        path: ./rspec
+
+jobs:
+  test-2.2:
+    <<: *ruby-docker-template
+    docker:
+      - image: circleci/ruby:2.2.10-jessie
+  test-2.3:
+    <<: *ruby-docker-template
+    docker:
+      - image: circleci/ruby:2.3.7-jessie
+  test-2.4:
+    <<: *ruby-docker-template
+    docker:
+      - image: circleci/ruby:2.4.5-stretch
+  test-2.5:
+    <<: *ruby-docker-template
+    docker:
+      - image: circleci/ruby:2.5.3-stretch
+  test-jruby-9.2:
+    <<: *ruby-docker-template
+    docker:
+      - image: circleci/jruby:9-jdk
+
+  # The following very slow job uses an Ubuntu container to run the Ruby versions that
+  # CircleCI doesn't provide Docker images for.
+  test-misc-rubies:
+    machine:
+      image: circleci/classic:latest
+    environment:
+      - RUBIES: "jruby-9.1.17.0"
+    steps:
+      - checkout
+      - run:
+          name: install all Ruby versions
+          command: "parallel rvm install ::: $RUBIES"
+      - run:
+          name: bundle install for all versions
+          shell: /bin/bash -leo pipefail # need -l in order for "rvm use" to work
+          command: |
+            set -e;
+            for i in $RUBIES;
+            do
+              rvm use $i;
+              if [[ $i == jruby* ]]; then
+                gem install jruby-openssl; # required by bundler, no effect on Ruby MRI
+              fi
+              gem install bundler -v "~> 1.17";
+              bundle install;
+              mv Gemfile.lock "Gemfile.lock.$i"
+            done
+      - run:
+          name: run tests for all versions
+          shell: /bin/bash -leo pipefail
+          command: |
+            set -e;
+            for i in $RUBIES;
+            do
+              rvm use $i;
+              cp "Gemfile.lock.$i" Gemfile.lock;
+              bundle exec rspec spec;
+            done

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+*.gem
+.DS_Store

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Change log
+
+All notable changes to the LaunchDarkly SSE Client for Ruby will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org).
+
+## [1.0.0] - 2019-01-03
+
+Initial release.

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,47 @@
+PATH
+  remote: .
+  specs:
+    ld-eventsource (1.0.0)
+      concurrent-ruby (~> 1.0)
+      http_tools (~> 0.4.5)
+      socketry (~> 0.5.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    concurrent-ruby (1.0.5)
+    diff-lcs (1.3)
+    hitimes (1.3.0)
+    http_tools (0.4.5)
+    rake (10.5.0)
+    rspec (3.7.0)
+      rspec-core (~> 3.7.0)
+      rspec-expectations (~> 3.7.0)
+      rspec-mocks (~> 3.7.0)
+    rspec-core (3.7.1)
+      rspec-support (~> 3.7.0)
+    rspec-expectations (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-mocks (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-support (3.7.0)
+    rspec_junit_formatter (0.3.0)
+      rspec-core (>= 2, < 4, != 2.12.0)
+    socketry (0.5.1)
+      hitimes (~> 1.2)
+
+PLATFORMS
+  java
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.7)
+  ld-eventsource!
+  rake (~> 10.0)
+  rspec (~> 3.2)
+  rspec_junit_formatter (~> 0.3.0)
+
+BUNDLED WITH
+   1.17.3

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2018 Catamorphic, Co.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,45 @@
+LaunchDarkly SSE Client for Ruby
+================================
+
+[![Gem Version](https://badge.fury.io/rb/ld-eventsource.svg)](http://badge.fury.io/rb/ld-eventsource) [![Circle CI](https://circleci.com/gh/launchdarkly/ruby-eventsource/tree/master.svg?style=svg)](https://circleci.com/gh/launchdarkly/ruby-eventsource/tree/master)
+
+A client for the [Server-Sent Events](https://www.w3.org/TR/eventsource/) protocol. This implementation runs on a worker thread, and uses the [`socketry`](https://rubygems.org/gems/socketry) gem to manage a persistent connection. Its primary purpose is to support the [LaunchDarkly SDK for Ruby](https://github.com/launchdarkly/ruby-client), but it can be used independently.
+
+Parts of this code are based on https://github.com/Tonkpils/celluloid-eventsource, but it does not use Celluloid.
+
+Supported Ruby versions
+-----------------------
+
+This gem has a minimum Ruby version of 2.2.6, or 9.1.6 for JRuby.
+
+Quick setup
+-----------
+
+1. Install the Ruby SDK with `gem`:
+
+```shell
+gem install ld-eventsource
+```
+
+2. Import the code:
+
+```ruby
+require 'ld-eventsource'
+```
+
+3. Create a new SSE client instance and register your event handler:
+
+```ruby
+sse_client = SSE::Client.new("http://hostname/resource/path") do |client|
+  client.on_event do |event|
+    puts "I received an event: #{event.type}, #{event.data}"
+  end
+end
+```
+
+For other options available with the `Client` constructor, see the [API documentation](https://www.rubydoc.info/gems/ld-eventsource).
+
+Contributing
+------------
+
+We welcome questions, suggestions, and pull requests at our [Github repository](https://github.com/launchdarkly/ruby-eventsource). Pull requests should be done from a fork.

data/Rakefile

@@ -0,0 +1,5 @@
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+task default: :spec

data/ld-eventsource.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "ld-eventsource/version"
+
+# rubocop:disable Metrics/BlockLength
+Gem::Specification.new do |spec|
+  spec.name          = "ld-eventsource"
+  spec.version       = SSE::VERSION
+  spec.authors       = ["LaunchDarkly"]
+  spec.email         = ["team@launchdarkly.com"]
+  spec.summary       = "LaunchDarkly SSE client"
+  spec.description   = "LaunchDarkly SSE client for Ruby"
+  spec.homepage      = "https://github.com/launchdarkly/ruby-eventsource"
+  spec.license       = "Apache-2.0"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rspec", "~> 3.2"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec_junit_formatter", "~> 0.3.0"
+
+  spec.add_runtime_dependency "concurrent-ruby", "~> 1.0"
+  spec.add_runtime_dependency "http_tools", '~> 0.4.5'
+  spec.add_runtime_dependency "socketry", "~> 0.5.1"
+end

data/lib/ld-eventsource.rb

@@ -0,0 +1,14 @@
+require "ld-eventsource/client"
+require "ld-eventsource/version"
+
+#
+# A client for the Server-Sent Events protocol.
+#
+module SSE
+  #
+  # Internal components of the SSE implementation. All classes in this module should be
+  # considered unsupported and subject to change.
+  #
+  module Impl
+  end
+end

data/lib/ld-eventsource/client.rb

@@ -0,0 +1,296 @@
+require "ld-eventsource/impl/backoff"
+require "ld-eventsource/impl/event_parser"
+require "ld-eventsource/impl/streaming_http"
+require "ld-eventsource/events"
+require "ld-eventsource/errors"
+
+require "concurrent/atomics"
+require "logger"
+require "thread"
+require "uri"
+
+module SSE
+  #
+  # A lightweight SSE client implementation. The client uses a worker thread to read from the
+  # streaming HTTP connection. Events are dispatched from the same worker thread.
+  #
+  # The client will attempt to recover from connection failures as follows:
+  #
+  # * The first time the connection is dropped, it will wait about one second (or whatever value is
+  # specified for `reconnect_time`) before attempting to reconnect. The actual delay has a
+  # pseudo-random jitter value added.
+  # * If the connection fails again within the time range specified by `reconnect_reset_interval`,
+  # it will exponentially increase the delay between attempts (and also apply a random jitter).
+  # However, if the connection stays up for at least that amount of time, the delay will be reset
+  # to the minimum.
+  # * Each time a new connection is made, the client will send a `Last-Event-Id` header so the server
+  # can pick up where it left off (if the server has been sending ID values for events).
+  #
+  # It is also possible to force the connection to be restarted if the server sends no data within an
+  # interval specified by `read_timeout`. Using a read timeout is advisable because otherwise it is
+  # possible in some circumstances for a connection failure to go undetected. To keep the connection
+  # from timing out if there are no events to send, the server could send a comment line (`":"`) at
+  # regular intervals as a heartbeat.
+  #
+  class Client
+    # The default value for `connect_timeout` in {#initialize}.
+    DEFAULT_CONNECT_TIMEOUT = 10
+
+    # The default value for `read_timeout` in {#initialize}.
+    DEFAULT_READ_TIMEOUT = 300
+
+    # The default value for `reconnect_time` in {#initialize}.
+    DEFAULT_RECONNECT_TIME = 1
+
+    # The maximum number of seconds that the client will wait before reconnecting.
+    MAX_RECONNECT_TIME = 30
+
+    # The default value for `reconnect_reset_interval` in {#initialize}.
+    DEFAULT_RECONNECT_RESET_INTERVAL = 60
+
+    #
+    # Creates a new SSE client.
+    #
+    # Once the client is created, it immediately attempts to open the SSE connection. You will
+    # normally want to register your event handler before this happens, so that no events are missed.
+    # To do this, provide a block after the constructor; the block will be executed before opening
+    # the connection.
+    #
+    # @example Specifying an event handler at initialization time
+    #     client = SSE::Client.new(uri) do |c|
+    #       c.on_event do |event|
+    #         puts "I got an event: #{event.type}, #{event.data}"
+    #       end
+    #     end
+    #
+    # @param uri [String] the URI to connect to
+    # @param headers [Hash] ({})  custom headers to send with each HTTP request
+    # @param connect_timeout [Float] (DEFAULT_CONNECT_TIMEOUT)  maximum time to wait for a
+    #   connection, in seconds
+    # @param read_timeout [Float] (DEFAULT_READ_TIMEOUT)  the connection will be dropped and
+    #   restarted if this number of seconds elapse with no data; nil for no timeout
+    # @param reconnect_time [Float] (DEFAULT_RECONNECT_TIME)  the initial delay before reconnecting
+    #   after a failure, in seconds; this can increase as described in {Client}
+    # @param reconnect_reset_interval [Float] (DEFAULT_RECONNECT_RESET_INTERVAL)  if a connection
+    #   stays alive for at least this number of seconds, the reconnect interval will return to the
+    #   initial value
+    # @param last_event_id [String] (nil)  the initial value that the client should send in the
+    #   `Last-Event-Id` header, if any
+    # @param proxy [String] (nil)  optional URI of a proxy server to use (you can also specify a
+    #   proxy with the `HTTP_PROXY` or `HTTPS_PROXY` environment variable)
+    # @param logger [Logger]  a Logger instance for the client to use for diagnostic output;
+    #   defaults to a logger with WARN level that goes to standard output
+    # @yieldparam [Client] client  the new client instance, before opening the connection
+    # 
+    def initialize(uri,
+          headers: {},
+          connect_timeout: DEFAULT_CONNECT_TIMEOUT,
+          read_timeout: DEFAULT_READ_TIMEOUT,
+          reconnect_time: DEFAULT_RECONNECT_TIME,
+          reconnect_reset_interval: DEFAULT_RECONNECT_RESET_INTERVAL,
+          last_event_id: nil,
+          proxy: nil,
+          logger: nil)
+      @uri = URI(uri)
+      @stopped = Concurrent::AtomicBoolean.new(false)
+
+      @headers = headers.clone
+      @connect_timeout = connect_timeout
+      @read_timeout = read_timeout
+      @logger = logger || default_logger
+
+      if proxy
+        @proxy = proxy
+      else
+        proxy_uri = @uri.find_proxy
+        if !proxy_uri.nil? && (proxy_uri.scheme == 'http' || proxy_uri.scheme == 'https')
+          @proxy = proxy_uri
+        end
+      end
+
+      @backoff = Impl::Backoff.new(reconnect_time || DEFAULT_RECONNECT_TIME, MAX_RECONNECT_TIME,
+        reconnect_reset_interval: reconnect_reset_interval)
+
+      @on = { event: ->(_) {}, error: ->(_) {} }
+      @last_id = last_event_id
+
+      yield self if block_given?
+
+      Thread.new do
+        run_stream
+      end
+    end
+
+    #
+    # Specifies a block or Proc to receive events from the stream. This will be called once for every
+    # valid event received, with a single parameter of type {StreamEvent}. It is called from the same
+    # worker thread that reads the stream, so no more events will be dispatched until it returns.
+    #
+    # Any exception that propagates out of the handler will cause the stream to disconnect and
+    # reconnect, on the assumption that data may have been lost and that restarting the stream will
+    # cause it to be resent.
+    #
+    # Any previously specified event handler will be replaced.
+    #
+    # @yieldparam event [StreamEvent]
+    #
+    def on_event(&action)
+      @on[:event] = action
+    end
+
+    #
+    # Specifies a block or Proc to receive connection errors. This will be called with a single
+    # parameter that is an instance of some exception class-- normally, either some I/O exception or
+    # one of the classes in {SSE::Errors}. It is called from the same worker thread that
+    # reads the stream, so no more events or errors will be dispatched until it returns.
+    #
+    # If the error handler decides that this type of error is not recoverable, it has the ability
+    # to prevent any further reconnect attempts by calling {Client#close} on the Client. For instance,
+    # you might want to do this if the server returned a `401 Unauthorized` error and no other authorization
+    # credentials are available, since any further requests would presumably also receive a 401.
+    #
+    # Any previously specified error handler will be replaced.
+    #
+    # @yieldparam error [StandardError]
+    #
+    def on_error(&action)
+      @on[:error] = 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.
+    #
+    def close
+      if @stopped.make_true
+        @cxn.close if !@cxn.nil?
+        @cxn = nil
+      end
+    end
+
+    private
+
+    def default_logger
+      log = ::Logger.new($stdout)
+      log.level = ::Logger::WARN
+      log.progname  = 'ld-eventsource'
+      log
+    end
+
+    def run_stream
+      while !@stopped.value
+        @cxn = nil
+        begin
+          @cxn = connect
+          # There's a potential race if close was called in the middle of the previous line, i.e. after we
+          # connected but before @cxn was set. Checking the variable again is a bit clunky but avoids that.
+          return if @stopped.value
+          read_stream(@cxn) if !@cxn.nil?
+        rescue Errno::EBADF
+          # Don't log this as an error - it probably means we closed our own connection deliberately
+          @logger.info { "Stream connection closed" }
+        rescue StandardError => e
+          # This should not be possible because connect catches all StandardErrors
+          log_and_dispatch_error(e, "Unexpected error from event source")
+        end
+        begin
+          @cxn.close if !@cxn.nil?
+        rescue StandardError => e
+          log_and_dispatch_error(e, "Unexpected error while closing stream")
+        end
+      end
+    end
+
+    # Try to establish a streaming connection. Returns the StreamingHTTPConnection object if successful.
+    def connect
+      loop do
+        return if @stopped.value
+        interval = @backoff.next_interval
+        if interval > 0
+          @logger.info { "Will retry connection after #{'%.3f' % interval} seconds" } 
+          sleep(interval)
+        end
+        begin
+          @logger.info { "Connecting to event stream at #{@uri}" }
+          cxn = Impl::StreamingHTTPConnection.new(@uri,
+            proxy: @proxy,
+            headers: build_headers,
+            connect_timeout: @connect_timeout,
+            read_timeout: @read_timeout
+          )
+          if cxn.status == 200
+            content_type = cxn.headers["content-type"]
+            if content_type && content_type.start_with?("text/event-stream")
+              return cxn  # we're good to proceed
+            else
+              cxn.close
+              err = Errors::HTTPContentTypeError.new(cxn.headers["content-type"])
+              @on[:error].call(err)
+              @logger.warn { "Event source returned unexpected content type '#{cxn.headers["content-type"]}'" }
+            end
+          else
+            body = cxn.read_all  # grab the whole response body in case it has error details
+            cxn.close
+            @logger.info { "Server returned error status #{cxn.status}" }
+            err = Errors::HTTPStatusError.new(cxn.status, body)
+            @on[:error].call(err)
+          end
+        rescue Errno::EBADF
+          raise # See EBADF comment in run_stream
+        rescue StandardError => e
+          cxn.close if !cxn.nil?
+          log_and_dispatch_error(e, "Unexpected error from event source")
+        end
+        # if unsuccessful, continue the loop to connect again
+      end
+    end
+
+    # Pipe the output of the StreamingHTTPConnection into the EventParser, and dispatch events as
+    # they arrive.
+    def read_stream(cxn)
+      # Tell the Backoff object that the connection is now in a valid state. It uses that information so
+      # it can automatically reset itself if enough time passes between failures.
+      @backoff.mark_success
+
+      event_parser = Impl::EventParser.new(cxn.read_lines)
+      event_parser.items.each do |item|
+        return if @stopped.value
+        case item
+          when StreamEvent
+            dispatch_event(item)
+          when Impl::SetRetryInterval
+            @logger.debug { "Received 'retry:' directive, setting interval to #{item.milliseconds}ms" }
+            @backoff.base_interval = item.milliseconds.to_f / 1000
+        end
+      end
+    end
+
+    def dispatch_event(event)
+      @logger.debug { "Received event: #{event}" }
+      @last_id = event.id
+
+      # Pass the event to the caller
+      @on[:event].call(event)
+    end
+
+    def log_and_dispatch_error(e, message)
+      @logger.warn { "#{message}: #{e.inspect}"}
+      @logger.debug { "Exception trace: #{e.backtrace}" }
+      begin
+        @on[:error].call(e)      
+      rescue StandardError => ee
+        @logger.warn { "Error handler threw an exception: #{ee.inspect}"}
+        @logger.debug { "Exception trace: #{ee.backtrace}" }
+      end
+    end
+
+    def build_headers
+      h = {
+        'Accept' => 'text/event-stream',
+        'Cache-Control' => 'no-cache'
+      }
+      h['Last-Event-Id'] = @last_id if !@last_id.nil?
+      h.merge(@headers)
+    end
+  end
+end