protocol-rack 0.17.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbf78ac425bc2df269ede6fc0f60d0d674f11d0e6d3fe5dc07f8c766d534bedb
-  data.tar.gz: e348d48975f98d10401e7198a7a0317483c5b2b42641a78e46e771623c804a8b
+  metadata.gz: 4fed6d6b2ffc0dc007d343e8f9414af4c61cd7c321cb289b6d218290977feb7f
+  data.tar.gz: d02dd7e216b58d3bbe94e5e99b4c71d689ad8de5cb7451a67a81bcd0ade5a55a
 SHA512:
-  metadata.gz: f3d717f59f06f4348fc44eba9b650cd8e99ca29ce731f5b2265e835fb95e71e1abaee47a65689903e6de48c23d1bace99c145405ad5a70de7054e2399ed202ce
-  data.tar.gz: b3fa66486f434892b3d076457d3a762fbbe1d76923c46c91e18466b00415767bded9625d13dd52cb88899b0d978915c9e3fb5c5926168ace1b1d4074d570e24e
+  metadata.gz: df29bd96d8542e75e146d0eec4d7813f7e037fdd84e68bd08ac1f6a4cfca66b3ec176dd3167e31eedb3ae849b44059c23b0fe57a4aea8b4a2c3f55c90755b36f
+  data.tar.gz: 6969ef3c4a7fb95083dd57697c5bcf0aee57ec1f9eee6f0b4233af56e4845513c21480cee2abc14daf320d5cf7c5c739b50448bc3d3c6023432292a6544d8876

data/context/getting-started.md

