shuttlebay 0.1.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4038d15bb64a686fa2abc8662520807bbdedc3ac6d3796688ccb57c4acef8aaa
+  data.tar.gz: 1bfb6f3eb2456f5b3b16117a45d5daa97f9c58e08420bf53c888d023b3f28210
+SHA512:
+  metadata.gz: 472a1f07635596621b47dfd053f6ffacb4d579def811317a90160cff2d9c52c547ee562f6b2071f2e559fe1228e9a18ecccb3fcf8457d2cb3fcdc6707f67bf1b
+  data.tar.gz: ffba9bc614e3b26f51db20e397d44cb640ca32a6ca58bda9e7c33f26eb4d9627991ee99e981cab37f9c047d2162980505f3aa1448695e229fd80a2f3b7ba3d37

data/Cargo.lock

@@ -0,0 +1,416 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "bindgen"
+version = "0.72.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "993776b509cfb49c750f11b8f07a46fa23e0a1386ffc01fb1e7d343efc387895"
+dependencies = [
+ "bitflags",
+ "cexpr",
+ "clang-sys",
+ "itertools",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "rustc-hash",
+ "shlex",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "bitflags"
+version = "2.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
+
+[[package]]
+name = "bytes"
+version = "1.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
+
+[[package]]
+name = "cexpr"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766"
+dependencies = [
+ "nom",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
+
+[[package]]
+name = "clang-sys"
+version = "1.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "157a8ba7b480713b56f4c09fd13fc3e0a22a5dfab8097ba61cbc5feef950788a"
+dependencies = [
+ "glob",
+ "libc",
+ "libloading",
+]
+
+[[package]]
+name = "either"
+version = "1.18.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "252afb9ae5eaa683babdc6a068b3f5726eb19e05070c731f9b2a23a7c3e8ed34"
+
+[[package]]
+name = "glob"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
+
+[[package]]
+name = "itertools"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
+dependencies = [
+ "either",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "lazy_static"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "20870f649af7073d53e38067b2a84312175d56ea15217e1b15bc83506ec50afb"
+
+[[package]]
+name = "libc"
+version = "0.2.190"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce5d3ddc6d3fa000eb1536d85e147bfe31aacaba692ed6a876f95cb7c855be78"
+
+[[package]]
+name = "libloading"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
+dependencies = [
+ "cfg-if",
+ "windows-link",
+]
+
+[[package]]
+name = "magnus"
+version = "0.9.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9068710e00d21be762edca59b9c4c8946dbdb29820d4f76ad559afea07982c9"
+dependencies = [
+ "bytes",
+ "magnus-macros",
+ "rb-sys",
+ "rb-sys-env",
+ "seq-macro",
+]
+
+[[package]]
+name = "magnus-macros"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9dafde2eeb66f090e0f326112323eb8324b12cb32b5d1210e541d3df6b0ce77e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "minimal-lexical"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
+
+[[package]]
+name = "mothership-docking-protocol"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aaec5966e84e1a3c65b5846bd89c0c0621de6c75362f9c669636449fdf5a4b99"
+dependencies = [
+ "serde",
+ "serde_json",
+ "thiserror",
+]
+
+[[package]]
+name = "nom"
+version = "7.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
+dependencies = [
+ "memchr",
+ "minimal-lexical",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rb-sys"
+version = "0.9.130"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "02faf625bb10ba893e3ae620f19c9fb1b5f8fcae0fe4eb86bb3f2230fad75edb"
+dependencies = [
+ "rb-sys-build",
+]
+
+[[package]]
+name = "rb-sys-build"
+version = "0.9.130"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05be6f9c86fe5482808162826f6c047d093b3670582296c770de1d94f8066694"
+dependencies = [
+ "bindgen",
+ "lazy_static",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "shell-words",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "rb-sys-env"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cca7ad6a7e21e72151d56fe2495a259b5670e204c3adac41ee7ef676ea08117a"
+
+[[package]]
+name = "regex"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
+
+[[package]]
+name = "seq-macro"
+version = "0.3.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bc711410fbe7399f390ca1c3b60ad0f53f80e95c5eb935e52268a0e2cd49acc"
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.151"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "shell-words"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc6fe69c597f9c37bfeeeeeb33da3530379845f10be461a66d16d03eca2ded77"
+
+[[package]]
+name = "shlex"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
+
+[[package]]
+name = "shuttlebay"
+version = "0.1.0"
+dependencies = [
+ "magnus",
+ "mothership-docking-protocol",
+ "rb-sys",
+ "serde_json",
+ "state-machines",
+]
+
+[[package]]
+name = "state-machines"
+version = "0.30.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2bc4296143483a9608a37ba4cf9955b42b8e2154dc58917df4f9cbe8120ebb4"
+dependencies = [
+ "state-machines-core",
+ "state-machines-macro",
+]
+
+[[package]]
+name = "state-machines-core"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "54b3da777f8a61919bdb3c6e9e445f2995f851b967e5d73b5949290dccfdcddd"
+
+[[package]]
+name = "state-machines-macro"
+version = "0.30.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "edf80d0c48518c7fb7fbb1dd4dda13a8dc189c1f15ac435545b351d5f2c276b1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8593e8e72159ed2257d083c7a454a85cbf854f37a0966d8d483aff8c8a3ebcee"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "thiserror"
+version = "2.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09e52cb86a36cede5cb101bf8908837b3e4c6e5e59fe7fd85c23fb56200d189e"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.26"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d245f478577f809a851594d02313b640fb437e0bb33866753cff937863096954"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"

data/Cargo.toml

@@ -0,0 +1,15 @@
+[workspace]
+members = ["ext/shuttlebay"]
+resolver = "3"
+
+[workspace.package]
+edition = "2024"
+rust-version = "1.99"
+license = "MIT"
+repository = "https://github.com/seuros/shuttlebay"
+
+[profile.release]
+lto = true
+codegen-units = 1
+opt-level = 3
+strip = true

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdelkader Boudih
+
+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.

data/README.md

@@ -0,0 +1,191 @@
+# Shuttlebay
+
+Run a Rack app as a [Mothership](https://github.com/seuros/mothership) `[[bays.http]]` bay.
+
+Mothership is the HTTP server. Shuttlebay is the Ruby side: it preloads your
+app, forks workers, and runs the app on threads that receive requests over
+Unix-socket docking links. A native engine (Rust, via magnus) decodes the
+docking protocol and builds the Rack env, so Ruby never parses HTTP.
+
+```mermaid
+flowchart TD
+    client([client]) -- HTTP --> mothership["mothership<br/>static, gzip, routing, limits, request ids…"]
+    mothership -- "docking protocol v3<br/>over a Unix socket" --> master["shuttlebay master<br/>config.ru preloaded: Rails, Sinatra, Roda, Padrino, …"]
+    master --> w0["worker 0<br/>threads, one docking link each"]
+    master --> w1["worker 1<br/>threads"]
+```
+
+## Install
+
+```ruby
+# Gemfile
+gem "shuttlebay"
+gem "guardship"    # the mothership binary (or: cargo install mothership)
+```
+
+```toml
+# ship-manifest.toml
+[mothership.bind]
+http = "0.0.0.0:3000"
+
+[[mothership.static_dirs]]   # public/ served by mothership, not Rails
+path = "./public"
+prefix = "/"
+
+[[bays.http]]
+name = "web"
+command = "bundle"
+args = ["exec", "shuttlebay", "config.ru"]
+workers = "auto"   # default: sized from CPUs and memory; 0 = single process
+threads = 5
+routes = [{ bind = "http", pattern = "/.*" }]
+```
+
+```bash
+bundle exec mothership
+```
+
+## What Mothership does instead of Rack middleware
+
+| Concern | Before (app server + middleware) | With Shuttlebay |
+|---|---|---|
+| HTTP parsing, keep-alive, slow clients | App server reactor | Mothership |
+| Static files | `ActionDispatch::Static` / nginx | `[[mothership.static_dirs]]` |
+| `send_file` / `Rack::Sendfile` | X-Sendfile + nginx | `to_path` bodies streamed from disk by Mothership |
+| Compression | `Rack::Deflater` / nginx | `compression = true` |
+| Request id, queue time | `ActionDispatch::RequestId`, LB | `X-Request-Id`, `X-Request-Start: t=<µs>` |
+| Real client IP | `RemoteIp` + proxy config | `REMOTE_ADDR` resolved (Forwarded / PROXY protocol) |
+| Load balancing to workers | kernel accept / `wait_for_less_busy_worker` | idle-thread checkout; queueing in Mothership |
+| Request body buffering | App server | Mothership reads the whole body before claiming a thread |
+
+When Rails is loaded, the bundled Railtie removes `Rack::Sendfile`, since the
+engine offloads `to_path` bodies itself.
+
+## Hooks
+
+`config.ru` loads in the master before forking, so register hooks there:
+
+```ruby
+Shuttlebay.before_fork { ActiveRecord::Base.connection_pool.disconnect! }
+Shuttlebay.on_worker_boot { |index| Rails.logger.info("worker #{index} up") }
+Shuttlebay.on_worker_shutdown { |index| Rails.logger.info("worker #{index} drained") }
+Shuttlebay.out_of_band { GC.start }   # runs when a worker has no request in flight
+run Rails.application
+```
+
+## Fibers
+
+With a fiber scheduler, each worker runs its `threads` docking links as fibers
+on one reactor thread instead of as threads. A request waiting on I/O parks
+its fiber, and the reactor serves the other links meanwhile.
+
+```ruby
+# config.ru (Gemfile: gem "async")
+require "async"
+Shuttlebay.fiber_scheduler { Async::Scheduler.new }
+run Rails.application
+```
+
+The block runs once per worker, after fork, on the reactor thread; any
+`Fiber::Scheduler` works. `threads` in the manifest still counts docking links
+per worker, so Mothership needs no change, but a parked fiber costs no thread,
+so it can go much higher (64, 256).
+
+- Fibers are not preempted: a request burning CPU stalls every other request
+  on its reactor. Size `workers` for CPU and `threads` for I/O wait.
+  `Shuttlebay.fiber_scheduler(reactors: 4) { … }` splits a worker's links
+  across 4 reactor threads, which Ruby does preempt, so one busy request
+  stalls a quarter of the links instead of all of them.
+- Only I/O through Ruby's scheduler yields: Ruby sockets (`Net::HTTP`, Redis
+  clients without hiredis), `pg`, `sleep`. C extensions doing their own
+  blocking I/O (`mysql2`, libcurl gems) stall the reactor.
+- Rails: set `config.active_support.isolation_level = :fiber` and size the
+  Active Record pool to at least `threads`.
+- Hijacked connections (WebSockets) still relay on their own threads.
+- Async's I/O hooks use `IO::Buffer`, so Ruby prints a one-time experimental
+  warning to stderr; `Warning[:experimental] = false` silences it.
+
+## Development server and system tests
+
+```bash
+bin/rails server -u shuttlebay        # or: rackup -s shuttlebay
+```
+
+```ruby
+# test/application_system_test_case.rb
+require "shuttlebay/capybara"
+Capybara.server = :shuttlebay
+```
+
+Both run the app in their own process and start a Mothership that attaches to
+it, so development and tests go through the same HTTP stack as production. The
+binary comes from `MOTHERSHIP_BIN`, the `guardship` gem, or `PATH`. The
+`Threads` option (`rackup -O Threads=5`) or `MS_BAY_THREADS` sets the thread
+count; Mothership sizes its link pool from what the app reports when it docks.
+
+For HTTPS, run Mothership with a `tls` bind and the app as a docking upstream
+(see the Mothership README) instead of the attached server.
+
+## Behaviour
+
+- **Responses:** HEAD, 1xx, 204 and 304 send no body. `to_ary` bodies go out
+  in one write. `each` bodies flush per chunk (SSE, `ActionController::Live`).
+  Rack 3 streaming bodies (`call`) are supported. A `to_path` body with status
+  200 is served by Mothership from disk.
+- **Thread handoff:** after the response's last byte, the thread closes the
+  body and runs `rack.response_finished` callbacks, then sends `Ready`.
+  Mothership routes the next request to that link only after `Ready`, so a
+  request never waits behind Rails' after-response work.
+- **Errors:** an exception before the head goes out becomes a 500. After the
+  head, the link is closed and the response aborts.
+  `rack.response_finished` callbacks run after every response.
+- **WebSockets:** run ActionCable on [orbitcast](https://github.com/seuros/orbitcast),
+  which holds the sockets in Rust and speaks ActionCable's protocol, so no
+  Ruby thread sits on a connection. Every other WebSocket (Faye,
+  `websocket-driver`, custom protocols, or ActionCable's built-in server in
+  development and system tests) goes through `rack.hijack`: the app answers on
+  the hijacked IO, Mothership relays the upgraded connection, and the thread
+  goes back to serving while the relay runs on threads of its own.
+- **Early hints:** not offered (`rack.early_hints` is absent). Mothership's
+  HTTP stack cannot send 1xx responses yet; Rails falls back to `Link`
+  headers on the final response.
+- **Large uploads:** bodies over 1 MiB are spooled to an unlinked temp file
+  (`rack.input` is a `Tempfile`). Memory stays bounded however large uploads
+  are allowed to be.
+- **Signals:** on `TERM`, workers stop accepting, drop idle links, and finish
+  in-flight requests within `MS_BAY_DRAIN_TIMEOUT` (Mothership passes the
+  bay's `request_timeout`). A dead worker is re-forked with backoff.
+- **Deploys:** `kill -USR1` the mothership process to roll the bay to new code
+  with no dropped requests (phased restart).
+- **TLS:** terminated by Mothership on a `tls` bind; the app sees
+  `rack.url_scheme = "https"`.
+- **Logs:** JSON lines on stdout, which Mothership passes through.
+
+## Environment (set by Mothership)
+
+`MS_SOCKET_PATH`, `MS_SHIP`, `MS_BAY_WORKERS`, `MS_BAY_THREADS`, `MS_BAY_DRAIN_TIMEOUT`.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake compile   # builds lib/shuttlebay/shuttlebay.{bundle,so}
+bundle exec rake test
+```
+
+The engine crate (`ext/shuttlebay`) shares the wire format with Mothership
+through `mothership-docking-protocol` and is never published to crates.io.
+Platform gems: `bundle exec rake platforms:build` (rb-sys-dock, Docker).
+
+Releases: release-please tags the version, CI builds the platform and source
+gems and attaches them to the GitHub release. Push them to rubygems.org from a
+workstation:
+
+```bash
+bundle exec rake 'gems:fetch[v0.1.0]'   # download the release's gems into pkg/
+bundle exec rake 'gems:push[v0.1.0]'    # fetch, then gem push each one
+```
+
+## License
+
+MIT

data/exe/shuttlebay

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/shuttlebay/logger'
+
+begin
+  require_relative '../lib/shuttlebay/runtime'
+  Shuttlebay::Server.from_env(ARGV).run
+rescue StandardError, ScriptError => e
+  Shuttlebay::Logger.new.error('shuttlebay stopped', **Shuttlebay::Logger.error_fields(e))
+  exit 1
+end

data/ext/shuttlebay/Cargo.toml

@@ -0,0 +1,31 @@
+[package]
+name = "shuttlebay"
+version = "0.1.4" # x-release-please-version
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+authors = ["Abdelkader Boudih <oss@seuros.com>"]
+description = "Ruby engine for Mothership HTTP bays: docking protocol codec and Rack env builder"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[lints.rust]
+unsafe_code = "deny"
+unused_must_use = "warn"
+
+[lints.clippy]
+all = { level = "warn", priority = -1 }
+pedantic = { level = "warn", priority = -1 }
+nursery = { level = "warn", priority = -1 }
+unwrap_used = "deny"
+expect_used = "deny"
+
+[dependencies]
+magnus = { version = "0.9", features = ["bytes"] }
+rb-sys = "0.9.124"
+mothership-docking-protocol = "0.2.0"
+serde_json = "1.0"
+state-machines = "0.30"