restify 2.1.0 → 3.0.0.rc3

data/lib/restify/adapter/ethon/pool.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Restify
+  module Adapter
+    class Ethon < Base
+      #
+      # Idle libcurl easy handles, kept for reuse.
+      #
+      # Handles can be taken and released from any thread. A handle must
+      # only be released once libcurl is done with it.
+      #
+      # @api private
+      #
+      class Pool
+        def initialize(size:, &factory)
+          @size    = size
+          @factory = factory
+          @mutex   = Mutex.new
+          @idle    = []
+        end
+
+        def checkout
+          @mutex.synchronize { @idle.pop } || @factory.call
+        end
+
+        def release(easy)
+          easy.reset
+
+          @mutex.synchronize { @idle << easy if @idle.size < @size }
+        end
+
+        # Forget all handles without releasing them as they belong to
+        # the parent process.
+        def forked!
+          @mutex.synchronize do
+            @idle.each {|easy| easy.handle.autorelease = false }
+            @idle.clear
+          end
+        end
+      end
+    end
+  end
+end

data/lib/restify/adapter/ethon.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require 'ethon'
+require 'nio'
+
+require 'restify/adapter/ethon/options'
+require 'restify/adapter/ethon/easy'
+require 'restify/adapter/ethon/event_loop'
+require 'restify/adapter/ethon/pool'
+
+module Restify
+  module Adapter
+    #
+    # An adapter using libcurl's multi interface via `Ethon` in
+    # `socket_action` mode, driven by a nio4r-based event loop.
+    #
+    # Requests are handed over to the event loop using a queue and the
+    # loop is woken up via `NIO::Selector#wakeup`. Both are safe to call
+    # from any thread.
+    #
+    # This is important because the event loop is run from either any
+    # waiting thread or a dedicated background thread.
+    #
+    # The background thread that is spawned on demand and restarted if
+    # it ever dies. A thread waiting on a request's promise takes over
+    # the loop and runs it itself until the promise is complete, see
+    # `#drive`. This avoids handing each request and response between
+    # threads, which is expensive (thread wakeup). Only one thread runs
+    # the loop at a time, therefore all libcurl and selector interaction
+    # is still serialized.
+    #
+    class Ethon < Base
+      include Logging
+
+      # Restify follows relations from URLs in server responses, and
+      # libcurl supports far more than HTTP, e.g. `file://` or `scp://`.
+      # Therefore only HTTP-like protocols must ever be used, both for
+      # the request itself and when following redirects.
+      #
+      # This is intentionally not configurable.
+      PROTOCOLS = %i[http https].freeze
+
+      # Set headers bypassing the wait for 100-continue responses many
+      # servers do not send correctly.
+      DEFAULT_HEADERS = {
+        'Expect' => '',
+        'Transfer-Encoding' => '',
+      }.freeze
+
+      DEFAULT_OPTIONS = {
+        followlocation: true,
+        tcp_keepalive: true,
+        tcp_keepidle: 5,
+        tcp_keepintvl: 5,
+      }.freeze
+
+      ENFORCED_OPTIONS = {
+        # Do not use signal handlers in libcurl, as it would interfere
+        # with the threads.
+        nosignal: true,
+
+        # Do not allow using and redirecting to unexpected (e.g. local)
+        # protocols.
+        protocols: PROTOCOLS,
+        redir_protocols: PROTOCOLS,
+      }.freeze
+
+      # Maximum number of idle easy handles kept for reuse.
+      POOL_SIZE = 64
+
+      def initialize(options: {}, **multi)
+        @options = Options.new({
+          **DEFAULT_OPTIONS,
+          **options,
+          **ENFORCED_OPTIONS,
+        })
+        @multi_options = multi
+
+        @mutex  = Mutex.new
+        @thread = nil
+
+        setup
+
+        super()
+      end
+
+      def call_native(request, writer)
+        check_fork!
+
+        easy = convert(request, writer)
+
+        debug 'request:add',
+          tag: request.object_id,
+          method: request.method.upcase,
+          url: request.uri,
+          timeout: request.timeout
+
+        # Ensure the event loop is running and let it pick up the new
+        # request.
+        thread
+
+        @events.enqueue(easy)
+      end
+
+      # Run the event loop in the calling thread until the promise is
+      # complete or the timeout expires, see `Promise#wait` and
+      # `EventLoop#drive`.
+      #
+      # This only processes transfers, i.e. fulfills or rejects the
+      # adapter's promises. Callbacks chained with `Promise#then` still
+      # only run in the thread waiting on them.
+      #
+      # Returns false when the loop cannot be run in the calling thread,
+      # i.e. when waiting from within the loop itself.
+      #
+      def drive(promise, timeout)
+        check_fork!
+
+        @events.drive(promise, timeout)
+      end
+
+      private
+
+      def driver
+        self
+      end
+
+      def setup
+        @pid    = Process.pid
+        @pool   = Pool.new(size: POOL_SIZE) { Easy.new }
+        @events = EventLoop.new(**@multi_options)
+      end
+
+      def check_fork!
+        return if @pid == Process.pid
+
+        @mutex.synchronize { forked! if @pid != Process.pid }
+      end
+
+      # A forked child process inherits the parent's event loop,
+      # connections and sockets. They must neither be used nor cleaned
+      # up here, as the parent still uses them.
+      #
+      # Therefore, abandon the state without releasing it, and set up
+      # everything again.
+      def forked!
+        @events.forked!
+        @pool.forked!
+
+        @thread = nil
+        setup
+      end
+
+      def convert(request, writer)
+        @pool.checkout.tap do |easy|
+          easy._otel_span = OpenTelemetry::Trace.current_span
+          easy._restify_request = request
+          easy._restify_writer = writer
+
+          easy.prepare(request, @options)
+
+          easy.on_complete do |completed|
+            complete(completed, request, writer)
+
+            @pool.release(completed)
+
+            # Wake up threads waiting on the loop to check if their
+            # result is available now.
+            @events.notify
+          end
+        end
+      end
+
+      def complete(easy, request, writer)
+        writer.set do
+          if logger&.debug?
+            debug 'request:complete',
+              tag: request.object_id,
+              status: easy.response_code,
+              message: easy.return_code
+          end
+
+          easy.response(request)
+        end
+      rescue StandardError => e
+        # This runs inside a libcurl callback, therefore no exception
+        # must ever escape from here. Anything reaching this point could
+        # not be handed to the promise anymore.
+        error(e)
+      end
+
+      def thread
+        @mutex.synchronize do
+          # Spawn thread if not yet started, or recreate it if it died.
+          if @thread.nil? || !@thread.status
+            debug 'loop:spawn'
+
+            events = @events
+            @thread = Thread.new { events.run }
+          end
+
+          @thread
+        end
+      end
+
+      def _log_prefix
+        "[#{object_id}/#{Thread.current.object_id}]"
+      end
+    end
+  end
+end

