async-http-cache 0.4.5 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ef0cd31192b81f8fc4acfefdb378d2ae673ec004b572555e1c1298a0afa5ba6
-  data.tar.gz: 554b926efed070b44a672c2e422cf7be1aa243cd619ab4260210d468321ff044
+  metadata.gz: 7ae1d78b87d12a34eb5217c0cf6a49d6ecd81c5322790d563568a48e951733fe
+  data.tar.gz: 44a915c95e0eced20d783f702179b701c1ba07678bc62e3201d8adce1b5d204c
 SHA512:
-  metadata.gz: f8e688e64d6cf8e734f80ef3cf1422de4b5ae89055d926b047c80d39ef2c23c70a5e085082e86a70fa09d912767505fc2bcaed1d837c3c3c1ce50a45efd3cc7e
-  data.tar.gz: 3e702d6db9c8764fd0d2932ba9bc3a27aafc76b001380f2dee77fcc4ceae350044593d36cb3661b945bda78f47bb951db43fa6b99d7fab5e51732a50d3cc3e18
+  metadata.gz: b2faf1e2713d8f273e9b938b6dfd01ece309533a8b96173306fc93c1cd02ca84305eada3dc99967d27605f6fca369bef6c57a745361882243a6e519a32987c48
+  data.tar.gz: ec998fd4509ec25c908c176ce894904eb7e3515073b7a750e56ac47022d6c336c4d6d0437ee2be1e9fa3bdc5c7f53868028a4dd82395691e2fc15d5e72437786

data/context/getting-started.md

@@ -0,0 +1,80 @@
+# Getting Started
+
+This guide explains how to get started with `async-http-cache`, a cache middleware for `Async::HTTP` clients and servers.
+
+## Installation
+
+Add the gem to your project:
+
+```bash
+$ bundle add async-http-cache
+```
+
+## Core Concepts
+
+`async-http-cache` has several core concepts:
+
+- A {Async::HTTP::Cache::General} which represents the main cache middleware that implements a general shared cache according to RFC 9111.
+- A cache store system that handles the actual storage and retrieval of cached responses.
+- Cache-aware request and response handling that respects HTTP caching headers.
+
+## Usage
+
+The cache middleware can be used with both `Async::HTTP` clients and servers to provide transparent HTTP caching.
+
+### Client Side Caching
+
+Here's how to use the cache with an HTTP client:
+
+```ruby
+require "async"
+require "async/http"
+require "async/http/cache"
+
+endpoint = Async::HTTP::Endpoint.parse("https://www.oriontransfer.co.nz")
+client = Async::HTTP::Client.new(endpoint)
+cache = Async::HTTP::Cache::General.new(client)
+
+Async do
+	2.times do
+		response = cache.get("/products/index")
+		puts response.inspect
+		# <Async::HTTP::Protocol::HTTP2::Response ...>
+		# <Async::HTTP::Cache::Response ...>
+		response.finish
+	end
+ensure
+	cache.close
+end
+```
+
+In this example:
+
+1. We create an HTTP client as usual
+2. We wrap it with `Async::HTTP::Cache::General` to add caching capability
+3. The first request will hit the remote server
+4. The second identical request will be served from the cache (if the response is cacheable)
+
+### Caching Behavior
+
+The cache middleware automatically handles:
+
+- **Cacheable Methods**: Only `GET` and `HEAD` requests are cached
+- **Cache Headers**: Respects `Cache-Control`, `Expires`, and other standard HTTP caching headers
+- **Response Codes**: Only certain response codes (200, 203, 300, 301, 302, 404, 410) are cached
+- **Request Validation**: Requests with authorization headers, cookies, or request bodies are not cached
+
+### Important Notes on Vary Header
+
+The `vary` header creates a headache for proxy implementations, because it creates a combinatorial explosion of cache keys, even if the content is the same. Try to avoid it unless absolutely necessary.
+
+## Custom Cache Stores
+
+By default, the cache uses an in-memory store, but you can provide custom storage backends:
+
+```ruby
+# Use a custom store
+cache = Async::HTTP::Cache::General.new(client, store: MyCustomStore.new)
+```
+
+The store must implement the interface defined by {Async::HTTP::Cache::Store}.

data/context/index.yaml

