Rename Recorder -> Capture.

Author: samuel-williams-shopify

async-http-recorder.gemspec renamed to async-http-capture.gemspec

@@ -1,20 +1,20 @@
 # frozen_string_literal: true
 
-require_relative "lib/async/http/recorder/version"
+require_relative "lib/async/http/capture/version"
 
 Gem::Specification.new do |spec|
 	spec.name = "async-http"
-	spec.version = Async::HTTP::Recorder::VERSION
+	spec.version = Async::HTTP::Capture::VERSION
 
-	spec.summary = "A HTTP request and response recorder."
+	spec.summary = "A HTTP request and response capture."
 	spec.authors = ["Samuel Williams"]
 	spec.license = "MIT"
 
 	spec.homepage = "https://github.com/socketry/async-http"
 
 	spec.metadata = {
-		"documentation_uri" => "https://socketry.github.io/async-http-recorder/",
-		"source_code_uri" => "https://github.com/socketry/async-http-recorder.git",
+		"documentation_uri" => "https://socketry.github.io/async-http-capture/",
+		"source_code_uri" => "https://github.com/socketry/async-http-capture.git",
 	}
 
 	spec.files = Dir.glob(["{lib}/**/*", "*.md"], File::FNM_DOTMATCH, base: __dir__)

lib/async/http/capture.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "capture/version"
+require_relative "capture/interaction"
+require_relative "capture/cassette"
+require_relative "capture/cassette_store"
+require_relative "capture/console_store"
+require_relative "capture/interaction_tracker"
+require_relative "capture/middleware"
+
+module Async
+	module HTTP
+		# @namespace
+		module Capture
+		end
+	end
+end

lib/async/http/recorder/cassette.rb renamed to lib/async/http/capture/cassette.rb

@@ -9,7 +9,7 @@
 
 module Async
 	module HTTP
-		module Recorder
+		module Capture
 			# Represents a collection of HTTP interactions using content-addressed storage.
 			# 
 			# A cassette serves as a container for multiple {Interaction} objects, storing each

lib/async/http/recorder/cassette_store.rb renamed to lib/async/http/capture/cassette_store.rb

@@ -9,7 +9,7 @@
 
 module Async
 	module HTTP
-		module Recorder
+		module Capture
 			# Store implementation that saves interactions to content-addressed files in a directory.
 			# 
 			# Each interaction is saved as a separate JSON file named by its content hash,

lib/async/http/recorder/console_store.rb renamed to lib/async/http/capture/console_store.rb

@@ -8,7 +8,7 @@
 
 module Async
 	module HTTP
-		module Recorder
+		module Capture
 			# Store implementation that logs interactions to the console.
 			# 
 			# This store outputs complete interaction data via the Console gem,

lib/async/http/recorder/interaction.rb renamed to lib/async/http/capture/interaction.rb

@@ -12,7 +12,7 @@
 
 module Async
 	module HTTP
-		module Recorder
+		module Capture
 			# Represents a single HTTP interaction containing request and optional response data.
 			# 
 			# This class serves as a simple data container that stores the raw interaction data
@@ -115,7 +115,7 @@ def serialize_request(request)
 					end
 
 					# Add body chunks if present:
-					if request.body && request.body.is_a?(Protocol::HTTP::Body::Buffered)
+					if request.body && request.body.is_a?(::Protocol::HTTP::Body::Buffered)
 						data[:body] = request.body.chunks
 					end
 
@@ -141,7 +141,7 @@ def serialize_response(response)
 					end
 
 					# Add body chunks if present:
-					if response.body && response.body.is_a?(Protocol::HTTP::Body::Buffered)
+					if response.body && response.body.is_a?(::Protocol::HTTP::Body::Buffered)
 						data[:body] = response.body.chunks
 					end
 
@@ -175,10 +175,10 @@ def make_response
 				# @parameter protocol [String | Array | Nil] The protocol information.
 				# @returns [Protocol::HTTP::Request] The constructed request object.
 				def build_request(scheme: nil, authority: nil, method:, path:, version: nil, headers: nil, body: nil, protocol: nil)
-					body = Protocol::HTTP::Body::Buffered.wrap(body) if body
+					body = ::Protocol::HTTP::Body::Buffered.wrap(body) if body
 					headers = build_headers(headers) if headers
 
