async-http-capture 0.1.0

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

@@ -0,0 +1,117 @@
+# 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)
+					# Check if we should capture this request:
+					unless capture?(request)
+						return super(request)
+					end
+					
+					# 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
+				
+				# Determine whether to capture the given request.
+				# Override this method in subclasses to implement custom filtering logic.
+				# @parameter request [Protocol::HTTP::Request] The incoming HTTP request.
+				# @returns [Boolean] True if the request should be captured, false otherwise.
+				def capture?(request)
+					true
+				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

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Async
+	module HTTP
+		module Capture
+			VERSION = "0.1.0"
+		end
+	end
+end

data/lib/async/http/capture.rb

@@ -0,0 +1,22 @@
+# 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"
+
+# @namespace
+module Async
+	# @namespace
+	module HTTP
+		# @namespace
+		module Capture
+		end
+	end
+end

data/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 2025, by Samuel Williams.  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/readme.md

@@ -0,0 +1,133 @@
+# Async::HTTP::Capture
+
+A Ruby gem for recording and replaying HTTP requests using `Protocol::HTTP`. Features content-addressed storage, parallel-safe recording, and flexible store backends.
+
+[![Development Status](https://github.com/socketry/async-http-capture/workflows/Test/badge.svg)](https://github.com/socketry/async-http-capture/actions?workflow=Test)
+
+## Features
+
+  - **Pure Protocol::HTTP**: Works directly with Protocol::HTTP objects, no lossy conversions
+  - **Content-Addressed Storage**: Each interaction saved as separate JSON file with content hash
+  - **Parallel-Safe**: Multiple processes can record simultaneously without conflicts
+  - **Flexible Stores**: Pluggable storage backends (files, console logging, etc.)
+  - **Complete Headers**: Full round-trip serialization including `fields` and `tail`
+  - **Error Handling**: Captures network errors and connection issues
+
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/async-http-capture/) for more details.
+
+  - [Getting Started](https://socketry.github.io/async-http-capture/guides/getting-started/index) - This guide explains how to get started with `async-http-capture`, a Ruby gem for recording and replaying HTTP requests using Protocol::HTTP.
+
+### Basic Recording to Files
+
+``` ruby
+require "async/http/capture"
+
+# Create a store that saves to content-addressed files:
+store = Async::HTTP::Capture::CassetteStore.new("interactions")
+
+# Create middleware:
+app = ->(request) { Protocol::HTTP::Response[200, {}, ["OK"]] }
+middleware = Async::HTTP::Capture::Middleware.new(app, store: store)
+
+# Record interactions:
+request = Protocol::HTTP::Request["GET", "/users"]
+response = middleware.call(request)
+```
+
+### Recording to Console Log
+
+``` ruby
+# Create a console store for debugging:
+console_store = Async::HTTP::Capture::ConsoleStore.new
+middleware = Async::HTTP::Capture::Middleware.new(app, store: console_store)
+
+# This will log interactions to console:
+middleware.call(request)
+# Output: "Recorded: GET /users"
+```
+
+### Loading and Replaying
+
+``` ruby
+# Load recorded interactions:
+cassette = Async::HTTP::Capture::Cassette.load("interactions")
+
+# Replay them:
+cassette.each do |interaction|
+  request = interaction.request  # Lazy construction
+  response = app.call(request)   # Send to your app
+end
+```
+
+### Recording with Responses
+
+``` ruby
+# Record both requests and responses:
+middleware = Async::HTTP::Capture::Middleware.new(
+  app, 
+  store: store,
+  record_response: true
+)
+
+response = middleware.call(request)
+# Both request and response are now recorded
+```
+
+## Architecture
+
+    Middleware -> Store.call(interaction) -> [CassetteStore | ConsoleStore | ...]
+
+  - **Middleware**: Pure capture logic, creates Interaction objects with Protocol::HTTP data
+  - **Store Interface**: Generic `call(interaction)` method for pluggable backends
+  - **Stores**: Handle serialization, filtering, persistence, or logging
+  - **Interaction**: Simple data container with lazy Protocol::HTTP object construction
+
+## Content-Addressed Storage
+
+Each interaction is saved to a file named by its content hash:
+
+    interactions/
+    ├── a1b2c3d4e5f67890.json  # GET /users
+    ├── f67890a1b2c3d4e5.json  # POST /orders  
+    └── 1234567890abcdef.json  # GET /health
+
+Benefits:
+
+  - **Automatic de-duplication**: Identical interactions → same filename
+  - **Parallel-safe**: Multiple processes can write without conflicts
+  - **Content integrity**: Hash verifies file contents
+  - **Git-friendly**: Stable filenames for version control
+
+## Store Implementations
+
+### CassetteStore
+
+Saves interactions to content-addressed JSON files in a directory.
+
+### ConsoleStore
+
+Logs interactions via the Console gem with different levels based on success/failure.
+
+### Custom Stores
+
+Implement the `Store` interface:
+
+``` ruby
+class MyStore
+  include Async::HTTP::Capture::Store
+  
+  def call(interaction)
+    # Handle the interaction as needed
+  end
+end
+```
+
+## Testing
+
+``` bash
+bundle exec sus
+```
+
+The gem includes comprehensive tests using the Sus testing framework with 41 tests and 101 assertions.

data/releases.md

@@ -0,0 +1,5 @@
+# Releases
+
+## v0.1.0
+
+  - Initial implementation.

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: async-http-capture
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Samuel Williams
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.90'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.90'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- context/getting-started.md
+- context/index.yaml
+- design.md
+- lib/async/http/capture.rb
+- lib/async/http/capture/cassette.rb
+- lib/async/http/capture/cassette_store.rb
+- lib/async/http/capture/console_store.rb
+- lib/async/http/capture/interaction.rb
+- lib/async/http/capture/interaction_tracker.rb
+- lib/async/http/capture/middleware.rb
+- lib/async/http/capture/version.rb
+- license.md
+- readme.md
+- releases.md
+homepage: https://github.com/socketry/async-http-capture
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://socketry.github.io/async-http-capture/
+  source_code_uri: https://github.com/socketry/async-http-capture.git
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A HTTP request and response capture.
+test_files: []