async-http-capture 0.1.0

data/lib/async/http/capture/cassette.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "json"
+require "time"
+require "fileutils"
+
+module Async
+	module HTTP
+		module Capture
+			# Represents a collection of HTTP interactions using content-addressed storage.
+			# 
+			# A cassette serves as a container for multiple {Interaction} objects, storing each
+			# interaction as a separate JSON file in a directory. Files are named using the
+			# content hash of the interaction, providing automatic de-duplication and 
+			# parallel-safe recording.
+			class Cassette
+				include Enumerable
+				
+				# @attribute [Array(Interaction)] The collection of interactions.
+				attr_reader :interactions
+				
+				# Initialize a new cassette with the provided interactions.
+				# @parameter interactions [Array(Interaction)] The interactions to include in the cassette.
+				def initialize(interactions = [])
+					@interactions = interactions
+				end
+				
+				# Iterate over each interaction in the cassette.
+				# @yields {|interaction| ...} Each interaction in the cassette.
+				#   @parameter interaction [Interaction] The current interaction being yielded.
+				def each(&block)
+					@interactions.each(&block)
+				end
+				
+				# Load a cassette from a directory of JSON interaction files.
+				# @parameter directory_path [String] The path to the directory containing JSON interaction files.
+				# @returns [Cassette] A new cassette instance with the loaded interactions.
+				# @raises [JSON::ParserError] If any file contains invalid JSON.
+				def self.load(directory_path)
+					return new([]) unless File.directory?(directory_path)
+					
+					json_files = Dir.glob(File.join(directory_path, "*.json"))
+					interactions = json_files.map do |file_path|
+						data = JSON.parse(File.read(file_path), symbolize_names: true)
+						Interaction.new(data)
+					end
+					new(interactions)
+				end
+				
+				# Save the cassette to a directory using content-addressed storage.
+				# Each interaction is saved as a separate JSON file named by its content hash.
+				# This approach provides de-duplication and parallel-safe recording.
+				# @parameter directory_path [String] The path to the directory where interactions should be saved.
+				def save(directory_path)
+					FileUtils.mkdir_p(directory_path)
+					
+					@interactions.each do |interaction|
+						filename = "#{interaction.content_hash}.json"
+						file_path = File.join(directory_path, filename)
+						File.write(file_path, JSON.pretty_generate(interaction.to_h))
+					end
+				end
+			end
+		end
+	end
+end

data/lib/async/http/capture/cassette_store.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "fileutils"
+require "json"
+require "time"
+
+require_relative "cassette"
+
+module Async
+	module HTTP
+		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,
+			# providing automatic de-duplication and parallel-safe recording.
+			class CassetteStore
+				# Initialize the cassette store.
+				# @parameter directory_path [String] The directory path where interactions should be saved.
+				def initialize(directory_path)
+					@directory_path = directory_path
+				end
+				
+				# @returns [Cassette] A cassette object representing the recorded interactions.
+				def cassette
+					Cassette.load(@directory_path)
+				end
+				
+				# Save an interaction to a content-addressed file with timestamp prefix.
+				# @parameter interaction [Interaction] The interaction to save.
+				def call(interaction)
+					FileUtils.mkdir_p(@directory_path)
+					
+					# Create filename with timestamp prefix for chronological ordering:
+					timestamp = Time.now.strftime("%Y%m%d-%H%M%S-%6N")  # Include microseconds
+					content_hash = interaction.content_hash
+					filename = "#{timestamp}-#{content_hash}.json"
+					file_path = File.join(@directory_path, filename)
+					
+					File.write(file_path, JSON.pretty_generate(interaction.serialize))
+				end
+			end
+		end
+	end
+end