-					Protocol::HTTP::Request.new(
+					::Protocol::HTTP::Request.new(
 						scheme,
 						authority,
 						method, 
@@ -198,10 +198,10 @@ def build_request(scheme: nil, authority: nil, method:, path:, version: nil, hea
 				# @parameter protocol [String | Array | Nil] The protocol information.
 				# @returns [Protocol::HTTP::Response] The constructed response object.
 				def build_response(version: nil, status:, headers: nil, body: nil, protocol: nil)
-					body = Protocol::HTTP::Body::Buffered.wrap(body) if body
+					body = ::Protocol::HTTP::Body::Buffered.wrap(body) if body
 					headers = build_headers(headers) if headers
 
-					Protocol::HTTP::Response.new(
+					::Protocol::HTTP::Response.new(
 						version,
 						status,
 						headers,
@@ -220,16 +220,16 @@ def build_headers(headers_data)
 						if headers_data.key?(:fields) || headers_data.key?("fields")
 							fields = headers_data[:fields] || headers_data["fields"]
 							tail = headers_data[:tail] || headers_data["tail"]
-							Protocol::HTTP::Headers.new(fields, tail)
+							::Protocol::HTTP::Headers.new(fields, tail)
 						else
 							# Simple hash format:
-							Protocol::HTTP::Headers[headers_data]
+							::Protocol::HTTP::Headers[headers_data]
 						end
 					when Array
 						# Array format of [name, value] pairs:
-						Protocol::HTTP::Headers[headers_data]
+						::Protocol::HTTP::Headers[headers_data]
 					else
-						Protocol::HTTP::Headers[headers_data]
+						::Protocol::HTTP::Headers[headers_data]
 					end
 				end
 			end

lib/async/http/capture/interaction_tracker.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "async/clock"
+require "protocol/http/request"
+require "protocol/http/response"
+
+require_relative "interaction"
+
+module Async
+	module HTTP
+		module Capture
+			# Tracks the completion of both request and response bodies for a single interaction. Records the interaction only when both sides are complete, capturing rich error context.
+			class InteractionTracker
+				# Initialize the tracker.
+				# @parameter store [Object] The store to record the interaction to.
+				# @parameter original_request [Protocol::HTTP::Request] The original request.
+				def initialize(store, original_request)
+					@store = store
+					@original_request = original_request
+					@original_response = nil
+					@request_complete = false
+					@response_complete = false
+					@request_body = nil
+					@response_body = nil
+					@error = nil
+					@clock = Async::Clock.start
+				end
+				
+				# Mark the request as ready (no body to process).
+				# @parameter request [Protocol::HTTP::Request] The request.
+				# @returns [Protocol::HTTP::Request] The same request.
+				def mark_request_ready(request)
+					@request_complete = true
+					check_completion
+					request
+				end
+				
+				# Mark the response as ready (no body to process).
+				# @parameter response [Protocol::HTTP::Response] The response.
+				# @returns [Protocol::HTTP::Response] The same response.
+				def mark_response_ready(response)
+					@original_response = response
+					@response_complete = true
+					check_completion
+					response
+				end
+				
+				# Called when request body processing completes.
+				# @parameter body [Protocol::HTTP::Body::Buffered | Nil] The captured body.
+				# @parameter error [Exception | Nil] Any error that occurred.
+				def request_completed(body: nil, error: nil)
+					@request_complete = true
+					@request_body = body
+					
+					if error
+						@error = capture_error_context(error, :request_body)
+					end
+					
+					check_completion
+				end
+				
+				# Called when response body processing completes.
+				# @parameter body [Protocol::HTTP::Body::Buffered | Nil] The captured body.
+				# @parameter error [Exception | Nil] Any error that occurred.
+				def response_completed(body: nil, error: nil)
+					@response_complete = true
+					@response_body = body
+					
+					if error
+						@error = capture_error_context(error, :response_body)
+					end
+					
+					check_completion
+				end
+				
+				# Set the response for this interaction.
+				# @parameter response [Protocol::HTTP::Response] The response to associate.
+				def set_response(response)
+					@original_response = response
+				end
+				
+				private
+				
+				# Capture raw error context for post-processing analysis.
+				# @parameter error [Exception] The error that occurred.
+				# @parameter phase [Symbol] The phase where the error occurred.
+				# @returns [Hash] Raw error context data for external analysis.
+				def capture_error_context(error, phase)
+					{
+						error_type: error.class.name,
+						error_message: error.message,
+						phase: phase,
+						elapsed_ms: (@clock.total * 1000).round(2),
+						timestamp: Time.now.iso8601
+					}
+				end
+				
+				# Check if both request and response are complete, and record if so.
+				def check_completion
+					return unless @request_complete && @response_complete
+					
+					# Create final request with buffered body:
+					final_request = ::Protocol::HTTP::Request.new(
+						@original_request.scheme,
+						@original_request.authority,
+						@original_request.method,
+						@original_request.path,
+						@original_request.version,
+						@original_request.headers,
+						@request_body,
+						@original_request.protocol
+					)
+					
+					# Create final response with buffered body:
+					final_response = nil
+					if @original_response
+						final_response = ::Protocol::HTTP::Response.new(
+							@original_response.version,
+							@original_response.status,
+							@original_response.headers,
+							@response_body,
+							@original_response.protocol
+						)
+					end
+					
+					# Create and record the interaction:
+					interaction_data = {}
+					interaction_data[:error] = @error if @error
+					
+					interaction = Interaction.new(
+						interaction_data,
+						request: final_request,
+						response: final_response
+					)
+					
+					@store.call(interaction)
+				end
+			end
+		end
+	end
+end

lib/async/http/capture/middleware.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "protocol/http/middleware"
+require "protocol/http/body/rewindable"
+require "protocol/http/body/completable"
+
+require_relative "interaction_tracker"
+
+module Async
+	module HTTP
+		module Capture
+			# Protocol::HTTP::Middleware for recording complete HTTP interactions.
+			# 
+			# This middleware captures both HTTP requests and responses, waiting for both
+			# to be fully processed before recording the complete interaction.
+			class Middleware < Protocol::HTTP::Middleware
+				# Initialize the recording middleware.
+				# @parameter app [Protocol::HTTP::Middleware] The next middleware in the chain.
+				# @parameter store [Object] An object that responds to #call(interaction) to handle recorded interactions.
+				def initialize(app, store:)
+					super(app)
+					@store = store
+				end
+				
+				# Process an HTTP request, capturing both request and response.
+				# @parameter request [Protocol::HTTP::Request] The incoming HTTP request.
+				# @returns [Protocol::HTTP::Response] The response from the next middleware.
+				def call(request)
+					# Create completion tracker for this interaction:
+					tracker = create_interaction_tracker(request)
+					
+					# Capture request body with completion tracking:
+					captured_request = capture_request_with_completion(request, tracker)
+					
+					# Get response from downstream middleware/app:
+					response = super(captured_request)
+					
+					# Capture response body with completion tracking:
+					capture_response_with_completion(captured_request, response, tracker)
+				end
+				
+				private
+				
+				# Create a completion tracker for a single interaction.
+				# @parameter request [Protocol::HTTP::Request] The original request.
+				# @returns [InteractionTracker] A new tracker instance.
+				def create_interaction_tracker(request)
+					InteractionTracker.new(@store, request)
+				end
+				
+				# Capture the request body with completion tracking.
+				# @parameter request [Protocol::HTTP::Request] The original request.
+				# @parameter tracker [InteractionTracker] The completion tracker.
+				# @returns [Protocol::HTTP::Request] A request with rewindable body.
+				def capture_request_with_completion(request, tracker)
+					return tracker.mark_request_ready(request) unless request.body && !request.body.empty?
+					
+					# Make the request body rewindable:
+					rewindable_body = ::Protocol::HTTP::Body::Rewindable.wrap(request)
+					
+					# Wrap with completion callback:
+					::Protocol::HTTP::Body::Completable.wrap(request) do |error|
+						if error
+							tracker.request_completed(error: error)
+						else
+							tracker.request_completed(body: rewindable_body.buffered)
+						end
+					end
+					
+					return request
+				end
+				
+				# Capture the response body with completion tracking.
+				# @parameter request [Protocol::HTTP::Request] The captured request.
+				# @parameter response [Protocol::HTTP::Response] The response to capture.
+				# @parameter tracker [InteractionTracker] The completion tracker.
+				# @returns [Protocol::HTTP::Response] The wrapped response.
+				def capture_response_with_completion(request, response, tracker)
+					# Set the response on the tracker:
+					tracker.set_response(response)
+					
+					return tracker.mark_response_ready(response) unless response.body && !response.body.empty?
+					
+					# Make the response body rewindable:
+					rewindable_body = ::Protocol::HTTP::Body::Rewindable.wrap(response)
+					
+					# Wrap with completion callback:
+					::Protocol::HTTP::Body::Completable.wrap(response) do |error|
+						if error
+							tracker.response_completed(error: error)
+						else
+							tracker.response_completed(body: rewindable_body.buffered)
+						end
+					end
+					
+					return response
+				end
+			end
+		end
+	end
+end