data/lib/restify/adapter/loop_lock.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Restify
+  module Adapter
+    #
+    # Manages coordination for exclusive ownership of an event loop,
+    # shared between a background thread and threads waiting on results.
+    # This way, the event loop can run on waiting threads directly,
+    # avoiding costly context switches to the background thread.
+    #
+    # Waiting threads have priority: the background thread only acquires
+    # the loop while no thread is waiting for it, and is interrupted to
+    # release it as soon as one is.
+    #
+    # Waiting threads can give up waiting once their result is
+    # available, e.g. because another thread running the loop produced
+    # it. Whoever runs the loop must call `#notify` after producing a
+    # result.
+    #
+    class LoopLock
+      # @yield Called when a waiting thread needs the background thread to
+      #   release the loop, e.g. to wake it up from `select`.
+      #
+      def initialize(&interrupt)
+        @interrupt = interrupt
+
+        reset!
+      end
+
+      # Acquire the loop for a thread waiting on a result.
+      #
+      # @param timeout [Restify::Timeout, Numeric] Maximum time to wait,
+      #   derived from the promise timeout of the waiting thread.
+      #
+      # @yieldreturn [Boolean] Whether the result is available, and
+      #   the loop is not needed anymore.
+      #
+      # @return [Boolean] true when the calling thread holds the loop,
+      #   false when the result is available or the timeout expired
+      #   first.
+      #
+      def acquire(timeout, &done)
+        timeout = Timeout.new(timeout)
+
+        background = @mutex.synchronize do
+          @waiters += 1
+          @background
+        end
+
+        @interrupt&.call if background
+
+        @mutex.synchronize do
+          loop do
+            return false if done&.call
+
+            remaining = timeout.remaining
+            return false unless remaining.positive?
+
+            if free?
+              @owner = Thread.current
+              return true
+            end
+
+            @changed.wait(@mutex, remaining)
+          end
+        ensure
+          @waiters -= 1
+
+          # Let the background thread continue.
+          @changed.broadcast if @waiters.zero?
+        end
+      end
+
+      # Acquire the loop for the background thread. Blocks while any
+      # other thread holds the loop or waits for it.
+      def acquire_background
+        @mutex.synchronize do
+          @changed.wait(@mutex) until free? && @waiters.zero?
+
+          @owner = Thread.current
+          @background = true
+        end
+      end
+
+      def release
+        @mutex.synchronize do
+          @owner = nil
+          @background = false
+          @changed.broadcast
+        end
+      end
+
+      def owned?
+        @owner.equal?(Thread.current)
+      end
+
+      def notify
+        return unless @waiters.positive?
+
+        @mutex.synchronize { @changed.broadcast }
+      end
+
+      # Forget all threads holding or waiting for the loop, e.g. in a
+      # forked child process, where these threads do not exist.
+      #
+      # Must not be called while other threads use the lock.
+      def reset!
+        @mutex      = Mutex.new
+        @changed    = ConditionVariable.new
+        @owner      = nil
+        @background = false
+        @waiters    = 0
+      end
+
+      private
+
+      # A thread holding the loop can be gone without releasing it, e.g.
+      # when killed.
+      def free?
+        @owner.nil? || !@owner.alive?
+      end
+    end
+  end
+end

