protocol-http-executor 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 74740e7516b0bed60f7da5365c618fea04a7e19eb0d29d4414bb117a483de0b4
+  data.tar.gz: dae71f98528888d7a4857acf3769a2c677bee5e911f78d8ecd7832039c33bc51
+SHA512:
+  metadata.gz: 8209ce922552055eaff122135e83a851b94a5db805c828f2e2a3972e28670bec04a5dda3da8f516cd7ec99843d2be84cfc07dfab3b3f2ea48fa04950f5ded9c1
+  data.tar.gz: a76a03945495577d6878f1e7a2638211c074cb68954087d89e91f0c32d3483023e84c77adc9a28d0de20905b586aa5f50539bbd64bcd1f90265a38da752de973

data/context/design-overview.md

@@ -0,0 +1,58 @@
+# Design Overview
+
+This guide explains how `protocol-http-executor` preserves HTTP request, response, streaming, error, and trailer semantics across an execution boundary.
+
+## Execution Boundary
+
+Thread and Ractor execution use the same worker and transport protocol. Only the mechanism which creates the isolated execution context differs. Keeping this boundary common allows a future fixed-size pool to dispatch the same per-request transport to an idle worker.
+
+Each request receives two connected Unix socket pairs:
+
+| Channel | Direction | Purpose |
+|---|---|---|
+| Control | Bidirectional | Request and response heads, interim responses, consumption mode, and cancellation. |
+| Body | Bidirectional | Request and upgraded-stream input flows to the worker; response chunks, trailers, and post-head errors flow to the caller. |
+
+Separating control and body traffic prevents control events from being delayed by body frames. The full-duplex body socket allows request input and response output to flow concurrently, while `shutdown(SHUT_WR)` represents the final EOF independently in each direction. Socket buffering provides bounded operating-system backpressure and integrates with the Ruby fiber scheduler.
+
+## Request and Response Phases
+
+``` mermaid
+sequenceDiagram
+	participant Caller
+	participant Worker
+	participant Application
+	Caller->>Worker: Request head
+	par Request input
+		Caller->>Worker: Body chunks, trailers, EOF
+	and Application execution
+		Worker->>Application: Reconstructed request
+		Application-->>Worker: Interim responses
+		Worker-->>Caller: Interim responses
+		Application->>Worker: Response
+	end
+	Worker->>Caller: Response head
+	Caller->>Worker: Read or direct-stream mode
+	Worker->>Caller: Body chunks and trailers
+	Worker-->>Caller: Shutdown write direction
+```
+
+Request and response heads contain their initial header fields only. Trailer fields remain delayed until the corresponding body reaches EOF. Empty bodies are omitted so the application observes a normal `nil` body rather than a synthetic stream.
+
+## Direct Duplex Streaming
+
+A normal response body is consumed by reading chunks. A streamable response body can instead be called with a duplex stream. The caller then forwards data in both directions:
+
+  - The input task completes any initial request body before reading upgraded-stream input.
+  - The worker exposes both phases as one readable stream to the application.
+  - Response output uses the opposite direction of the full-duplex body socket and can progress independently.
+
+The initial request-body boundary remains an explicit event because upgraded-stream input can follow it. Once no more data can follow in a direction, the sender shuts down that socket direction and the receiver observes a normal EOF.
+
+This ordering preserves the HTTP message boundary while still supporting protocols which take over the connection after the response head.
+
+## Errors and Closure
+
+Errors before the response head are reported on the control channel and cause the middleware call to fail. Errors after the response head are reported on the output channel and are raised when the response body is consumed.
+
+Closing an unfinished response closes all transport channels and cancels caller-side forwarding tasks. Transport closure interrupts workers blocked on body IO. Applications which never yield or perform IO remain subject to the lifecycle limitations of their underlying thread or Ractor.

data/context/getting-started.md

