async-http-faraday 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8efd253e7a697bce2dbe8aafcab6cc667584242e923ee060213ee88ba40a2ce
-  data.tar.gz: 34c1d934c5e153091a04e5208144026d5da10e6dd429c67a0770a3f25b71ecdc
+  metadata.gz: a24c51b0aca4a4243f088331a3731da8792287fe94f30e1b2d6f398dd521a238
+  data.tar.gz: '0687f09a3bc87ab6989b4cabc108aff16e21c606755c04fd77112afc40d4d124'
 SHA512:
-  metadata.gz: 7d921cee566700dc9c82bbf9f993f20c8f912523ed75b78d7f644c0e962fce63203f38648867ebc74b600713d1240db7909d69f0199ac56e3dcef90942ac855e
-  data.tar.gz: 8a7746559ec23c868445ae1d18201d6ac00c38ef1c950d0401d14cf62c4852c4861ad852d5bc9fe7044840b7db659ff63ef7088354fded353014f1641d04bdad
+  metadata.gz: ed876ca460be8b0e402240081ab6dcc9318af3e1dce3e34787c40e3bee45fff6e472bb72f30babc666d8ad7660f688d066903f09a253dfc70081fcc2d76e95ca
+  data.tar.gz: a1dc04a882e162e15c9161cddd48c298e027ed83fb2d5e09a0438f925277e7ad139e0f4577c13ca47f2f0164bde3a9e830cb1062a6eecbc84dbcbc52350cf785

data/lib/async/http/faraday/adapter.rb

@@ -7,6 +7,7 @@
 # Copyright, 2019-2020, by Igor Sidorov.
 # Copyright, 2023, by Genki Takiuchi.
 # Copyright, 2023, by Flavio Fernandes.
+# Copyright, 2024, by Jacob Frautschi.
 
 require 'faraday'
 require 'faraday/adapter'
@@ -15,27 +16,40 @@ require 'kernel/sync'
 require 'async/http/client'
 require 'async/http/proxy'
 
+require_relative 'clients'
+
 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,
@@ -49,76 +63,47 @@ module Async
 					SocketError
 				].freeze
 				
-				def initialize(*arguments, timeout: nil, **options, &block)
-					super(*arguments, **options)
-					
-					@timeout = timeout
-					
-					@clients = {}
-					
-					@options = options
-				end
-				
-				def make_client(endpoint)
-					Client.new(endpoint, **@connection_options)
-				end
-				
-				def host_key(endpoint)
-					url = endpoint.url.dup
-					
-					url.path = ""
-					url.fragment = nil
-					url.query = nil
-					
-					return url
-				end
-				
-				def client_for(endpoint)
-					key = host_key(endpoint)
+				# 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(...)
+					super
 					
-					@clients.fetch(key) do
-						@clients[key] = make_client(endpoint)
-					end
-				end
-				
-				def proxy_client_for(proxy_endpoint, endpoint)
-					key = [host_key(proxy_endpoint), host_key(endpoint)]
+					@timeout = @connection_options.delete(:timeout)
 					
-					@clients.fetch(key) do
-						client = client_for(proxy_endpoint)
-						@clients[key] = client.proxied_client(endpoint)
+					if clients = @connection_options.delete(:clients)
+						@clients = clients.call(**@connection_options, &@config_block)
+					else
+						@clients = PersistentClients.new(**@connection_options, &@config_block)
 					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
-					
-					@clients.clear
-					
-					clients.each(&:close)
+					@clients.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
 					
-					# for compatibility with the default adapter
+					# For compatibility with the default adapter:
 					env.url.path = '/' if env.url.path.empty?
 					
-					Sync do
-						endpoint = Endpoint.new(env.url)
-						
-						if proxy = env.request.proxy
-							proxy_endpoint = Endpoint.new(proxy.uri)
-							client = self.proxy_client_for(proxy_endpoint, endpoint)
-						else
-							client = self.client_for(endpoint)
-						end
-						
+					with_client(env) do |endpoint, client|
 						if body = env.body
-							# We need to wrap the body in a Readable object so that it can be read in chunks:
+							# We need to ensure the body is wrapped in a Readable object so that it can be read in chunks:
 							# Faraday's body only responds to `#read`.
-							if body.respond_to?(:read)
+							if body.is_a?(::Protocol::HTTP::Body::Readable)
+								# Good to go
+							elsif body.respond_to?(:read)
 								body = BodyReadWrapper.new(body)
 							else
 								body = ::Protocol::HTTP::Body::Buffered.wrap(body)
@@ -151,6 +136,24 @@ module Async
 				
 				private
 				
+				def with_client(env)
+					Sync do
+						endpoint = Endpoint.new(env.url)
+						
+						if proxy = env.request.proxy
+							proxy_endpoint = Endpoint.new(proxy.uri)
+							
+							@clients.with_proxied_client(proxy_endpoint, endpoint) do |client|
+								yield endpoint, client
+							end
+						else
+							@clients.with_client(endpoint) do |client|
+								yield endpoint, client
+							end
+						end
+					end
+				end
+				
 				def with_timeout(task: Async::Task.current)
 					if @timeout
 						task.with_timeout(@timeout, ::Faraday::TimeoutError) do

