async-http 0.101.0 → 0.102.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 397ffac9d60c7ff7d3524624cffdfb5105a2cdc1e7a540cc8b282824b5bf890a
-  data.tar.gz: fd2cc4a962f28ddb8cb79f4035315816b9a7dd5785e76494b764764f3dd51ef6
+  metadata.gz: 39dbd69fca4e67586111ac9fc21231b0a4aff0ade936468c8851707004d9c456
+  data.tar.gz: c10435cb4d54c2220170624931c87ed77302eb01ff8c9b70a89c22bc56c551cb
 SHA512:
-  metadata.gz: 771358b08bcf8ceba72af908b5b5f3d78be7a3751a7051d6350132bb9e942809054da7b2b205169df6eb9e26a49a873743b187df9d0a7d49bc43166db9769519
-  data.tar.gz: 998d6fcc02cf5b56f5883d6c26cf3e4a5ca009e2fa1234037c9c2fe4ccabc6262c9b6ede32778a98aabf5e1fd1f9ed3cdae7c9f8613b96338df8bf84ebd36b0c
+  metadata.gz: 0367722b925fb45a0517f1890aac1b724aa025d9db58843f034e8b9cc03ffb18044398a442b6ffff92cd4e0ac0a04773730c22384a21640521865e4dd3858993
+  data.tar.gz: 7602b933368edfdbc7e812fab78193a5436ed7a95de8214ecc3ba42618e7c20c2b26c10309c6609952381992387c23d2f4a5ff30b7bff25dd4a315055fd5d24d

data/context/choosing-a-client.md