data/lib/async/http/capture/console_store.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "console"
+require "json"
+
+module Async
+	module HTTP
+		module Capture
+			# Store implementation that logs interactions to the console.
+			# 
+			# This store outputs complete interaction data via the Console gem,
+			# particularly useful for debugging network errors and monitoring HTTP traffic.
+			class ConsoleStore
+				
+				# Initialize the console store.
+				# @parameter logger [Console::Logger] The logger to use (defaults to Console).
+				def initialize(logger: Console)
+					@logger = logger
+				end
+				
+				# Log an interaction to the console with full fidelity.
+				# The output includes complete interaction data to enable debugging and reconstruction.
+				# @parameter interaction [Interaction] The interaction to log.
+				def call(interaction)
+					# Let the interaction serialize itself:
+					serializable_data = interaction.serialize
+					
+					request_info = extract_request_info(serializable_data)
+					
+					if serializable_data[:error]
+						# Log errors with full interaction data:
+						@logger.error(self, "HTTP Error: #{request_info}") {JSON.pretty_generate(serializable_data)}
+					elsif serializable_data[:response]
+						# Log successful interactions with summary + full data:
+						status = serializable_data[:response][:status]
+						@logger.info(self, "#{request_info} -> #{status}") {JSON.pretty_generate(serializable_data)}
+					else
+						# Log request-only interactions:
+						@logger.debug(self, "Recorded: #{request_info}") {JSON.pretty_generate(serializable_data)}
+					end
+				end
+				
+				private
+				
+				# Extract request info for summary logging.
+				# @parameter data [Hash] The serialized interaction data.
+				# @returns [String] A summary of the request.
+				def extract_request_info(data)
+					return "Unknown request" unless data[:request]
+					
+					method = data[:request][:method] || "UNKNOWN"
+					path = data[:request][:path] || "/"
+					"#{method} #{path}"
+				end
+			end
+		end
+	end
+end