@@ -0,0 +1,12 @@
+# 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: Standard-compliant cache for async-http.
+metadata:
+  documentation_uri: https://socketry.github.io/async-http-cache/
+  source_code_uri: https://github.com/socketry/async-http-cache.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to get started with `async-http-cache`, a cache
+    middleware for `Async::HTTP` clients and servers.

data/lib/async/http/cache/body.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 require "protocol/http/body/rewindable"
 require "protocol/http/body/completable"
@@ -13,10 +13,17 @@ require "console/event/failure"
 module Async
 	module HTTP
 		module Cache
+			# Provides utilities for wrapping HTTP response bodies with caching capabilities.
 			module Body
 				TRAILER = "trailer"
 				ETAG = "etag"
 				
+				# Wrap a response body with caching functionality, including ETag generation and completion handling.
+				# @parameter response [Protocol::HTTP::Response] The HTTP response to wrap.
+				# @yields {|response, body| ...} The block to execute when caching is complete.
+				#   @parameter response [Protocol::HTTP::Response] The wrapped response.
+				#   @parameter body [Protocol::HTTP::Body::Buffered, nil] The buffered response body.
+				# @returns [Protocol::HTTP::Response] The original response, potentially with modified headers.
 				def self.wrap(response, &block)
 					if body = response.body
 						if body.empty?
@@ -27,13 +34,13 @@ module Async
 							rewindable = ::Protocol::HTTP::Body::Rewindable.wrap(response)
 							
 							unless response.headers.include?(ETAG)
+								# Add the etag header to the trailers:
+								response.headers.add(TRAILER, ETAG)
+								
 								# Compute a digest and add it to the response headers:
 								::Protocol::HTTP::Body::Digestable.wrap(response) do |wrapper|
 									response.headers.add(ETAG, wrapper.etag)
 								end
-								
-								# Ensure the etag is listed as a trailer:
-								response.headers.add(TRAILER, ETAG)
 							end
 							
 							# Wrap the response with the callback:

data/lib/async/http/cache/general.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 # Copyright, 2022, by Colin Kelley.
 
 require "set"
@@ -37,6 +37,9 @@ module Async
 					410 => true  # Gone
 				}.freeze
 				
+				# Initialize a new cache middleware instance.
+				# @parameter app [Object] The downstream application or middleware.
+				# @parameter store [Store] The cache store to use for persistence.
 				def initialize(app, store: Store.default)
 					super(app)
 					
@@ -48,18 +51,25 @@ module Async
 				attr :count
 				attr :store
 				
+				# Close the cache and clean up resources.
 				def close
 					@store.close
 				ensure
 					super
 				end
 				
+				# Generate a cache key for the given request.
+				# @parameter request [Protocol::HTTP::Request] The HTTP request.
+				# @returns [Array] A cache key array containing authority, method, and path.
 				def key(request)
 					@store.normalize(request)
 					
 					[request.authority, request.method, request.path]
 				end
 				
+				# Determine if a request is cacheable based on method, headers, and body.
+				# @parameter request [Protocol::HTTP::Request] The HTTP request to check.
+				# @returns [Boolean] True if the request can be cached.
 				def cacheable_request?(request)
 					# We don't support caching requests which have a request body:
 					if request.body
@@ -88,6 +98,9 @@ module Async
 					return true
 				end
 				
+				# Check if response headers allow caching.
+				# @parameter headers [Protocol::HTTP::Headers] The response headers to check.
+				# @returns [Boolean] True if headers permit caching.
 				def cacheable_response_headers?(headers)
 					if cache_control = headers[CACHE_CONTROL]
 						if cache_control.no_store? || cache_control.private?
@@ -100,10 +113,13 @@ module Async
 						Console.logger.debug(self) {"Cannot cache response with set-cookie header!"}
 						return false
 					end
-								
+					
 					return true
 				end
 				
+				# Determine if a response is cacheable based on status code and headers.
+				# @parameter response [Protocol::HTTP::Response] The HTTP response to check.
+				# @returns [Boolean] True if the response can be cached.
 				def cacheable_response?(response)
 					# At this point, we know response.status and response.headers.
 					# But we don't know response.body or response.headers.trailer.
@@ -162,6 +178,9 @@ module Async
 					end
 				end
 				