@@ -0,0 +1,69 @@
+# Getting Started
+
+This guide explains how to execute `Protocol::HTTP` applications in isolated threads or Ractors.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add protocol-http-executor
+~~~
+
+## Core Concepts
+
+`protocol-http-executor` provides middleware which reconstructs each request inside an isolated execution context and reconstructs the resulting response for the caller.
+
+  - {ruby Protocol::HTTP::Executor::Threaded} creates one native thread per request.
+  - {ruby Protocol::HTTP::Executor::Ractored} creates one Ractor per request using the Ruby head/4.1 Ractor API.
+  - {ruby Protocol::HTTP::Executor::Execution} forwards request and response bodies while preserving HTTP message semantics.
+
+Calls must run inside an Async task. This allows request input, response output, and upgraded duplex streams to make progress concurrently.
+
+## Thread Execution
+
+Use thread execution when an application or one of its dependencies can block the current event-loop thread. The application is shared between worker threads, so it must be thread-safe.
+
+``` ruby
+require "async"
+require "protocol/http/executor"
+
+application = Protocol::HTTP::Middleware::HelloWorld
+executor = Protocol::HTTP::Executor::Threaded.new(application)
+
+begin
+	Sync do
+		request = Protocol::HTTP::Request["GET", "/"]
+		response = executor.call(request)
+		
+		puts response.read
+	end
+ensure
+	executor.close
+end
+```
+
+## Ractor Execution
+
+Use Ractor execution to isolate mutable Ruby objects and enable parallel Ruby execution where the application supports it. The application object must be shareable.
+
+``` ruby
+module Application
+	def self.call(request)
+		Protocol::HTTP::Response[200, body: ["Hello World"]]
+	end
+	
+	def self.close
+	end
+end
+
+executor = Protocol::HTTP::Executor::Ractored.new(Application)
+```
+
+Ractor execution makes the default `Protocol::HTTP::Headers` policy shareable before creating workers. Custom application state and dependencies must independently satisfy Ractor isolation requirements.
+
+## Streaming and Trailers
+
+Non-empty request and response bodies are forwarded one chunk at a time. Trailer fields are forwarded after the last body chunk and applied to the receiving headers before EOF is returned.
+
+When a response body reports `stream?`, calling its `call(stream)` method enables direct duplex forwarding. Initial request-body chunks are delivered first, followed by upgraded-stream input.

data/context/index.yaml

@@ -0,0 +1,18 @@
+# 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: Execute Protocol::HTTP applications across isolated execution contexts.
+metadata:
+  bug_tracker_uri: https://github.com/socketry/protocol-http-executor/issues
+  changelog_uri: https://github.com/socketry/protocol-http-executor/blob/main/releases.md
+  documentation_uri: https://socketry.github.io/protocol-http-executor/
+  source_code_uri: https://github.com/socketry/protocol-http-executor.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to execute `Protocol::HTTP` applications in
+    isolated threads or Ractors.
+- path: design-overview.md
+  title: Design Overview
+  description: This guide explains how `protocol-http-executor` preserves HTTP request,
+    response, streaming, error, and trailer semantics across an execution boundary.