@@ -0,0 +1,55 @@
+# Getting Started
+
+This guide explains how to get started with `protocol-rack` and integrate Rack applications with `Protocol::HTTP` servers.
+
+## Installation
+
+Add the gem to your project:
+
+```bash
+$ bundle add protocol-rack
+```
+
+## Core Concepts
+
+`protocol-rack` provides a bridge between two HTTP ecosystems:
+
+- **Rack**: The standard Ruby web server interface used by frameworks like Rails, Sinatra, and Roda.
+- **`Protocol::HTTP`**: A modern, asynchronous HTTP protocol implementation used by servers like Falcon and Async.
+
+The library enables bidirectional integration:
+
+- **Application Adapter**: Run existing Rack applications on `Protocol::HTTP` servers (like Falcon).
+- **Server Adapter**: Run `Protocol::HTTP` applications on Rack-compatible servers (like Puma).
+
+## Usage
+
+The most common use case is running a Rack application on an asynchronous `Protocol::HTTP` server like [falcon](https://github.com/socketry/falcon). This allows you to leverage the performance benefits of async I/O while using your existing Rack-based application code.
+
+### Running a Rack Application
+
+When you have an existing Rack application (like a Rails app, Sinatra app, or any app that follows the Rack specification), you can adapt it to run on `Protocol::HTTP` servers:
+
+```ruby
+require "async"
+require "async/http/server"
+require "async/http/endpoint"
+require "protocol/rack/adapter"
+
+# Your existing Rack application:
+app = proc do |env|
+	[200, {"content-type" => "text/plain"}, ["Hello World"]]
+end
+
+# Create an adapter:
+middleware = Protocol::Rack::Adapter.new(app)
+
+# Run on an async server:
+Async do
+	endpoint = Async::HTTP::Endpoint.parse("http://localhost:9292")
+	server = Async::HTTP::Server.new(middleware, endpoint)
+	server.run
+end
+```
+
+The adapter automatically detects your Rack version (v2, v3, or v3.1+) and uses the appropriate implementation, ensuring compatibility without any configuration.

data/context/index.yaml

@@ -0,0 +1,16 @@
+# 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: An implementation of the Rack protocol/specification.
+metadata:
+  documentation_uri: https://socketry.github.io/protocol-rack/
+  source_code_uri: https://github.com/socketry/protocol-rack.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to get started with `protocol-rack` and integrate
+    Rack applications with `Protocol::HTTP` servers.
+- path: request-response.md
+  title: Request and Response Handling
+  description: This guide explains how to work with requests and responses when bridging
+    between Rack and `Protocol::HTTP`, covering advanced use cases and edge cases.

data/context/request-response.md

@@ -0,0 +1,253 @@
+# Request and Response Handling
+
+This guide explains how to work with requests and responses when bridging between Rack and `Protocol::HTTP`, covering advanced use cases and edge cases.
+
+## Request Conversion
+
+The {ruby Protocol::Rack::Request} class converts Rack environment hashes into rich `Protocol::HTTP` request objects, providing access to modern HTTP features while maintaining compatibility with Rack.
+
+### Basic Request Access
+
+```ruby
+require "protocol/rack/request"
+
+run do |env|
+	request = Protocol::Rack::Request[env]
+	
+	# Access request properties:
+	puts request.method         # "GET", "POST", etc.
+	puts request.path           # "/users/123"
+	puts request.url_scheme     # "http" or "https"
+	puts request.authority      # "example.com:80"
+end
+```
+
+### Headers
+
+Headers are automatically extracted from Rack's `HTTP_*` environment variables:
+
+```ruby
+run do |env|
+	request = Protocol::Rack::Request[env]
+	
+	# Headers are available as a `Protocol::HTTP::Headers` object:
+	user_agent = request.headers["user-agent"]
+	content_type = request.headers["content-type"]
+	
+	# Headers are case-insensitive:
+	user_agent = request.headers["User-Agent"]  # Same as above
+end
+```
+
+The adapter converts Rack's `HTTP_ACCEPT_ENCODING` format to standard HTTP header names (`accept-encoding`).
+
+### Request Body
+
+The request body is wrapped in a `Protocol::HTTP`-compatible interface:
+
+```ruby
+run do |env|
+	request = Protocol::Rack::Request[env]
+	
+	# Read the entire body:
+	body = request.body.read
+	
+	# Or stream it:
+	request.body.each do |chunk|
+		process_chunk(chunk)
+	end
+	
+	# The body supports rewind if the underlying Rack input supports it:
+	request.body.rewind
+end
+```
+
+The body wrapper handles Rack's `rack.input` interface, which may or may not support `rewind` depending on the server.
+
+### Query Parameters
+
+Query parameters are parsed from the request path:
+
+```ruby
+run do |env|
+	request = Protocol::Rack::Request[env]
+	
+	# Access query string:
+	query = request.query  # "name=value&other=123"
+	
+	# Parse query parameters (if using a helper):
+	params = URI.decode_www_form(query).to_h
+end
+```
+
+### Protocol Upgrades
+
+The adapter handles protocol upgrade requests (like WebSockets):
+
+```ruby
+run do |env|
+	request = Protocol::Rack::Request[env]
+	
+	# Check for upgrade protocols:
+	if protocols = request.protocol
+		# protocols is an array: ["websocket"]:
+		if protocols.include?("websocket")
+			# Handle WebSocket upgrade.
+		end
+	end
+end
+```
+
+Protocols are extracted from either `rack.protocol` or the `HTTP_UPGRADE` header.
+
+## Response Conversion
+
+The {ruby Protocol::Rack::Response} class and {ruby Protocol::Rack::Adapter.make_response} handle converting `Protocol::HTTP` responses back to Rack format.
+
+### Basic Response
+
+```ruby
+require "protocol/rack/adapter"
+
+run do |env|
+	request = Protocol::Rack::Request[env]
+	
+	# Create a `Protocol::HTTP` response:
+	response = Protocol::HTTP::Response[
+		200,
+		{"content-type" => "text/html"},
+		["<h1>Hello</h1>"]
+	]
+	
+	# Convert to Rack format:
+	Protocol::Rack::Adapter.make_response(env, response)
+end
+```
+
+### Response Bodies
+
+The adapter handles different types of response bodies:
+
+#### Enumerable Bodies
+
+```ruby
+# Array bodies:
+response = Protocol::HTTP::Response[
+	200,
+	{"content-type" => "text/plain"},
+	["Hello", " ", "World"]
+]
+
+# Enumerable bodies:
+response = Protocol::HTTP::Response[
+	200,
+	{"content-type" => "text/plain"},
+	Enumerator.new do |yielder|
+		yielder << "Chunk 1\n"
+		yielder << "Chunk 2\n"
+	end
+]
+```
+
+#### Streaming Bodies
+
+```ruby
+# Streaming response body:
+body = Protocol::HTTP::Body::Buffered.new(["Streaming content"])
+
+response = Protocol::HTTP::Response[
+	200,
+	{"content-type" => "text/plain"},
+	body
+]
+```
+
+#### File Bodies
+
+```ruby
+# File-based responses:
+body = Protocol::HTTP::Body::File.open("path/to/file.txt")
+
+response = Protocol::HTTP::Response[
+	200,
+	{"content-type" => "text/plain"},
+	body
+]
+```
+
+### HEAD Requests
+
+The adapter automatically handles HEAD requests by removing response bodies:
+
+```ruby
+run do |env|
+	request = Protocol::Rack::Request[env]
+	
+	# Create a response with a body:
+	response = Protocol::HTTP::Response[
+		200,
+		{"content-type" => "text/html"},
+		["<h1>Full Response</h1>"]
+	]
+	
+	# For HEAD requests, the body is automatically removed:
+	Protocol::Rack::Adapter.make_response(env, response)
+end
+```
+
+### Status Codes Without Bodies
+
+Certain status codes (204 No Content, 205 Reset Content, 304 Not Modified) should not include response bodies. The adapter handles this automatically:
+
+```ruby
+response = Protocol::HTTP::Response[
+	204,  # No Content
+	{},
+	["This body will be removed"]
+]
+
+# The adapter automatically removes the body for 204 responses.
+```
+
+### Rack-Specific Features
+
+#### Hijacking
+
+Rack supports response hijacking, which allows taking over the connection:
+
+```ruby
+# In a Rack application:
+[200, {"rack.hijack" => proc{|io| io.write("Hijacked!")}}, []]
+
+# The adapter handles hijacking automatically using streaming responses.
+```
+
+#### Response Finished Callbacks
+
+Rack 2+ supports `rack.response_finished` callbacks:
+
+```ruby
+env["rack.response_finished"] ||= []
+env["rack.response_finished"] << proc do |env, status, headers, error|
+	# Cleanup or logging after response is sent
+	puts "Response finished: #{status}"
+end
+```
+
+The adapter invokes these callbacks in reverse order of registration, as specified by the Rack specification.
+
+### Hop Headers
+
+HTTP hop-by-hop headers (like `Connection`, `Transfer-Encoding`) are automatically removed from responses, as they should not be forwarded through proxies:
+
+```ruby
+response = Protocol::HTTP::Response[
+	200,
+	{
+		"content-type" => "text/plain",
+		"connection" => "close",          # This will be removed
+		"transfer-encoding" => "chunked"  # This will be removed
+	},
+	["Body"]
+]
+```

data/lib/protocol/rack/adapter/generic.rb

@@ -135,6 +135,38 @@ module Protocol
 					}
 				end
 				
