sus-fixtures-async-http 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ca53e2286a46691cf27d9c9255bd10dabce31145376b7b9b0e64fda362b810a
-  data.tar.gz: 432d75147545cd62dd857f03b3ec0c5b6eca775595571c01b3ceb83ddbaeeced
+  metadata.gz: a02a80acae8f8b6c8502986b21ca39d7e950dabfde21839d3632735213f11cc0
+  data.tar.gz: 1ae85d08937d7340805503b06f3559baaa3ebe7d70aca052bdb6216a508dab13
 SHA512:
-  metadata.gz: 80b91bb25f1f2ec269fe0c382a308e2ca015c23c5aad40fa6a48f86d934dcea55595b368b3089790f476510128ba31f901d4efe3ad4155fb23889c72124f3a1a
-  data.tar.gz: e40898d89d6c4125b914e47bcb46b4e4f315791e8b168db87fab9fc880cb66575295b3ec2b65b3c265cb873a1f5a5330b4a3ffcd8e38e107048f10a18e738521
+  metadata.gz: 9144f6a3c90fb80a07d1e5717591a47a6c73f001105241b3b4912d54a0a96f04383e9cc657190671ad8477295ac3f0672c48ed14bf285e6fef27d81793db62b8
+  data.tar.gz: 748af62b604a42f8b342e813502f2a372de16d0135e4c260b96141b95aa6f8d09fc7ecc11e361dbdc69389bfaeb64fdf5cd2897c801a9e3e86ac63b1104bd90a

data/context/getting-started.md

@@ -0,0 +1,147 @@
+# Getting Started
+
+This guide explains how to use the `sus-fixtures-async-http` gem to test HTTP clients and servers.
+
+## Installation
+
+Add the gem to your project:
+
+``` bash
+$ bundle add sus-fixtures-async-http
+```
+
+## Usage
+
+Here is a simple example showing how to test the default server:
+
+``` ruby
+include Sus::Fixtures::Async::HTTP::ServerContext
+
+let(:response) {client.get("/")}
+
+it 'can perform a request' do
+	expect(response.read).to be == "Hello World!"
+end
+```
+
+### Custom Applications
+
+You can create a custom application to test your own HTTP handlers:
+
+``` ruby
+include Sus::Fixtures::Async::HTTP::ServerContext
+
+let(:app) do
+	Protocol::HTTP::Middleware.for do |request|
+		case request.path
+		when "/"
+			Protocol::HTTP::Response[200, {}, ["Home Page"]]
+		when "/api/status"
+			Protocol::HTTP::Response[200, {"content-type" => "application/json"}, ['{"status":"ok"}']]
+		else
+			Protocol::HTTP::Response[404, {}, ["Not Found"]]
+		end
+	end
+end
+
+it 'serves the home page' do
+	response = client.get("/")
+	expect(response.status).to be == 200
+	expect(response.read).to be == "Home Page"
+end
+
+it 'serves API endpoints' do
+	response = client.get("/api/status")
+	expect(response.status).to be == 200
+	expect(response.headers["content-type"]).to be == "application/json"
+	expect(response.read).to be == '{"status":"ok"}'
+end
+
+it 'returns 404 for unknown paths' do
+	response = client.get("/unknown")
+	expect(response.status).to be == 404
+end
+```
+
+### Testing Different HTTP Methods
+
+Test various HTTP methods and request bodies:
+
+``` ruby
+include Sus::Fixtures::Async::HTTP::ServerContext
+
+let(:app) do
+	Protocol::HTTP::Middleware.for do |request|
+		case [request.method, request.path]
+		when ["GET", "/users"]
+			Protocol::HTTP::Response[200, {}, ['[{"id":1,"name":"John"}]']]
+		when ["POST", "/users"]
+			body = request.body.read
+			Protocol::HTTP::Response[201, {}, ["Created: #{body}"]]
+		when ["PUT", "/users/1"]
+			body = request.body.read
+			Protocol::HTTP::Response[200, {}, ["Updated: #{body}"]]
+		when ["DELETE", "/users/1"]
+			Protocol::HTTP::Response[204, {}, [""]]
+		else
+			Protocol::HTTP::Response[404, {}, ["Not Found"]]
+		end
+	end
+end
+
+it 'handles GET requests' do
+	response = client.get("/users")
+	expect(response.status).to be == 200
+end
+
+it 'handles POST requests' do
+	response = client.post("/users", {}, ['{"name":"Alice"}'])
+	expect(response.status).to be == 201
+	expect(response.read).to be(:include?, "Alice")
+end
+
+it 'handles PUT requests' do
+	response = client.put("/users/1", {}, ['{"name":"Bob"}'])
+	expect(response.status).to be == 200
+end
+
+it 'handles DELETE requests' do
+	response = client.delete("/users/1")
+	expect(response.status).to be == 204
+end
+```
+
+## Configuration Options
+
+### Custom URLs and Ports
+
+Override the server URL and endpoint options:
+
+``` ruby
+include Sus::Fixtures::Async::HTTP::ServerContext
+
+let(:url) {"http://localhost:9999"}
+
+let(:endpoint_options) do
+	{reuse_port: true, protocol: protocol, timeout: 30}
+end
+
+it 'uses custom configuration' do
+	expect(bound_url).to be(:include?, ":9999")
+end
+```
+
+### Protocol Selection
+
+Test with different HTTP protocol versions:
+
+``` ruby
+include Sus::Fixtures::Async::HTTP::ServerContext
+
+let(:protocol) {Async::HTTP::Protocol::HTTP2}
+
+it 'uses HTTP/2 protocol' do
+	response = client.get("/")
+	expect(response).to have_attributes(version: "HTTP/2.0")
+end
+```