data/lib/protocol/http/executor/body/input.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "protocol/http/body/readable"
+
+module Protocol
+	module HTTP
+		module Executor
+			# @namespace
+			module Body
+				# A request body reconstructed from input channel events.
+				class Input < ::Protocol::HTTP::Body::Readable
+					# Initialize an input body.
+					#
+					# @parameter channel [Channel] The input channel.
+					# @parameter headers [Protocol::HTTP::Headers] The request headers to receive trailers.
+					# @parameter metadata [Hash] The original body metadata.
+					def initialize(channel, headers, metadata)
+						@channel = channel
+						@headers = headers
+						@length = metadata[:length]
+						@stream = metadata[:stream]
+						@finished = false
+						@closed = false
+					end
+					
+					# @attribute [Integer | Nil] The original body length.
+					attr :length
+					
+					# @returns [Boolean] Whether the original body preferred streaming.
+					def stream?
+						@stream
+					end
+					
+					# @returns [Boolean] Whether the body has finished.
+					def empty?
+						@finished
+					end
+					
+					# Read the next request body chunk.
+					#
+					# @returns [String | Nil] The next chunk, or `nil` after body completion.
+					def read
+						return nil if @closed || @finished
+						
+						loop do
+							message = @channel.read
+							raise ClosedError unless message
+							
+							type, payload = message
+							
+							case type
+							when :chunk
+								return payload
+							when :trailers
+								apply_trailers(payload)
+							when :end
+								@finished = true
+								return nil
+							when :error
+								@finished = true
+								raise RemoteError.new(payload)
+							else
+								raise ClosedError, "Unexpected input event: #{type.inspect}!"
+							end
+						end
+					end
+					
+					# Close the request body.
+					#
+					# A body closed after EOF leaves the channel available for a subsequent upgraded stream.
+					def close(error = nil)
+						return if @closed
+						
+						@closed = true
+						@channel.close_read unless @finished
+					end
+					
+					private
+					
+					def apply_trailers(fields)
+						@headers.trailer!
+						fields.each do |key, value|
+							@headers.add(key, value, trailer: true)
+						end
+					end
+				end
+				
+				# An upgraded stream input that follows the initial request body phase.
+				class StreamInput < ::Protocol::HTTP::Body::Readable
+					# Initialize a stream input.
+					#
+					# @parameter channel [Channel] The input channel.
+					# @parameter headers [Protocol::HTTP::Headers] The request headers to receive trailers.
+					def initialize(channel, headers)
+						@channel = channel
+						@headers = headers
+						@closed = false
+					end
+					
+					# Read the next request or upgraded-stream chunk.
+					def read
+						return nil if @closed
+						
+						loop do
+							message = @channel.read
+							unless message
+								@closed = true
+								return nil
+							end
+							
+							type, payload = message
+							
+							case type
+							when :chunk, :stream_chunk
+								return payload
+							when :trailers
+								@headers.trailer!
+								payload.each{|key, value| @headers.add(key, value, trailer: true)}
+							when :end
+								# The request body ended; an upgraded stream may follow:
+								next
+							when :error, :stream_error
+								@closed = true
+								raise RemoteError.new(payload)
+							else
+								raise ClosedError, "Unexpected stream input event: #{type.inspect}!"
+							end
+						end
+					end
+					
+					# Close the stream input channel.
+					def close(error = nil)
+						return if @closed
+						
+						@closed = true
+						@channel.close_read
+					end
+				end
+			end
+		end
+	end
+end