+				# Handle errors that occur during request processing. Logs the error, closes any response body, invokes `rack.response_finished` callbacks, and returns an appropriate failure response.
+				# 
+				# The `rack.response_finished` callbacks are invoked in reverse order of registration, as specified by the Rack specification. If a callback raises an exception, it is caught and logged, but does not prevent other callbacks from being invoked.
+				# 
+				# @parameter env [Hash] The Rack environment hash.
+				# @parameter status [Integer | Nil] The HTTP status code, if available. May be `nil` if the error occurred before the application returned a response.
+				# @parameter headers [Hash | Nil] The response headers, if available. May be `nil` if the error occurred before the application returned a response.
+				# @parameter body [Object | Nil] The response body, if available. May be `nil` if the error occurred before the application returned a response.
+				# @parameter error [Exception] The exception that occurred during request processing.
+				# @returns [Protocol::HTTP::Response] A failure response representing the error.
+				def handle_error(env, status, headers, body, error)
+					Console.error(self, "Error occurred during request processing:", error)
+					
+					# Close the response body if it exists and supports closing.
+					body&.close if body.respond_to?(:close)
+					
+					# Invoke `rack.response_finished` callbacks in reverse order of registration.
+					# This ensures that callbacks registered later are invoked first, matching the Rack specification.
+					env&.[](RACK_RESPONSE_FINISHED)&.reverse_each do |callback|
+						begin
+							callback.call(env, status, headers, error)
+						rescue => callback_error
+							# If a callback raises an exception, log it but continue invoking other callbacks.
+							# The Rack specification states that callbacks should not raise exceptions, but we handle
+							# this gracefully to prevent one misbehaving callback from breaking others.
+							Console.error(self, "Error occurred during response finished callback:", callback_error)
+						end
+					end
+					
+					return failure_response(error)
+				end
+				
 				# Build a rack `env` from the incoming request and apply it to the rack middleware.
 				#
 				# @parameter request [Protocol::HTTP::Request] The incoming request.
@@ -158,16 +190,8 @@ module Protocol
 					headers, meta = self.wrap_headers(headers)
 					
 					return Response.wrap(env, status, headers, meta, body, request)
-				rescue => exception
-					Console.error(self, exception)
-					
-					body&.close if body.respond_to?(:close)
-					
-					env&.[](RACK_RESPONSE_FINISHED)&.each do |callback|
-						callback.call(env, status, headers, exception)
-					end
-					
-					return failure_response(exception)
+				rescue => error
+					return self.handle_error(env, status, headers, body, error)
 				end
 				
 				# Generate a suitable response for the given exception.

