Protocol::HTTP::Executor

Execute Protocol::HTTP applications in isolated threads or Ractors while preserving the request/response streaming model.

Features

• Reconstruct requests and responses on either side of the execution boundary.
• Stream request and response bodies with scheduler-compatible backpressure.
• Preserve metadata, peer addresses, interim responses, errors, protocol upgrades, and trailers.
• Use the same semantic transport for thread-per-request and Ractor-per-request execution.

Each request uses two Unix socket pairs: a bidirectional control channel and a full-duplex body channel. The caller writes request data while reading response data, with socket half-closure representing the final EOF in each direction.

Usage

Please see the project documentation for more details.

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

• Design Overview - This guide explains how protocol-http-executor preserves HTTP request, response, streaming, error, and trailer semantics across an execution boundary.

Examples

• Rack - Run a config.ru Rack application inline, threaded, or Ractored using Falcon's config/serve.rb.
• Busy - Compare CPU-bound, I/O-bound, and mixed workloads across execution backends.
• Writebook - Run Shopify's Ractor-safe Rails experiment using Falcon's inline, threaded, or Ractored execution backends.

Semantic Transport

Request and response heads are sent separately from their bodies. Body chunks are forwarded only for non-empty bodies. Trailer fields are sent after the final body chunk and applied before EOF is exposed to the receiving application.

Streamable response bodies select a direct duplex mode. Initial request-body chunks are forwarded first, followed by upgraded-stream input, while response output flows independently in the other direction.

Releases

Please see the project releases for all releases.

Unreleased

• Add a Rack example using Falcon's config/serve.rb, Protocol::Rack, and Rack's opt-in Ractor support.

v0.0.1

• Add thread-per-request and Ruby head/4.1 Ractor-per-request HTTP execution.
• Preserve streamed request and response bodies, interim responses, errors, protocols, peer addresses, and trailers across the execution boundary.
• Use a full-duplex body socket with independent half-closure for request and response EOF.
• Transfer socket descriptors into Ractors without copying socket objects.
• Route errors on the control or body channel according to whether the response head has been sent.

Contributing

We welcome contributions to this project.

1. Fork the repository.
2. Create your feature branch (git checkout -b my-new-feature).
3. Commit your changes (git commit -am 'Add some feature.').
4. Push to the branch (git push origin my-new-feature).
5. Create a new pull request.

Running Tests

To run the test suite:

$ bundle exec sus

Making Releases

To make a new release:

$ bundle exec bake gem:release:patch # or minor or major

Developer Certificate of Origin

In order to protect users of this project, we require all contributors to comply with the Developer Certificate of Origin. This ensures that all contributions are properly licensed and attributed.

Community Guidelines

This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.