shuttlebay 0.1.4 → 0.2.0

data/ext/shuttlebay/src/codec.rs

@@ -1,16 +1,18 @@
 use std::{cell::RefCell, fmt::Display};
 
-use magnus::{Error, RHash, RString, Ruby, Symbol, Value, prelude::*, scan_args::scan_args};
+use magnus::{
+    Error, RArray, RHash, RString, Ruby, Symbol, Value, prelude::*, scan_args::scan_args,
+};
 use mothership_docking_protocol::{
-    Dock, HAUL_CHUNK_LEN, Hail, MAX_FRAME_PAYLOAD, MessageType, Moored, ProtocolError, Reply,
-    ReplyBody, VERSION, decode_hail, decode_haul, decode_header, encode_dock, encode_ready,
-    encode_reply, push_haul,
+    Dock, HAUL_CHUNK_LEN, Hail, MAX_FRAME_PAYLOAD, MessageType, Moored, Pair, ProtocolError, Reply,
+    ReplyBody, VERSION, decode_hail, decode_haul, decode_header, encode_dock, encode_haul_header,
+    encode_ready, encode_reply, push_haul,
 };
 
 use crate::{
-    OrProtocolError, headers,
+    OrProtocolError, headers, interned,
     link::{self, LinkEvent, LinkState},
-    protocol_error, spool_file, string_io,
+    null_input, protocol_error, spool_file, string_io,
 };
 
 const READ_CHUNK: usize = 64 * 1024;
@@ -19,6 +21,17 @@ pub const SPOOL_THRESHOLD: u64 = 1024 * 1024;
 
 const MAX_BODY: u64 = 4 * 1024 * 1024 * 1024;
 
