async-http 0.101.0 → 0.102.0

data/context/testing.md

@@ -1,77 +1,205 @@
 # Testing
 
-This guide explains how to use `Async::HTTP` clients and servers in your tests.
+This guide explains how to test `Async::HTTP` clients and servers without depending on external HTTP services.
 
-In general, you should avoid making real HTTP requests in your tests. Instead, you should use a mock server or a fake client.
+Real network services make tests slower and less deterministic. Prefer one of these approaches:
 
-## Mocking HTTP Responses
+- Use [`sus-fixtures-protocol-http`](https://socketry.github.io/sus-fixtures-protocol-http/guides/getting-started/) to exercise HTTP middleware directly without a client or server.
+- Use `sus-fixtures-async-http` to run an application with a managed local server and client.
+- Use ruby:`Async::HTTP::Mock::Endpoint` when testing a client that expects to connect to a particular remote endpoint.
 
-The mocking feature of `Async::HTTP` uses a real server running in a separate task, and routes all requests to it. This allows you to intercept requests and return custom responses, but still use the real HTTP client.
+## Testing Middleware Directly
 
-In order to enable this feature, you must create an instance of {ruby Async::HTTP::Mock::Endpoint} which will handle the requests.
+When a test only needs to construct requests and inspect responses, `sus-fixtures-protocol-http` can call `Protocol::HTTP` middleware in-process without starting a client or server. Add the fixture to your test dependencies:
+
+~~~ bash
+$ bundle add sus --group test
+$ bundle add sus-fixtures-protocol-http --group test
+~~~
+
+Include `MiddlewareContext` and provide the middleware under test:
 
 ~~~ ruby
-require 'async/http'
-require 'async/http/mock'
+require "sus/fixtures/protocol/http/middleware_context"
+
+describe "My HTTP application" do
+	include Sus::Fixtures::Protocol::HTTP::MiddlewareContext
+	
+	let(:middleware) do
+		Protocol::HTTP::Middleware.for do |request|
+			Protocol::HTTP::Response[200, {}, ["Hello #{request.path}"]]
+		end
+	end
+	
+	it "handles a request directly" do
+		response = client.get("/world")
+		
+		expect(response.status).to be == 200
+		expect(response.read).to be == "Hello /world"
+	end
+end
+~~~
+
+The fixture closes the final request, response, and middleware after each test. Use `sus-fixtures-async-http` when the test needs a real client/server exchange.
 
-mock_endpoint = Async::HTTP::Mock::Endpoint.new
+## Testing with a Client and Server
 
-Sync do
-	# Start a background server:
-	server_task = Async(transient: true) do
-		mock_endpoint.run do |request|
-			# Respond to the request:
-			::Protocol::HTTP::Response[200, {}, ["Hello, World"]]
+The `ServerContext` fixture manages an ephemeral listening endpoint, server task, and connected client. Add the fixture to your test dependencies:
+
+~~~ bash
+$ bundle add sus --group test
+$ bundle add sus-fixtures-async-http --group test
+~~~
+
+Define the application under test and make requests through the provided `client`:
+
+~~~ ruby
+require "sus/fixtures/async/http"
+
+describe "My HTTP application" do
+	include Sus::Fixtures::Async::HTTP::ServerContext
+	
+	let(:app) do
+		Protocol::HTTP::Middleware.for do |request|
+			case request.path
+			when "/health"
+				Protocol::HTTP::Response[
+					200,
+					{"content-type" => "application/json"},
+					['{"status":"ok"}'],
+				]
+			else
+				Protocol::HTTP::Response[404, {}, ["Not Found"]]
+			end
 		end
 	end
 	
-	endpoint = Async::HTTP::Endpoint.parse("https://www.google.com")
-	mocked_endpoint = mock_endpoint.wrap(endpoint)
-	client = Async::HTTP::Client.new(mocked_endpoint)
+	it "serves the health endpoint" do
+		response = client.get("/health")
+		
+		expect(response).to be(:success?)
+		expect(response.headers["content-type"]).to be == "application/json"
+		expect(response.read).to be == '{"status":"ok"}'
+	ensure
+		response&.close
+	end
 	
-	response = client.get("/")
-	puts response.read
-	# => "Hello, World"
+	it "returns not found for unknown paths" do
+		response = client.get("/missing")
+		expect(response.status).to be == 404
+	ensure
+		response&.close
+	end
 end
 ~~~
 
-## Transparent Mocking
+The fixture closes the client, stops the server, and releases the bound endpoint after each test. Override `app`, `url`, `protocol`, `endpoint_options`, or `retries` to configure a scenario.
 
-Using your test framework's mocking capabilities, you can easily replace the `Async::HTTP::Client#new` with a method that returns a client with a mocked endpoint.
+### Testing HTTP/2
 
-### Sus Integration
+Override `protocol` when behavior must be verified with a specific HTTP version:
 
 ~~~ ruby
-require 'async/http'
-require 'async/http/mock'
-require 'sus/fixtures/async/reactor_context'
+describe "My HTTP/2 application" do
+	include Sus::Fixtures::Async::HTTP::ServerContext
+	
+	let(:protocol) {Async::HTTP::Protocol::HTTP2}
+	
+	it "responds using HTTP/2" do
+		response = client.get("/")
+		expect(response.version).to be == "HTTP/2"
+	ensure
+		response&.close
+	end
+end
+~~~
+
+Test normal behavior without forcing a protocol unless the distinction is relevant to the feature under test.
 
-include Sus::Fixtures::Async::ReactorContext
+## Testing a Client with a Mock Endpoint
 
-let(:mock_endpoint) {Async::HTTP::Mock::Endpoint.new}
+ruby:`Async::HTTP::Mock::Endpoint` connects the real client and server protocol implementations through a local socket pair. It does not open a network port, but requests still exercise serialization, connection handling, and response bodies.
+
+Use ruby:`Async::HTTP::Mock::Endpoint#wrap` to preserve the scheme and authority expected by the client:
+
+~~~ ruby
+require "async/http"
+require "async/http/mock"
+require "sus/fixtures/async/reactor_context"
 
-def before
-	super
+describe "A remote service client" do
+	include Sus::Fixtures::Async::ReactorContext
 	
-	# Mock the HTTP client:
-	mock(Async::HTTP::Client) do |mock|
-		mock.wrap(:new) do |original, endpoint|
-			original.call(mock_endpoint.wrap(endpoint))
+	it "handles a successful response" do
+		mock_endpoint = Async::HTTP::Mock::Endpoint.new
+		server_task = Async do
+			mock_endpoint.run do |request|
+				Protocol::HTTP::Response[200, {}, ["Authority: #{request.authority}"]]
+			end
 		end
+		
+		remote_endpoint = Async::HTTP::Endpoint.parse("https://api.example.com")
+		client = Async::HTTP::Client.new(mock_endpoint.wrap(remote_endpoint))
+		response = client.get("/status")
+		
+		expect(response.read).to be == "Authority: api.example.com"
+	ensure
+		response&.close
+		client&.close
+		server_task&.stop
 	end
+end
+~~~
+
+Return different statuses, headers, bodies, delays, or malformed behavior from the mock server to exercise client error handling.
+
+## Transparently Replacing Client Endpoints
+
+Some applications construct ruby:`Async::HTTP::Client` internally. A test can wrap the constructor so those clients connect to a mock endpoint while retaining the original endpoint metadata and client options:
+
+~~~ ruby
+require "async/http"
+require "async/http/mock"
+require "sus/fixtures/async/reactor_context"
+
+describe "A client created by application code" do
+	include Sus::Fixtures::Async::ReactorContext
+	
+	let(:mock_endpoint) {Async::HTTP::Mock::Endpoint.new}
 	
-	# Run the mock server:
-	Async(transient: true) do
-		mock_endpoint.run do |request|
-			::Protocol::HTTP::Response[200, {}, ["Hello, World"]]
+	def before
+		super
+		
+		replacement_endpoint = mock_endpoint
+		mock(Async::HTTP::Client) do |wrapper|
+			wrapper.wrap(:new) do |original, endpoint, **options|
+				original.call(replacement_endpoint.wrap(endpoint), **options)
+			end
+		end
+		
+		@server_task = Async do
+			mock_endpoint.run do |request|
+				Protocol::HTTP::Response[200, {}, ["Hello, World"]]
+			end
 		end
 	end
-end
-
-it "should perform a web request" do
-	client = Async::HTTP::Client.new(Async::HTTP::Endpoint.parse("https://www.google.com"))
-	response = client.get("/")
-	# The response is mocked:
-	expect(response.read).to be == "Hello, World"
+	
+	def after(error = nil)
+		@server_task&.stop
+		super
+	end
+	
+	it "routes the request through the mock endpoint" do
+		endpoint = Async::HTTP::Endpoint.parse("https://api.example.com")
+		client = Async::HTTP::Client.new(endpoint, retries: 1)
+		response = client.get("/")
+		
+		expect(response.read).to be == "Hello, World"
+	ensure
+		response&.close
+		client&.close
+	end
 end
 ~~~
+
+Always accept and forward `**options` when wrapping the constructor so the test does not silently change client configuration.

data/lib/async/http/body/hijack.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 
 require "protocol/http/body/readable"
 require "protocol/http/body/stream"

data/lib/async/http/body/pipe.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2025, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 # Copyright, 2020, by Bruno Sutic.
 
 require_relative "writable"
@@ -63,7 +63,7 @@ module Async
 				end
 				
 				# Read from the head of the pipe and write to the @output stream.
-				# If the @tail is closed, this will cause chunk to be nil, which in turn will call `@output.close` and `@head.close`
+				# A write-side close on @tail produces EOF and closes @output independently of the input direction.
 				def writer(task)
 					@writer = task
 					

data/lib/async/http/body.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2026, by Samuel Williams.
 
 require "protocol/http/body/buffered"
 require_relative "body/writable"

data/lib/async/http/internet.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2026, by Samuel Williams.
 # Copyright, 2024, by Igor Sidorov.
 
 require_relative "client"

data/lib/async/http/middleware/location_redirector.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024-2025, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 require "protocol/http/middleware"
 require "protocol/http/body/rewindable"

data/lib/async/http/mock/endpoint.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 require_relative "../protocol"
 

data/lib/async/http/protocol/configurable.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 module Async
 	module HTTP

data/lib/async/http/protocol/http.rb

@@ -2,7 +2,7 @@
 
 # Released under the MIT License.
 # Copyright, 2024, by Thomas Morgan.
-# Copyright, 2024-2025, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 require_relative "defaulton"
 

data/lib/async/http/protocol/http1/finishable.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
+# Copyright, 2026, by Jun Jiang.
 
 require "protocol/http/body/wrapper"
 require "async/promise"

data/lib/async/http/protocol/http1/request.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2025, by Samuel Williams.
+# Copyright, 2018-2026, by Samuel Williams.
 
 require_relative "../request"
 

data/lib/async/http/protocol/http1/response.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2026, by Samuel Williams.
 # Copyright, 2023, by Josh Huber.
 
 require_relative "../response"

data/lib/async/http/protocol/http1.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2025, by Samuel Williams.
+# Copyright, 2017-2026, by Samuel Williams.
 # Copyright, 2024, by Thomas Morgan.
 
 require_relative "configurable"

data/lib/async/http/protocol/http10.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2025, by Samuel Williams.
+# Copyright, 2017-2026, by Samuel Williams.
 # Copyright, 2024, by Thomas Morgan.
 
 require_relative "http1"

data/lib/async/http/protocol/http11.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2025, by Samuel Williams.
+# Copyright, 2017-2026, by Samuel Williams.
 # Copyright, 2018, by Janko Marohnić.
 # Copyright, 2024, by Thomas Morgan.
 

data/lib/async/http/protocol/http2/client.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2025, by Samuel Williams.
+# Copyright, 2018-2026, by Samuel Williams.
+# Copyright, 2026, by Denis Talakevich.
 
 require_relative "connection"
 require_relative "response"
@@ -34,7 +35,11 @@ module Async
 					
 					# Used by the client to send requests to the remote server.
 					def call(request)
-						raise ::Protocol::HTTP2::Error, "Connection closed!" if self.closed?
+						# The remote peer has sent a GOAWAY frame, so it will not process any new streams on this connection. The request has not been sent yet, so it is safe to retry it on a new connection, even if it is not idempotent. This is checked first, because a connection with no streams left to drain is closed by the GOAWAY itself.
+						raise ::Protocol::HTTP::RefusedError, "Connection is going away!" if self.goaway_received?
+						
+						# The connection can close after being acquired from the pool. No stream has been created yet, so the request has not been written and is safe to retry.
+						raise ::Protocol::HTTP::RefusedError, "Connection closed!" if self.closed?
 						
 						response = create_response
 						write_request(response, request)

data/lib/async/http/protocol/http2/connection.rb

@@ -4,6 +4,7 @@
 # Copyright, 2018-2026, by Samuel Williams.
 # Copyright, 2020, by Bruno Sutic.
 # Copyright, 2025, by Jean Boussier.
+# Copyright, 2026, by Denis Talakevich.
 
 require_relative "stream"
 
@@ -88,16 +89,27 @@ module Async
 					
 					# Close the connection and stop the background reader.
 					def close(error = nil)
-						# Ensure the reader task is stopped.
-						if @reader
-							reader = @reader
+						if reader = @reader
 							@reader = nil
-							reader.stop
+							
+							# The reader task can close the connection itself, e.g. when the last stream completes and the connection is released back to the pool. Stopping it here would cancel the current task in the middle of this method, leaving the underlying stream open, so we let it unwind by itself: `closed?` is now true, so the read loop exits.
+							reader.stop unless reader.current?
 						end
 						
 						super
 					end
 					
+					# The connection has finished draining the streams which the remote peer accepted before its graceful GOAWAY.
+					#
+					# The last of those streams can complete on the sending side, in a task other than the background reader - the response arrived first and the request body was still being written. The reader is then parked in a blocking read and will never notice that the connection is closed, so we stop it and let its `ensure` close the connection.
+					def close_if_drained!
+						super
+						
+						if self.closed? and (reader = @reader) and !reader.current?
+							reader.stop
+						end
+					end
+					
 					# Start a transient background task that reads frames from the connection.
 					def read_in_background(parent: Task.current)
 						raise RuntimeError, "Connection is closed!" if closed?
@@ -142,12 +154,14 @@ module Async
 					
 					# Can we use this connection to make requests?
 					def viable?
-						@stream&.readable?
+						!self.goaway_received? && @stream&.readable?
 					end
 					
 					# @returns [Boolean] Whether the connection can be reused.
+					#
+					# Once the remote peer has sent a GOAWAY frame, it will not process any new streams on this connection, so it must not be handed out for another request, even while the streams it accepted are still being drained.
 					def reusable?
-						!self.closed?
+						!self.closed? && !self.goaway_received?
 					end
 					
 					# @returns [String] The HTTP version string.

data/lib/async/http/protocol/http2/input.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require "protocol/http/body/writable"
 
@@ -25,8 +25,8 @@ module Async
 					# @returns [String | Nil] The next chunk, or `nil` if the body is complete.
 					def read
 						if chunk = super
-							# If we read a chunk fron the stream, we want to extend the window if required so more data will be provided.
-							@stream.request_window_update
+							# If we read a chunk from the stream, we want to extend the window if required so more data will be provided.
+							@stream&.request_window_update
 						end
 						
 						# We track the expected length and check we got what we were expecting.
@@ -42,6 +42,17 @@ module Async
 						
 						return chunk
 					end
+					
+					# Close the application-facing input body and notify the stream that incoming data is no longer being consumed. While local output is active, the HTTP/2 stream remains open. Once output also closes, the remaining wire stream is terminated without an error.
+					# @parameter error [Exception | Nil] The error that caused the input to be closed, if any.
+					def close(error = nil)
+						super
+						
+						if stream = @stream
+							@stream = nil
+							stream.finish_input(self, error)
+						end
+					end
 				end
 			end
 		end

data/lib/async/http/protocol/http2/output.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require "protocol/http/body/stream"
 
@@ -54,22 +54,24 @@ module Async
 					# @parameter chunk [String] The data to write.
 					def write(chunk)
 						until chunk.empty?
-							maximum_size = @stream.available_frame_size
+							stream = @stream or raise IOError, "HTTP/2 stream is closed!"
+							maximum_size = stream.available_frame_size
 							
 							# We try to avoid synchronization if possible:
 							if maximum_size <= 0
 								@guard.synchronize do
-									maximum_size = @stream.available_frame_size
+									maximum_size = stream.available_frame_size
 									
 									while maximum_size <= 0
 										@window_updated.wait(@guard)
 										
-										maximum_size = @stream.available_frame_size
+										stream = @stream or raise IOError, "HTTP/2 stream is closed!"
+										maximum_size = stream.available_frame_size
 									end
 								end
 							end
 							
-							break unless chunk = send_data(chunk, maximum_size)
+							break unless chunk = send_data(stream, chunk, maximum_size)
 						end
 					end
 					
@@ -96,6 +98,19 @@ module Async
 						end
 					end
 					
+					# Close the wire output without cancelling a streamable body. This allows bidirectional bodies to observe an orderly input closure and finish normally. A non-streaming producer has no input side through which closure can propagate, so it is stopped directly.
+					def close_stream
+						if @body.stream?
+							@stream = nil
+							
+							@guard.synchronize do
+								@window_updated.broadcast
+							end
+						else
+							stop(nil)
+						end
+					end
+					
 					private
 					
 					def stream(task)
@@ -137,11 +152,11 @@ module Async
 					# @param maximum_size [Integer] send up to this many bytes of data.
 					# @param stream [Stream] the stream to use for sending data frames.
 					# @return [String, nil] any data that could not be written.
-					def send_data(chunk, maximum_size)
+					def send_data(stream, chunk, maximum_size)
 						if chunk.bytesize <= maximum_size
-							@stream.send_data(chunk, maximum_size: maximum_size)
+							stream.send_data(chunk, maximum_size: maximum_size)
 						else
-							@stream.send_data(chunk.byteslice(0, maximum_size), maximum_size: maximum_size)
+							stream.send_data(chunk.byteslice(0, maximum_size), maximum_size: maximum_size)
 							
 							# The window was not big enough to send all the data, so we save it for next time:
 							return chunk.byteslice(maximum_size, chunk.bytesize - maximum_size)

data/lib/async/http/protocol/http2/response.rb

@@ -30,11 +30,13 @@ module Async
 						# Wait for the response headers and return the response body.
 						# @returns [Protocol::HTTP::Body::Readable | Nil] The response body.
 						def wait_for_input
+							response = @response
+							
 							# The input isn't ready until the response headers have been received:
-							@response.wait
+							response.wait
 							
 							# There is a possible race condition if you try to access @input - it might already be closed and nil.
-							return @response.body
+							return response.body
 						end
 						
 						# Handle a push promise stream from the server.
@@ -169,6 +171,17 @@ module Async
 						@stream.wait
 					end
 					
+					# Close this response as quickly as possible. If the response body is still active, cancel the HTTP/2 exchange rather than draining it.
+					# @parameter error [Exception | Nil] The error which closed the response.
+					def close(error = nil)
+						if @body && !@stream.closed?
+							code = error ? ::Protocol::HTTP2::Error::INTERNAL_ERROR : ::Protocol::HTTP2::Error::CANCEL
+							@stream.send_reset_stream(code)
+						end
+						
+						super
+					end
+					
 					# @returns [Boolean] Whether the original request was a HEAD request.
 					def head?
 						@request&.head?

data/lib/async/http/protocol/http2/server.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2025, by Samuel Williams.
+# Copyright, 2018-2026, by Samuel Williams.
 
 require_relative "connection"
 require_relative "request"