async-http-capture 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1daaf4df163cc364474c3fa2317fc470599b93291f172612534c251de4213f7d
-  data.tar.gz: eeb94b760ea184040e56a2d334e9eb655864f4275d3e9397ae99f19ca3f237c5
+  metadata.gz: 53f67ea6516d2dabe2edca496f827aefa4324bec0388be36e4771d6d5564aea3
+  data.tar.gz: dd344bbf8bca118a37e214fee92dc0d743c264ff011aed8517a9bf4db2a2b098
 SHA512:
-  metadata.gz: aec6884a20a7bf778d2a420927893c0bb24cbf988554b6a1c23fa8336abe332c37037663060e84e04acf0fdc365d1fa38196d934bcda1e824dabcdf5276c3ab9
-  data.tar.gz: b3cdf504d73f9ec34dea3e0faf4db09f813c616fc800b1922149e27687a5c02716b06d051e1a0d2626bb203a814c7cc4f4bc2c917e842357354b9b36ccc11993
+  metadata.gz: 02234f7f20f20a03768322275c9dc76d1501b8ea220185279b5f0a1d9a0d911646ee2777b64f26b0ac0a36e09613f457d6393a5775340915cd9d9fa0d1ad869d
+  data.tar.gz: a319dd4cc411dca4e4fcd1d7f347a5437f825263d6a5685d2529f48d2d296993c01ee764b7e8a45fd5b33d4bdfd47c42b7996a437190cad20b8332ff28b081be

data/context/falcon-integration.md

@@ -0,0 +1,115 @@
+# Falcon Integration
+
+This guide explains how to integrate `async-http-capture` with Falcon web server for recording and replaying HTTP interactions.
+
+## Core Concepts
+
+Falcon integration with `async-http-capture` uses the {ruby Async::HTTP::Capture::Environment} to provide clean, declarative configuration for both recording and replay functionality.
+
+## Usage
+
+Create a `falcon.rb` configuration file:
+
+~~~ ruby
+#!/usr/bin/env falcon-host
+# frozen_string_literal: true
+
+require "falcon/environment/rack"
+require "async/http/capture"
+
+service "my-app" do
+	include Falcon::Environment::Rack
+	include Async::HTTP::Capture::Environment
+end
+~~~
+
+This minimal configuration automatically:
+
+- **Records interactions** to `cassette/recordings/` directory
+- **Replays existing recordings** from `cassette/warmup/` for application warmup
+- **Logs interactions** to console for visibility
+
+### Custom Configuration
+
+Override the environment methods to customize behavior:
+
+~~~ ruby
+service "my-app" do
+	include Falcon::Environment::Rack
+	include Async::HTTP::Capture::Environment
+		
+	def capture_cassette_directory
+		# Custom warmup directory:
+		"recordings/warmup"
+	end
+	
+	def capture_recordings_directory
+		# Custom recording directory:
+		"recordings/production"
+	end
+	
+	def capture_console_logging
+		# Disable console output for production:
+		false
+	end
+end
+~~~
+
+## Running the Server
+
+Start your Falcon server with recording enabled:
+
+~~~ bash
+$ bundle exec ./falcon.rb
+~~~
+
+The server will:
+
+1. **Start up**: Load and replay any existing recordings for warmup
+2. **Accept requests**: Process incoming HTTP requests normally  
+3. **Record interactions**: Save all new interactions to timestamped files
+4. **Log activity**: Show recording activity in console (if enabled)
+
+## Application Warmup
+
+One of the most powerful features is automatic application warmup using recorded interactions:
+
+### Recording Phase
+
+During development or testing, make requests to capture typical usage patterns:
+
+~~~ bash
+# Make various requests to capture typical traffic patterns
+curl http://localhost:9292/health
+curl http://localhost:9292/api/users
+curl -X POST http://localhost:9292/api/orders \
+  -H "content-type: application/json" \
+  -d '{"product_id": 123, "quantity": 2}'
+~~~
+
+These requests are recorded to `cassette/recordings/` as:
+
+~~~ 
+cassette/recordings/
+├── 20250821-105406-271633-12345-67890.json  # GET /health
+├── 20250821-105407-123456-12345-67890.json  # GET /api/users
+└── 20250821-105408-654321-12345-67890.json  # POST /api/orders
+~~~
+
+Files are named: `YYYYMMDD-HHMMSS-MICROSECONDS-PID-OBJECT_ID.json`
+
+Where:
+- `YYYYMMDD-HHMMSS-MICROSECONDS` = timestamp with microsecond precision.
+- `PID` = process ID.
+- `OBJECT_ID` = store instance object ID.
+
+### Warmup Phase
+
+On subsequent server starts, the Environment automatically replays recorded interactions to warm up:
+
+- **Database connections**
+- **Application caches** 
+- **JIT compilation**
+- **Service dependencies**
+
+This dramatically improves first-request latency and provides predictable application startup behavior in production.