+/// CGI params whose values come from a small set and that apps replace
+/// rather than mutate: each value is one shared frozen String.
+const SHARED_VALUES: [&[u8]; 6] = [
+    b"REQUEST_METHOD",
+    b"SCRIPT_NAME",
+    b"SERVER_PORT",
+    b"SERVER_PROTOCOL",
+    b"SERVER_SOFTWARE",
+    b"HTTPS",
+];
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 enum Kind {
     Empty,
@@ -101,13 +114,17 @@ impl Codec {
 
         let env: RHash = template.funcall("dup", ())?;
         for (name, value) in &hail.params {
-            let name = std::str::from_utf8(name)
-                .map_or_else(|_| ruby.str_from_slice(name), |name| ruby.str_new(name));
-            env.aset(name, ruby.str_from_slice(value))?;
+            let value = if shares_value(name, value) {
+                interned::value(ruby, value)?
+            } else {
+                ruby.str_from_slice(value)
+            };
+            env.aset(interned::key(ruby, name)?, value)?;
         }
         let secure = hail.params.iter().any(|(name, value)| name == b"HTTPS" && value == b"on");
-        env.aset("rack.url_scheme", if secure { "https" } else { "http" })?;
-        env.aset("rack.input", input)?;
+        let scheme: &[u8] = if secure { b"https" } else { b"http" };
+        env.aset(interned::key(ruby, b"rack.url_scheme")?, interned::value(ruby, scheme)?)?;
+        env.aset(interned::key(ruby, b"rack.input")?, input)?;
 
         rb_self.try_with_state(ruby, |state| link::begin(&mut state.link, hail.request_id))?;
         Ok(Some(env))
@@ -122,10 +139,7 @@ impl Codec {
         let (path,) = args.optional;
         let path = path.flatten();
 
-        let status =
-            u16::try_from(status).ok().filter(|status| (100..=599).contains(status)).ok_or_else(
-                || Error::new(ruby.exception_arg_error(), format!("invalid HTTP status: {status}")),
-            )?;
+        let status = http_status(ruby, status)?;
         let kind = match kind.name()?.as_ref() {
             "empty" => Kind::Empty,
             "stream" => Kind::Stream,
@@ -161,20 +175,66 @@ impl Codec {
             Kind::Tunnel => LinkEvent::ReplyTunnel,
         };
         rb_self.try_with_state(ruby, |state| -> Result<(), &str> {
-            let (request_id, _) = link::advance(&mut state.link, event, |from| {
-                if from == LinkState::Idle {
-                    "reply called without a request"
-                } else {
-                    "reply already sent for this request"
-                }
-            })?;
-            let frame = encode_reply(&Reply { request_id, status, headers, body })
-                .map_err(|_| "reply head exceeds the frame size limit")?;
-            state.outbox.extend_from_slice(&frame);
-            Ok(())
+            push_reply(state, event, status, headers, body).map(drop)
         })
     }
 
+    /// Send a whole response at once: Reply head, body and FIN leave in one
+    /// write, so Mothership always lands it as a complete body. A single chunk
+    /// (a rendered page) is handed to the socket as is, never copied into a
+    /// frame buffer; several are framed together.
+    pub fn reply_whole(
+        ruby: &Ruby,
+        rb_self: &Self,
+        io: Value,
+        status: i64,
+        headers: RHash,
+        chunks: RArray,
+    ) -> Result<(), Error> {
+        let status = http_status(ruby, status)?;
+        let headers = headers::flatten(ruby, headers)?;
+        // Checked before the link moves, so a bad body still gets a 500.
+        for index in 0..chunks.len() {
+            body_chunk(ruby, chunks, index)?;
+        }
+        let only = (chunks.len() == 1)
+            .then(|| body_chunk(ruby, chunks, 0))
+            .transpose()?
+            .filter(|chunk| chunk.len() <= HAUL_CHUNK_LEN);
+
+        let request_id = rb_self.try_with_state(ruby, |state| {
+            push_reply(state, LinkEvent::ReplyStream, status, headers, ReplyBody::Stream)
+        })?;
+
+        if let Some(chunk) = only {
+            rb_self.try_with_state(ruby, |state| -> Result<(), &str> {
+                let haul = encode_haul_header(request_id, true, chunk.len())
+                    .map_err(|_| "body chunk exceeds the frame size limit")?;
+                state.outbox.extend_from_slice(&haul);
+                finish_stream(state)
+            })?;
+            let head = rb_self.with_state(ruby, |state| std::mem::take(&mut state.outbox))?;
+            // A tuple keeps both Strings on the stack, visible to the GC,
+            // for the whole write.
+            let _: Value = io.funcall("write", (ruby.str_from_slice(&head), chunk))?;
+            return Ok(());
+        }
+
+        for index in 0..chunks.len() {
+            let bytes = body_chunk(ruby, chunks, index)?.to_bytes();
+            rb_self.try_with_state(ruby, |state| {
+                push_body(&mut state.outbox, request_id, &bytes, false)
+                    .map_err(|_| "body chunk exceeds the frame size limit")
+            })?;
+        }
+        rb_self.try_with_state(ruby, |state| -> Result<(), &str> {
+            push_haul(&mut state.outbox, request_id, true, &[])
+                .map_err(|_| "FIN frame could not be encoded")?;
+            finish_stream(state)
+        })?;
+        rb_self.flush_to(ruby, io)
+    }
+
     pub fn write(ruby: &Ruby, rb_self: &Self, io: Value, chunk: RString) -> Result<(), Error> {
         let chunk = chunk.to_bytes();
         let pending = rb_self.try_with_state(ruby, |state| -> Result<_, &str> {
@@ -326,6 +386,9 @@ impl Codec {
             "request body of {} bytes exceeds the engine limit",
             hail.content_length
         );
+        if hail.content_length == 0 {
+            return null_input(ruby);
+        }
         let expected = usize::try_from(hail.content_length)
             .map_err(|_| protocol_error(ruby, "request body does not fit in memory"))?;
         let mut sink = if hail.content_length > SPOOL_THRESHOLD {
@@ -333,9 +396,7 @@ impl Codec {
         } else {
             BodySink::Memory(Vec::with_capacity(expected))
         };
-        if expected > 0 {
-            self.receive_body(ruby, io, hail, expected, &mut sink)?;
-        }
+        self.receive_body(ruby, io, hail, expected, &mut sink)?;
         sink.into_input(ruby)
     }
 
@@ -447,6 +508,56 @@ impl BodySink {
     }
 }
 
+fn http_status(ruby: &Ruby, status: i64) -> Result<u16, Error> {
+    u16::try_from(status).ok().filter(|status| (100..=599).contains(status)).ok_or_else(|| {
+        Error::new(ruby.exception_arg_error(), format!("invalid HTTP status: {status}"))
+    })
+}
+
+fn shares_value(name: &[u8], value: &[u8]) -> bool {
+    SHARED_VALUES.contains(&name) || (name == b"QUERY_STRING" && value.is_empty())
+}
+
+/// Body chunk `index`: Rack bodies yield Strings, nothing else.
+fn body_chunk(ruby: &Ruby, chunks: RArray, index: usize) -> Result<RString, Error> {
+    let offset = isize::try_from(index)
+        .map_err(|_| Error::new(ruby.exception_range_error(), "body array too long"))?;
+    let chunk: Value = chunks.entry(offset)?;
+    RString::from_value(chunk).ok_or_else(|| {
+        Error::new(
+            ruby.exception_type_error(),
+            format!("body chunk must be a String, got {}", chunk.class().inspect()),
+        )
+    })
+}
+
+/// Move the link past its Reply and queue the Reply head; the request id is
+/// what the body frames must carry.
+fn push_reply(
+    state: &mut State,
+    event: LinkEvent,
+    status: u16,
+    headers: Vec<Pair>,
+    body: ReplyBody,
+) -> Result<u32, &'static str> {
+    let (request_id, _) = link::advance(&mut state.link, event, |from| {
+        if from == LinkState::Idle {
+            "reply called without a request"
+        } else {
+            "reply already sent for this request"
+        }
+    })?;
+    let frame = encode_reply(&Reply { request_id, status, headers, body })
+        .map_err(|_| "reply head exceeds the frame size limit")?;
+    state.outbox.extend_from_slice(&frame);
+    Ok(request_id)
+}
+
+/// A streamed body is complete: the link waits for `ready`.
+fn finish_stream(state: &mut State) -> Result<(), &'static str> {
+    link::advance(&mut state.link, LinkEvent::Finish, |_| "finish called twice").map(drop)
+}
+
 fn push_body(
     outbox: &mut Vec<u8>,
     request_id: u32,

data/ext/shuttlebay/src/interned.rs

@@ -0,0 +1,93 @@
+//! Frozen, interned Strings for env keys and a few fixed CGI values, so each
+//! request's env reuses them instead of allocating one String per param.
+//!
+//! The table only grows, and only up to [`CAPACITY`] entries per kind: header
+//! names reach it from clients, and past the cap a name gets a fresh String,
+//! as without the table. Every interned String is kept alive by one rooted
+//! Array; the table holds no lock while it calls into Ruby, since a Ruby call
+//! can switch threads and another thread's lookup would then deadlock.
+
+use std::{
+    collections::HashMap,
+    sync::{LazyLock, Mutex, OnceLock, PoisonError},
+};
+
+use magnus::{Error, RArray, RString, Ruby, value::Opaque};
+
+use crate::OrProtocolError;
+
+const CAPACITY: usize = 1024;
+
+#[derive(Default)]
+struct Table {
+    /// Env keys: UTF-8 when the name is, binary otherwise
+    keys: HashMap<Box<[u8]>, Opaque<RString>>,
+    /// Env values: binary, like every other param value
+    values: HashMap<Box<[u8]>, Opaque<RString>>,
+}
+
+#[derive(Clone, Copy)]
+enum Kind {
+    Key,
+    Value,
+}
+
+impl Table {
+    const fn strings(&mut self, kind: Kind) -> &mut HashMap<Box<[u8]>, Opaque<RString>> {
+        match kind {
+            Kind::Key => &mut self.keys,
+            Kind::Value => &mut self.values,
+        }
+    }
+}
+
+static TABLE: LazyLock<Mutex<Table>> = LazyLock::new(Mutex::default);
+static ROOT: OnceLock<Opaque<RArray>> = OnceLock::new();
+
+/// Create the Array that keeps interned Strings alive. Called once, at load.
+pub fn init(ruby: &Ruby) {
+    let root = ruby.ary_new();
+    ruby.gc_register_mark_object(root);
+    crate::cache(&ROOT, root);
+}
+
+/// The env key for a param name.
+pub fn key(ruby: &Ruby, name: &[u8]) -> Result<RString, Error> {
+    intern(ruby, Kind::Key, name)
+}
+
+/// A shared, frozen param value.
+pub fn value(ruby: &Ruby, value: &[u8]) -> Result<RString, Error> {
+    intern(ruby, Kind::Value, value)
+}
+
+fn intern(ruby: &Ruby, kind: Kind, bytes: &[u8]) -> Result<RString, Error> {
+    if let Some(found) = lock().strings(kind).get(bytes) {
+        return Ok(ruby.get_inner(*found));
+    }
+
+    let fresh = match kind {
+        Kind::Key => std::str::from_utf8(bytes)
+            .map_or_else(|_| ruby.str_from_slice(bytes), |name| ruby.str_new(name)),
+        Kind::Value => ruby.str_from_slice(bytes),
+    };
+    let interned = fresh.to_interned_str();
+
+    let mut table = lock();
+    let strings = table.strings(kind);
+    if strings.len() >= CAPACITY || strings.contains_key(bytes) {
+        return Ok(interned);
+    }
+    strings.insert(bytes.into(), Opaque::from(interned));
+    drop(table);
+
+    let root = ROOT.get().ok_or("interned strings were not initialised").or_protocol_error(ruby)?;
+    ruby.get_inner(*root).push(interned)?;
+    Ok(interned)
+}
+
+/// The table holds plain maps that stay consistent even if a holder
+/// panicked, so a poisoned lock is still safe to use.
+fn lock() -> std::sync::MutexGuard<'static, Table> {
+    TABLE.lock().unwrap_or_else(PoisonError::into_inner)
+}

data/ext/shuttlebay/src/lib.rs

@@ -15,6 +15,7 @@ macro_rules! ensure {
 
 mod codec;
 mod headers;
+mod interned;
 mod link;
 
 use codec::Codec;
@@ -22,6 +23,7 @@ use codec::Codec;
 static PROTOCOL_ERROR: OnceLock<Opaque<ExceptionClass>> = OnceLock::new();
 static STRING_IO: OnceLock<Opaque<RClass>> = OnceLock::new();
 static ENGINE: OnceLock<Opaque<RModule>> = OnceLock::new();
+static NULL_INPUT: OnceLock<Opaque<Value>> = OnceLock::new();
 
 pub(crate) fn protocol_error(ruby: &Ruby, message: impl Into<String>) -> Error {
     let class = cached(ruby, &PROTOCOL_ERROR).unwrap_or_else(|| ruby.exception_runtime_error());
@@ -42,6 +44,18 @@ pub(crate) fn spool_file(ruby: &Ruby) -> Result<Value, Error> {
     initialised(ruby, &ENGINE, "Shuttlebay::Engine was not initialised")?.funcall("spool_file", ())
 }
 
+/// `Shuttlebay::Engine::NULL_INPUT`, the `rack.input` of every bodiless
+/// request. Defined in Ruby after this library loads, so resolved on first use.
+pub(crate) fn null_input(ruby: &Ruby) -> Result<Value, Error> {
+    if let Some(input) = cached(ruby, &NULL_INPUT) {
+        return Ok(input);
+    }
+    let engine = initialised(ruby, &ENGINE, "Shuttlebay::Engine was not initialised")?;
+    let input: Value = engine.const_get("NULL_INPUT")?;
+    cache(&NULL_INPUT, input);
+    Ok(input)
+}
+
 pub(crate) fn string_io(ruby: &Ruby) -> Result<RClass, Error> {
     initialised(ruby, &STRING_IO, "StringIO was not resolved at load time")
 }
@@ -65,6 +79,7 @@ fn initialised<T: ReprValue>(
 #[magnus::init(name = "shuttlebay")]
 fn init(ruby: &Ruby) -> Result<(), Error> {
     ruby.require("stringio")?;
+    interned::init(ruby);
     cache(&STRING_IO, ruby.class_object().const_get::<_, RClass>("StringIO")?);
 
     let shuttlebay = ruby.define_module("Shuttlebay")?;
@@ -82,6 +97,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     codec.define_method("dock", method!(Codec::dock, 3))?;
     codec.define_method("read_request", method!(Codec::read_request, 2))?;
     codec.define_method("reply", method!(Codec::reply, -1))?;
+    codec.define_method("reply_whole", method!(Codec::reply_whole, 4))?;
     codec.define_method("write", method!(Codec::write, 2))?;
     codec.define_method("flush", method!(Codec::flush, 1))?;
     codec.define_method("finish", method!(Codec::finish, 1))?;

data/lib/shuttlebay/cache.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+module Shuttlebay
+  # Mothership's edge cache, from the app: tag responses with the data they
+  # show, and purge the tags when that data changes, so entries live until
+  # purged instead of until a guessed TTL runs out.
+  #
+  #   # in a controller
+  #   Shuttlebay::Cache.tag(response.headers, "book-#{@book.id}", 'books')
+  #   # in a model
+  #   after_commit { Shuttlebay::Cache.purge(tags: ["book-#{id}", 'books']) }
+  #
+  # Purging works from any process Mothership runs (web workers, job
+  # workers): it posts to the admin endpoint in MS_ADMIN_URL, which
+  # Mothership sets when it has a metrics port.
+  module Cache
+    HEADER = 'cache-tag'
+
+    module_function
+
+    # Add `tags` to the response's Cache-Tag (Mothership keeps it from clients).
+    def tag(headers, *tags)
+      tags = tags.flatten.map { |tag| tag.to_s.strip }.reject(&:empty?)
+      return headers if tags.empty?
+
+      headers[HEADER] = [headers[HEADER], *tags].compact.reject(&:empty?).join(', ')
+      headers
+    end
+
+    # Purge the entries tagged with any of `tags`, for any of `urls` (path and
+    # query), under any of `prefixes`, or `all`. `soft: true` marks them stale
+    # instead: still served while one request refreshes them. Returns how many
+    # were purged; nil outside Mothership (no MS_ADMIN_URL), where there is no
+    # cache to purge. A purge Mothership refuses raises Shuttlebay::Error.
+    def purge(tags: [], urls: [], prefixes: [], all: false, soft: false, admin_url: ENV.fetch('MS_ADMIN_URL', nil),
+              timeout: 2)
+      params = Array(tags).map { |tag| ['tag', tag.to_s] } + Array(urls).map { |url| ['url', url.to_s] } +
+               Array(prefixes).map { |prefix| ['prefix', prefix.to_s] }
+      params << %w[all true] if all
+      raise ArgumentError, 'purge needs tags, urls, prefixes or all: true' if params.empty?
+      return nil if admin_url.nil? || admin_url.empty?
+
+      params << %w[soft true] if soft
+      post_purge(URI.join(admin_url, '/cache/purge').tap { |uri| uri.query = URI.encode_www_form(params) }, timeout)
+    end
+
+    def post_purge(uri, timeout)
+      response = Net::HTTP.start(uri.host, uri.port, open_timeout: timeout, read_timeout: timeout) do |http|
+        http.post(uri.request_uri, '')
+      end
+      raise Error, "cache purge failed: #{response.code} #{response.body}" unless response.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(response.body).fetch('purged')
+    end
+    private_class_method :post_purge
+  end
+end

data/lib/shuttlebay/engine.rb

@@ -19,5 +19,30 @@ module Shuttlebay
     def self.spool_file
       Tempfile.new('shuttlebay-body', binmode: true).tap(&:unlink)
     end
+
+    # The rack.input of a request without a body, like Puma's NullIO: always
+    # at EOF and stateless, so one frozen instance serves every request.
+    class NullInput
+      def gets = nil
+      def each = nil
+      def rewind = 0
+      def close = nil
+      def closed? = false
+      def eof? = true
+      def size = 0
+      def string = ''
+
+      def read(length = nil, buffer = nil)
+        raise ArgumentError, "negative length #{length} given" if length&.negative?
+
+        buffer = buffer.nil? ? +''.b : String.try_convert(buffer)
+        raise TypeError, 'buffer must be a String' unless buffer
+
+        buffer.clear
+        length&.positive? ? nil : buffer
+      end
+    end
+
+    NULL_INPUT = NullInput.new.freeze
   end
 end

data/lib/shuttlebay/handler.rb

@@ -74,11 +74,15 @@ module Shuttlebay
     def respond(io, codec, env, status, headers, body)
       head_sent = false
       kind, path = reply_kind(env, status, body)
-      chunks = body.to_ary if kind == :stream && body.respond_to?(:to_ary)
+      if kind == :stream && body.respond_to?(:to_ary)
+        # The whole body is in hand: head, body and FIN leave in one write.
+        codec.reply_whole(io, status, headers, body.to_ary)
+        return [true, nil]
+      end
 
       codec.reply(io, status, headers, kind, path)
       head_sent = true
-      write_body(io, codec, body, chunks) if kind == :stream
+      write_body(io, codec, body) if kind == :stream
       codec.finish(io)
       [true, nil]
     rescue *LINK_LOST => e
@@ -100,10 +104,8 @@ module Shuttlebay
       [:stream, nil]
     end
 
-    def write_body(io, codec, body, chunks)
-      if chunks
-        chunks.each { |chunk| codec.write(io, chunk) }
-      elsif body.respond_to?(:each)
+    def write_body(io, codec, body)
+      if body.respond_to?(:each)
         body.each do |chunk|
           codec.write(io, chunk)
           codec.flush(io)

data/lib/shuttlebay/logger.rb

@@ -16,6 +16,11 @@ module Shuttlebay
       define_method(level) { |msg, **fields| log(level, msg, **fields) }
     end
 
+    # This logger as `ship`'s: same stream, another ship name.
+    def for_ship(ship)
+      ship == @ship ? self : self.class.new(@io, ship: ship)
+    end
+
     def log(level, msg, **fields)
       line = JSON.generate({ level: level, msg: msg, ship: @ship, pid: Process.pid, **fields })
       @io.write("#{line}\n")

data/lib/shuttlebay/railtie.rb

@@ -1,11 +1,52 @@
 # frozen_string_literal: true
 
+require 'json'
 require 'rack/sendfile'
 
 module Shuttlebay
+  # Under Mothership, some of a Rails app's middleware repeats work Mothership
+  # already does for its HTTP bays: the app's copy is removed. Other servers
+  # (rails server, Puma) keep the full stack.
+  #
+  # - Rack::Sendfile: Mothership serves `to_path` bodies itself.
+  # - ActionDispatch::Static: when Mothership serves the app's public/ at `/`
+  #   for everything routed to the bay (it lists those in MS_STATIC_ROOTS).
+  #   The app's `public_file_server.headers` Mothership does not send (per
+  #   MS_STATIC_HEADERS) are logged: they belong in the manifest now.
+  # - Rack::ETag, Rack::ConditionalGet: when Mothership tags responses and
+  #   answers revalidations (MS_CONDITIONAL_GET=1), off the app's GVL.
   class Railtie < ::Rails::Railtie
     initializer 'shuttlebay.mothership_serves_files' do |app|
-      app.config.middleware.delete(::Rack::Sendfile) if Shuttlebay.running?
+      next unless Shuttlebay.running?
+
+      middleware = app.config.middleware
+      middleware.delete(::Rack::Sendfile) if Shuttlebay.offloaded?(:sendfile)
+      public = app.paths['public'].first
+      if Shuttlebay.offloaded?(:static, public)
+        middleware.delete(::ActionDispatch::Static)
+        Shuttlebay::Railtie.warn_unsent_headers(public, app.config.public_file_server.headers)
+      end
+      if Shuttlebay.offloaded?(:conditional_get)
+        middleware.delete(::Rack::ETag)
+        middleware.delete(::Rack::ConditionalGet)
+      end
+    end
+
+    # The app's `headers` for public/ files that Mothership, serving them
+    # now, does not send as given; logged once, at boot.
+    def self.warn_unsent_headers(public, headers, announced = ENV.fetch('MS_STATIC_HEADERS', '{}'))
+      unsent = unsent_headers(public, headers, announced)
+      return if unsent.empty?
+
+      Shuttlebay.logger.warn('public_file_server.headers are not sent by Mothership, which serves public/; ' \
+                             'add them to the [[mothership.static_dirs]] headers', missing: unsent)
+    end
+
+    def self.unsent_headers(public, headers, announced)
+      sent = JSON.parse(announced).fetch(File.realpath(public), {})
+      (headers || {}).to_h { |name, value| [name.to_s.downcase, value.to_s] }.reject { |name, value| sent[name] == value }
+    rescue JSON::ParserError, SystemCallError
+      (headers || {}).to_h { |name, value| [name.to_s.downcase, value.to_s] }
     end
   end
 end

data/lib/shuttlebay/runtime.rb

@@ -13,12 +13,16 @@ module Shuttlebay
   class << self
     attr_accessor :config
 
-    attr_writer :running, :logger
+    attr_writer :running, :logger, :warmup
 
     def running?
       @running == true
     end
 
+    def warmup?
+      @warmup != false
+    end
+
     def logger
       @logger ||= Logger.new
     end
@@ -51,8 +55,46 @@ module Shuttlebay
       @fiber_scheduler_factory = factory
     end
 
-    def run_hooks(name, *)
-      hooks.fetch(name).each { |hook| hook.call(*) }
+    # Run `name`'s hooks with `args`, each given only as many as it takes:
+    # `on_worker_boot { |index| }` and `{ |index, ship| }` both work, lambdas
+    # and methods included.
+    def run_hooks(name, *args)
+      hooks.fetch(name).each do |hook|
+        hook.call(*(hook.arity.negative? ? args : args.first(hook.arity)))
+      end
+    end
+
+    # Whether Mothership does `concern` for this app, so its Rack middleware
+    # for it can go (the Railtie does this for Rails; elsewhere, in
+    # config.ru):
+    #
+    #   use Rack::ETag unless Shuttlebay.offloaded?(:conditional_get)
+    #   use Rack::Static, urls: [""], root: "public" unless Shuttlebay.offloaded?(:static, "public")
+    #
+    # - :sendfile: `to_path` bodies are streamed by Mothership (Rack::Sendfile)
+    # - :conditional_get: ETags and 304s (Rack::ETag, Rack::ConditionalGet)
+    # - :static, dir: `dir` is served at `/`, pages by name included
+    #   (Rack::Static, ActionDispatch::Static)
+    #
+    # Always false outside Mothership.
+    def offloaded?(concern, dir = nil)
+      return false unless running?
+
+      case concern
+      when :sendfile then true
+      when :conditional_get then ENV['MS_CONDITIONAL_GET'] == '1'
+      when :static then static_root?(dir)
+      else raise ArgumentError, "unknown concern #{concern.inspect} (:sendfile, :conditional_get, :static)"
+      end
+    end
+
+    # Whether Mothership serves `dir` at `/` (it lists those in MS_STATIC_ROOTS).
+    def static_root?(dir, roots = ENV.fetch('MS_STATIC_ROOTS', ''))
+      raise ArgumentError, 'Shuttlebay.offloaded?(:static, dir) needs the directory' if dir.nil?
+
+      roots.split("\n").include?(File.realpath(dir))
+    rescue SystemCallError
+      false
     end
 
     def clear_hooks!