+				# Process an HTTP request, checking cache first and storing responses when appropriate.
+				# @parameter request [Protocol::HTTP::Request] The HTTP request to process.
+				# @returns [Protocol::HTTP::Response] Either a cached response or a fresh response from upstream.
 				def call(request)
 					cache_control = request.headers[CACHE_CONTROL]
 					

data/lib/async/http/cache/response.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 require "protocol/http/response"
 require "async/clock"
@@ -9,12 +9,16 @@ require "async/clock"
 module Async
 	module HTTP
 		module Cache
+			# Represents a cached HTTP response with cache-specific metadata and functionality.
 			class Response < ::Protocol::HTTP::Response
 				CACHE_CONTROL = "cache-control"
 				ETAG = "etag"
 				
 				X_CACHE = "x-cache"
 				
+				# Initialize a new cached response.
+				# @parameter response [Protocol::HTTP::Response] The original HTTP response.
+				# @parameter body [Protocol::HTTP::Body] The response body.
 				def initialize(response, body)
 					@generated_at = Async::Clock.now
 					
@@ -34,20 +38,28 @@ module Async
 				
 				attr :generated_at
 				
+				# Get the ETag header value for this cached response.
+				# @returns [String, nil] The ETag value or nil if not present.
 				def etag
 					@etag ||= @headers[ETAG]
 				end
 				
+				# Calculate the age of this cached response in seconds.
+				# @returns [Float] The number of seconds since the response was generated.
 				def age
 					Async::Clock.now - @generated_at
 				end
 				
+				# Check if this cached response has expired based on its max-age.
+				# @returns [Boolean, nil] True if expired, false if still valid, nil if no max-age set.
 				def expired?
 					if @max_age
 						self.age > @max_age
 					end
 				end
 				
+				# Create a duplicate of this cached response with independent body and headers.
+				# @returns [Response] A new Response instance with duplicated body and headers.
 				def dup
 					dup = super
 					

data/lib/async/http/cache/store/memory.rb

@@ -1,13 +1,18 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 module Async
 	module HTTP
 		module Cache
 			module Store
+				# Represents an in-memory cache store with automatic pruning of expired entries.
 				class Memory
+					# Initialize a new in-memory cache store.
+					# @parameter limit [Integer] Maximum number of entries to store.
+					# @parameter maximum_size [Integer] Maximum size in bytes for individual cached responses.
+					# @parameter prune_interval [Integer] Interval in seconds between automatic pruning operations.
 					def initialize(limit: 1024, maximum_size: 1024*64, prune_interval: 60)
 						@index = {}
 						@limit = limit
@@ -42,6 +47,7 @@ module Async
 						end
 					end
 					
+					# Close the cache store and stop background pruning.
 					def close
 						@gardener.stop
 					end
@@ -51,6 +57,10 @@ module Async
 					IF_NONE_MATCH = "if-none-match"
 					NOT_MODIFIED = ::Protocol::HTTP::Response[304]
 					
+					# Look up a cached response for the given key and request.
+					# @parameter key [Array] The cache key to look up.
+					# @parameter request [Protocol::HTTP::Request] The HTTP request.
+					# @returns [Protocol::HTTP::Response, nil] The cached response or nil if not found/expired.
 					def lookup(key, request)
 						if response = @index[key]
 							if response.expired?
@@ -77,6 +87,10 @@ module Async
 						end
 					end
 					
+					# Insert a response into the cache if it meets size and limit constraints.
+					# @parameter key [Array] The cache key.
+					# @parameter request [Protocol::HTTP::Request] The HTTP request.
+					# @parameter response [Protocol::HTTP::Response] The HTTP response to cache.
 					def insert(key, request, response)
 						if @index.size < @limit
 							length = response.body&.length

data/lib/async/http/cache/store/vary.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 module Async
 	module HTTP
@@ -10,18 +10,25 @@ module Async
 				VARY = "vary"
 				ACCEPT_ENCODING = "accept-encoding"
 				
+				# Represents a cache store wrapper that handles HTTP Vary header functionality.
 				class Vary
+					# Initialize a new Vary store wrapper.
+					# @parameter delegate [Store] The underlying cache store to delegate to.
+					# @parameter vary [Hash] Initial vary header mappings.
 					def initialize(delegate, vary = {})
 						@delegate = delegate
 						@vary = vary
 					end
 					
+					# Close the vary store and its delegate.
 					def close
 						@delegate.close
 					end
 					
 					attr :delegate
 					
