Getting Started

This guide explains how to execute Protocol::HTTP applications in isolated threads or Ractors.

Installation

Add the gem to your project:

$ 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.

class Protocol::HTTP::Executor::Threaded creates one native thread per request.
class Protocol::HTTP::Executor::Ractored creates one Ractor per request using the Ruby head/4.1 Ractor API.
class 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.

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.

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.