@@ -0,0 +1,164 @@
+# Choosing a Client
+
+This guide explains how to choose between ruby:`Async::HTTP::Internet`, ruby:`Async::HTTP::Client`, and higher-level interfaces for libraries.
+
+ruby:`Async::HTTP::Internet` and ruby:`Async::HTTP::Client` use the same request and response model. The important differences are how destinations are selected, where connection settings are applied, and who owns the client life cycle.
+
+## Quick Decision
+
+| Situation | Interface | Why |
+| --- | --- | --- |
+| Requests may target different origins and the defaults are suitable. | Shared ruby:`Async::HTTP::Internet` | Selects and reuses a client for each origin automatically. |
+| Requests may target different origins, but need common client options or explicit ownership. | Explicit ruby:`Async::HTTP::Internet` | Applies the same options to each managed client and can be injected or closed early. |
+| Requests repeatedly target one configured origin. | ruby:`Async::HTTP::Client` | Exposes the endpoint, protocol, retry, and connection-pool configuration directly. |
+| A library wraps one HTTP service directly. | Injected ruby:`Async::HTTP::Client` or `Protocol::HTTP` middleware | Leaves transport configuration, ownership, and testing under application control. |
+| A library models an HTTP API as resources and representations. | [`async-rest`](https://socketry.github.io/async-rest/guides/getting-started/) | Provides higher-level API modeling over an injectable `Protocol::HTTP` delegate. |
+| A library uses Faraday as its HTTP abstraction. | [`async-http-faraday`](https://socketry.github.io/async-http-faraday/guides/getting-started/) | Lets the application retain the Faraday interface while using `Async::HTTP` as the transport. |
+
+Application code can start with the shared `Internet` interface unless it has a specific ownership or configuration requirement. Library code should accept an explicit HTTP dependency.
+
+## Shared Internet for General Requests
+
+The shared `Internet` interface is the simplest choice for requests to arbitrary URLs. It maintains one client for each origin and reuses persistent connections:
+
+~~~ ruby
+require "async/http/internet/instance"
+
+urls = [
+	"https://www.ruby-lang.org/en/",
+	"https://example.com/",
+]
+
+Sync do
+	urls.each do |url|
+		Async::HTTP::Internet.get(url) do |response|
+			puts "#{url}: #{response.status}"
+		end
+	end
+end
+~~~
+
+The class-level interface uses a thread-local `Internet` instance. Its connection pools are bound to the event loop and close when that event loop exits. The response block closes each response after it is processed.
+
+Use the shared interface when:
+
+- The application requests URLs from multiple or dynamically selected origins.
+- Default retry and connection-pool settings are suitable.
+- The client does not need to be injected as an application dependency.
+
+## Explicit Internet for Shared Configuration
+
+An explicit `Internet` provides the same per-origin client selection while making ownership and client options visible. Options are passed to every client it creates; for example, `limit` applies independently to the pool for each origin:
+
+~~~ ruby
+require "async/http/internet"
+
+Sync do
+	internet = Async::HTTP::Internet.new(retries: 1, limit: 4)
+	
+	begin
+		internet.get("https://www.ruby-lang.org/en/") do |response|
+			puts response.status
+		end
+	ensure
+		internet.close
+	end
+end
+~~~
+
+Use an explicit `Internet` when:
+
+- Several origins should share the same retry or pool settings.
+- The client should be injected into another object or replaced during testing.
+- Connections should be released before the event loop exits.
+
+## Client for One Endpoint
+
+A `Client` targets one ruby:`Async::HTTP::Endpoint`. Use it when a remote service is a stable part of the application architecture and needs its own protocol, TLS, retry, or pool configuration:
+
+~~~ ruby
+require "async/http"
+
+endpoint = Async::HTTP::Endpoint.parse("https://httpbin.org")
+
+Sync do
+	Async::HTTP::Client.open(endpoint, retries: 1, limit: 4) do |client|
+		response = client.get("/status/200")
+		
+		begin
+			puts response.status
+		ensure
+			response.close
+		end
+	end
+end
+~~~
+
+Client convenience methods accept a path rather than a complete URL. They return a response that the caller must close. `Client.open` closes the client and its connection pool when the block exits.
+
+Reuse a client for repeated requests rather than creating one per request; otherwise the application cannot benefit from persistent connections.
+
+## Building a Library That Makes HTTP Requests
+
+A library should generally accept its HTTP client as an explicit dependency. This lets the application configure connection limits, retries, proxies, instrumentation, and test doubles without the library creating hidden global state:
+
+~~~ ruby
+require "async/http"
+
+class StatusService
+	def initialize(client)
+		@client = client
+	end
+	
+	def healthy?
+		response = @client.get("/status/200")
+		response.status == 200
+	ensure
+		response&.close
+	end
+end
+
+endpoint = Async::HTTP::Endpoint.parse("https://httpbin.org")
+
+Sync do
+	Async::HTTP::Client.open(endpoint) do |client|
+		puts StatusService.new(client).healthy?
+	end
+end
+~~~
+
+The library does not close an injected client because the caller owns it and may share it with other components. If the library also provides an `open` convenience method that constructs a client, that method should close the client it creates when its block exits.
+
+Define the accepted interface precisely. A ruby:`Async::HTTP::Client` is bound to one endpoint and its convenience methods accept relative paths, while ruby:`Async::HTTP::Internet` selects an endpoint from a complete URL. They should not be treated as interchangeable merely because both provide methods such as `get`. If the library constructs ruby:`Protocol::HTTP::Request` objects and only calls `call`, it can accept a `Protocol::HTTP` middleware delegate instead of requiring a concrete client.
+
+## Modeling Resources with async-rest
+
+Use [`async-rest`](https://socketry.github.io/async-rest/guides/getting-started/) when a library benefits from modeling a remote HTTP API as resources and representations rather than exposing request operations directly.
+
+ruby:`Async::REST::Resource` accepts a `Protocol::HTTP` middleware delegate, so the application can supply and configure the transport. Its `open` method provides the complementary convenience interface: it creates a ruby:`Async::HTTP::Client`, yields the resource, and closes the client when the block exits.
+
+## Supporting Faraday with async-http-faraday
+
+Use [`async-http-faraday`](https://socketry.github.io/async-http-faraday/guides/getting-started/) when a library uses Faraday as its public HTTP abstraction or needs compatibility with the Faraday ecosystem. A new Async-native library can usually accept a ruby:`Async::HTTP::Client` or `Protocol::HTTP` middleware delegate directly.
+
+If a library uses Faraday, accept a configured `Faraday::Connection` rather than changing `Faraday.default_adapter` globally. The application can then select the `Async::HTTP` adapter for that connection:
+
+~~~ ruby
+require "async/http/faraday"
+
+class StatusService
+	def initialize(connection)
+		@connection = connection
+	end
+	
+	def healthy?
+		@connection.get("/status/200").success?
+	end
+end
+
+connection = Faraday.new("https://httpbin.org") do |builder|
+	builder.adapter :async_http
+end
+
+puts StatusService.new(connection).healthy?
+~~~

data/context/concurrent-requests.md

@@ -0,0 +1,134 @@
+# Concurrent Requests and Connection Pooling
+
+This guide explains how to run HTTP requests concurrently while keeping request fan-out, connection usage, and resource life cycles bounded.
+
+Concurrent requests allow independent network operations to overlap. `Async::HTTP` combines this task concurrency with persistent connection pools, but the number of request tasks and the number of connections are separate controls.
+
+## Running Independent Requests Concurrently
+
+When several requests do not depend on each other, start one child task for each request and then wait for their results:
+
+~~~ ruby
+require "async/http/internet/instance"
+require "json"
+
+names = ["async", "async-http", "falcon"]
+
+versions = Sync do |task|
+	tasks = names.map do |name|
+		task.async do
+			url = "https://rubygems.org/api/v1/gems/#{name}.json"
+			
+			Async::HTTP::Internet.get(url) do |response|
+				raise "Could not fetch #{name}: #{response.status}" unless response.success?
+				
+				JSON.parse(response.read).fetch("version")
+			end
+		end
+	end
+	
+	tasks.map(&:wait)
+end
+
+names.zip(versions) do |name, version|
+	puts "#{name}: #{version}"
+end
+~~~
+
+Each request can make progress while the others are waiting for network I/O. ruby:`Async::Task#wait` returns the task result and re-raises any failure, so request errors are not silently discarded. Results are collected in the original order even if requests finish in a different order.
+
+The response block closes each response after its body is processed. General task creation, cancellation, and failure propagation are covered by the [`async` Tasks guide](https://socketry.github.io/async/guides/tasks/).
+
+## Limiting Request Concurrency
+
+Creating one task per item is appropriate for a small, fixed collection. A large or externally supplied collection should have an explicit concurrency limit so it cannot overwhelm the remote service or retain an unbounded number of pending operations.
+
+Use ruby:`Async::Semaphore` to set a fixed request limit and ruby:`Async::Barrier` to wait for all the work:
+
+~~~ ruby
+require "async"
+require "async/semaphore"
+require "async/http/internet"
+
+names = ["async", "async-http", "falcon", "protocol-http", "io-event", "console"]
+
+Sync do
+	internet = Async::HTTP::Internet.new(limit: 2)
+	
+	begin
+		Barrier(parent: nil) do |barrier|
+			requests = Async::Semaphore.new(4, parent: barrier)
+			
+			names.each do |name|
+				requests.async do
+					url = "https://rubygems.org/api/v1/gems/#{name}.json"
+					
+					internet.get(url) do |response|
+						raise "Could not fetch #{name}: #{response.status}" unless response.success?
+						
+						puts "#{name}: #{response.status}"
+					end
+				end
+			end
+		end
+	ensure
+		internet.close
+	end
+end
+~~~
+
+The semaphore allows at most four request operations to run at once. The barrier tracks those tasks, waits for them to finish, propagates failures, and cancels unfinished work if the block exits early. `parent: nil` disables the barrier's load-based scheduling because the semaphore already provides an explicit limit.
+
+See the [`async` Best Practices guide](https://socketry.github.io/async/guides/best-practices/) for general guidance on barriers, semaphores, and large workloads.
+
+## Request Limits and Connection Limits
+
+Request concurrency and pool capacity solve different problems:
+
+| Control | What It Limits | Scope |
+| --- | --- | --- |
+| ruby:`Async::Semaphore` | Concurrent request operations and their application work. | The tasks started through that semaphore. |
+| `limit` passed to ruby:`Async::HTTP::Client` | Connections held by one client pool. | One configured endpoint. |
+| `limit` passed to ruby:`Async::HTTP::Internet` | Connections held by each client it creates. | Applied independently to every origin. |
+
+The client creates connections lazily and reuses viable persistent connections. When its pool reaches `limit`, a request waits until an existing connection has capacity or is released.
+
+For HTTP/1, a connection normally processes one request at a time, so connection capacity also constrains active requests. HTTP/2 can multiplex several request streams over one connection, so a small connection pool may support much higher request concurrency. Use a semaphore when the application needs a protocol-independent request limit; use `limit` to control connection resources.
+
+## Releasing Connections for Reuse
+
+A response retains pool capacity until its body is finished or closed. Always close responses promptly, especially before starting more requests that use the same limited pool:
+
+~~~ ruby
+require "async/http"
+
+endpoint = Async::HTTP::Endpoint.parse("https://rubygems.org")
+
+Sync do
+	Async::HTTP::Client.open(endpoint, limit: 1) do |client|
+		response = client.get("/api/v1/gems/async-http.json")
+		
+		begin
+			raise "Download failed: #{response.status}" unless response.success?
+			
+			bytes = 0
+			
+			response.each do |chunk|
+				bytes += chunk.bytesize
+			end
+			
+			puts "Downloaded #{bytes} bytes."
+		ensure
+			response.close
+		end
+	end
+end
+~~~
+
+The block form of ruby:`Async::HTTP::Internet` performs this cleanup automatically. When using ruby:`Async::HTTP::Client`, close the response explicitly with an `ensure` block. Holding an unread response while waiting for another request can exhaust an HTTP/1 pool and make the second request wait indefinitely.
+
+## Pool Life Cycle
+
+Connection pools are bound to the event loop in which they are used. Their internal maintenance task is transient, so it does not keep the event loop alive and closes the pool when the event loop exits.
+
+Use the shared ruby:`Async::HTTP::Internet` interface when connections can remain open until the event loop exits. Use ruby:`Async::HTTP::Client.open`, or explicitly close an `Internet` or `Client`, when connections should be released earlier. See [Choosing a Client](../choosing-a-client/) for the ownership trade-offs.

data/context/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-This guide explains how to get started with `Async::HTTP`.
+This guide explains how to make HTTP requests and serve HTTP responses with `Async::HTTP`.
 
 ## Installation
 
@@ -12,137 +12,174 @@ $ bundle add async-http
 
 ## Core Concepts
 
-- {ruby Async::HTTP::Client} is the main class for making HTTP requests.
-- {ruby Async::HTTP::Internet} provides a simple interface for making requests to any server "on the internet".
-- {ruby Async::HTTP::Server} is the main class for handling HTTP requests.
-- {ruby Async::HTTP::Endpoint} can parse HTTP URLs in order to create a client or server.
-- [`protocol-http`](https://github.com/socketry/protocol-http) provides the abstract HTTP protocol interfaces.
+`Async::HTTP` provides several interfaces for different kinds of HTTP applications:
 
-## Usage
+- ruby:`Async::HTTP::Internet` makes requests to arbitrary hosts and manages a client for each remote endpoint.
+- ruby:`Async::HTTP::Client` manages persistent connections to a specific endpoint.
+- ruby:`Async::HTTP::Server` accepts connections and dispatches requests to an HTTP application.
+- ruby:`Async::HTTP::Endpoint` describes how a client connects or a server listens, including the URL, protocol, and TLS configuration.
+- [`protocol-http`](https://github.com/socketry/protocol-http) provides the shared request, response, header, and body interfaces.
 
-### Making a Request
+Use `Internet` for general-purpose requests to different hosts. Use `Client` when your application repeatedly communicates with one endpoint or needs endpoint-specific configuration. See [Choosing a Client](../choosing-a-client/) for the ownership and configuration trade-offs.
 
-To make a request, use {ruby Async::HTTP::Internet} and call the appropriate method:
+## Making a Request
+
+The shared ruby:`Async::HTTP::Internet` instance provides a convenient starting point. Run asynchronous HTTP operations inside `Sync`, which creates or reuses the event loop while returning the block result directly:
 
 ~~~ ruby
-require 'async/http/internet/instance'
+require "async/http/internet/instance"
 
 Sync do
 	Async::HTTP::Internet.get("https://httpbin.org/get") do |response|
+		puts "Status: #{response.status}"
 		puts response.read
 	end
 end
 ~~~
 
-The following methods are supported:
+Passing a block automatically closes the response when the block exits, including when an exception is raised. Responses are streamed, so callers that do not use the block form must close the response explicitly.
 
 ~~~ ruby
-Async::HTTP::Internet.methods(false)
-# => [:patch, :options, :connect, :post, :get, :delete, :head, :trace, :put]
+require "async/http/internet/instance"
+
+Sync do
+	response = Async::HTTP::Internet.get("https://httpbin.org/get")
+	puts response.read
+ensure
+	response&.close
+end
 ~~~
 
-Using a block will automatically close the response when the block completes. If you want to keep the response open, you can manage it manually:
+Convenience methods are provided for `GET`, `HEAD`, `POST`, `PUT`, `DELETE`, `CONNECT`, `OPTIONS`, `TRACE`, `PATCH`, and `QUERY` requests.
+
+### Connection Persistence
+
+`Internet` creates a ruby:`Async::HTTP::Client` for each remote endpoint and reuses its persistent connections. The underlying async pools are bound to the event loop and are closed when that event loop exits.
+
+An explicitly created `Internet` can also be closed early when an application wants to release all cached clients before the event loop exits:
 
 ~~~ ruby
-require 'async/http/internet/instance'
+require "async/http/internet"
 
 Sync do
-	response = Async::HTTP::Internet.get("https://httpbin.org/get")
-	puts response.read
+	internet = Async::HTTP::Internet.new
+
+	internet.get("https://example.com") do |response|
+		puts response.status
+	end
 ensure
-	response&.close
+	internet&.close
 end
 ~~~
 
-As responses are streamed, you must ensure it is closed when you are finished with it.
+See [Concurrent Requests and Connection Pooling](../concurrent-requests/) to run independent requests together and configure separate limits for request tasks and connections.
 
-#### Persistence
+## Working with Responses
 
-By default, {ruby Async::HTTP::Internet} will create a {ruby Async::HTTP::Client} for each remote host you communicate with, and will keep those connections open for as long as possible. This is useful for reducing the latency of subsequent requests to the same host. When you exit the event loop, the connections will be closed automatically.
+A response contains a status, headers, and a streaming body. Check the status before processing content, and use header names in lower case:
+
+~~~ ruby
+require "async/http/internet/instance"
+
+Sync do
+	Async::HTTP::Internet.get("https://httpbin.org/json") do |response|
+		if response.success?
+			puts response.headers["content-type"]
+			puts response.read
+		else
+			warn "Request failed with status #{response.status}."
+		end
+	end
+end
+~~~
+
+For larger responses, process the body incrementally rather than reading it into one string. See the [`protocol-http` message body documentation](https://socketry.github.io/protocol-http/guides/message-body/) for the complete body interface.
 
 ### Downloading a File
 
+Use `response.save` to stream a response directly to a file:
+
 ~~~ ruby
-require 'async/http/internet/instance'
+require "async/http/internet/instance"
 
 Sync do
-	# Issue a GET request to Google:
-	response = Async::HTTP::Internet.get("https://www.google.com/search?q=kittens")
-	
-	# Save the response body to a local file:
-	response.save("/tmp/search.html")
-ensure
-	response&.close
+	Async::HTTP::Internet.get("https://example.com/archive.zip") do |response|
+		raise "Download failed with status #{response.status}." unless response.success?
+		
+		response.save("archive.zip")
+	end
 end
 ~~~
 
-### Posting Data
+## Posting JSON
 
-To post data, use the `post` method:
+Pass headers and a body after the request target. The body may be a string or a compatible `protocol-http` body object.
 
 ~~~ ruby
-require 'async/http/internet/instance'
+require "async/http/internet/instance"
+require "json"
 
-data = {'life' => 42}
+data = {life: 42}
+headers = [
+	["accept", "application/json"],
+	["content-type", "application/json"],
+]
 
 Sync do
-	# Prepare the request:
-	headers = [['accept', 'application/json']]
-	body = JSON.dump(data)
-	
-	# Issues a POST request:
-	response = Async::HTTP::Internet.post("https://httpbin.org/anything", headers, body)
-	
-	# Save the response body to a local file:
-	pp JSON.parse(response.read)
-ensure
-	response&.close
+	Async::HTTP::Internet.post("https://httpbin.org/anything", headers, JSON.dump(data)) do |response|
+		raise "Request failed with status #{response.status}." unless response.success?
+		
+		puts JSON.pretty_generate(JSON.parse(response.read))
+	end
 end
 ~~~
 
-For more complex scenarios, including HTTP APIs, consider using [async-rest](https://github.com/socketry/async-rest) instead.
+For resource-oriented HTTP APIs, consider using [`async-rest`](https://github.com/socketry/async-rest), which builds on `Async::HTTP`.
 
-### Timeouts
+## Applying a Timeout
 
-To set a timeout for a request, use the `Task#with_timeout` method:
+Networks can stall indefinitely, so impose a timeout around operations that must complete within a fixed duration:
 
 ~~~ ruby
-require 'async/http/internet/instance'
+require "async/http/internet/instance"
 
 Sync do |task|
-	# Request will timeout after 2 seconds
 	task.with_timeout(2) do
-		response = Async::HTTP::Internet.get "https://httpbin.org/delay/10"
-	ensure
-		response&.close
+		Async::HTTP::Internet.get("https://httpbin.org/delay/10") do |response|
+			puts response.read
+		end
 	end
 rescue Async::TimeoutError
-	puts "The request timed out"
+	warn "The request timed out."
 end
 ~~~
 
-### Making a Server
+The response block still closes the response if the timeout interrupts the request while its body is being processed.
+
+## Making a Server
 
-To create a server, use an instance of {ruby Async::HTTP::Server}:
+ruby:`Async::HTTP::Server` accepts an application that maps each request to a ruby:`Protocol::HTTP::Response`. The following example starts a local server, makes one request, and then releases both client and server resources:
 
 ~~~ ruby
-require 'async/http'
+require "async/http"
 
-endpoint = Async::HTTP::Endpoint.parse('http://localhost:9292')
+endpoint = Async::HTTP::Endpoint.parse("http://localhost:9292")
+server = Async::HTTP::Server.for(endpoint) do |request|
+	Protocol::HTTP::Response[200, {"content-type" => "text/plain"}, ["Hello World"]]
+end
 
-Sync do |task|
-	Async(transient: true) do
-		server = Async::HTTP::Server.for(endpoint) do |request|
-			::Protocol::HTTP::Response[200, {}, ["Hello World"]]
-		end
-		
-		server.run
-	end
+Sync do
+	server_task = server.run
 	
-	client = Async::HTTP::Client.new(endpoint)
-	response = client.get("/")
-	puts response.read
+	Async::HTTP::Client.open(endpoint) do |client|
+		response = client.get("/")
+		puts response.read
+	ensure
+		response&.close
+	end
 ensure
-	response&.close
+	server_task&.stop
 end
 ~~~
+
+Use Falcon when you need to host a Rack application or deploy an HTTP server in production. Use `Async::HTTP::Server` directly when building a protocol-level server or embedding HTTP handling into another asynchronous application.

data/context/index.yaml

@@ -3,13 +3,24 @@
 ---
 description: A HTTP client and server library.
 metadata:
+  bug_tracker_uri: https://github.com/socketry/async-http/issues
+  changelog_uri: https://github.com/socketry/async-http/blob/main/releases.md
   documentation_uri: https://socketry.github.io/async-http/
   source_code_uri: https://github.com/socketry/async-http.git
 files:
 - path: getting-started.md
   title: Getting Started
-  description: This guide explains how to get started with `Async::HTTP`.
+  description: This guide explains how to make HTTP requests and serve HTTP responses
+    with `Async::HTTP`.
+- path: choosing-a-client.md
+  title: Choosing a Client
+  description: This guide explains how to choose between ruby:`Async::HTTP::Internet`,
+    ruby:`Async::HTTP::Client`, and higher-level interfaces for libraries.
+- path: concurrent-requests.md
+  title: Concurrent Requests and Connection Pooling
+  description: This guide explains how to run HTTP requests concurrently while keeping
+    request fan-out, connection usage, and resource life cycles bounded.
 - path: testing.md
   title: Testing
-  description: This guide explains how to use `Async::HTTP` clients and servers in
-    your tests.
+  description: This guide explains how to test `Async::HTTP` clients and servers without
+    depending on external HTTP services.