data/context/index.yaml

@@ -0,0 +1,13 @@
+# 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: Test fixtures for running in Async::HTTP.
+metadata:
+  documentation_uri: https://socketry.github.io/sus-fixtures-async-http/
+  funding_uri: https://github.com/sponsors/ioquatix/
+  source_code_uri: https://github.com/socketry/sus-fixtures-async-http.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use the `sus-fixtures-async-http` gem to
+    test HTTP clients and servers.

data/lib/sus/fixtures/async/http/server_context.rb

@@ -1,28 +1,44 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 
-require 'sus/fixtures/async/reactor_context'
+require "sus/fixtures/async/reactor_context"
 
-require 'async/http/server'
-require 'async/http/client'
-require 'async/http/endpoint'
+require "async/http/server"
+require "async/http/client"
+require "async/http/endpoint"
 
 module Sus::Fixtures
 	module Async
 		module HTTP
+			# ServerContext provides a test fixture for HTTP server and client testing.
+			# It sets up an HTTP server with a bound endpoint and provides a corresponding client
+			# for making requests. This context handles the lifecycle of both server and client,
+			# ensuring proper setup and teardown.
+			#
+			# The context automatically:
+			# - Binds to an available port
+			# - Starts an HTTP server with configurable middleware
+			# - Creates a client configured to connect to the server
+			# - Handles cleanup of resources after tests
 			module ServerContext
 				include ReactorContext
 				
+				# The HTTP protocol version to use for the server.
+				# @returns [Class] The protocol class (defaults to HTTP/1.1).
 				def protocol
 					::Async::HTTP::Protocol::HTTP1
 				end
 				
+				# The base URL for the HTTP server.
+				# @returns [String] The URL string with host and port (defaults to localhost:0 for auto-assigned port).
 				def url
-					'http://localhost:0'
+					"http://localhost:0"
 				end
 				
+				# Get all bound URLs for the server endpoints.
+				# @returns [Array(String)] Array of URLs the server is bound to, sorted alphabetically.
 				def bound_urls
 					urls = []
 					
@@ -44,61 +60,94 @@ module Sus::Fixtures
 					return urls
 				end
 				
+				# Get the first bound URL for the server.
+				# @returns [String] The first bound URL, typically used for single-endpoint testing.
 				def bound_url
 					bound_urls.first
 				end
 				
+				# Options for configuring the HTTP endpoint.
+				# @returns [Hash] Hash of endpoint options including port reuse and protocol settings.
 				def endpoint_options
 					{reuse_port: true, protocol: protocol}
 				end
 				
+				# The HTTP endpoint configuration.
+				# @returns [Async::HTTP::Endpoint] Parsed endpoint with configured options.
 				def endpoint
 					::Async::HTTP::Endpoint.parse(url, **endpoint_options)
 				end
 				
+				# Number of retries for client requests.
+				# @returns [Integer] Number of retry attempts (defaults to 1).
 				def retries
 					1
 				end
 				
+				# The HTTP application/middleware to serve.
+				# @returns [Object] The application object that handles HTTP requests (defaults to HelloWorld middleware).
 				def app
 					::Protocol::HTTP::Middleware::HelloWorld
 				end
 				
+				# The middleware stack for the HTTP server.
+				# @returns [Object] The middleware configuration (defaults to the app).
 				def middleware
 					app
 				end
 				