+					# Normalize request headers to reduce cache key variations.
+					# @parameter request [Protocol::HTTP::Request] The HTTP request to normalize.
 					def normalize(request)
 						if accept_encoding = request.headers[ACCEPT_ENCODING]
 							if accept_encoding.include?("gzip")
@@ -32,10 +39,18 @@ module Async
 						end
 					end
 					
+					# Generate vary-specific key components from request headers.
+					# @parameter headers [Protocol::HTTP::Headers] The request headers.
+					# @parameter vary [Array] Array of header names that affect caching.
+					# @returns [Array] Array of header values for the vary keys.
 					def key_for(headers, vary)
 						vary.map{|key| headers[key]}
 					end
 					
+					# Look up a cached response, accounting for vary headers.
+					# @parameter key [Array] The base cache key.
+					# @parameter request [Protocol::HTTP::Request] The HTTP request.
+					# @returns [Protocol::HTTP::Response, nil] The cached response or nil if not found.
 					def lookup(key, request)
 						if vary = @vary[key]
 							# We should provide user-supported normalization here:
@@ -45,6 +60,10 @@ module Async
 						return @delegate.lookup(key, request)
 					end
 					
+					# Insert a response into the cache, handling vary headers appropriately.
+					# @parameter key [Array] The base cache key.
+					# @parameter request [Protocol::HTTP::Request] The HTTP request.
+					# @parameter response [Protocol::HTTP::Response] The HTTP response to cache.
 					def insert(key, request, response)
 						if vary = response.headers[VARY]&.sort
 							@vary[key] = vary

data/lib/async/http/cache/store.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 require_relative "store/memory"
 require_relative "store/vary"
@@ -9,7 +9,10 @@ require_relative "store/vary"
 module Async
 	module HTTP
 		module Cache
+			# Provides cache storage implementations and utilities.
 			module Store
+				# Create a default cache store with Vary support over an in-memory store.
+				# @returns [Store::Vary] A default cache store instance.
 				def self.default
 					Vary.new(Memory.new)
 				end

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

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
+# @namespace
 module Async
+	# @namespace
 	module HTTP
+		# @namespace
 		module Cache
-			VERSION = "0.4.5"
+			VERSION = "0.4.6"
 		end
 	end
 end

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2020-2024, by Samuel Williams.  
+Copyright, 2020-2025, by Samuel Williams.  
 Copyright, 2021, by Olle Jonsson.  
 Copyright, 2022, by Colin Kelley.  
 

data/readme.md

@@ -6,33 +6,64 @@ Provides a cache middleware for `Async::HTTP` clients and servers.
 
 ## Usage
 
