protocol-http-executor 0.0.1

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

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async/task"
+require "protocol/http/response"
+
+module Protocol
+	module HTTP
+		module Executor
+			# Manages one request and its isolated worker transport.
+			class Execution
+				# Initialize an execution.
+				#
+				# @parameter endpoint [Transport::Endpoint] The caller endpoint.
+				# @parameter backend [Thread | Ractor] The isolated execution context.
+				# @parameter request [Protocol::HTTP::Request] The original request.
+				# @parameter parent [Async::Task] The parent task for body forwarding.
+				def initialize(endpoint, backend, request, parent)
+					@endpoint = endpoint
+					@backend = backend
+					@request = request
+					@parent = parent
+					@input_task = nil
+					@input_close_task = nil
+					@finished = false
+					@mutex = Mutex.new
+				end
+				
+				# @attribute [Channel] The control channel.
+				def control
+					@endpoint.control
+				end
+				
+				# @attribute [Channel] The bidirectional body channel.
+				def body
+					@endpoint.body
+				end
+				
+				# Start the worker request and wait for the response head.
+				#
+				# @returns [Protocol::HTTP::Response] The reconstructed response.
+				def call
+					description = request_description(@request)
+					control.write(:request, description)
+					
+					if description[:body]
+						@input_task = @parent.async do
+							forward_request_body(@request.body)
+						end
+					end
+					
+					wait_for_response
+				rescue
+					cancel($!)
+					raise
+				end
+				
+				# Forward upgraded-stream input after the request body phase.
+				#
+				# @parameter stream [IO | Object] The caller's duplex stream.
+				# @returns [Async::Task] The forwarding task.
+				def stream_input(stream)
+					@parent.async do
+						@input_task&.wait
+						
+						while chunk = read_stream_chunk(stream)
+							body.write(:stream_chunk, chunk)
+						end
+					rescue => error
+						begin
+							body.write(:stream_error, RemoteError.dump(error))
+						rescue ClosedError
+							# The worker has already finished:
+						end
+					ensure
+						body.close_write
+					end
+				end
+				
+				# Finish the request direction once the initial request body has been forwarded.
+				def close_input
+					@input_close_task ||= @parent.async do
+						@input_task&.wait
+						body.close_write
+					end
+				end
+				
+				# Finish the execution and release its transport.
+				def finish
+					return unless transition_to_finished
+					
+					@input_task&.cancel
+					@input_close_task&.cancel
+					@endpoint.close
+					@backend.join
+					return nil
+				end
+				
+				# Cancel the execution and release its transport.
+				#
+				# @parameter error [Exception | Nil] The cancellation reason.
+				def cancel(error = nil)
+					return unless transition_to_finished
+					
+					begin
+						control.write(:cancel, error && RemoteError.dump(error))
+					rescue ClosedError
+						# The worker has already finished:
+					end
+					
+					@input_task&.cancel
+					@input_close_task&.cancel
+					@request.close(error)
+					@endpoint.close
+					return nil
+				end
+				
+				private
+				
+				def wait_for_response
+					loop do
+						message = control.read
+						raise ClosedError unless message
+						
+						type, payload = message
+						case type
+						when :interim_response
+							status, fields = payload
+							@request.send_interim_response(status, ::Protocol::HTTP::Headers[fields])
+						when :response
+							return build_response(payload)
+						when :error
+							raise RemoteError.new(payload)
+						else
+							raise ClosedError, "Unexpected control event: #{type.inspect}!"
+						end
+					end
+				end
+				
+				def build_response(description)
+					headers = ::Protocol::HTTP::Headers[description[:headers]]
+					apply_trailers(headers, description[:trailers])
+					
+					body = if metadata = description[:body]
+						Body::Output.new(self, headers, metadata)
+					end
+					
+					response = ::Protocol::HTTP::Response.new(
+						description[:version],
+						description[:status],
+						headers,
+						body,
+						description[:protocol],
+					)
+					
+					finish unless body
+					return response
+				end
+				
+				def request_description(request)
+					body = request.body
+					body_metadata = Worker.body_metadata(body)
+					trailers = nil
+					
+					unless body_metadata
+						trailers = request.headers.trailer.to_a
+						trailers = nil if trailers.empty?
+					end
+					
+					return {
+						scheme: request.scheme,
+						authority: request.authority,
+						method: request.method,
+						path: request.path,
+						version: request.version,
+						headers: request.headers.header.to_a,
+						trailers: trailers,
+						body: body_metadata,
+						protocol: request.protocol,
+						peer: request.peer&.address,
+					}
+				end
+				
+				def forward_request_body(body)
+					while chunk = body.read
+						self.body.write(:chunk, chunk)
+					end
+					
+					trailers = @request.headers.trailer.to_a
+					self.body.write(:trailers, trailers) unless trailers.empty?
+					self.body.write(:end)
+				rescue => error
+					begin
+						self.body.write(:error, RemoteError.dump(error))
+					rescue ClosedError
+						# The worker has stopped reading the request body:
+					end
+				ensure
+					body.close(error)
+				end
+				
+				def read_stream_chunk(stream)
+					if stream.respond_to?(:read_partial)
+						return stream.read_partial
+					end
+					
+					return stream.readpartial(64 * 1024)
+				rescue EOFError
+					return nil
+				end
+				
+				def apply_trailers(headers, trailers)
+					return unless trailers
+					
+					headers.trailer!
+					trailers.each{|key, value| headers.add(key, value, trailer: true)}
+				end
+				
+				def transition_to_finished
+					@mutex.synchronize do
+						return false if @finished
+						
+						@finished = true
+						return true
+					end
+				end
+			end
+		end
+	end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async/task"
+require "protocol/http/middleware"
+
+module Protocol
+	module HTTP
+		module Executor
+			# The common middleware implementation for isolated execution contexts.
+			class Generic < ::Protocol::HTTP::Middleware
+				# Execute a request using a new isolated execution context.
+				#
+				# @parameter request [Protocol::HTTP::Request] The request to execute.
+				# @returns [Protocol::HTTP::Response] The remote response.
+				def call(request)
+					parent = ::Async::Task.current
+					endpoint, worker_streams = Transport.pair
+					backend = spawn(worker_streams)
+					
+					Execution.new(endpoint, backend, request, parent).call
+				rescue
+					endpoint&.close
+					raise
+				end
+				
+				private
+				
+				# Spawn the isolated execution context.
+				#
+				# @parameter worker_streams [Array(IO)] The worker transport streams.
+				# @returns [Thread | Ractor] The isolated execution context.
+				def spawn(worker_streams)
+					raise NotImplementedError
+				end
+			end
+		end
+	end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Protocol
+	module HTTP
+		module Executor
+			# Executes each request in a dedicated Ruby 4.1 Ractor.
+			class Ractored < Generic
+				# Initialize a Ractored executor.
+				#
+				# @parameter delegate [Interface(:call)] A shareable HTTP application.
+				def initialize(delegate)
+					unless self.class.supported?
+						raise NotImplementedError, "Ractor execution requires the Ruby head/4.1 Ractor API."
+					end
+					
+					unless ::Ractor.shareable?(delegate)
+						raise ArgumentError, "The Ractor application must be shareable."
+					end
+					
+					# Protocol::HTTP applications construct headers inside the worker, so the
+					# default policy must be visible from non-main Ractors:
+					::Ractor.make_shareable(::Protocol::HTTP::Headers::POLICY)
+					
+					super
+				end
+				
+				# @returns [Boolean] Whether the required Ractor API is available.
+				def self.supported?
+					defined?(::Ractor) && ::Ractor.method_defined?(:join) && ::Ractor.method_defined?(:value)
+				end
+				
+				private
+				
+				def spawn(worker_streams)
+					descriptors = worker_streams.map(&:fileno).freeze
+					worker = ::Ractor.new(@delegate, descriptors, name: "protocol-http-executor"){|application, descriptors| Protocol::HTTP::Executor::Worker.run(application, descriptors.map{|descriptor| ::Socket.for_fd(descriptor)})}
+					
+					# The worker now owns the descriptors. Close these wrappers without closing
+					# the underlying descriptors:
+					worker_streams.each do |stream|
+						stream.autoclose = false
+						stream.close
+					end
+					
+					return worker
+				end
+			end
+		end
+	end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "protocol/http/request"
+require "protocol/http/peer"
+
+module Protocol
+	module HTTP
+		module Executor
+			# A reconstructed request owned by the execution context.
+			class Request < ::Protocol::HTTP::Request
+				# Initialize a reconstructed request.
+				#
+				# @parameter description [Hash] The serialized request description.
+				# @parameter endpoint [Transport::Endpoint] The worker transport endpoint.
+				def initialize(description, endpoint)
+					@peer = if address = description[:peer]
+						::Protocol::HTTP::Peer.new(address)
+					end
+					
+					headers = ::Protocol::HTTP::Headers[description[:headers]]
+					if trailers = description[:trailers]
+						headers.trailer!
+						trailers.each{|key, value| headers.add(key, value, trailer: true)}
+					end
+					
+					body = if metadata = description[:body]
+						Body::Input.new(endpoint.body, headers, metadata)
+					end
+					
+					interim_response = proc do |status, interim_headers|
+						fields = ::Protocol::HTTP::Headers[interim_headers].header.to_a
+						endpoint.control.write(:interim_response, [status, fields])
+					end
+					
+					super(
+						description[:scheme],
+						description[:authority],
+						description[:method],
+						description[:path],
+						description[:version],
+						headers,
+						body,
+						description[:protocol],
+						interim_response,
+					)
+				end
+				
+				# @attribute [Protocol::HTTP::Peer | Nil] The reconstructed remote peer.
+				attr :peer
+			end
+		end
+	end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Protocol
+	module HTTP
+		module Executor
+			# Executes each request in a dedicated native thread.
+			class Threaded < Generic
+				private
+				
+				def spawn(worker_streams)
+					application = @delegate
+					
+					return Thread.new(application, worker_streams) do |delegate, streams|
+						Worker.run(delegate, streams)
+					end
+				end
+			end
+		end
+	end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "socket"
+
+module Protocol
+	module HTTP
+		module Executor
+			# A per-request transport with independent control and full-duplex body channels.
+			module Transport
+				# One endpoint of an execution transport.
+				class Endpoint
+					# Initialize an endpoint from its connected IO objects.
+					#
+					# @parameter control [IO] The bidirectional control stream.
+					# @parameter body [IO] The bidirectional request and response body stream.
+					def initialize(control, body)
+						@control = Channel.new(control)
+						@body = Channel.new(body)
+					end
+					
+					# @attribute [Channel] The bidirectional control channel.
+					attr :control
+					
+					# @attribute [Channel] The bidirectional body channel.
+					attr :body
+					
+					# Close all channels.
+					def close
+						@control.close
+						@body.close
+					end
+				end
+				
+				# Create connected client and worker transport endpoints.
+				#
+				# @returns [Array(Endpoint, Array(IO))] The client endpoint and worker IO objects.
+				def self.pair
+					client_control, worker_control = Socket.pair(:UNIX, :STREAM, 0)
+					client_body, worker_body = Socket.pair(:UNIX, :STREAM, 0)
+					
+					client = Endpoint.new(client_control, client_body)
+					worker = [worker_control, worker_body]
+					
+					return client, worker
+				end
+			end
+		end
+	end
+end

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Protocol
+	module HTTP
+		module Executor
+			VERSION = "0.0.1"
+		end
+	end
+end

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

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async"
+
+require "protocol/http/body/stream"
+require "protocol/http/response"
+
+module Protocol
+	module HTTP
+		module Executor
+			# Executes one transported request in the isolated execution context.
+			module Worker
+				# Run the application using the given transport streams.
+				#
+				# @parameter application [Interface(:call)] The HTTP application.
+				# @parameter streams [Array(IO)] The control and bidirectional body streams.
+				def self.run(application, streams)
+					endpoint = Transport::Endpoint.new(*streams)
+					
+					Sync do
+						execute(application, endpoint)
+					end
+				ensure
+					endpoint&.close
+				end
+				
+				# Execute a request received on the endpoint.
+				#
+				# @parameter application [Interface(:call)] The HTTP application.
+				# @parameter endpoint [Transport::Endpoint] The worker endpoint.
+				def self.execute(application, endpoint)
+					response_started = false
+					message = endpoint.control.read
+					raise ClosedError unless message
+					
+					type, description = message
+					raise ClosedError, "Expected a request, but received #{type.inspect}!" unless type == :request
+					
+					request = Request.new(description, endpoint)
+					response = application.call(request)
+					response ||= ::Protocol::HTTP::Response[500]
+					
+					body = response.body
+					body_metadata = body_metadata(body)
+					trailers = nil
+					
+					unless body_metadata
+						trailers = response.headers.trailer.to_a
+						trailers = nil if trailers.empty?
+					end
+					
+					endpoint.control.write(:response, {
+						version: response.version,
+						status: response.status,
+						headers: response.headers.header.to_a,
+						trailers: trailers,
+						body: body_metadata,
+						protocol: response.protocol,
+					})
+					response_started = true
+					
+					if body_metadata
+						consume(response, request, endpoint)
+					else
+						response.close
+					end
+				rescue => error
+					if response_started
+						write_error(endpoint.body, error)
+					else
+						write_error(endpoint.control, error)
+					end
+					
+					begin
+						response&.close(error)
+					rescue
+						# The original error has already been reported:
+					end
+				ensure
+					request&.close
+				end
+				
+				# Consume the response body according to the caller's selected mode.
+				#
+				# @parameter response [Protocol::HTTP::Response] The response to consume.
+				# @parameter request [Request] The reconstructed request.
+				# @parameter endpoint [Transport::Endpoint] The worker endpoint.
+				def self.consume(response, request, endpoint)
+					message = endpoint.control.read
+					raise ClosedError unless message
+					
+					type, mode = message
+					return if type == :cancel
+					raise ClosedError, "Expected a consumption mode, but received #{type.inspect}!" unless type == :consume
+					
+					case mode
+					when :read
+						response.body.each{|chunk| endpoint.body.write(:chunk, chunk)}
+					when :stream
+						input = Body::StreamInput.new(endpoint.body, request.headers)
+						output = Body::StreamOutput.new(endpoint.body)
+						stream = ::Protocol::HTTP::Body::Stream.new(input, output)
+						response.body.call(stream)
+					else
+						raise ArgumentError, "Unknown response consumption mode: #{mode.inspect}!"
+					end
+					
+					trailers = response.headers.trailer.to_a
+					endpoint.body.write(:trailers, trailers) unless trailers.empty?
+					endpoint.body.close_write
+				rescue => error
+					write_error(endpoint.body, error)
+				ensure
+					response.close(error)
+				end
+				
+				# Describe a non-empty body for transport.
+				#
+				# @parameter body [Protocol::HTTP::Body::Readable | Nil] The body.
+				# @returns [Hash | Nil] The body metadata, or `nil` for no body.
+				def self.body_metadata(body)
+					return unless body
+					return if body.empty?
+					
+					return {
+						length: body.length,
+						stream: body.stream?,
+					}
+				end
+				
+				# Write an error unless the transport has already closed.
+				#
+				# @parameter channel [Channel] The destination channel.
+				# @parameter error [Exception] The error to report.
+				def self.write_error(channel, error)
+					channel.write(:error, RemoteError.dump(error))
+				rescue ClosedError
+					# The caller has already abandoned the execution:
+				end
+			end
+		end
+	end
+end

data/lib/protocol/http/executor.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "executor/version"
+require_relative "executor/error"
+require_relative "executor/channel"
+require_relative "executor/transport"
+require_relative "executor/request"
+require_relative "executor/body/input"
+require_relative "executor/body/output"
+require_relative "executor/worker"
+require_relative "executor/execution"
+require_relative "executor/generic"
+require_relative "executor/threaded"
+require_relative "executor/ractored"
+
+# @namespace
+module Protocol
+	# @namespace
+	module HTTP
+		# Execute HTTP applications in isolated execution contexts.
+		module Executor
+		end
+	end
+end

data/license.md

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