async-http 0.91.0 → 0.92.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae6c0e0cd15050304be680a8c0b5e49447fb83c6533b7aefebec427a83ae3aac
-  data.tar.gz: 614910bd99032d2f19672876eada276fba03a887feafec21f3a50263410f272e
+  metadata.gz: d2eec64b9787b5fbad7b8d4b7d45566efcb701b1dcfb9aa7774bf3e2bc3f79f1
+  data.tar.gz: 2105c3c5bb32cb5d69359bb077e4bba77bdcad644cc8186149b34c425749ccc3
 SHA512:
-  metadata.gz: 301c38b5c92a927d11d73420e88a47442e3dbcc7445850bb269412dc1c2c4edf3dd97456e8bbbed13de1fa013dec139652b274248ae882e294ce48912d3935e9
-  data.tar.gz: 6e2dc40b2761b4484191368b2ebadea5045d1d35c28306bbd09b97d5433badeb1c5e31a1c9af54222e7583377488bdcf4f300b545882d7ed1d303c2470c13716
+  metadata.gz: b797e853dec72a6f115c73aa3199ae135d28f5dbaf6f2eb21ceb19bb5a747c4b3c6aadc2212a9352c86f2ea64c17a4864a829a9aea0de80fabfdef0205782df9
+  data.tar.gz: a39431a5f5ddeedaf208121a64b232b318b73716c018de26dad6bcb1ff98cb12a3ad68e4ba11ea8b27291ee25eae1604af3f9c53152fda81cbcdab6132c709f7

checksums.yaml.gz.sig