data/lib/restify/adapter/telemetry.rb

@@ -8,23 +8,25 @@ module Restify
     module Telemetry
       def call(request)
         method = request.method.to_s.upcase
-        uri = URI.parse(request.uri)
-        name = "#{method} #{uri.scheme}://#{uri.host}:#{uri.port}"
+        uri = request.uri
+        port = uri.inferred_port
+        name = "#{method} #{uri.scheme}://#{uri.host}:#{port}"
 
+        # Remove `nil` as OTEL spans must not contain any nil attributes
         attributes = {
           'http.request.method' => method,
           'server.address' => uri.host,
-          'server.port' => uri.port,
+          'server.port' => port,
           'url.full' => uri.to_s,
           'url.scheme' => uri.scheme,
-        }
+        }.compact
 
         span = tracer.start_span(name, attributes:, kind: :client)
         OpenTelemetry::Trace.with_span(span) do
           OpenTelemetry.propagation.inject(request.headers)
 
           super.tap do |x|
-            x.add_observer do |_, response, err|
+            x.add_observer do |response, err|
               if response
                 span.set_attribute('http.response.status_code', response&.code)
                 span.status = OpenTelemetry::Trace::Status.error unless (100..399).cover?(response&.code)

data/lib/restify/adapter/typhoeus.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
-require 'typhoeus'
-
-Ethon.logger = Logging.logger[Ethon]
+begin
+  require 'typhoeus'
+rescue LoadError => e
+  raise LoadError.new(
+    "Restify::Adapter::Typhoeus requires the `typhoeus` gem, add it to your Gemfile (#{e.message})",
+  )
+end
 
 module Restify
   module Adapter
@@ -23,6 +27,14 @@ module Restify
         tcp_keepintvl: 5,
       }.freeze
 
+      # Restify follows relations from URLs in server responses, and
+      # libcurl supports far more than HTTP, e.g. `file://` or `scp://`.
+      # Therefore only HTTP-like protocols must ever be used, both for
+      # the request itself and when following redirects.
+      #
+      # This is intentionally not configurable.
+      PROTOCOLS = %i[http https].freeze
+
       # Patch Hydra to restore the correct OpenTelemetry span when
       # adding the request, so that the Ethon instrumentation can
       # properly pick up the context where the Restify request
@@ -41,8 +53,8 @@ module Restify
         end
       end
 
-      def initialize(sync: false, options: {}, **kwargs)
-        @hydra = ::Typhoeus::Hydra.new(**kwargs)
+      def initialize(sync: false, options: {}, **)
+        @hydra = ::Typhoeus::Hydra.new(**)
         @hydra.extend(EasyOverride)
 
         @mutex   = Mutex.new
@@ -62,8 +74,11 @@ module Restify
         req = convert(request, writer)
 
         if sync?
-          @hydra.queue(req)
-          @hydra.run
+          begin
+            req.run
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            writer.reject(e)
+          end
         else
           debug 'request:add',
             tag: request.object_id,
@@ -71,7 +86,7 @@ module Restify
             url: request.uri,
             timeout: request.timeout
 
-          @queue << convert(request, writer)
+          @queue << req
 
           thread.run unless thread.status
         end
@@ -88,33 +103,38 @@ module Restify
           body: request.body,
           timeout: request.timeout,
           connecttimeout: request.timeout,
+
+          # Block accessing and redirecting to non-HTTP protocols:
+          protocols: PROTOCOLS,
+          redir_protocols: PROTOCOLS,
         ).tap do |req|
           req._otel_span = OpenTelemetry::Trace.current_span
           req._restify_writer = writer
 
           req.on_complete do |response|
-            debug 'request:complete',
-              tag: request.object_id,
-              status: response.code,
-              message: response.return_message,
-              timeout: response.timed_out?
-
-            if response.timed_out? || response.code.zero?
-              writer.reject \
-                Restify::NetworkError.new(request, response.return_message)
-            else
-              writer.fulfill convert_back(response, request)
+            writer.set do
+              debug 'request:complete',
+                tag: request.object_id,
+                status: response.code,
+                message: response.return_message,
+                timeout: response.timed_out?
+
+              if response.timed_out? || response.code.zero?
+                raise Restify::NetworkError.new(request, response.return_message)
+              end
+
+              convert_back(response, request)
             end
 