+				# Create the server endpoint from a bound endpoint.
+				# @parameter bound_endpoint [Async::HTTP::Endpoint] The bound endpoint.
+				# @returns [Async::HTTP::Endpoint] The server endpoint configuration.
 				def make_server_endpoint(bound_endpoint)
 					bound_endpoint
 				end
 				
+				# Create an HTTP server instance.
+				# @parameter endpoint [Async::HTTP::Endpoint] The endpoint to bind the server to.
+				# @returns [Async::HTTP::Server] The configured HTTP server.
 				def make_server(endpoint)
 					::Async::HTTP::Server.new(middleware, endpoint)
 				end
 				
+				# The HTTP server instance.
+				# @returns [Async::HTTP::Server] The running HTTP server.
 				def server
 					@server
 				end
 				
+				# The HTTP client instance.
+				# @returns [Async::HTTP::Client] The HTTP client configured to connect to the server.
 				def client
 					@client
 				end
 				
+				# The client endpoint configuration.
+				# @returns [Async::HTTP::Endpoint] The endpoint the client uses to connect to the server.
 				def client_endpoint
 					@client_endpoint
 				end
 				
+				# Create a client endpoint from a bound endpoint.
+				# @parameter bound_endpoint [Async::HTTP::Endpoint] The bound server endpoint.
+				# @returns [Async::HTTP::Endpoint] The client endpoint with local address and timeout.
 				def make_client_endpoint(bound_endpoint)
 					# Pass through the timeout:
 					bound_endpoint.local_address_endpoint(timeout: endpoint.timeout)
 				end
 				
+				# Create an HTTP client instance.
+				# @parameter endpoint [Async::HTTP::Endpoint] The endpoint to connect to.
+				# @parameter options [Hash] Additional client options.
+				# @returns [Async::HTTP::Client] The configured HTTP client.
 				def make_client(endpoint, **options)
 					options[:retries] = retries unless options.key?(:retries)
 					
 					::Async::HTTP::Client.new(endpoint, **options)
 				end
 				
+				# Set up the server and client before running tests.
+				# This method binds the endpoint, starts the server, and creates a client.
 				def before
 					super
 					
@@ -115,9 +164,7 @@ module Sus::Fixtures
 					
 					@server = make_server(@server_endpoint)
 					
-					@server_task = Async do
-						@server.run
-					end
+					@server_task = @server.run
 					
 					@client_endpoint = make_client_endpoint(@bound_endpoint)
 					mock(@client_endpoint) do |wrapper|
@@ -130,11 +177,15 @@ module Sus::Fixtures
 					@client = make_client(@client_endpoint)
 				end
 				
+				# Clean up resources after running tests.
+				# This method closes the client, stops the server, and closes the bound endpoint.
+				# @parameter error [Exception | Nil] Any error that occurred during the test.
 				def after(error = nil)
 					# We add a timeout here, to avoid hanging in `@client.close`:
 					::Async::Task.current.with_timeout(1) do
 						@client&.close
 						@server_task&.stop
+						@server_task&.wait
 						@bound_endpoint&.close
 					end
 					

data/lib/sus/fixtures/async/http/version.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 
 module Sus
 	module Fixtures
 		module Async
 			module HTTP
-				VERSION = "0.10.0"
+				VERSION = "0.12.0"
 			end
 		end
 	end

data/lib/sus/fixtures/async/http.rb

@@ -1,7 +1,20 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2023, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 
-require_relative 'http/server_context'
-require_relative 'http/version'
+# @namespace
+module Sus
+	# @namespace
+	module Fixtures
+		# @namespace
+		module Async
+			# @namespace
+			module HTTP
+			end
+		end
+	end
+end
+
+require_relative "http/server_context"
+require_relative "http/version"

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2022-2024, by Samuel Williams.  
+Copyright, 2022-2025, by Samuel Williams.  
 Copyright, 2023, by Felix Yan.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

data/readme.md

@@ -2,13 +2,60 @@
 
 Provides a convenient fixture for running a web server.
 
