Skip to content

Commit

Permalink
Documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
ioquatix committed Jul 13, 2024
1 parent fcca9d8 commit dd1e4e4
Show file tree
Hide file tree
Showing 3 changed files with 48 additions and 0 deletions.
10 changes: 10 additions & 0 deletions lib/async/http/faraday.rb
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,13 @@
require_relative "faraday/adapter"

Faraday::Adapter.register_middleware :async_http => Async::HTTP::Faraday::Adapter

# @namespace
module Async
# @namespace
module HTTP
# @namespace
module Faraday
end
end
end
37 changes: 37 additions & 0 deletions lib/async/http/faraday/adapter.rb
Original file line number Diff line number Diff line change
Expand Up @@ -18,24 +18,35 @@
module Async
module HTTP
module Faraday
# This is a simple wrapper around Faraday's body that allows it to be read in chunks.
class BodyReadWrapper < ::Protocol::HTTP::Body::Readable
# Create a new wrapper around the given body.
#
# The body must respond to `#read` and `#close` and is often an instance of `IO` or `Faraday::Multipart::CompositeReadIO`.
#
# @parameter body [Interface(:read)] The input body to wrap.
# @parameter block_size [Integer] The size of the blocks to read from the body.
def initialize(body, block_size: 4096)
@body = body
@block_size = block_size
end

# Close the body if possible.
def close(error = nil)
@body.close if @body.respond_to?(:close)
ensure
super
end

# Read from the body in chunks.
def read
@body.read(@block_size)
end
end

# An adapter that allows Faraday to use Async::HTTP as the underlying HTTP client.
class Adapter < ::Faraday::Adapter
# The exceptions that are considered connection errors and result in a `Faraday::ConnectionFailed` exception.
CONNECTION_EXCEPTIONS = [
Errno::EADDRNOTAVAIL,
Errno::ECONNABORTED,
Expand All @@ -49,6 +60,10 @@ class Adapter < ::Faraday::Adapter
SocketError
].freeze

# Create a Farady compatible adapter.
#
# @parameter timeout [Integer] The timeout for requests.
# @parameter options [Hash] Additional options to pass to the underlying Async::HTTP::Client.
def initialize(*arguments, timeout: nil, **options, &block)
super(*arguments, **options)

Expand All @@ -59,10 +74,18 @@ def initialize(*arguments, timeout: nil, **options, &block)
@options = options
end

# Make a new client for the given endpoint.
#
# @parameter endpoint [IO::Endpoint::Generic] The endpoint to create the client for.
def make_client(endpoint)
Client.new(endpoint, **@connection_options)
end

# Get the host key for the given endpoint.
#
# This is used to cache clients for the same host.
#
# @parameter endpoint [IO::Endpoint::Generic] The endpoint to get the host key for.
def host_key(endpoint)
url = endpoint.url.dup

Expand All @@ -73,6 +96,9 @@ def host_key(endpoint)
return url
end

# Get a client for the given endpoint. If a client already exists for the host, it will be reused.
#
# @parameter endpoint [IO::Endpoint::Generic] The endpoint to get the client for.
def client_for(endpoint)
key = host_key(endpoint)

Expand All @@ -81,6 +107,10 @@ def client_for(endpoint)
end
end

# Get a client for the given proxy endpoint and endpoint. If a client already exists for the host, it will be reused.
#
# @parameter proxy_endpoint [IO::Endpoint::Generic] The proxy endpoint to use.
# @parameter endpoint [IO::Endpoint::Generic] The endpoint to get the client for.
def proxy_client_for(proxy_endpoint, endpoint)
key = [host_key(proxy_endpoint), host_key(endpoint)]

Expand All @@ -90,6 +120,7 @@ def proxy_client_for(proxy_endpoint, endpoint)
end
end

# Close all clients.
def close
# The order of operations here is to avoid a race condition between iterating over clients (#close may yield) and creating new clients.
clients = @clients.values
Expand All @@ -99,6 +130,12 @@ def close
clients.each(&:close)
end

# Make a request using the adapter.
#
# @parameter env [Faraday::Env] The environment to make the request in.
# @raises [Faraday::TimeoutError] If the request times out.
# @raises [Faraday::SSLError] If there is an SSL error.
# @raises [Faraday::ConnectionFailed] If there is a connection error.
def call(env)
super

Expand Down
1 change: 1 addition & 0 deletions lib/async/http/faraday/default.rb
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,5 @@

require_relative 'adapter'

# Set the default adapter to use Async::HTTP.
::Faraday.default_adapter = :async_http

0 comments on commit dd1e4e4

Please sign in to comment.