data/lib/protocol/http/executor/body/output.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "protocol/http/body/readable"
+
+module Protocol
+	module HTTP
+		module Executor
+			module Body
+				# A response body read from the worker output channel.
+				class Output < ::Protocol::HTTP::Body::Readable
+					# Initialize a remote response body.
+					#
+					# @parameter execution [Execution] The owning execution.
+					# @parameter headers [Protocol::HTTP::Headers] The response headers to receive trailers.
+					# @parameter metadata [Hash] The remote response body metadata.
+					def initialize(execution, headers, metadata)
+						@execution = execution
+						@headers = headers
+						@length = metadata[:length]
+						@stream = metadata[:stream]
+						@mode = nil
+						@finished = false
+					end
+					
+					# @attribute [Integer | Nil] The remote response body length.
+					attr :length
+					
+					# @returns [Boolean] Whether the remote body prefers direct streaming.
+					def stream?
+						@stream
+					end
+					
+					# @returns [Boolean] Whether the remote body has finished.
+					def empty?
+						@finished
+					end
+					
+					# Read the next response body chunk.
+					def read
+						return nil if @finished
+						
+						start(:read)
+						return read_output
+					end
+					
+					# Stream the remote body directly through the given duplex stream.
+					def call(stream)
+						unless stream?
+							return super(stream)
+						end
+						
+						start(:stream)
+						input_task = @execution.stream_input(stream)
+						error = nil
+						
+						begin
+							while chunk = read_output
+								stream.write(chunk)
+								stream.flush
+							end
+						rescue => error
+							@execution.cancel(error)
+							raise
+						ensure
+							input_task&.cancel
+							stream.close(error)
+							@execution.finish unless error
+						end
+					end
+					
+					# Close the response body and cancel unfinished execution.
+					def close(error = nil)
+						unless @finished
+							@finished = true
+							@execution.cancel(error)
+						end
+					end
+					
+					private
+					
+					def start(mode)
+						if @mode && @mode != mode
+							raise IOError, "The response body is already being consumed using #{@mode.inspect}!"
+						end
+						
+						unless @mode
+							@mode = mode
+							@execution.control.write(:consume, mode)
+							@execution.close_input if mode == :read
+						end
+					end
+					
+					def read_output
+						loop do
+							message = @execution.body.read
+							unless message
+								@finished = true
+								@execution.finish
+								return nil
+							end
+							
+							type, payload = message
+							
+							case type
+							when :chunk
+								return payload
+							when :trailers
+								apply_trailers(payload)
+							when :error
+								@finished = true
+								@execution.finish
+								raise RemoteError.new(payload)
+							else
+								raise ClosedError, "Unexpected output event: #{type.inspect}!"
+							end
+						end
+					end
+					
+					def apply_trailers(fields)
+						@headers.trailer!
+						fields.each do |key, value|
+							@headers.add(key, value, trailer: true)
+						end
+					end
+				end
+				
+				# A writable output used while executing a streamable body in the worker.
+				class StreamOutput
+					# Initialize a stream output.
+					#
+					# @parameter channel [Channel] The worker output channel.
+					def initialize(channel)
+						@channel = channel
+						@closed = false
+					end
+					
+					# Write an output chunk.
+					def write(chunk)
+						raise IOError, "The stream output is closed!" if @closed
+						
+						@channel.write(:chunk, chunk)
+						return chunk.bytesize
+					end
+					
+					alias << write
+					
+					# Flush pending output.
+					def flush
+					end
+					
+					# Close the stream output for writing.
+					def close_write(error = nil)
+						@closed = true
+					end
+					
+					# Close the stream output for writing.
+					def close(error = nil)
+						close_write(error)
+					end
+					
+					# @returns [Boolean] Whether the output has been closed.
+					def closed?
+						@closed
+					end
+					
+					# @returns [Boolean] Whether the output contains pending chunks.
+					def empty?
+						true
+					end
+				end
+			end
+		end
+	end
+end

