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 browse the reference index or refer to the guides below.
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
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 browse the releases for more details.
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.
- Fork the repository.
- Create your feature branch (
git checkout -b my-new-feature). - Commit your changes (
git commit -am 'Add some feature.'). - Push to the branch (
git push origin my-new-feature). - 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.