shuttlebay 0.1.4 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 4038d15bb64a686fa2abc8662520807bbdedc3ac6d3796688ccb57c4acef8aaa
4
- data.tar.gz: 1bfb6f3eb2456f5b3b16117a45d5daa97f9c58e08420bf53c888d023b3f28210
3
+ metadata.gz: 3e58d1e24092ae4ba3e6a37a5ad342d55497d1ac4dc13eaef5cf2751f3f33f7d
4
+ data.tar.gz: f24f366d0b6e785e8c5a7e65806586de4e246f1116e69e421a6ca84c08d9607e
5
5
  SHA512:
6
- metadata.gz: 472a1f07635596621b47dfd053f6ffacb4d579def811317a90160cff2d9c52c547ee562f6b2071f2e559fe1228e9a18ecccb3fcf8457d2cb3fcdc6707f67bf1b
7
- data.tar.gz: ffba9bc614e3b26f51db20e397d44cb640ca32a6ca58bda9e7c33f26eb4d9627991ee99e981cab37f9c047d2162980505f3aa1448695e229fd80a2f3b7ba3d37
6
+ metadata.gz: 2d26f2bb11c9f9494133822a9a05485c1111af4a89c360407f74134611c72a1e06ee74ff1bbe1047c2568e7fb7921258ae18bd9bfe627302d87bea237adaa683
7
+ data.tar.gz: ebabfa9fc4c2a6bf9a791e93affb9b110da1d0ca09b8119c30beca81e08b21ae65bc0e7f2c68b921cf0039680bc6f3e2548bd232c99ff19df2cc770239d1d6c9
data/Cargo.lock CHANGED
@@ -69,9 +69,9 @@ dependencies = [
69
69
 
70
70
  [[package]]
71
71
  name = "either"
72
- version = "1.18.0"
72
+ version = "1.19.0"
73
73
  source = "registry+https://github.com/rust-lang/crates.io-index"
74
- checksum = "252afb9ae5eaa683babdc6a068b3f5726eb19e05070c731f9b2a23a7c3e8ed34"
74
+ checksum = "0e9c71c2167ca323c882b99918929403426e2373ea17242ff5653e0d5e1058be"
75
75
 
76
76
  [[package]]
77
77
  name = "glob"
@@ -79,6 +79,12 @@ version = "0.3.4"
79
79
  source = "registry+https://github.com/rust-lang/crates.io-index"
80
80
  checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
81
81
 
82
+ [[package]]
83
+ name = "harel-machines"
84
+ version = "0.3.0"
85
+ source = "registry+https://github.com/rust-lang/crates.io-index"
86
+ checksum = "c55c0689200ba712a0c4360a54ec8bac72ba928bc3229e558b1ebb1ea01a49d7"
87
+
82
88
  [[package]]
83
89
  name = "itertools"
84
90
  version = "0.13.0"
@@ -102,9 +108,9 @@ checksum = "20870f649af7073d53e38067b2a84312175d56ea15217e1b15bc83506ec50afb"
102
108
 
103
109
  [[package]]
104
110
  name = "libc"
105
- version = "0.2.190"
111
+ version = "0.2.191"
106
112
  source = "registry+https://github.com/rust-lang/crates.io-index"
107
- checksum = "ce5d3ddc6d3fa000eb1536d85e147bfe31aacaba692ed6a876f95cb7c855be78"
113
+ checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
108
114
 
109
115
  [[package]]
110
116
  name = "libloading"
@@ -118,9 +124,9 @@ dependencies = [
118
124
 
119
125
  [[package]]
120
126
  name = "magnus"
121
- version = "0.9.2"
127
+ version = "0.9.3"
122
128
  source = "registry+https://github.com/rust-lang/crates.io-index"
123
- checksum = "b9068710e00d21be762edca59b9c4c8946dbdb29820d4f76ad559afea07982c9"
129
+ checksum = "40ef424404d166cbb71c8b8d19c9c589c748c4547c1afa1928c5504299f6c713"
124
130
  dependencies = [
125
131
  "bytes",
126
132
  "magnus-macros",
@@ -154,9 +160,9 @@ checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
154
160
 
155
161
  [[package]]
156
162
  name = "mothership-docking-protocol"
157
- version = "0.2.0"
163
+ version = "0.3.0"
158
164
  source = "registry+https://github.com/rust-lang/crates.io-index"
159
- checksum = "aaec5966e84e1a3c65b5846bd89c0c0621de6c75362f9c669636449fdf5a4b99"
165
+ checksum = "e43cb62ea01813b2fe88036c2e65c724a0020f97139023f4b8aea5e78626461b"
160
166
  dependencies = [
161
167
  "serde",
162
168
  "serde_json",
@@ -289,14 +295,14 @@ checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
289
295
  dependencies = [
290
296
  "proc-macro2",
291
297
  "quote",
292
- "syn 3.0.6",
298
+ "syn 3.0.9",
293
299
  ]
294
300
 
295
301
  [[package]]
296
302
  name = "serde_json"
297
- version = "1.0.151"
303
+ version = "1.0.154"
298
304
  source = "registry+https://github.com/rust-lang/crates.io-index"
299
- checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
305
+ checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"
300
306
  dependencies = [
301
307
  "itoa",
302
308
  "memchr",
@@ -319,7 +325,7 @@ checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
319
325
 
320
326
  [[package]]
321
327
  name = "shuttlebay"
322
- version = "0.1.0"
328
+ version = "0.2.0"
323
329
  dependencies = [
324
330
  "magnus",
325
331
  "mothership-docking-protocol",
@@ -330,9 +336,9 @@ dependencies = [
330
336
 
331
337
  [[package]]
332
338
  name = "state-machines"
333
- version = "0.30.0"
339
+ version = "0.35.0"
334
340
  source = "registry+https://github.com/rust-lang/crates.io-index"
335
- checksum = "f2bc4296143483a9608a37ba4cf9955b42b8e2154dc58917df4f9cbe8120ebb4"
341
+ checksum = "f2fb3f0428a4a79e7929cacf1186fea42291446987807a5136daae4161c13fcf"
336
342
  dependencies = [
337
343
  "state-machines-core",
338
344
  "state-machines-macro",
@@ -340,19 +346,20 @@ dependencies = [
340
346
 
341
347
  [[package]]
342
348
  name = "state-machines-core"
343
- version = "0.11.0"
349
+ version = "0.15.0"
344
350
  source = "registry+https://github.com/rust-lang/crates.io-index"
345
- checksum = "54b3da777f8a61919bdb3c6e9e445f2995f851b967e5d73b5949290dccfdcddd"
351
+ checksum = "1d027fb20a763004675f678951c6c9537d9dbc2b26056c37d41cefb014e55daf"
346
352
 
347
353
  [[package]]
348
354
  name = "state-machines-macro"
349
- version = "0.30.0"
355
+ version = "0.35.0"
350
356
  source = "registry+https://github.com/rust-lang/crates.io-index"
351
- checksum = "edf80d0c48518c7fb7fbb1dd4dda13a8dc189c1f15ac435545b351d5f2c276b1"
357
+ checksum = "c16c56f4525fd7923580b96d7066341d3b10e772aa2e679e0c65b04881ba9439"
352
358
  dependencies = [
359
+ "harel-machines",
353
360
  "proc-macro2",
354
361
  "quote",
355
- "syn 2.0.119",
362
+ "syn 3.0.9",
356
363
  ]
357
364
 
358
365
  [[package]]
@@ -368,9 +375,9 @@ dependencies = [
368
375
 
369
376
  [[package]]
370
377
  name = "syn"
371
- version = "3.0.6"
378
+ version = "3.0.9"
372
379
  source = "registry+https://github.com/rust-lang/crates.io-index"
373
- checksum = "8593e8e72159ed2257d083c7a454a85cbf854f37a0966d8d483aff8c8a3ebcee"
380
+ checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
374
381
  dependencies = [
375
382
  "proc-macro2",
376
383
  "quote",
@@ -394,14 +401,14 @@ checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524"
394
401
  dependencies = [
395
402
  "proc-macro2",
396
403
  "quote",
397
- "syn 3.0.6",
404
+ "syn 3.0.9",
398
405
  ]
399
406
 
400
407
  [[package]]
401
408
  name = "unicode-ident"
402
- version = "1.0.26"
409
+ version = "1.0.27"
403
410
  source = "registry+https://github.com/rust-lang/crates.io-index"
404
- checksum = "d245f478577f809a851594d02313b640fb437e0bb33866753cff937863096954"
411
+ checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
405
412
 
406
413
  [[package]]
407
414
  name = "windows-link"
data/README.md CHANGED
@@ -15,6 +15,10 @@ flowchart TD
15
15
  master --> w1["worker 1<br/>threads"]
16
16
  ```
17
17
 
18
+ **New here?** [docs/guide.md](docs/guide.md) walks a Rails app from install to
19
+ production: the manifest, coming from Puma, moving `Rack::Attack` rules,
20
+ caching, TLS and HTTP/2, Docker and Kamal, several hosts.
21
+
18
22
  ## Install
19
23
 
20
24
  ```ruby
@@ -57,9 +61,59 @@ bundle exec mothership
57
61
  | Real client IP | `RemoteIp` + proxy config | `REMOTE_ADDR` resolved (Forwarded / PROXY protocol) |
58
62
  | Load balancing to workers | kernel accept / `wait_for_less_busy_worker` | idle-thread checkout; queueing in Mothership |
59
63
  | Request body buffering | App server | Mothership reads the whole body before claiming a thread |
64
+ | `ETag` / `If-None-Match` → 304 | `Rack::ETag`, `Rack::ConditionalGet` | Mothership hashes complete bodies and answers 304 |
65
+ | IP allowlists, rate limits | `Rack::Attack` | `ip_allowlist`, `rate_limits`, `trusted_proxies` in the manifest |
66
+ | Page / API caching | CDN, `Rack::Cache` | `[mothership.response_cache]`, purged by tag |
67
+
68
+ When Rails is loaded, the bundled Railtie removes the middleware Mothership
69
+ makes redundant:
70
+
71
+ - `Rack::Sendfile`: the engine offloads `to_path` bodies itself.
72
+ - `ActionDispatch::Static`: when Mothership serves the app's `public/` as a
73
+ static dir (`MS_STATIC_ROOTS`). `config.public_file_server.headers` it
74
+ does not send (per `MS_STATIC_HEADERS`) are logged at boot: move them to
75
+ the static dir's `headers` in the manifest.
76
+ - `Rack::ETag` and `Rack::ConditionalGet`: when Mothership validates
77
+ conditionals (`MS_CONDITIONAL_GET=1`), so bodies are not hashed twice.
78
+
79
+ Other Rack apps (Sinatra, Roda, Hanami) ask the same in `config.ru`;
80
+ `Shuttlebay.offloaded?` is false under any other server:
81
+
82
+ ```ruby
83
+ use Rack::ETag unless Shuttlebay.offloaded?(:conditional_get)
84
+ use Rack::ConditionalGet unless Shuttlebay.offloaded?(:conditional_get)
85
+ use Rack::Static, urls: [""], root: "public", cascade: true unless Shuttlebay.offloaded?(:static, "public")
86
+ use Rack::Sendfile unless Shuttlebay.offloaded?(:sendfile)
87
+ run App
88
+ ```
89
+
90
+ Rate limiting and allowlists in `Rack::Attack` are app configuration: drop
91
+ them yourself once the manifest enforces the same rules.
92
+
93
+ ## Caching at the edge
94
+
95
+ Mothership's response cache keeps entries until their data changes when the
96
+ app tags responses with what they show and purges the tags on change:
97
+
98
+ ```ruby
99
+ class BooksController < ApplicationController
100
+ def show
101
+ @book = Book.find(params[:id])
102
+ Shuttlebay::Cache.tag(response.headers, "book-#{@book.id}", "books")
103
+ expires_in 1.hour, public: true # or a manifest rule
104
+ end
105
+ end
106
+
107
+ class Book < ApplicationRecord
108
+ after_commit { Shuttlebay::Cache.purge(tags: ["book-#{id}", "books"]) }
109
+ end
110
+ ```
60
111
 
61
- When Rails is loaded, the bundled Railtie removes `Rack::Sendfile`, since the
62
- engine offloads `to_path` bodies itself.
112
+ `purge` also takes `urls:` (path and query), `prefixes:`, `all: true`, and
113
+ `soft: true` (mark stale and revalidate instead of dropping). It posts to
114
+ `MS_ADMIN_URL`, returns the number purged, is a no-op returning `nil` where
115
+ there is no Mothership, and raises `Shuttlebay::Error` when Mothership refuses
116
+ (e.g. no cache configured) or a network error when it is unreachable.
63
117
 
64
118
  ## Hooks
65
119
 
@@ -67,7 +121,7 @@ engine offloads `to_path` bodies itself.
67
121
 
68
122
  ```ruby
69
123
  Shuttlebay.before_fork { ActiveRecord::Base.connection_pool.disconnect! }
70
- Shuttlebay.on_worker_boot { |index| Rails.logger.info("worker #{index} up") }
124
+ Shuttlebay.on_worker_boot { |index, ship| Rails.logger.info("#{ship} worker #{index} up") }
71
125
  Shuttlebay.on_worker_shutdown { |index| Rails.logger.info("worker #{index} drained") }
72
126
  Shuttlebay.out_of_band { GC.start } # runs when a worker has no request in flight
73
127
  run Rails.application
@@ -152,18 +206,35 @@ For HTTPS, run Mothership with a `tls` bind and the app as a docking upstream
152
206
  - **Large uploads:** bodies over 1 MiB are spooled to an unlinked temp file
153
207
  (`rack.input` is a `Tempfile`). Memory stays bounded however large uploads
154
208
  are allowed to be.
209
+ - **Warmup:** the master calls `Process.warmup` once the app is loaded, so
210
+ workers fork from a compacted heap. `Shuttlebay.warmup = false` in
211
+ `config.ru` skips it.
212
+ - **Forks:** a `fork_from` bay in the manifest is served by this master: it
213
+ loads that bay's app too and forks its workers, sharing the preloaded heap.
214
+ A fork app that fails to load is logged and skipped. Each worker serves one
215
+ bay: it holds only that bay's socket, logs and sees (`MS_SHIP`) its name,
216
+ and hooks get it as their second argument (`|index, ship|`; hooks taking
217
+ only the index keep working).
155
218
  - **Signals:** on `TERM`, workers stop accepting, drop idle links, and finish
156
219
  in-flight requests within `MS_BAY_DRAIN_TIMEOUT` (Mothership passes the
157
220
  bay's `request_timeout`). A dead worker is re-forked with backoff.
158
221
  - **Deploys:** `kill -USR1` the mothership process to roll the bay to new code
159
222
  with no dropped requests (phased restart).
160
- - **TLS:** terminated by Mothership on a `tls` bind; the app sees
161
- `rack.url_scheme = "https"`.
223
+ - **TLS:** terminated by Mothership on a `tls` bind (guardship 0.2.1 and
224
+ later ship with TLS); the app sees `rack.url_scheme = "https"`.
225
+ - **HTTP/2:** browsers get it from Mothership's `tls` binds (ALPN), or from
226
+ the CDN or proxy in front; cleartext binds also take HTTP/2 with prior
227
+ knowledge. The app is unaffected: every request reaches it the same way,
228
+ as a Rack env, whatever the client spoke.
162
229
  - **Logs:** JSON lines on stdout, which Mothership passes through.
163
230
 
164
231
  ## Environment (set by Mothership)
165
232
 
166
- `MS_SOCKET_PATH`, `MS_SHIP`, `MS_BAY_WORKERS`, `MS_BAY_THREADS`, `MS_BAY_DRAIN_TIMEOUT`.
233
+ `MS_SOCKET_PATH`, `MS_SHIP`, `MS_BAY_WORKERS`, `MS_BAY_THREADS`, `MS_BAY_DRAIN_TIMEOUT`,
234
+ `MS_STATIC_ROOTS` (directories Mothership serves at `/`, one per line),
235
+ `MS_STATIC_HEADERS` (the headers their files carry, JSON by path),
236
+ `MS_CONDITIONAL_GET=1` (Mothership answers conditionals),
237
+ `MS_ADMIN_URL` (admin endpoint for cache purges).
167
238
 
168
239
  ## Development
169
240
 
data/docs/guide.md ADDED
@@ -0,0 +1,323 @@
1
+ # Running a Rails app on Shuttlebay
2
+
3
+ From `rails new` (or an app on Puma) to production behind Mothership. Any
4
+ Rack app works the same way; the Rails-specific parts are marked.
5
+
6
+ Mothership is the HTTP server: it terminates connections, serves `public/`,
7
+ compresses, limits, caches and routes. Shuttlebay runs your app on threads
8
+ that Mothership hands finished requests to. There is no Puma, no Thruster
9
+ and no nginx left in the request path.
10
+
11
+ ## 1. Install
12
+
13
+ ```ruby
14
+ # Gemfile
15
+ gem "shuttlebay"
16
+ gem "guardship" # the mothership binary, prebuilt for macOS, Linux, FreeBSD 15+
17
+ ```
18
+
19
+ ```bash
20
+ bundle install
21
+ bundle exec mothership --help
22
+ ```
23
+
24
+ Keep Puma in the Gemfile if you like: nothing below removes it, and
25
+ `rails server` without `-u` still uses it.
26
+
27
+ ## 2. Development and system tests
28
+
29
+ ```bash
30
+ bin/rails server -u shuttlebay
31
+ ```
32
+
33
+ ```ruby
34
+ # test/application_system_test_case.rb
35
+ require "shuttlebay/capybara"
36
+ Capybara.server = :shuttlebay
37
+ ```
38
+
39
+ Both start a Mothership attached to the app, so what you test is the stack
40
+ you deploy.
41
+
42
+ ## 3. The manifest
43
+
44
+ Mothership reads `ship-manifest.toml` from the directory it starts in:
45
+
46
+ ```toml
47
+ [mothership]
48
+ compression = true
49
+
50
+ [mothership.bind]
51
+ http = "0.0.0.0:3000"
52
+
53
+ [[mothership.static_dirs]]
54
+ path = "./public"
55
+ prefix = "/"
56
+ headers = { "cache-control" = "public, max-age=31536000" }
57
+
58
+ [[bays.http]]
59
+ name = "web"
60
+ command = "bundle"
61
+ args = ["exec", "shuttlebay", "config.ru"]
62
+ env = { RAILS_ENV = "production" }
63
+ workers = "auto"
64
+ threads = 5
65
+ routes = [{ bind = "http", pattern = "/.*" }]
66
+ ```
67
+
68
+ ```bash
69
+ bundle exec mothership clearance # validate the manifest
70
+ bundle exec mothership chart # what is routed where
71
+ bundle exec mothership # run
72
+ ```
73
+
74
+ - `workers = "auto"` forks one worker per CPU the process may use, as many as
75
+ memory affords (512 MiB each); a 1 CPU or 1 GiB container serves from one
76
+ process. A number, or `"$WEB_CONCURRENCY"`, works too.
77
+ - `threads` is the threads per worker, each with its own docking link to
78
+ Mothership. A request goes only to an idle thread; when all are busy it
79
+ waits in Mothership (`queue_timeout`, 30 s, then `503`).
80
+ - The static dir serves `public/` before any request reaches Rails, `/about`
81
+ from `about.html` and precompressed `.br`/`.gz` files included. The
82
+ Railtie sees that and drops `ActionDispatch::Static`. Give it the headers
83
+ your `config.public_file_server.headers` sets: the Railtie logs a warning at
84
+ boot for any it does not see there.
85
+
86
+ ## 4. Coming from Puma
87
+
88
+ | `config/puma.rb` | With Shuttlebay |
89
+ |---|---|
90
+ | `workers ENV.fetch("WEB_CONCURRENCY")` | `workers = "$WEB_CONCURRENCY"` (or `"auto"`) |
91
+ | `threads n, n` / `RAILS_MAX_THREADS` | `threads = "$RAILS_MAX_THREADS"` |
92
+ | `port` / `bind` | `[mothership.bind]` |
93
+ | `preload_app!` | always: `config.ru` loads in the master, then workers fork |
94
+ | `before_fork`, `on_worker_boot`, `on_worker_shutdown`, `out_of_band` | `Shuttlebay.before_fork { }` and friends, in `config.ru` |
95
+ | `worker_timeout` | the bay's `request_timeout` (`504`, then the stuck worker is recycled) |
96
+ | `pumactl phased-restart` / `plugin :tmp_restart` | `kill -USR1` the mothership process |
97
+ | `wait_for_less_busy_worker` | built in: requests only go to idle threads |
98
+
99
+ Hooks go in `config.ru`, before `run`:
100
+
101
+ ```ruby
102
+ # config.ru
103
+ require_relative "config/environment"
104
+
105
+ Shuttlebay.on_worker_boot { |index| Rails.logger.info("worker #{index} up") }
106
+ Shuttlebay.out_of_band { GC.start } # when a worker has no request in flight
107
+
108
+ run Rails.application
109
+ Rails.application.load_server
110
+ ```
111
+
112
+ `config/puma.rb` can stay for `rails server`; Shuttlebay never reads it.
113
+
114
+ ## 5. Let Mothership do the middleware's work
115
+
116
+ Under Mothership the Railtie removes, on its own, what Mothership already does:
117
+ `Rack::Sendfile`, `ActionDispatch::Static` (when the static dir serves
118
+ `public/`) and `Rack::ETag` / `Rack::ConditionalGet` (Mothership tags pages and
119
+ answers revalidations itself, off the GVL). Nothing changes under Puma.
120
+
121
+ `Rack::Attack` rules are your configuration, so you move them yourself:
122
+
123
+ ```ruby
124
+ # config/initializers/rack_attack.rb, before
125
+ Rack::Attack.throttle("api", limit: 60, period: 1.minute) do |req|
126
+ req.ip if req.path.start_with?("/api/")
127
+ end
128
+ ```
129
+
130
+ ```toml
131
+ # ship-manifest.toml, after
132
+ [[mothership.rate_limits]]
133
+ pattern = "^/api/"
134
+ limit = 60
135
+ period = "1m"
136
+ ```
137
+
138
+ Mothership keeps the counts in memory, with no cache-store write per request,
139
+ and answers `429` with `Retry-After`. Allowlists move to
140
+ `[[mothership.ip_allowlist]]`; see the Mothership README for both.
141
+
142
+ ## 6. Behind a CDN or a proxy
143
+
144
+ Behind Cloudflare, Kamal proxy or a load balancer, tell Mothership which
145
+ proxies to see through, so allowlists and rate limits apply to the visitor,
146
+ not to the proxy:
147
+
148
+ ```toml
149
+ [mothership]
150
+ trusted_proxies = ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"] # + your CDN's ranges
151
+ ```
152
+
153
+ The app's `REMOTE_ADDR` is the address that connected to Mothership (or the
154
+ PROXY-protocol one, with `proxy_protocol = true` on the bind), and the
155
+ forwarding headers pass through. Rails resolves `request.remote_ip` from them
156
+ as it always has: keep the configuration you need for that today (for
157
+ Cloudflare, `cloudflare-rails`).
158
+
159
+ ## 7. Caching
160
+
161
+ Mothership can cache whole responses in memory, the way a CDN does, purged by
162
+ tag when the data changes:
163
+
164
+ ```toml
165
+ [mothership]
166
+ metrics_port = 9090 # also serves the purge endpoint, on 127.0.0.1
167
+
168
+ [mothership.response_cache]
169
+ status_header = true # Cache-Status on responses
170
+
171
+ [[mothership.response_cache.rules]]
172
+ pattern = "^/api/"
173
+ ttl = "5m"
174
+ stale = "1m"
175
+ bypass_cookies = ["_myapp_session"] # signed-in users skip the cache
176
+ ```
177
+
178
+ ```ruby
179
+ class BooksController < ApplicationController
180
+ def show
181
+ @book = Book.find(params[:id])
182
+ Shuttlebay::Cache.tag(response.headers, "book-#{@book.id}")
183
+ end
184
+ end
185
+
186
+ class Book < ApplicationRecord
187
+ after_commit { Shuttlebay::Cache.purge(tags: ["book-#{id}"]) }
188
+ end
189
+ ```
190
+
191
+ A successful `POST`/`PUT`/`PATCH`/`DELETE` through Mothership already
192
+ invalidates its own URL. Requests with `Authorization`, or with a cookie a rule
193
+ does not let through, never touch a rule's cache. The README's caching section
194
+ covers the rest.
195
+
196
+ ## 8. TLS and HTTP/2
197
+
198
+ Behind a CDN or Kamal proxy, they terminate TLS and speak HTTP/2 to browsers;
199
+ Mothership listens on plain HTTP behind them, and nothing here is needed.
200
+
201
+ To terminate TLS in Mothership itself (guardship 0.2.1 and later), get a
202
+ certificate first, then add a TLS bind.
203
+
204
+ **The certificate.** Mothership serves `public/`, so certbot's webroot mode
205
+ works while the app runs on plain HTTP:
206
+
207
+ ```bash
208
+ mkdir -p public/.well-known/acme-challenge # create it before certbot runs
209
+ certbot certonly --webroot -w ./public -d example.com -d www.example.com
210
+ ```
211
+
212
+ Create `.well-known` beforehand: Mothership skips the filesystem for
213
+ top-level names it has not seen in `public/` (it re-lists the directory
214
+ about once a second), so one certbot creates on the spot can miss the
215
+ validation request. One certificate can name every domain (`-d` repeated).
216
+
217
+ **The binds.**
218
+
219
+ ```toml
220
+ [mothership.bind]
221
+ http = "0.0.0.0:80"
222
+ https = { addr = "0.0.0.0:443", tls = { cert = "/etc/letsencrypt/live/example.com/fullchain.pem", key = "/etc/letsencrypt/live/example.com/privkey.pem" } }
223
+
224
+ [[bays.http]]
225
+ name = "web"
226
+ # command, args, workers, threads as before
227
+ routes = [
228
+ { bind = "http", pattern = "/.*" },
229
+ { bind = "https", pattern = "/.*" },
230
+ ]
231
+ ```
232
+
233
+ ```ruby
234
+ # config/environments/production.rb
235
+ config.force_ssl = true # redirects HTTP to HTTPS, sends HSTS, secures cookies
236
+ ```
237
+
238
+ - Browsers get HTTP/2 (negotiated over ALPN). On the TLS bind the app sees
239
+ `rack.url_scheme = "https"` and `HTTPS=on`, so `force_ssl` and
240
+ `request.ssl?` work with no `assume_ssl` or forwarded headers.
241
+ - Renewals are picked up without a restart, within 30 s of certbot writing
242
+ them. A renewal that does not load is logged; the old one keeps serving.
243
+ - Let's Encrypt keys are readable by root only: run with access to them, or
244
+ have a certbot `--deploy-hook` copy the pair where the app's user can read
245
+ it. Ports 80 and 443 need `setcap cap_net_bind_service=+ep` on the binary,
246
+ `AmbientCapabilities=CAP_NET_BIND_SERVICE` under systemd, or a container.
247
+
248
+ From guardship 0.3, Mothership can also redirect HTTP to HTTPS itself
249
+ (`http = { addr = "0.0.0.0:80", https_redirect = true }`, ACME challenges
250
+ left on HTTP) and serve a certificate per domain on one bind
251
+ (`tls = [{ cert, key }, ...]`, picked by SNI); see the Mothership README.
252
+
253
+ ## 9. Docker and Kamal
254
+
255
+ Mothership replaces `./bin/thrust ./bin/rails server` in the Dockerfile Rails
256
+ generates:
257
+
258
+ ```dockerfile
259
+ EXPOSE 80
260
+ CMD ["bundle", "exec", "mothership"]
261
+ ```
262
+
263
+ with the bind on port 80 (`http = "0.0.0.0:80"`), where kamal-proxy expects
264
+ the app. Rails' `bin/docker-entrypoint` prepares the database only when the
265
+ command is `./bin/rails server`, so run that as a prelaunch job instead:
266
+
267
+ ```toml
268
+ [[mothership.prelaunch]]
269
+ name = "db-prepare"
270
+ command = "bin/rails"
271
+ args = ["db:prepare"]
272
+ ```
273
+
274
+ ```yaml
275
+ # config/deploy.yml
276
+ proxy:
277
+ host: app.example.com
278
+ ssl: true
279
+ healthcheck:
280
+ path: /up
281
+ ```
282
+
283
+ Mothership runs fine as PID 1: on Linux it reaps and forwards signals itself
284
+ (`docker run --init` is still the safer default elsewhere). Kamal deploys by
285
+ starting a new container and moving traffic to it once `/up` answers, so
286
+ phased restarts (`kill -USR1`) are for servers you deploy to in place.
287
+
288
+ On several hosts:
289
+
290
+ - Run prelaunch jobs (migrations) once: tag one host and elect it.
291
+
292
+ ```yaml
293
+ servers:
294
+ web:
295
+ - 10.0.0.5: flagship
296
+ - 10.0.0.6
297
+ env:
298
+ tags:
299
+ flagship:
300
+ MS_FLAGSHIP: "true"
301
+ ```
302
+
303
+ ```toml
304
+ [mothership.flagship]
305
+ enabled = true
306
+ election = "static"
307
+ static_flagship = "$MS_FLAGSHIP"
308
+ ```
309
+
310
+ - With a response cache, let the hosts relay purges and invalidations to one
311
+ another (`[mothership.response_cache.peers]` in the Mothership README).
312
+
313
+ ## 10. Watching it run
314
+
315
+ - `bundle exec mothership health` prints the fleet's health as JSON (needs
316
+ `metrics_port`); `/metrics` serves Prometheus metrics, `mothership_http_bay_*`
317
+ among them.
318
+ - Both Mothership and Shuttlebay log JSON lines to stdout.
319
+ - `503 Starting`: the bay is still booting (`boot_timeout`, 120 s).
320
+ - `503` once running: every thread was busy for `queue_timeout`; add
321
+ `threads` (I/O-bound apps) or `workers` (CPU-bound ones).
322
+ - `504`: no response head within `request_timeout` (60 s); the stuck worker
323
+ is recycled.
@@ -1,6 +1,6 @@
1
1
  [package]
2
2
  name = "shuttlebay"
3
- version = "0.1.4" # x-release-please-version
3
+ version = "0.2.1" # x-release-please-version
4
4
  edition.workspace = true
5
5
  rust-version.workspace = true
6
6
  license.workspace = true
@@ -25,7 +25,7 @@ expect_used = "deny"
25
25
 
26
26
  [dependencies]
27
27
  magnus = { version = "0.9", features = ["bytes"] }
28
- rb-sys = "0.9.124"
29
- mothership-docking-protocol = "0.2.0"
28
+ rb-sys = "0.9.130"
29
+ mothership-docking-protocol = "0.3.0"
30
30
  serde_json = "1.0"
31
- state-machines = "0.30"
31
+ state-machines = "0.35"