-### Client Side
-
-``` ruby
-require 'async'
-require 'async/http'
-require 'async/http/cache'
-
-endpoint = Async::HTTP::Endpoint.parse("https://www.oriontransfer.co.nz")
-client = Async::HTTP::Client.new(endpoint)
-cache = Async::HTTP::Cache::General.new(client)
-
-Async do
-	2.times do
-		response = cache.get("/products/index")
-		puts response.inspect
-		# <Async::HTTP::Protocol::HTTP2::Response ...>
-		# <Async::HTTP::Cache::Response ...>
-		response.finish
-	end
-ensure
-	cache.close
-end
-```
-
-## Vary
-
-The `vary` header creates a headache for proxy implementations, because it creates a combinatorial explosion of cache keys, even if the content is the same. Try to avoid it unless absolutely necessary.
+Please see the [project documentation](https://socketry.github.io/async-http-cache/) for more details.
+
+  - [Getting Started](https://socketry.github.io/async-http-cache/guides/getting-started/index) - This guide explains how to get started with `async-http-cache`, a cache middleware for `Async::HTTP` clients and servers.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/async-http-cache/releases/index) for all releases.
+
+### v0.4.6
+
+  - Improved documentation and agent context.
+
+### v0.4.5
+
+  - Modernized gem structure and dependencies.
+
+### v0.4.4
+
+  - Modernized gem structure and test suite.
+  - Added reference to RFC 9111 in documentation.
+  - Improved cache-ability checks by moving response validation to `General` class.
+
+### v0.4.3
+
+  - Improved `Memory` store with configurable limits and pruning intervals.
+  - Enhanced cache-control header handling for `no-store` and `private` directives.
+  - Fixed spelling of `cacheable?` method (was `cachable?`).
+  - Optimized cacheable response code checks using hash table lookup.
+  - Added external test suite for validation.
+
+### v0.4.2
+
+  - Improved memory cache gardener task to be transient with proper annotations.
+
+### v0.4.1
+
+  - Updated to use `Console.logger` for consistent logging.
+  - Modernized gem structure.
+
+### v0.4.0
+
+  - **Breaking**: Renamed `trailers` to `trailer` for consistency with HTTP specifications.
+  - Updated dependency on `async-http`.
+
+### v0.3.0
+
+  - Updated dependencies to latest versions.
+
+### v0.2.0
+
+  - Added support for ETag validation with `if-none-match` header handling.
+  - Improved streaming response handling with trailing ETag generation.
+  - Enhanced trailer support for body digest calculation.
+  - Removed support for end-of-life Ruby versions.
+
+### v0.1.5
+
+  - Fixed handling of responses with `nil` body length to prevent caching errors.
 
 ## Contributing
 

data/releases.md

@@ -0,0 +1,81 @@
+# Releases
+
+## v0.4.6
+
+  - Improved documentation and agent context.
+
+## v0.4.5
+
+  - Modernized gem structure and dependencies.
+
+## v0.4.4
+
+  - Modernized gem structure and test suite.
+  - Added reference to RFC 9111 in documentation.
+  - Improved cache-ability checks by moving response validation to `General` class.
+
+## v0.4.3
+
+  - Improved `Memory` store with configurable limits and pruning intervals.
+  - Enhanced cache-control header handling for `no-store` and `private` directives.
+  - Fixed spelling of `cacheable?` method (was `cachable?`).
+  - Optimized cacheable response code checks using hash table lookup.
+  - Added external test suite for validation.
+
+## v0.4.2
+
+  - Improved memory cache gardener task to be transient with proper annotations.
+
+## v0.4.1
+
+  - Updated to use `Console.logger` for consistent logging.
+  - Modernized gem structure.
+
+## v0.4.0
+
+  - **Breaking**: Renamed `trailers` to `trailer` for consistency with HTTP specifications.
+  - Updated dependency on `async-http`.
+
+## v0.3.0
+
+  - Updated dependencies to latest versions.
+
+## v0.2.0
+
+  - Added support for ETag validation with `if-none-match` header handling.
+  - Improved streaming response handling with trailing ETag generation.
+  - Enhanced trailer support for body digest calculation.
+  - Removed support for end-of-life Ruby versions.
+
+## v0.1.5
+
+  - Fixed handling of responses with `nil` body length to prevent caching errors.
+
+## v0.1.4
+
+  - Fixed caching behavior for `HEAD` requests to handle empty bodies correctly.
+
+## v0.1.3
+
+  - Updated dependencies.
+
+## v0.1.2
+
+  - Improved handling of malformed or missing `cache-control` headers.
+
+## v0.1.1
+
+  - Added automatic cache pruning with background gardener task.
+  - Improved `vary` header handling with better key generation.
+  - Enhanced request `cache-control` header checking.
+  - Added detailed cache statistics logging.
+  - Improved error logging for response failures.
+
+## v0.1.0
+
+  - Initial release with HTTP caching middleware.
+  - Support for `GET` and `HEAD` request caching.
+  - In-memory cache store with configurable limits.
+  - Vary header support for content negotiation.
+  - Cache-control directive compliance.
+  - Response validation based on status codes and headers.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-http-cache
 version: !ruby/object:Gem::Version
-  version: 0.4.5
+  version: 0.4.6
 platform: ruby
 authors:
 - Samuel Williams
@@ -38,7 +38,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-03-04 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-http
@@ -58,6 +58,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- context/getting-started.md
+- context/index.yaml
 - lib/async/http/cache.rb
 - lib/async/http/cache/body.rb
 - lib/async/http/cache/general.rb
@@ -68,10 +70,12 @@ files:
 - lib/async/http/cache/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/async-http-cache
 licenses:
 - MIT
 metadata:
+  documentation_uri: https://socketry.github.io/async-http-cache/
   source_code_uri: https://github.com/socketry/async-http-cache.git
 rdoc_options: []
 require_paths:
@@ -80,14 +84,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.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Standard-compliant cache for async-http.
 test_files: []