-            # Add all newly queued requests to active hydra, e.g. requests
-            # queued in a completion callback.
+            # Add all newly queued requests to active hydra, e.g.
+            # requests queued in a completion callback.
             dequeue_all
           end
         end
       end
 
       def convert_back(response, request)
-        uri     = request.uri
+        uri     = effective_uri(response, request)
         status  = response.code
         body    = response.body
         headers = convert_headers(response.headers)
@@ -122,6 +142,15 @@ module Restify
         ::Restify::Response.new(request, uri, status, headers, body)
       end
 
+      def effective_uri(response, request)
+        url = response.effective_url
+
+        # Only parse the URL after redirects, as parsing is expensive.
+        return request.uri if url.nil? || url == request.uri.to_s
+
+        Addressable::URI.parse(url)
+      end
+
       def convert_headers(headers)
         return {} unless headers.respond_to?(:each_pair)
 
@@ -165,7 +194,7 @@ module Restify
           runs += 1
           debug 'hydra:completed'
         rescue StandardError => e
-          logger.error(e)
+          error(e)
         end
       ensure
         debug 'hydra:exit'

data/lib/restify/context.rb

@@ -30,13 +30,23 @@ module Restify
       @options = kwargs
     end
 
+    # Resolve a URI against the context URI. Absolute URIs are returned
+    # as they are, e.g. when already joined by a relation.
+    #
+    # @param uri [Addressable::URI, String] URI to resolve.
+    # @return [Addressable::URI] Absolute URI.
+    #
     def join(uri)
-      self.uri.join uri
+      if uri.is_a?(Addressable::URI) && uri.absolute?
+        uri
+      else
+        self.uri.join(uri)
+      end
     end
 
-    def inherit(uri, **kwargs)
+    def inherit(uri, **)
       uri ||= self.uri
-      Context.new(uri, **kwargs, **options)
+      Context.new(uri, **, **options)
     end
 
     def process(response)
@@ -47,16 +57,16 @@ module Restify
       processor.new(context, response).resource
     end
 
-    def request(method, uri, data: nil, headers: {}, **kwargs)
+    def request(method, uri, data: nil, headers: {}, **)
       request = Request.new(
         headers: default_headers.merge(headers),
-        **kwargs,
+        **,
         method:,
         uri: join(uri),
         data:,
       )
 
-      ret = cache.call(request) {|req| adapter.call(req) }
+      ret = cache ? cache.call(request) {|req| adapter.call(req) } : adapter.call(request)
       ret.then do |response|
         raise ResponseError.from_code(response) if response.errored?
 

data/lib/restify/error.rb

@@ -13,6 +13,19 @@ module Restify
     end
   end
 
+  # A {ParseError} is raised when accessing the data of a resource,
+  # whose response body could not be parsed, e.g. invalid JSON. The
+  # original error is available as {#cause}.
+  #
+  class ParseError < StandardError
+    attr_reader :response
+
+    def initialize(response, message)
+      @response = response
+      super("Could not parse response body for `#{response&.uri}': #{message}")
+    end
+  end
+
   # A {ResponseError} is returned on a non-successful
   # response from server. Usually it will either be a
   # {ClientError} or a {ServerError}.

data/lib/restify/global.rb

@@ -2,47 +2,26 @@
 
 module Restify
   module Global
-    def new(uri, **opts)
-      context = resolve_context uri, **opts
+    def new(uri, **)
+      context = resolve_context(uri, **)
 
       Relation.new context, context.uri
     end
 
-    def adapter
-      @adapter ||= begin
-        Restify::Adapter::Typhoeus.new
-      end
-    end
-
-    def adapter=(adapter)
-      @adapter = adapter
-    end
-
-    def cache
-      @cache ||= begin
-        require 'active_support'
-        require 'active_support/cache'
-        Restify::Cache.new store: ActiveSupport::Cache::MemoryStore.new
-      end
-    end
-
-    def cache=(cache)
-      @cache = cache
-    end
+    attr_writer :adapter
+    attr_accessor :cache, :logger
 
-    def logger
-      ::Logging.logger[Restify]
+    def adapter
+      @adapter ||= Restify::Adapter::Ethon.new
     end
 
-    def logger=(logger); end
-
     private
 
-    def resolve_context(uri, **opts)
+    def resolve_context(uri, **)
       if uri.is_a? Symbol
-        Restify::Registry.fetch(uri).inherit(nil, **opts)
+        Restify::Registry.fetch(uri).inherit(nil, **)
       else
-        Context.new(uri, **opts)
+        Context.new(uri, **)
       end
     end
   end