data/lib/protocol/http/executor/channel.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "socket"
+
+module Protocol
+	module HTTP
+		module Executor
+			# A framed, bidirectional message channel over an `IO` object.
+			class Channel
+				HEADER_FORMAT = "N"
+				HEADER_SIZE = 4
+				MAXIMUM_FRAME_SIZE = 256 * 1024 * 1024
+				
+				# Initialize a channel over the given IO object.
+				#
+				# @parameter io [IO] The connected stream.
+				def initialize(io)
+					@io = io
+					@write_mutex = Mutex.new
+					@read_closed = false
+					@write_closed = false
+				end
+				
+				# Send a typed message.
+				#
+				# @parameter type [Symbol] The message type.
+				# @parameter payload [Object] The message payload.
+				def write(type, payload = nil)
+					data = Marshal.dump([type, payload])
+					
+					if data.bytesize > MAXIMUM_FRAME_SIZE
+						raise ArgumentError, "Frame is too large: #{data.bytesize} bytes!"
+					end
+					
+					frame = [data.bytesize].pack(HEADER_FORMAT) << data
+					
+					@write_mutex.synchronize do
+						raise ClosedError if @write_closed
+						
+						write_all(frame)
+					end
+					
+					return nil
+				rescue IOError, SystemCallError => error
+					raise ClosedError, error.message
+				end
+				
+				# Read the next typed message.
+				#
+				# @returns [Array(Symbol, Object) | Nil] The next message, or `nil` after a clean close.
+				def read
+					return nil if @read_closed
+					
+					header = read_exactly(HEADER_SIZE, eof: true)
+					unless header
+						@read_closed = true
+						return nil
+					end
+					
+					length = header.unpack1(HEADER_FORMAT)
+					if length > MAXIMUM_FRAME_SIZE
+						raise ClosedError, "Invalid frame size: #{length} bytes!"
+					end
+					
+					return Marshal.load(read_exactly(length))
+				rescue EOFError, IOError, SystemCallError => error
+					raise ClosedError, error.message
+				end
+				
+				# Shut down the reading direction while leaving the writing direction available.
+				def close_read
+					return if @read_closed
+					
+					@read_closed = true
+					@io.shutdown(::Socket::SHUT_RD)
+				rescue IOError, SystemCallError
+					# The channel was already closed concurrently:
+				end
+				
+				# Shut down the writing direction while leaving the reading direction available.
+				def close_write
+					@write_mutex.synchronize do
+						return if @write_closed
+						
+						@write_closed = true
+						@io.shutdown(::Socket::SHUT_WR)
+					end
+				rescue IOError, SystemCallError
+					# The channel was already closed concurrently:
+				end
+				
+				# Close the underlying IO object.
+				def close
+					return if @io.closed?
+					
+					@read_closed = true
+					@write_closed = true
+					@io.close
+				rescue IOError
+					# The channel was already closed concurrently:
+				end
+				
+				# @returns [Boolean] Whether the channel has been closed.
+				def closed?
+					(@read_closed && @write_closed) || @io.closed?
+				end
+				
+				private
+				
+				# Write the complete buffer to the IO object.
+				def write_all(buffer)
+					offset = 0
+					
+					while offset < buffer.bytesize
+						offset += @io.write(buffer.byteslice(offset, buffer.bytesize - offset))
+					end
+				end
+				
+				# Read exactly the requested number of bytes.
+				def read_exactly(length, eof: false)
+					buffer = String.new(capacity: length, encoding: Encoding::BINARY)
+					
+					while buffer.bytesize < length
+						begin
+							buffer << @io.readpartial(length - buffer.bytesize)
+						rescue EOFError
+							if eof && buffer.empty?
+								return nil
+							end
+							
+							raise
+						end
+					end
+					
+					return buffer
+				end
+			end
+		end
+	end
+end

data/lib/protocol/http/executor/error.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "protocol/http/error"
+
+module Protocol
+	module HTTP
+		module Executor
+			# Raised when the remote execution context reports an error.
+			class RemoteError < ::Protocol::HTTP::RemoteError
+				# Convert an exception into a transport-safe description.
+				#
+				# @parameter error [Exception] The exception to describe.
+				# @returns [Hash] A transport-safe error description.
+				def self.dump(error)
+					{
+						class: error.class.name,
+						message: error.message,
+						backtrace: error.backtrace,
+					}
+				end
+				
+				# Initialize a remote error from its description.
+				#
+				# @parameter description [Hash] The remote error description.
+				def initialize(description)
+					@description = description
+					
+					super("#{description[:class]}: #{description[:message]}")
+					self.set_backtrace(description[:backtrace]) if description[:backtrace]
+				end
+				
+				# @attribute [Hash] The remote error description.
+				attr :description
+			end
+			
+			# Raised when an execution transport closes unexpectedly.
+			class ClosedError < RemoteError
+				# Initialize an unexpected transport closure.
+				def initialize(message = "The execution transport closed unexpectedly.")
+					super(class: self.class.name, message: message, backtrace: nil)
+				end
+			end
+		end
+	end
+end