data/lib/protocol/rack/adapter/rack2.rb

@@ -111,17 +111,8 @@ module Protocol
 					# end
 					
 					return Response.wrap(env, status, headers, meta, body, request)
-				rescue => exception
-					Console.error(self, exception)
-					
-					body&.close if body.respond_to?(:close)
-					
-					# Rack 2 does not include `rack.response_finished` in the specification. However, if the application has set it, we will call the callbacks here as it would be extremely surprising to not do so.
-					env&.[](RACK_RESPONSE_FINISHED)&.each do |callback|
-						callback.call(env, status, headers, exception)
-					end
-					
-					return failure_response(exception)
+				rescue => error
+					return self.handle_error(env, status, headers, body, error)
 				end
 				
 				# Process the rack response headers into a {Protocol::HTTP::Headers} instance, along with any extra `rack.` metadata.

data/lib/protocol/rack/body.rb

@@ -7,6 +7,7 @@ require_relative "body/streaming"
 require_relative "body/enumerable"
 require_relative "constants"
 
+require "console"
 require "protocol/http/body/completable"
 require "protocol/http/body/head"
 
@@ -103,8 +104,10 @@ module Protocol
 				return body
 			end
 			
-			# Create a completion callback for response finished handlers.
-			# The callback is called with any error that occurred during response processing.
+			# Create a completion callback for response finished handlers. The callback is called with any error that occurred during response processing.
+			# 
+			# Callbacks are invoked in reverse order of registration, as specified by the Rack specification.
+			# If a callback raises an exception, it is caught and logged, but does not prevent other callbacks from being invoked.
 			# 
 			# @parameter response_finished [Array] Array of response finished callbacks.
 			# @parameter env [Hash] The Rack environment.
@@ -113,8 +116,16 @@ module Protocol
 			# @returns [Proc] A callback that calls all response finished handlers.
 			def self.completion_callback(response_finished, env, status, headers)
 				proc do |error|
-					response_finished.each do |callback|
-						callback.call(env, status, headers, error)
+					# Invoke callbacks in reverse order of registration, as specified by the Rack specification.
+					response_finished.reverse_each do |callback|
+						begin
+							callback.call(env, status, headers, error)
+						rescue => callback_error
+							# If a callback raises an exception, log it but continue invoking other callbacks.
+							# The Rack specification states that callbacks should not raise exceptions, but we handle
+							# this gracefully to prevent one misbehaving callback from breaking others.
+							Console.error(self, "Error occurred during response finished callback:", callback_error)
+						end
 					end
 				end
 			end

data/lib/protocol/rack/version.rb

@@ -5,6 +5,6 @@
 
 module Protocol
 	module Rack
-		VERSION = "0.17.0"
+		VERSION = "0.18.0"
 	end
 end

data/readme.md

@@ -13,6 +13,10 @@ Provides abstractions for working with the Rack specification on top of [`Protoc
 
 Please see the [project documentation](https://socketry.github.io/protocol-rack/) for more details.
 
+  - [Getting Started](https://socketry.github.io/protocol-rack/guides/getting-started/index) - This guide explains how to get started with `protocol-rack` and integrate Rack applications with `Protocol::HTTP` servers.
+
+  - [Request and Response Handling](https://socketry.github.io/protocol-rack/guides/request-response/index) - This guide explains how to work with requests and responses when bridging between Rack and `Protocol::HTTP`, covering advanced use cases and edge cases.
+
 ### Application Adapter
 
 Given a rack application, you can adapt it for use on `async-http`:
@@ -67,6 +71,11 @@ end
 
 Please see the [project releases](https://socketry.github.io/protocol-rack/releases/index) for all releases.
 
+### v0.18.0
+
+  - Correctly invoke `rack.response_finished` in reverse order.
+  - Tolerate errors during `rack.response_finished` callbacks.
+
 ### v0.17.0
 
   - Support `rack.response_finished` in Rack 2 if it's present in the environment.

data/releases.md

@@ -1,5 +1,10 @@
 # Releases
 
+## v0.18.0
+
+  - Correctly invoke `rack.response_finished` in reverse order.
+  - Tolerate errors during `rack.response_finished` callbacks.
+
 ## v0.17.0
 
   - Support `rack.response_finished` in Rack 2 if it's present in the environment.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-rack
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.18.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -86,6 +86,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- context/getting-started.md
+- context/index.yaml
+- context/request-response.md
 - lib/protocol/rack.rb
 - lib/protocol/rack/adapter.rb
 - lib/protocol/rack/adapter/generic.rb