data/context/getting-started.md

@@ -17,7 +17,7 @@ $ bundle add async-http-capture
 - A {ruby Async::HTTP::Capture::Middleware} which captures HTTP requests and responses as they pass through your application.
 - An {ruby Async::HTTP::Capture::Interaction} which represents a single HTTP request/response pair with lazy Protocol::HTTP object construction.
 - A {ruby Async::HTTP::Capture::Cassette} which is a collection of interactions that can be loaded from and saved to JSON files.
-- A {ruby Async::HTTP::Capture::CassetteStore} which provides content-addressed storage, saving each interaction to a separate file named by its content hash.
+- A {ruby Async::HTTP::Capture::CassetteStore} which provides timestamped storage, saving each interaction to a separate file named by timestamp.
 - A {ruby Async::HTTP::Capture::ConsoleStore} which logs interactions to the console for debugging purposes.
 
 ## Usage
@@ -35,11 +35,11 @@ Here's how to record HTTP interactions to files:
 ~~~ ruby
 require "async/http/capture"
 
-# Create a store that saves to content-addressed files:
+# Create a store that saves to timestamped files:
 store = Async::HTTP::Capture::CassetteStore.new("interactions")
 
 # Create your application
-app = ->(request) { Protocol::HTTP::Response[200, {}, ["OK"]] }
+app = ->(request) {Protocol::HTTP::Response[200, {}, ["OK"]]}
 
 # Wrap it with recording middleware:
 middleware = Async::HTTP::Capture::Middleware.new(app, store: store)
@@ -47,7 +47,7 @@ middleware = Async::HTTP::Capture::Middleware.new(app, store: store)
 # Make requests - they will be automatically recorded:
 request = Protocol::HTTP::Request["GET", "/users"]
 response = middleware.call(request)
-# This creates a file like interactions/a1b2c3d4e5f67890.json
+# This creates a file like recordings/20250821-105406-271633-12345-67890.json
 ~~~
 
 ### Recording with Console Output
@@ -70,45 +70,46 @@ middleware.call(request)
 # Load recorded interactions:
 cassette = Async::HTTP::Capture::Cassette.load("interactions")
 
-# Replay them against your application:
+# Option 1: Use the built-in replay method for application warmup
+cassette.replay(app)
+
+# Option 2: Manual iteration for custom processing
 cassette.each do |interaction|
-  request = interaction.request  # Lazy Protocol::HTTP::Request construction
-  response = app.call(request)   # Send to your app
-  puts "#{request.method} #{request.path} -> #{response.status}"
+	request = interaction.request  # Lazy Protocol::HTTP::Request construction
+	response = app.call(request)   # Send to your app
+	puts "#{request.method} #{request.path} -> #{response.status}"
 end
 ~~~
 
 ## Recording HTTP Requests and Responses
 
-By default, only requests are recorded. To capture responses as well:
+The middleware automatically records both requests and responses:
 
 ~~~ ruby
 middleware = Async::HTTP::Capture::Middleware.new(
-  app, 
-  store: store,
-  record_response: true
+	app, 
+	store: store
 )
 
 response = middleware.call(request)