data/lib/async/http/faraday/clients.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018, by Andreas Garnaes.
+# Copyright, 2019, by Denis Talakevich.
+# Copyright, 2019-2020, by Igor Sidorov.
+# Copyright, 2023, by Genki Takiuchi.
+# Copyright, 2023, by Flavio Fernandes.
+# Copyright, 2024, by Jacob Frautschi.
+
+require 'faraday'
+require 'faraday/adapter'
+require 'kernel/sync'
+
+require 'async/http/client'
+require 'async/http/proxy'
+
+module Async
+	module HTTP
+		module Faraday
+			# An interface for creating and managing HTTP clients.
+			class Clients
+				# Create a new instance of the class.
+				def self.call(...)
+					new(...)
+				end
+				
+				# Create a new interface for managing HTTP clients.
+				#
+				# @parameter options [Hash] The options to create the clients with.
+				# @parameter block [Proc] An optional block to call with the client before it is used.
+				def initialize(**options, &block)
+					@options = options
+					@block = block
+				end
+				
+				# Close all clients.
+				def close
+				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 = Client.new(endpoint, **@options)
+					@block&.call(client)
+					return client
+				end
+				
+				# Get a client for the given endpoint.
+				#
+				# @parameter endpoint [IO::Endpoint::Generic] The endpoint to get the client for.
+				# @yields {|client| ...} A client for the given endpoint.
+				def with_client(endpoint)
+					client = make_client(endpoint)
+					
+					yield client
+				ensure
+					client&.close
+				end
+				
+				# Get a client for the given proxy endpoint and endpoint.
+				#
+				# @parameter proxy_endpoint [IO::Endpoint::Generic] The proxy endpoint to use.
+				# @parameter endpoint [IO::Endpoint::Generic] The endpoint to get the client for.
+				# @yields {|client| ...} A client for the given endpoint.
+				def with_proxied_client(proxy_endpoint, endpoint)
+					client = client_for(proxy_endpoint)
+					proxied_client = client.proxied_client(endpoint)
+					
+					yield proxied_client 
+				ensure
+					proxied_client&.close
+					client&.close
+				end
+			end
+			
+			# An interface for creating and managing persistent HTTP clients.
+			class PersistentClients < Clients
+				# Create a new instance of the class.
+				def initialize(...)
+					super
+					
+					@clients = {}
+				end
+				
+				# Close all clients.
+				def close
+					super
+					
+					clients = @clients.values
+					@clients.clear
+					
+					clients.each(&:close)
+				end
+				
+				# Get a client for the given endpoint. If a client already exists for the host, it will be reused.
+				#
+				# @yields {|client| ...} A client for the given endpoint.
+				def with_client(endpoint)
+					yield make_client(endpoint)
+				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 with_proxied_client(proxy_endpoint, endpoint)
+					key = [host_key(proxy_endpoint), host_key(endpoint)]
+					
+					proxied_client = fetch(key) do
+						client_for(proxy_endpoint).proxied_client(endpoint)
+					end
+					
+					yield proxied_client
+				end
+				
+				private
+				
+				def fetch(key)
+					@clients.fetch(key) do
+						@clients[key] = yield
+					end
+				end
+				
+				def host_key(endpoint)
+					url = endpoint.url.dup
+					
+					url.path = ""
+					url.fragment = nil
+					url.query = nil
+					
+					return url
+				end
+				
+				def client_for(endpoint)
+					key = host_key(endpoint)
+					
+					fetch(key) do
+						make_client
+					end
+				end
+			end
+			
+			# An interface for creating and managing per-thread persistent HTTP clients.
+			class PerThreadPersistentClients
+				# Create a new instance of the class.
+				#
+				# @parameter options [Hash] The options to create the clients with.
+				# @parameter block [Proc] An optional block to call with the client before it is used.
+				def initialize(**options, &block)
+					@options = options
+					@block = block
+					
+					@key = :"#{self.class}_#{object_id}"
+				end
+				
+				# Get a client for the given endpoint. If a client already exists for the host, it will be reused.
+				#
+				# The client instance will be will be cached per-thread.
+				#
+				# @yields {|client| ...} A client for the given endpoint.
+				def with_client(endpoint, &block)
+					clients.with_client(endpoint, &block)
+				end
+				
+				# Get a client for the given proxy endpoint and endpoint. If a client already exists for the host, it will be reused.
+				#
+				# The client instance will be will be cached per-thread.
+				#
+				# @parameter proxy_endpoint [IO::Endpoint::Generic] The proxy endpoint to use.
+				# @parameter endpoint [IO::Endpoint::Generic] The endpoint to get the client for.
+				def with_proxied_client(proxy_endpoint, endpoint, &block)
+					clients.with_proxied_client(proxy_endpoint, endpoint, &block)
+				end
+				
+				# Close all clients.
+				#
+				# This will close all clients associated with all threads.
+				def close
+					Thread.list.each do |thread|
+						if clients = thread[@key]
+							clients.close
+							
+							thread[@key] = nil
+						end
+					end
+				end
+				
+				private
+				
+				def make_clients
+					PersistentClients.new(**@options, &@block)
+				end
+				
+				def clients
+					thread = Thread.current
+					
+					return thread.thread_variable_get(@key) || thread.thread_variable_set(@key, make_clients)
+				end
+			end
+		end
+	end
+end