data/lib/async/http/capture/interaction.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "digest/sha2"
+require "json"
+require "protocol/http/request"
+require "protocol/http/response"
+require "protocol/http/headers"
+require "protocol/http/body/buffered"
+
+module Async
+	module HTTP
+		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
+			# and provides factory methods to construct {Protocol::HTTP::Request} and 
+			# {Protocol::HTTP::Response} objects on demand. May also contain error information
+			# if the interaction failed.
+			class Interaction
+				# Initialize a new interaction with the provided data.
+				# @parameter data [Hash] The interaction data containing serialized request and optional response information.
+				# @parameter request [Protocol::HTTP::Request | Nil] A pre-constructed request object.
+				# @parameter response [Protocol::HTTP::Response | Nil] A pre-constructed response object.
+				def initialize(data, request: nil, response: nil)
+					@data = data
+					@request = request
+					@response = response
+				end
+				
+				# Get the Protocol::HTTP::Request object, constructing it lazily if not already provided.
+				# @returns [Protocol::HTTP::Request | Nil] The request object, or nil if no request data is present.
+				def request
+					@request ||= make_request
+				end
+				
+				# Get the Protocol::HTTP::Response object, constructing it lazily if not already provided.
+				# @returns [Protocol::HTTP::Response | Nil] The response object, or nil if no response data is present.
+				def response
+					@response ||= make_response
+				end
+				
+				# Get any error that occurred during the interaction.
+				# @returns [Exception | String | Nil] The error information, or nil if no error occurred.
+				def error
+					@data[:error]
+				end
+				
+				# Convert the interaction to a hash representation.
+				# @returns [Hash] The raw interaction data.
+				def to_h
+					@data
+				end
+				
+				# Create an interaction from a hash of data.
+				# @parameter hash [Hash] The interaction data hash.
+				# @returns [Interaction] A new interaction instance.
+				def self.from_hash(hash)
+					new(hash)
+				end
+				
+				# Generate a content-addressed hash for this interaction.
+				# This hash can be used as a unique filename for content-addressed storage.
+				# @returns [String] A 16-character hexadecimal hash of the interaction content.
+				def content_hash
+					# Create a consistent JSON representation for hashing:
+					json_string = JSON.generate(serialize, sort_keys: true)
+					Digest::SHA256.hexdigest(json_string)[0, 16]
+				end
+				
+				# Serialize the interaction to a data format suitable for storage or hashing.
+				# Converts Protocol::HTTP objects to plain data structures.
+				# @returns [Hash] The serialized interaction data.
+				def serialize
+					data = @data.dup
+					
+					if request_obj = self.request
+						data[:request] = serialize_request(request_obj)
+					end
+					
+					if response_obj = self.response  
+						data[:response] = serialize_response(response_obj)
+					end
+					
+					if error = self.error
+						data[:error] = error.is_a?(Exception) ? error.message : error.to_s
+					end
+					
+					data
+				end
+				
+				# Provide a reasonable string representation of this interaction.
+				# @returns [String] A human-readable description of the interaction.
+				def to_s
+					parts = []
+					
+					# Add request information
+					if request_data = @data[:request]
+						method = request_data[:method] || "?"
+						path = request_data[:path] || "/"
+						parts << "#{method} #{path}"
+					end
+					
+					# Add response status if available
+					if response_data = @data[:response]
+						status = response_data[:status]
+						parts << "-> #{status}" if status
+					end
+					
+					# Add error if present
+					if error_data = @data[:error]
+						parts << "(ERROR: #{error_data})"
+					end
+					
+					# Add timestamp if available
+					if timestamp = @data[:timestamp]
+						parts << "[#{timestamp}]"
+					end
+					
+					parts.join(" ")
+				end
+				
+				private
+				
+				# Serialize a Protocol::HTTP::Request to a hash.
+				# @parameter request [Protocol::HTTP::Request] The request to serialize.
+				# @returns [Hash] The serialized request data.
+				def serialize_request(request)
+					data = {
+						scheme: request.scheme,
+						authority: request.authority,
+						method: request.method,
+						path: request.path,
+						version: request.version,
+						protocol: request.protocol
+					}
+					
+					# Add headers if present:
+					if request.headers && !request.headers.empty?
+						data[:headers] = {
+							fields: request.headers.fields,
+							tail: request.headers.tail
+						}
+					end
+					
+					# Add body chunks if present:
+					if request.body && request.body.is_a?(::Protocol::HTTP::Body::Buffered)
+						data[:body] = request.body.chunks
+					end
+					
+					data
+				end
+				
+				# Serialize a Protocol::HTTP::Response to a hash.
+				# @parameter response [Protocol::HTTP::Response] The response to serialize.
+				# @returns [Hash] The serialized response data.
+				def serialize_response(response)
+					data = {
+						version: response.version,
+						status: response.status,
+						protocol: response.protocol
+					}
+					
+					# Add headers if present:
+					if response.headers && !response.headers.empty?
+						data[:headers] = {
+							fields: response.headers.fields,
+							tail: response.headers.tail
+						}
+					end
+					
+					# Add body chunks if present:
+					if response.body && response.body.is_a?(::Protocol::HTTP::Body::Buffered)
+						data[:body] = response.body.chunks
+					end
+					
+					data
+				end
+				
+				# Create a Protocol::HTTP::Request from the stored request data.
+				# @returns [Protocol::HTTP::Request] The constructed request object.
+				def make_request
+					if request_data = @data[:request]
+						build_request(**request_data)
+					end
+				end
+				
+				# Create a Protocol::HTTP::Response from the stored response data.
+				# @returns [Protocol::HTTP::Response] The constructed response object.
+				def make_response
+					if response_data = @data[:response]
+						build_response(**response_data)
+					end
+				end
+				
+				# Build a Protocol::HTTP::Request from the provided parameters.
+				# @parameter scheme [String | Nil] The request scheme (e.g. "https").
+				# @parameter authority [String | Nil] The request authority (e.g. "example.com").
+				# @parameter method [String] The HTTP method (e.g. "GET", "POST").
+				# @parameter path [String] The request path (e.g. "/users/123").
+				# @parameter version [String | Nil] The HTTP version (e.g. "HTTP/1.1").
+				# @parameter headers [Array | Nil] Array of header name-value pairs.
+				# @parameter body [Array | Nil] Array of body chunks.
+				# @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
+					headers = build_headers(headers) if headers
+					
+					::Protocol::HTTP::Request.new(
+						scheme,
+						authority,
+						method, 
+						path,
+						version,
+						headers,
+						body,
+						protocol
+					)
+				end
+				
+				# Build a Protocol::HTTP::Response from the provided parameters.
+				# @parameter version [String | Nil] The HTTP version (e.g. "HTTP/1.1").
+				# @parameter status [Integer] The HTTP status code (e.g. 200, 404).
+				# @parameter headers [Array | Nil] Array of header name-value pairs.
+				# @parameter body [Array | Nil] Array of body chunks.
+				# @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
+					headers = build_headers(headers) if headers
+					
+					::Protocol::HTTP::Response.new(
+						version,
+						status,
+						headers,
+						body,
+						protocol
+					)
+				end
+				
+				# Build Protocol::HTTP::Headers from serialized data.
+				# @parameter headers_data [Hash | Array] The serialized headers data.
+				# @returns [Protocol::HTTP::Headers] The constructed headers object.
+				def build_headers(headers_data)
+					case headers_data
+					when Hash
+						# Hash format with fields and tail for complete header reconstruction:
+						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)
+						else
+							# Simple hash format:
+							::Protocol::HTTP::Headers[headers_data]
+						end
+					when Array
+						# Array format of [name, value] pairs:
+						::Protocol::HTTP::Headers[headers_data]
+					else
+						::Protocol::HTTP::Headers[headers_data]
+					end
+				end
+			end
+		end
+	end
+end

data/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