-# Both request and response are now recorded
+# Both request and response are recorded.
 ~~~
 
-## Content-Addressed Storage
+## Timestamped Storage
 
-Each interaction is saved to a file named by its content hash, providing several benefits:
+Each interaction is saved to a file named with timestamp, process ID, and object ID, providing several benefits:
 
 ~~~ 
-interactions/
-├── a1b2c3d4e5f67890.json  # GET /users
-├── f67890a1b2c3d4e5.json  # POST /orders  
-└── 1234567890abcdef.json  # GET /health
+recordings/
+├── 20250821-105406-271633-12345-67890.json  # GET /users
+├── 20250821-105006-257022-12346-67891.json  # POST /orders
+└── 20250820-101234-567890-12347-67892.json  # GET /health
 ~~~
 
 Benefits:
-- **Automatic de-duplication**: Identical interactions → same filename
+- **Chronological ordering**: Files sorted by timestamp
 - **Parallel-safe**: Multiple processes can write without conflicts  
-- **Content integrity**: Hash verifies file contents
-- **Git-friendly**: Stable filenames for version control
+- **Human-readable**: Timestamps are easy to understand
 
 ## Application Warmup
 
@@ -122,17 +123,17 @@ endpoint = Async::HTTP::Endpoint.parse("https://api.example.com")
 store = Async::HTTP::Capture::CassetteStore.new("warmup_interactions")
 
 recording_middleware = Async::HTTP::Capture::Middleware.new(
-  nil,
-  store: store
+	nil,
+	store: store
 )
 
 client = Async::HTTP::Client.new(endpoint, middleware: [recording_middleware])
 
 # Make the requests you want to record
 Async do
-  client.get("/health")
-  client.get("/api/popular-items") 
-  client.post("/api/user-sessions", {user_id: 123})
+	client.get("/health")
+	client.get("/api/popular-items") 
+	client.post("/api/user-sessions", {user_id: 123})
 end
 
 # Step 2: Use recorded interactions to warm up your application
@@ -141,13 +142,13 @@ app = MyApplication.new
 
 puts "Warming up with #{cassette.interactions.size} recorded interactions..."
 cassette.each do |interaction|
-  request = interaction.request
-  begin
-    app_response = app.call(request)
-    puts "Warmed up #{request.method} #{request.path} -> #{app_response.status}"
-  rescue => error
-    puts "Warning: #{request.method} #{request.path} -> #{error.message}"
-  end
+	request = interaction.request
+	begin
+		app_response = app.call(request)
+		puts "Warmed up #{request.method} #{request.path} -> #{app_response.status}"
+	rescue => error
+		puts "Warning: #{request.method} #{request.path} -> #{error.message}"
+	end
 end
 
 puts "Warmup complete!"