@@ -1 +1,3 @@
-='#S�|�<�[kG�ee�CDJ�yy4� =V'C������,�d���	�1{(}�+|��4q��`�_Xߑf��%G�N�$��W.��j7��܇�����e�����fo=�瀎��������
�+8w�k
�uNĆ\����/b�,�|�Y�pjb�D���A��d$C��Ͱu��_Åw	zg(�;E*�'�	���D?6�̾ݰi������0,U�����ۖ�Q���LZ:��͠L��Mz_i�|�4�Ş�ԋA��BlX�,�c
+����+.�<�@�9ԭ�3Z���ƹ!9r*��=��,�<�No��;�1�G�C�
+W(T��j)5�+�ă�B�T��������*?>!�=u`��#�ƍ���7e���$%J���@�R6� Jfz��mi=�A��`�%��Y]T�my����L�P䶍�W7&�Bt����
+|�(��#C}���|?�ڜj 3?b��������ʃ�2q�Eo�7����Y(������h����T������,/���%��.�V&9�z�&�z�6v�B�3h�-.HT����h�'FdC��vZ�w;(���-�ٔ'�V�	O.�m��07]D�?C��Za��w�V�jI

data/context/getting-started.md

@@ -0,0 +1,148 @@
+# Getting Started
+
+This guide explains how to get started with `Async::HTTP`.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ 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.
+
+## Usage
+
+### Making a Request
+
+To make a request, use {ruby Async::HTTP::Internet} and call the appropriate method:
+
+~~~ ruby
+require 'async/http/internet/instance'
+
+Sync do
+	Async::HTTP::Internet.get("https://httpbin.org/get") do |response|
+		puts response.read
+	end
+end
+~~~
+
+The following methods are supported:
+
+~~~ ruby
+Async::HTTP::Internet.methods(false)
+# => [:patch, :options, :connect, :post, :get, :delete, :head, :trace, :put]
+~~~
+
+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:
+
+~~~ ruby
+require 'async/http/internet/instance'
+
+Sync do
+	response = Async::HTTP::Internet.get("https://httpbin.org/get")
+	puts response.read
+ensure
+	response&.close
+end
+~~~
+
+As responses are streamed, you must ensure it is closed when you are finished with it.
+
+#### Persistence
+
+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.
+
+### Downloading a File
+
+~~~ ruby
+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
+end
+~~~
+
+### Posting Data
+
+To post data, use the `post` method:
+
+~~~ ruby
+require 'async/http/internet/instance'
+
+data = {'life' => 42}
+
+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
+end
+~~~
+
+For more complex scenarios, including HTTP APIs, consider using [async-rest](https://github.com/socketry/async-rest) instead.
+
+### Timeouts
+
+To set a timeout for a request, use the `Task#with_timeout` method:
+
+~~~ ruby
+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
+	end
+rescue Async::TimeoutError
+	puts "The request timed out"
+end
+~~~
+
+### Making a Server
+
+To create a server, use an instance of {ruby Async::HTTP::Server}:
+
+~~~ ruby
+require 'async/http'
+
+endpoint = Async::HTTP::Endpoint.parse('http://localhost:9292')
+
+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
+	
+	client = Async::HTTP::Client.new(endpoint)
+	response = client.get("/")
+	puts response.read
+ensure
+	response&.close
+end
+~~~

data/context/index.yaml

@@ -0,0 +1,15 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: A HTTP client and server library.
+metadata:
+  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`.
+- path: testing.md
+  title: Testing
+  description: This guide explains how to use `Async::HTTP` clients and servers in
+    your tests.

data/context/testing.md

@@ -0,0 +1,77 @@
+# Testing
+
+This guide explains how to use `Async::HTTP` clients and servers in your tests.
+
+In general, you should avoid making real HTTP requests in your tests. Instead, you should use a mock server or a fake client.
+
+## Mocking HTTP Responses
+
+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.
+
+In order to enable this feature, you must create an instance of {ruby Async::HTTP::Mock::Endpoint} which will handle the requests.
+
+~~~ ruby
+require 'async/http'
+require 'async/http/mock'
+
+mock_endpoint = Async::HTTP::Mock::Endpoint.new
+
+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"]]
+		end
+	end
+	
+	endpoint = Async::HTTP::Endpoint.parse("https://www.google.com")
+	mocked_endpoint = mock_endpoint.wrap(endpoint)
+	client = Async::HTTP::Client.new(mocked_endpoint)
+	
+	response = client.get("/")
+	puts response.read
+	# => "Hello, World"
+end
+~~~
+
+## Transparent Mocking
+
+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.
+
+### Sus Integration
+
+~~~ ruby
+require 'async/http'
+require 'async/http/mock'
+require 'sus/fixtures/async/reactor_context'
+
+include Sus::Fixtures::Async::ReactorContext
+
+let(:mock_endpoint) {Async::HTTP::Mock::Endpoint.new}
+
+def before
+	super
+	
+	# Mock the HTTP client:
+	mock(Async::HTTP::Client) do |mock|
+		mock.wrap(:new) do |original, endpoint|
+			original.call(mock_endpoint.wrap(endpoint))
+		end
+	end
+	
+	# Run the mock server:
+	Async(transient: true) do
+		mock_endpoint.run do |request|
+			::Protocol::HTTP::Response[200, {}, ["Hello, World"]]
+		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"
+end
+~~~

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 # Copyright, 2020, by Bruno Sutic.
 
 require_relative "writable"

data/lib/async/http/endpoint.rb

@@ -6,6 +6,7 @@
 # Copyright, 2024, by Thomas Morgan.
 # Copyright, 2024, by Igor Sidorov.
 # Copyright, 2024, by Hal Brodigan.
+# Copyright, 2025, by William T. Nelson.
 
 require "io/endpoint"
 require "io/endpoint/host_endpoint"
@@ -16,9 +17,6 @@ require_relative "protocol/https"
 
 require "uri"
 
-# Compatibility with Ruby 3.1.2
-require "uri/wss"
-
 module Async
 	module HTTP
 		# Represents a way to connect to a remote HTTP server.

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

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
-
-require_relative "../reference"
+# Copyright, 2024-2025, by Samuel Williams.
 
 require "protocol/http/middleware"
 require "protocol/http/body/rewindable"
+require "protocol/url/reference"
 
 module Async
 	module HTTP
@@ -71,7 +70,7 @@ module Async
 					end
 					
 					# Update the path of the request:
-					request.path = Reference[request.path] + location
+					request.path = ::Protocol::URL::Reference[request.path] + location
 					
 					# Follow the redirect:
 					return true

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

@@ -152,6 +152,7 @@ module Async
 									task.yield
 								end
 							rescue => error
+								# We store error (as a local variable) for later use in the ensure block.
 								raise
 							ensure
 								body&.close(error)

data/lib/async/http/version.rb

@@ -5,6 +5,6 @@
 
 module Async
 	module HTTP
-		VERSION = "0.91.0"
+		VERSION = "0.92.1"
 	end
 end

data/lib/metrics/provider/async/http/client.rb

@@ -9,7 +9,7 @@ require "metrics/provider"
 Metrics::Provider(Async::HTTP::Client) do
 	ASYNC_HTTP_CLIENT_REQUEST_INITIATED = Metrics.metric("async.http.client.request.initiated", :counter, description: "The number of HTTP client requests initiated.")
 	ASYNC_HTTP_CLIENT_REQUEST_FINISHED = Metrics.metric("async.http.client.request.finished", :counter, description: "The number of HTTP client requests finished.")
-
+	
 	def make_response(request, connection, attempt)
 		ASYNC_HTTP_CLIENT_REQUEST_INITIATED.emit(1, tags: ["method:#{request.method}"])
 		

data/lib/metrics/provider/async/http/server.rb

@@ -9,7 +9,7 @@ require "metrics/provider"
 Metrics::Provider(Async::HTTP::Server) do
 	ASYNC_HTTP_SERVER_REQUEST_INITIATED = Metrics.metric("async.http.server.request.initiated", :counter, description: "The number of HTTP server requests initiated.")
 	ASYNC_HTTP_SERVER_REQUEST_FINISHED = Metrics.metric("async.http.server.request.finished", :counter, description: "The number of HTTP server requests finished.")
-
+	
 	def call(request)
 		ASYNC_HTTP_SERVER_REQUEST_INITIATED.emit(1, tags: ["method:#{request.method}"])
 		

data/lib/metrics/provider/async/http.rb

@@ -1,4 +1,7 @@
 # frozen_string_literal: true
 
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
 require_relative "http/client"
 require_relative "http/server"

data/lib/traces/provider/async/http/client.rb

@@ -1,3 +1,8 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
 require_relative "../../../../async/http/client"
 
 Traces::Provider(Async::HTTP::Client) do

data/lib/traces/provider/async/http/protocol/http1/client.rb

@@ -1,3 +1,8 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
 require_relative "../../../../../../async/http/protocol/http1/client"
 
 Traces::Provider(Async::HTTP::Protocol::HTTP1::Client) do

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

@@ -1,3 +1,8 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
 require_relative "../../../../../../async/http/protocol/http2/client"
 
 Traces::Provider(Async::HTTP::Protocol::HTTP2::Client) do

data/lib/traces/provider/async/http/server.rb

@@ -1,3 +1,8 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
 require_relative "../../../../async/http/server"
 
 Traces::Provider(Async::HTTP::Server) do
@@ -35,4 +40,4 @@ Traces::Provider(Async::HTTP::Server) do
 			end
 		end
 	end
-end
+end

data/lib/traces/provider/async/http.rb

@@ -1,2 +1,7 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
 require_relative "http/client"
-require_relative "http/server"
+require_relative "http/server"

data/license.md

@@ -23,6 +23,8 @@ Copyright, 2023, by Josh Huber.
 Copyright, 2024, by Anton Zhuravsky.  
 Copyright, 2024, by Hal Brodigan.  
 Copyright, 2025, by Jean Boussier.  
+Copyright, 2025, by Yuuji Yaginuma.  
+Copyright, 2025, by William T. Nelson.  
 
 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

@@ -16,6 +16,10 @@ Please see the [project documentation](https://socketry.github.io/async-http/) f
 
 Please see the [project releases](https://socketry.github.io/async-http/releases/index) for all releases.
 
+### v0.92.0
+
+  - **Breaking**: Remove `Async::HTTP::Reference`. Use `Protocol::URL::Reference` directly instead.
+
 ### v0.91.0
 
   - Move all default trace providers into `traces/provider/async/http`.
@@ -53,12 +57,6 @@ Please see the [project releases](https://socketry.github.io/async-http/releases
   - Improved HTTP/1 connection handling.
   - The input stream is no longer closed when the output stream is closed.
 
-### v0.76.0
-
-  - `Async::HTTP::Body::Writable` is moved to `Protocol::HTTP::Body::Writable`.
-  - Remove `Async::HTTP::Body::Delayed` with no replacement.
-  - Remove `Async::HTTP::Body::Slowloris` with no replacement.
-
 ## See Also
 
   - [benchmark-http](https://github.com/socketry/benchmark-http) — A benchmarking tool to report on web server concurrency.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.92.0
+
+  - **Breaking**: Remove `Async::HTTP::Reference`. Use `Protocol::URL::Reference` directly instead.
+
 ## v0.91.0
 
   - Move all default trace providers into `traces/provider/async/http`.
@@ -145,7 +149,7 @@ internet.get("https://example.com", scheme: "http")
 ``` ruby
 # Server side:
 def call(request)
-	if request.headers['expect'].include?('100-continue')
+	if request.headers["expect"].include?("100-continue")
 		request.send_interim_response(100)
 	end
 	

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-http
 version: !ruby/object:Gem::Version
-  version: 0.91.0
+  version: 0.92.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -11,6 +11,7 @@ authors:
 - Thomas Morgan
 - Adam Daniels
 - Igor Sidorov
+- William T. Nelson
 - Anton Zhuravsky
 - Cyril Roelandt
 - Denis Talakevich
@@ -26,6 +27,7 @@ authors:
 - Tim Meusel
 - Trevor Turk
 - Viacheslav Koval
+- Yuuji Yaginuma
 - dependabot[bot]
 bindir: bin
 cert_chain:
@@ -172,6 +174,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: protocol-url
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: traces
   requirement: !ruby/object:Gem::Requirement
@@ -192,6 +208,9 @@ extra_rdoc_files: []
 files:
 - bake/async/http.rb
 - bake/async/http/h2spec.rb
+- context/getting-started.md
+- context/index.yaml
+- context/testing.md
 - lib/async/http.rb
 - lib/async/http/body.rb
 - lib/async/http/body/hijack.rb
@@ -230,7 +249,6 @@ files:
 - lib/async/http/protocol/request.rb
 - lib/async/http/protocol/response.rb
 - lib/async/http/proxy.rb
-- lib/async/http/reference.rb
 - lib/async/http/relative_location.rb
 - lib/async/http/server.rb
 - lib/async/http/statistics.rb
@@ -266,7 +284,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.2
 specification_version: 4
 summary: A HTTP client and server library.
 test_files: []

data/lib/async/http/reference.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
-
-require "protocol/http/reference"
-
-module Async
-	module HTTP
-		Reference = ::Protocol::HTTP::Reference
-	end
-end