-[![Development Status](https://github.com/suspecting/sus-fixtures-async-http/workflows/Test/badge.svg)](https://github.com/suspecting/sus-fixtures-async-http/actions?workflow=Test)
+[![Development Status](https://github.com/socketry/sus-fixtures-async-http/workflows/Test/badge.svg)](https://github.com/socketry/sus-fixtures-async-http/actions?workflow=Test)
 
 ## Usage
 
-Please see the [project documentation](https://suspecting.github.io/sus-fixtures-async-http/) for more details.
+Please see the [project documentation](https://socketry.github.io/sus-fixtures-async-http/) for more details.
 
-  - [Getting Started](https://suspecting.github.io/sus-fixtures-async-http/guides/getting-started/index) - This guide explains how to use the `sus-fixtures-async-http` gem to test HTTP clients and servers.
+  - [Getting Started](https://socketry.github.io/sus-fixtures-async-http/guides/getting-started/index) - This guide explains how to use the `sus-fixtures-async-http` gem to test HTTP clients and servers.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/sus-fixtures-async-http/releases/index) for all releases.
+
+### v0.12.0
+
+  - Add agent context.
+
+### v0.11.0
+
+  - 100% documentation coverage.
+  - Remove unused outer server task.
+
+### v0.10.0
+
+  - Make it easier to override endpoint options like `timeout`.
+  - Remove default connection timeout.
+
+### v0.9.1
+
+  - Remove default connection timeout.
+
+### v0.9.0
+
+  - Add optional `after(error)` argument.
+  - Add Getting Started guide.
+
+### v0.8.1
+
+  - Add a timeout to prevent hangs during `@client.close`.
+
+### v0.8.0
+
+  - Don't depend on `async-io` directly.
+
+### v0.7.0
+
+  - Pass through the timeout.
+
+### v0.6.0
+
+  - Expose `make_client` similar to `make_server`.
+
+### v0.5.0
+
+  - Fix `make_server` to use endpoint argument.
 
 ## Contributing
 

data/releases.md

@@ -0,0 +1,87 @@
+# Releases
+
+## v0.12.0
+
+  - Add agent context.
+
+## v0.11.0
+
+  - 100% documentation coverage.
+  - Remove unused outer server task.
+
+## v0.10.0
+
+  - Make it easier to override endpoint options like `timeout`.
+  - Remove default connection timeout.
+
+## v0.9.1
+
+  - Remove default connection timeout.
+
+## v0.9.0
+
+  - Add optional `after(error)` argument.
+  - Add Getting Started guide.
+
+## v0.8.1
+
+  - Add a timeout to prevent hangs during `@client.close`.
+
+## v0.8.0
+
+  - Don't depend on `async-io` directly.
+
+## v0.7.0
+
+  - Pass through the timeout.
+
+## v0.6.0
+
+  - Expose `make_client` similar to `make_server`.
+
+## v0.5.0
+
+  - Fix `make_server` to use endpoint argument.
+
+## v0.4.0
+
+  - Add SSL support.
+  - Correct homepage in gemspec.
+
+## v0.3.0
+
+  - Sort bound URLs for more predictable tests.
+  - Add missing dependency on `async-http`.
+  - Expose url and bound\_urls.
+
+## v0.2.3
+
+  - Mock path on `client_endpoint`.
+
+## v0.2.2
+
+  - Fix timeout.
+
+## v0.2.1
+
+  - Fix `client_endpoint` and add tests.
+
+## v0.2.0
+
+  - Expose client endpoint.
+
+## v0.1.3
+
+  - Improve compatibility with simultaneous execution by using host-allocated ports.
+
+## v0.1.2
+
+  - Relax dependency.
+
+## v0.1.1
+
+  - Fix all the things.
+
+## v0.1.0
+
+  - Initial implementation.

metadata

@@ -1,12 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: sus-fixtures-async-http
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Samuel Williams
 - Felix Yan
-autorequire:
 bindir: bin
 cert_chain:
 - |
@@ -38,7 +37,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-11-20 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-http
@@ -82,25 +81,25 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.1'
-description:
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- context/getting-started.md
+- context/index.yaml
 - lib/sus/fixtures/async/http.rb
 - lib/sus/fixtures/async/http/server_context.rb
 - lib/sus/fixtures/async/http/version.rb
 - license.md
 - readme.md
-homepage: https://github.com/suspecting/sus-fixtures-async-http
+- releases.md
+homepage: https://github.com/socketry/sus-fixtures-async-http
 licenses:
 - MIT
 metadata:
-  documentation_uri: https://suspecting.github.io/sus-fixtures-async-http/
+  documentation_uri: https://socketry.github.io/sus-fixtures-async-http/
   funding_uri: https://github.com/sponsors/ioquatix/
-  source_code_uri: https://github.com/suspecting/sus-fixtures-async-http.git
-post_install_message:
+  source_code_uri: https://github.com/socketry/sus-fixtures-async-http.git
 rdoc_options: []
 require_paths:
 - lib
@@ -108,15 +107,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Test fixtures for running in Async::HTTP.
 test_files: []