@@ -159,28 +160,14 @@ You can create custom storage backends by implementing the {ruby Async::HTTP::Ca
 
 ~~~ ruby
 class MyCustomStore
-  include Async::HTTP::Capture::Store
-  
-  def call(interaction)
-    # Handle the interaction as needed
-    # e.g., send to a database, external service, etc.
-    puts "Custom handling: #{interaction.request.method} #{interaction.request.path}"
-  end
+	def call(interaction)
+		# Handle the interaction as needed
+		# e.g., send to a database, external service, etc.
+		puts "Custom handling: #{interaction.request.method} #{interaction.request.path}"
+	end
 end
 
 # Use your custom store
 custom_store = MyCustomStore.new
 middleware = Async::HTTP::Capture::Middleware.new(app, store: custom_store)
 ~~~
-
-## Key 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
-- **Lazy Construction**: Protocol::HTTP objects are constructed on-demand for memory efficiency
-
-This makes `async-http-capture` ideal for testing, debugging, application warmup, and HTTP traffic analysis scenarios.

data/context/index.yaml

@@ -10,3 +10,7 @@ files:
   title: Getting Started
   description: This guide explains how to get started with `async-http-capture`, a
     Ruby gem for recording and replaying HTTP requests using Protocol::HTTP.
+- path: falcon-integration.md
+  title: Falcon Integration
+  description: This guide explains how to integrate `async-http-capture` with Falcon
+    web server for recording and replaying HTTP interactions.

data/design.md

@@ -115,7 +115,7 @@ end
 
 ```ruby
 # Load recorded interactions and replay them (no middleware needed)
-cassette = Async::HTTP::Record::Cassette.load("interactions.json")
+cassette = Async::HTTP::Capture::Cassette.load("recordings")
 
 # Simple replay: interactions construct Protocol::HTTP objects lazily
 cassette.each do |interaction|
@@ -124,7 +124,7 @@ cassette.each do |interaction|
 	# Your app handles the request normally (warming up caches, etc.)
 end
 
-# Manual cassette creation using data hashes  
+# Manual cassette creation using data hashes:
 interactions = [
 	Async::HTTP::Record::Interaction.new({
 		request: {
@@ -144,7 +144,7 @@ interactions = [
 ]
 
 cassette = Async::HTTP::Record::Cassette.new(interactions)
-cassette.save("interactions.json")
+cassette.save("recordings")
 ```
 
 ### Recording Middleware
@@ -170,7 +170,7 @@ class Async::HTTP::Record::Middleware < Protocol::HTTP::Middleware
 		# Capture request body if present
 		captured_request = capture_request_body(request)
 		
-		# Get response from downstream middleware/app  
+		# Get response from downstream middleware/app
 		response = super(captured_request)
 		
 		if @record_response
@@ -480,11 +480,11 @@ For warmup scenarios where you only need requests:
 
 ## Implementation Strategy
 
-### Phase 1: Core Components  
+### Phase 1: Core Components
 - [ ] `Interaction` class as immutable data holder using Protocol::HTTP objects with bodies
 - [ ] `Cassette` class with JSON serialization and loading
 
-### Phase 2: Replay Integration  
+### Phase 2: Replay Integration
 - [ ] Simple replay by iterating through interactions and calling `app.call(request)`
 - [ ] No middleware needed - direct request sending to your application
 - [ ] Proper error handling during replay for robust warmup scenarios
@@ -539,7 +539,7 @@ cassette.save("warmup.json")
 require "async/http/record"
 
 # Load recorded interactions
-cassette = Async::HTTP::Record::Cassette.load("interactions.json")
+cassette = Async::HTTP::Capture::Cassette.load("recordings")
 
 # Your application
 app = MyApplication.new
@@ -569,7 +569,7 @@ require "async/http/record"
 endpoint = Async::HTTP::Endpoint.parse("https://api.example.com")
 recording_middleware = Async::HTTP::Record::Middleware.new(
 	nil,
-	cassette_path: "interactions.json"
+	cassette_path: "recordings"
 )
 
 client = Async::HTTP::Client.new(endpoint, middleware: [recording_middleware])
@@ -585,8 +585,8 @@ end
 # Step 2: Use recorded interactions to warm up your application
 require "async/http/record"
 
-# Load recorded interactions  
-cassette = Async::HTTP::Record::Cassette.load("interactions.json")
+# Load recorded interactions
+cassette = Async::HTTP::Capture::Cassette.load("recordings")
 
 # Your application
 app = MyApplication.new
@@ -610,11 +610,11 @@ puts "Warmup complete! Starting server..."
 
 ### Simple Error Strategy
 - Missing cassette file: raise clear error with path
-- Invalid JSON: raise parsing error with line number  
+- Invalid JSON: raise parsing error with line number
 - Invalid request data: raise validation error
 - Keep error messages focused and actionable
 
-## Testing Strategy  
+## Testing Strategy
 
 ### Unit Tests
 ```ruby
@@ -724,13 +724,13 @@ Following async-http-cache's proven approach:
 - Use `Protocol::HTTP::Body::Completable` for completion callbacks
 - Use `Protocol::HTTP::Body::Buffered` for final storage as arrays of strings
 
-### 5. Simple Replay Pattern  
+### 5. Simple Replay Pattern
 No middleware needed for replay - just iterate through recorded interactions and call `app.call(request)` to warm up your application directly.
 
-### 6. Optional Response Recording  
+### 6. Optional Response Recording
 Responses are not recorded by default (`record_response: false`) since many use cases only need request recording for testing or mocking.
 
-### 7. JSON-Only Storage  
+### 7. JSON-Only Storage
 Simple, human-readable format that's easy to inspect and version control.
 
 ### 8. No Global State
@@ -760,7 +760,7 @@ All components are explicit about their dependencies and configuration.
 
 This design enables a clean workflow:
 
-1. **Recording**: Use `Middleware` with default `record_response: false` to capture requests during development/testing  
+1. **Recording**: Use `Middleware` with default `record_response: false` to capture requests during development/testing
 2. **Replay**: Simple iteration - `cassette.each { |interaction| app.call(interaction.request) }` with lazy Protocol::HTTP object construction
 3. **Lazy Construction**: `Interaction` stores data and builds Protocol::HTTP objects on first access via `request`/`response` methods
 4. **Leverages Existing APIs**: Uses `Protocol::HTTP::Body::Buffered.wrap()` and standard Protocol::HTTP constructors

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

@@ -6,6 +6,7 @@
 require "json"
 require "time"
 require "fileutils"
+require "console"
 
 module Async
 	module HTTP
@@ -47,22 +48,48 @@ module Async
 						data = JSON.parse(File.read(file_path), symbolize_names: true)
 						Interaction.new(data)
 					end
-					new(interactions)
+					
+					return self.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.
+				# Save the cassette to a directory using timestamped files.
+				# Each interaction is saved as a separate JSON file with a timestamp-based name.
+				# This approach provides 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"
+					@interactions.each_with_index do |interaction, index|
+						timestamp = Time.now.strftime("%Y%m%d-%H%M%S-%6N") 
+						filename = "#{timestamp}-#{index}.json"
 						file_path = File.join(directory_path, filename)
 						File.write(file_path, JSON.pretty_generate(interaction.to_h))
 					end
 				end
+				
+				# Replay all interactions against the provided application.
+				# This is useful for warming up applications by replaying recorded traffic.
+				# @parameter app [#call] The application to replay interactions against.
+				def replay(app)
+					count = @interactions.length
+					Console.info(self) {"Replaying #{count} interactions for warmup..."}
+					
+					@interactions.each do |interaction|
+						Console.debug(self, "Replaying interaction:", interaction)
+						
+						# Replay the interaction against the app:
+						if request = interaction.request
+							begin
+								response = app.call(request)
+								response.finish
+							rescue => error
+								Console.warn(self, "Failed to replay interaction:", error)
+							end
+						end
+					end
+					
+					Console.info(self) {"Warmup complete."}
+				end
 			end
 		end
 	end

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

@@ -12,15 +12,16 @@ require_relative "cassette"
 module Async
 	module HTTP
 		module Capture
-			# Store implementation that saves interactions to content-addressed files in a directory.
+			# Store implementation that saves interactions to timestamped 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.
+			# Each interaction is saved as a separate JSON file named by timestamp,
+			# using atomic write + move operations for 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
+					@suffix = "#{Process.pid}-#{self.object_id}"
 				end
 				
 				# @returns [Cassette] A cassette object representing the recorded interactions.
@@ -28,15 +29,14 @@ module Async
 					Cassette.load(@directory_path)
 				end
 				
-				# Save an interaction to a content-addressed file with timestamp prefix.
+				# Save an interaction to a timestamped file using PID and object ID for uniqueness.
 				# @parameter interaction [Interaction] The interaction to save.
 				def call(interaction)
 					FileUtils.mkdir_p(@directory_path)
 					
-					# Create filename with timestamp prefix for chronological ordering:
+					# Create filename with timestamp, PID, and object ID for complete uniqueness:
 					timestamp = Time.now.strftime("%Y%m%d-%H%M%S-%6N")  # Include microseconds
-					content_hash = interaction.content_hash
-					filename = "#{timestamp}-#{content_hash}.json"
+					filename = "#{timestamp}-#{@suffix}.json"
 					file_path = File.join(@directory_path, filename)
 					
 					File.write(file_path, JSON.pretty_generate(interaction.serialize))

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "cassette"
+require_relative "cassette_store"
+require_relative "console_store"
+require_relative "middleware"
+require "console"
+
+module Async
+	module HTTP
+		module Capture
+			# A flat environment module for HTTP capture services.
+			# 
+			# Provides simple, declarative configuration for recording and replaying HTTP interactions.
+			# Override these methods in your service to customize behavior.
+			module Environment
+				# Directory path to load cassettes from for replay warmup.
+				# Override this method to specify a different directory.
+				def capture_cassette_directory
+					"cassette/warmup"
+				end
+				
+				# Directory path to save recordings to.
+				# Override this method to specify where recordings should be saved.
+				def capture_recordings_directory
+					"cassette/recordings"
+				end
+				
+				# Whether to enable console logging of interactions (default: false).
+				# Override this method to enable console output.
+				def capture_console_logging
+					true
+				end
+				
+				# Load the cassette for replay if configured
+				def capture_cassette
+					if capture_cassette_directory && File.directory?(capture_cassette_directory)
+						Cassette.load(capture_cassette_directory)
+					end
+				end
+				
+				# Get the recording store if configured
+				def capture_recording_store
+					stores = []
+					
+					# Add file storage if directory configured
+					if capture_recordings_directory
+						stores << CassetteStore.new(capture_recordings_directory)
+					end
+					
+					# Add console logging if enabled
+					if capture_console_logging
+						stores << ConsoleStore.new
+					end
+					
+					# Return combined store or nil
+					case stores.length
+					when 0
+						nil
+					when 1
+						stores.first
+					else
+						# Multiple stores - combine them
+						proc do |interaction|
+							stores.each {|store| store.call(interaction)}
+						end
+					end
+				end
+				
+				# The middleware class to use for recording.
+				def capture_middleware_class
+					Middleware
+				end
+				
+				# Wrap the middleware with the recording middleware.
+				# @parameter middleware [Middleware] The middleware to wrap.
+				# @parameter store [CassetteStore] The store to use for recording.
+				# @returns [Middleware] The wrapped middleware.
+				def capture_middleware(middleware)
+					if store = capture_recording_store
+						middleware = capture_middleware_class.new(middleware, store: store)
+					end
+					
+					return middleware
+				end
+				
+				# Set up middleware chain with recording support.
+				def middleware
+					# Get the underlying application by calling super:
+					middleware = super
+					
+					# Warm up the application with recorded interactions if available:
+					capture_cassette&.replay(middleware)
+					
+					# Wrap with recording middleware if store is configured
+					return capture_middleware(middleware)
+				end
+			end
+		end
+	end
+end

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

@@ -3,8 +3,8 @@
 # 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"
@@ -61,16 +61,7 @@ module Async
 					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.
+				# Serialize the interaction to a data format suitable for storage.
 				# Converts Protocol::HTTP objects to plain data structures.
 				# @returns [Hash] The serialized interaction data.
 				def serialize
@@ -80,7 +71,7 @@ module Async
 						data[:request] = serialize_request(request_obj)
 					end
 					
-					if response_obj = self.response  
+					if response_obj = self.response
 						data[:response] = serialize_response(response_obj)
 					end
 					
@@ -147,7 +138,7 @@ module Async
 					
 					# Add body chunks if present:
 					if request.body && request.body.is_a?(::Protocol::HTTP::Body::Buffered)
-						data[:body] = request.body.chunks
+						data[:body] = serialize_body_chunks(request.body.chunks)
 					end
 					
 					data
@@ -173,12 +164,30 @@ module Async
 					
 					# Add body chunks if present:
 					if response.body && response.body.is_a?(::Protocol::HTTP::Body::Buffered)
-						data[:body] = response.body.chunks
+						data[:body] = serialize_body_chunks(response.body.chunks)
 					end
 					
 					data
 				end
 				
+			private
+				
+				# Serialize body chunks using built-in pack for base64 encoding.
+				# @parameter chunks [Array(String)] The chunks to serialize.
+				# @returns [Array(String)] Base64 encoded chunks.
+				def serialize_body_chunks(chunks)
+					chunks.map {|chunk| [chunk].pack("m0")}
+				end
+				
+				# Deserialize body chunks from base64 using built-in unpack1.
+				# @parameter chunks [Array(String)] Base64 encoded chunks.
+				# @returns [Protocol::HTTP::Body::Buffered] Reconstructed buffered body.
+				def deserialize_body_chunks(chunks)
+					::Protocol::HTTP::Body::Buffered.wrap(
+							chunks.map {|encoded_chunk| encoded_chunk.unpack1("m0")}
+						)
+				end
+				
 				# Create a Protocol::HTTP::Request from the stored request data.
 				# @returns [Protocol::HTTP::Request] The constructed request object.
 				def make_request
@@ -206,7 +215,7 @@ module Async
 				# @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 = deserialize_body_chunks(body) if body
 					headers = build_headers(headers) if headers
 					
 					::Protocol::HTTP::Request.new(
@@ -229,7 +238,7 @@ module Async
 				# @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 = deserialize_body_chunks(body) if body
 					headers = build_headers(headers) if headers
 					
 					::Protocol::HTTP::Response.new(

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

@@ -27,6 +27,10 @@ module Async
 					@response_body = nil
 					@error = nil
 					@clock = Async::Clock.start
+					
+					# Will capture body as_json data at completion time for accurate state:
+					@debug_request_body = nil
+					@debug_response_body = nil
 				end
 				
 				# Mark the request as ready (no body to process).
@@ -55,6 +59,9 @@ module Async
 					@request_complete = true
 					@request_body = body
 					
+					# Capture as_json at completion time for accurate stateful information:
+					@debug_request_body = @original_request.body&.as_json
+					
 					if error
 						@error = capture_error_context(error, :request_body)
 					end
@@ -69,6 +76,9 @@ module Async
 					@response_complete = true
 					@response_body = body
 					
+					# Capture as_json at completion time for accurate stateful information:
+					@debug_response_body = @original_response&.body&.as_json
+					
 					if error
 						@error = capture_error_context(error, :response_body)
 					end
@@ -130,6 +140,11 @@ module Async
 					interaction_data = {}
 					interaction_data[:error] = @error if @error
 					
+					# Add as_json data for debugging (captured at completion time):
+					interaction_data[:debug] = {}
+					interaction_data[:debug][:request_body] = @debug_request_body if @debug_request_body
+					interaction_data[:debug][:response_body] = @debug_response_body if @debug_response_body
+					
 					interaction = Interaction.new(
 						interaction_data,
 						request: final_request,

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

@@ -16,7 +16,7 @@ module Async
 			# 
 			# 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
+			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.
@@ -76,10 +76,13 @@ module Async
 					
 					# Wrap with completion callback:
 					::Protocol::HTTP::Body::Completable.wrap(request) do |error|
+						# Always capture whatever body data we have, even if there was an error
+						captured_body = rewindable_body.buffered rescue nil
+						
 						if error
-							tracker.request_completed(error: error)
+							tracker.request_completed(body: captured_body, error: error)
 						else
-							tracker.request_completed(body: rewindable_body.buffered)
+							tracker.request_completed(body: captured_body)
 						end
 					end
 					
@@ -102,10 +105,13 @@ module Async
 					
 					# Wrap with completion callback:
 					::Protocol::HTTP::Body::Completable.wrap(response) do |error|
+						# Always capture whatever body data we have, even if there was an error
+						captured_body = rewindable_body.buffered rescue nil
+						
 						if error
-							tracker.response_completed(error: error)
+							tracker.response_completed(body: captured_body, error: error)
 						else
-							tracker.response_completed(body: rewindable_body.buffered)
+							tracker.response_completed(body: captured_body)
 						end
 					end
 					

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

@@ -6,7 +6,7 @@
 module Async
 	module HTTP
 		module Capture
-			VERSION = "0.1.0"
+			VERSION = "0.2.0"
 		end
 	end
 end

data/lib/async/http/capture.rb

@@ -10,6 +10,7 @@ require_relative "capture/cassette_store"
 require_relative "capture/console_store"
 require_relative "capture/interaction_tracker"
 require_relative "capture/middleware"
+require_relative "capture/environment"
 
 # @namespace
 module Async

data/readme.md

@@ -1,13 +1,13 @@
 # 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.
+A Ruby gem for recording and replaying HTTP requests using `Protocol::HTTP`. Features timestamped 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
+  - **Timestamped Storage**: Each interaction saved as separate JSON file with timestamp
   - **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`
@@ -19,12 +19,14 @@ Please see the [project documentation](https://socketry.github.io/async-http-cap
 
   - [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.
 
+  - [Falcon Integration](https://socketry.github.io/async-http-capture/guides/falcon-integration/index) - This guide explains how to integrate `async-http-capture` with Falcon web server for recording and replaying HTTP interactions.
+
 ### Basic Recording to Files
 
 ``` ruby
 require "async/http/capture"
 
-# Create a store that saves to content-addressed files:
+# Create a store that saves to timestamped files:
 store = Async::HTTP::Capture::CassetteStore.new("interactions")
 
 # Create middleware:
@@ -84,27 +86,26 @@ response = middleware.call(request)
   - **Stores**: Handle serialization, filtering, persistence, or logging
   - **Interaction**: Simple data container with lazy Protocol::HTTP object construction
 
-## Content-Addressed Storage
+## Timestamped Storage
 
-Each interaction is saved to a file named by its content hash:
+Each interaction is saved to a file named with timestamp, process ID, and object ID:
 
-    interactions/
-    ├── a1b2c3d4e5f67890.json  # GET /users
-    ├── f67890a1b2c3d4e5.json  # POST /orders  
-    └── 1234567890abcdef.json  # GET /health
+    recordings/
+    ├── 20250821-105406-271633-12345-67890.json  # GET /users
+    ├── 20250821-105006-257022-12346-67891.json  # POST /orders
+    └── 20250820-101234-567890-12347-67892.json  # GET /health
 
 Benefits:
 
-  - **Automatic de-duplication**: Identical interactions → same filename
+  - **Chronological ordering**: Files sorted by timestamp
   - **Parallel-safe**: Multiple processes can write without conflicts
-  - **Content integrity**: Hash verifies file contents
-  - **Git-friendly**: Stable filenames for version control
+  - **Human-readable**: Timestamps are easy to understand
 
 ## Store Implementations
 
 ### CassetteStore
 
-Saves interactions to content-addressed JSON files in a directory.
+Saves interactions to timestamped JSON files in a directory.
 
 ### ConsoleStore
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-http-capture
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -23,10 +23,25 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.90'
+- !ruby/object:Gem::Dependency
+  name: protocol-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.53.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.53.0
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- context/falcon-integration.md
 - context/getting-started.md
 - context/index.yaml
 - design.md
@@ -34,6 +49,7 @@ files:
 - lib/async/http/capture/cassette.rb
 - lib/async/http/capture/cassette_store.rb
 - lib/async/http/capture/console_store.rb
+- lib/async/http/capture/environment.rb
 - lib/async/http/capture/interaction.rb
 - lib/async/http/capture/interaction_tracker.rb
 - lib/async/http/capture/middleware.rb