data/lib/async/http/faraday/default.rb

@@ -5,4 +5,5 @@
 
 require_relative 'adapter'
 
+# Set the default adapter to use Async::HTTP.
 ::Faraday.default_adapter = :async_http

data/lib/async/http/faraday/version.rb

@@ -6,7 +6,7 @@
 module Async
 	module HTTP
 		module Faraday
-			VERSION = "0.14.0"
+			VERSION = "0.15.0"
 		end
 	end
 end

data/lib/async/http/faraday.rb

@@ -7,3 +7,13 @@ require_relative "faraday/version"
 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

data/license.md

@@ -8,6 +8,7 @@ Copyright, 2020-2021, by Olle Jonsson.
 Copyright, 2020, by Benoit Daloze.  
 Copyright, 2023, by Genki Takiuchi.  
 Copyright, 2023, by Flavio Fernandes.  
+Copyright, 2024, by Jacob Frautschi.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -1,56 +1,17 @@
 # Async::HTTP::Faraday
 
-Provides an adaptor for [Faraday](https://github.com/lostisland/faraday) to perform async HTTP requests. If you are designing a new library, you should probably just use `Async::HTTP::Client` directly.
+Provides an adaptor for [Faraday](https://github.com/lostisland/faraday) to perform async HTTP requests. If you are designing a new library, you should probably just use `Async::HTTP::Client` directly. However, for existing projects and libraries that use Faraday as an abstract interface, this can be a drop-in replacement to improve concurrency. It should be noted that the default `Net::HTTP` adapter works perfectly okay with Async, however it does not use persistent connections by default.
 
-[![Development Status](https://github.com/socketry/async-http-faraday/workflows/Test/badge.svg)](https://github.com/socketry/async-http-faraday/actions?workflow=Test)
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-``` ruby
-gem 'async-http-faraday'
-```
+  - Persistent connections by default.
+  - Supports HTTP/1 and HTTP/2 (and HTTP/3 in the future).
 
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install async-http-faraday
+[![Development Status](https://github.com/socketry/async-http-faraday/workflows/Test/badge.svg)](https://github.com/socketry/async-http-faraday/actions?workflow=Test)
 
 ## Usage
 
-Here is how you set faraday to use `Async::HTTP`:
-
-``` ruby
-require 'async/http/faraday'
-
-# Make it the global default:
-Faraday.default_adapter = :async_http
-
-# Per connection:
-connection = Faraday.new(...) do |builder|
-	builder.adapter :async_http
-end
-```
-
-Here is how you make a request:
-
-``` ruby
-Async do
-	response = connection.get("/index")
-end
-```
-
-### Default
-
-To make this the default adaptor:
+Please see the [project documentation](https://socketry.github.io/async-http/) for more details.
 
-``` ruby
-require 'async/http/faraday/default'
-```
+  - [Getting Started](https://socketry.github.io/async-http/guides/getting-started/index) - This guide explains how to use use `Async::HTTP::Faraday` as a drop-in replacement for improved concurrency.
 
 ## Contributing
 
@@ -64,8 +25,8 @@ We welcome contributions to this project.
 
 ### Developer Certificate of Origin
 
-This project uses the [Developer Certificate of Origin](https://developercertificate.org/). All contributors to this project must agree to this document to have their contributions accepted.
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
 
-### Contributor Covenant
+### Community Guidelines
 
-This project is governed by the [Contributor Covenant](https://www.contributor-covenant.org/). All contributors and participants agree to abide by its terms.
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-http-faraday
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -12,6 +12,7 @@ authors:
 - Benoit Daloze
 - Denis Talakevich
 - Flavio Fernandes
+- Jacob Frautschi
 autorequire:
 bindir: bin
 cert_chain:
@@ -44,7 +45,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-04-23 00:00:00.000000000 Z
+date: 2024-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-http
@@ -83,6 +84,7 @@ files:
 - examples/topics.rb
 - lib/async/http/faraday.rb
 - lib/async/http/faraday/adapter.rb
+- lib/async/http/faraday/clients.rb
 - lib/async/http/faraday/default.rb
 - lib/async/http/faraday/version.rb
 - license.md
@@ -108,7 +110,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: Provides an adaptor between async-http and faraday.