tonic-rails 0.3.0-x86_64-linux-gnu → 0.5.0-x86_64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b594b6ba6699510bedb286cab5e05fc8fa3578d200fdb704fd8335529ee0105
-  data.tar.gz: df3ddc7f65ca300dce59a26855fcadfd88f573c9f892039afa727ec16a3dc01e
+  metadata.gz: 5aa7de65014581bfcd5575510bdcd6ec9ec4bd0ab81473e49077188093ff436a
+  data.tar.gz: eaf8038cfa3d9b62e16d575b4e56001bb9873cdc30ed19f9ab43967869d907f5
 SHA512:
-  metadata.gz: 0d8da9f21bc78c95c31b708a0349d54f23e9a5395bad4de0d46937ec1fae721bd6590a74d498dd523e087b1a1c90b23af6a10c93f2cfaab262d554e3c74272a0
-  data.tar.gz: a67219c39168b2eeae48a638b73ebdfa65a4c5a0300138577088f214868db989e36196647639753563584e49dfb256da0175f2b13aac0b8526d30cb9cee38f44
+  metadata.gz: cc4417d8c41fb9fb0e363ffb0605ac745d9b564e63a413b7b86e6d2d8a0c861f035f2553a6df8602466ead880cd58d1cc50bfc798536e97bc967d67b7b107b0f
+  data.tar.gz: 484f38fa65491cf4e34e32e30e35af03ee7b5de3e354b33e4c23fbbe1df50b55a7dc9d19411f59ef1db04767fca9eb69d90facdae940e79f4f0cd6f92c77700c

data/CHANGELOG.md

@@ -7,6 +7,35 @@ minor versions may contain breaking changes.
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-11
+
+### Added
+
+- Multi-process mode: `config.processes = 4` runs four server processes
+  on one port, so services that spend their time in Ruby use four cores
+  instead of one. The app loads once and forks the workers. They share
+  the listening socket, with new connections going to the least busy
+  worker. Workers that die are replaced, and SIGTERM drains them all.
+  `on_worker_boot` runs in each worker after fork. Works with
+  `tonic_rails:serve` and the Puma plugin; Unix only. Closes #23.
+- Benchmark: `PROCESSES` and `CONNECTIONS` for `bench/run_bench.sh`, and
+  `-connections` for the Go client.
+
+### Changed
+
+- The Puma plugin waits `drain_timeout` + 10 seconds (was + 5) for the
+  gRPC server to stop before killing it, which leaves a multi-process
+  server time to stop its own workers.
+
+## [0.4.0] - 2026-10-11
+
+### Added
+
+- gRPC-Web: `config.grpc_web = true` serves browser clients (unary and
+  server-streaming RPCs, binary and text encodings) without a proxy, on the
+  same port as native gRPC, with CORS via `grpc_web_origins`,
+  `grpc_web_allowed_headers` and `grpc_web_exposed_headers`. Closes #22.
+
 ## [0.3.0] - 2026-10-11
 
 ### Added
@@ -116,7 +145,9 @@ First public release.
 - Precompiled native gems for Linux (x86_64, aarch64; glibc and musl) and
   macOS (x86_64, arm64), Ruby 3.3 to 4.0.
 
-[Unreleased]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/CodingAnarchy/tonic-rails/releases/tag/v0.1.0

data/README.md

@@ -363,6 +363,44 @@ Tonic::Rails.configure do |config|
 end
 ```
 
+## Browser clients (gRPC-Web)
+
+Browsers can't speak native gRPC, but they can speak
+[gRPC-Web](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md).
+Turn it on and your existing handlers serve web frontends directly, with
+no Envoy or other proxy:
+
+```ruby
+Tonic::Rails.configure do |config|
+  config.grpc_web = true
+  config.grpc_web_origins = ["https://app.example.com"]   # CORS; omit for same-origin only
+  config.grpc_web_exposed_headers = %w[x-request-id]     # response metadata browsers may read
+end
+```
+
+Then call it from the browser with any gRPC-Web client, for example
+[Connect](https://connectrpc.com/docs/web/using-clients):
+
+```ts
+import { createClient } from "@connectrpc/connect";
+import { createGrpcWebTransport } from "@connectrpc/connect-web";
+import { ItemService } from "./gen/demo/v1/items_pb";
+
+const client = createClient(ItemService, createGrpcWebTransport({ baseUrl: "https://api.example.com" }));
+const item = await client.getItem({ id: 1n });
+```
+
+- Unary and server-streaming RPCs work; browsers can't do client or
+  bidirectional streaming.
+- Errors, response headers and trailers reach the browser as usual.
+- Native gRPC clients keep working on the same port. Enabling gRPC-Web
+  also accepts HTTP/1.1, which browsers use without TLS; over HTTPS they
+  negotiate HTTP/2.
+- `grpc_web_origins` sets CORS: listed origins may call with credentials
+  (cookies); `"*"` allows any origin without credentials (logged as a
+  warning). `grpc_web_allowed_headers` adds request headers beyond the
+  standard ones (`authorization` is already allowed).
+
 ## Testing handlers
 
 `Tonic::Rails::Testing` calls a handler in-process, with real protobuf
@@ -432,6 +470,8 @@ end
 |--------|---------|-------------|
 | `bind_address` | `"0.0.0.0:50051"` | Address to listen on |
 | `dispatch_threads` | `4` | Ruby threads running handlers; match your database pool |
+| `processes` | `1` | Server processes sharing the port (see [Threads or processes](#threads-or-processes)); Unix only |
+| `on_worker_boot` | `nil` | Callable run in each worker process after fork, given its index |
 | `dispatch_queue_size` | `128` | Calls that may wait for a thread; beyond this, `RESOURCE_EXHAUSTED` |
 | `worker_threads` | CPU count | Tokio threads for the transport |
 | `max_message_size` | 4 MiB | Request and response limit (also caps decompressed size) |
@@ -441,6 +481,9 @@ end
 | `tls_client_ca_path` | `nil` | PEM CA bundle; requires client certificates (mutual TLS) |
 | `drain_timeout` | `10` | Seconds to let in-flight calls finish on shutdown |
 | `keepalive_interval`, `keepalive_timeout` | `15`, `5` | HTTP/2 PING interval and timeout, seconds |
+| `grpc_web` | `false` | Serve gRPC-Web for browser clients (see [Browser clients](#browser-clients-grpc-web)) |
+| `grpc_web_origins` | `[]` | Browser origins allowed via CORS; `"*"` for any (no credentials) |
+| `grpc_web_allowed_headers`, `grpc_web_exposed_headers` | `[]` | Extra CORS request / response headers |
 | `health_check` | `nil` | Callable; while false or raising, health reports `NOT_SERVING` |
 | `health_check_interval` | `5` | Seconds between health checks |
 | `compression` | `false` | gzip responses over 1 KiB for clients that accept it |
@@ -449,14 +492,60 @@ end
 | `log_requests` | `false` | Log one line per call through `logger` (unexpected exceptions are always logged) |
 | `auto_start` | `false` | Start in a thread of `rails server`; for development (see [auto_start](#auto_start)) |
 
-### Sizing threads
+### Threads or processes
 
 Handlers run on `dispatch_threads` Ruby threads. Blocking I/O (database,
-HTTP) releases the GVL, so more threads means more concurrent I/O. CPU
-work does not parallelise within a process. Set threads to the
-concurrency your I/O needs, size the database pool to match, and add
-processes for CPU-heavy services: the listener uses `SO_REUSEPORT`, so
-several processes can bind the same port.
+HTTP) releases Ruby's global VM lock, so more threads means more
+concurrent I/O. Ruby code itself runs one thread at a time per process,
+though: a service that spends its time in Ruby (building large
+responses, serializing, computing) tops out at one core however many
+threads it has.
+
+So:
+
+- **Mostly waiting on I/O?** Add threads. They're cheap, and one process
+  goes a long way. Size the database pool to match.
+- **Mostly running Ruby?** Add processes. `processes = 4` runs four
+  copies of the server on the same port and uses four cores.
+
+```ruby
+config.tonic_rails.processes = ENV.fetch("GRPC_PROCESSES", 4).to_i
+config.tonic_rails.dispatch_threads = 5 # per process
+```
+
+Most services mix both. A reasonable start is one process per core and
+a handful of threads in each. Every process has its own database pool,
+so the database sees up to `processes × dispatch_threads` connections.
+
+With `processes` above 1, `bin/rails tonic_rails:serve` loads the app
+once and forks the workers, which share memory until they write to it.
+The process you started supervises them:
+
+- Workers share one listening socket, and a worker with fewer open
+  connections picks up new ones first. gRPC clients keep connections
+  open and send every call over them, so a single client connection
+  is served by a single worker: spread load with several connections
+  or several clients.
+- If a worker dies, it's logged and replaced.
+- SIGTERM or SIGINT to the supervisor drains every worker (health
+  reports `NOT_SERVING`, in-flight calls finish) and it exits once all
+  have stopped. Workers stop on their own if the supervisor disappears.
+- If a worker fails while starting (a bad configuration, say), the
+  server doesn't start.
+
+Active Record reconnects in each worker by itself. Reopen anything else
+that can't be shared across `fork` in `on_worker_boot`:
+
+```ruby
+config.tonic_rails.on_worker_boot = ->(index) { MyQueueClient.reconnect! }
+```
+
+Health checks, `health_check`, `serving!`, `not_serving!` and `stats`
+work per worker: calling `serving!` or `not_serving!` in the supervisor
+after the server has started doesn't reach the workers.
+
+Multi-process mode needs `fork()`, so it isn't available on Windows. Run
+one server process per core there, each on its own port.
 
 ### Running with Puma
 
@@ -472,7 +561,8 @@ web workers. It starts after Puma boots and drains gracefully when Puma
 stops or restarts. If the gRPC process dies, Puma shuts down too, so your
 supervisor restarts both. It works with `rails server`, plain `puma`, and
 `preload_app!`. (Not on Windows, which has no `fork()`: run
-`tonic_rails:serve` as its own process there.)
+`tonic_rails:serve` as its own process there.) With `processes` above 1,
+that child process supervises the gRPC workers.
 
 For larger deployments, a dedicated `bin/rails tonic_rails:serve` process
 (scaled separately) is still the most flexible option.
@@ -482,7 +572,7 @@ For larger deployments, a dedicated `bin/rails tonic_rails:serve` process
 `auto_start = true` starts the gRPC server in a background thread of
 `rails server` (never in consoles, rake tasks or tests). It's handy in
 development; in production use the Puma plugin or a dedicated process.
-Don't combine it with the plugin.
+Don't combine it with the plugin, and it can't run multiple `processes`.
 
 ## Operations
 

data/lib/puma/plugin/tonic_rails.rb

@@ -9,7 +9,8 @@ require "puma/plugin"
 #
 # The gRPC server runs as one child process of the Puma master, in single
 # and cluster mode alike, so it has its own GVL and never competes with web
-# workers.  It starts once Puma has booted, drains gracefully when Puma
+# workers.  With `config.processes > 1`, that child supervises the gRPC
+# worker processes.  It starts once Puma has booted, drains gracefully when Puma
 # stops or restarts, stops itself if Puma goes away, and if it dies
 # unexpectedly Puma shuts down too, so a supervisor can restart both.
 Puma::Plugin.create do
@@ -62,7 +63,8 @@ Puma::Plugin.create do
   end
 
   # Puma fires its stop hooks from its TERM trap handler, so this must
-  # not block indefinitely: allow the server's drain timeout plus a margin,
+  # not block indefinitely: allow the server's drain timeout plus a margin
+  # (longer than the one a multi-process server gives its own workers),
   # then kill it.
   def stop_grpc
     pid = @grpc_pid
@@ -87,7 +89,7 @@ Puma::Plugin.create do
 
   def stop_timeout
     drain = defined?(Tonic::Rails) ? Tonic::Rails.configuration.drain_timeout.to_f : 10.0
-    drain + 5
+    drain + 10
   end
 
   def monitor_grpc

data/lib/tonic/rails/cluster.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Tonic
+  module Rails
+    # Multi-process mode (`config.processes > 1`).
+    #
+    # The process that calls Server#start becomes a supervisor: it binds the
+    # listening socket, then forks one worker per process.  Workers inherit
+    # the loaded app (copy-on-write) and the socket, and each runs a full
+    # server (its own tokio runtime, created after the fork) accepting on
+    # it.  The supervisor never starts a runtime itself, so nothing
+    # multi-threaded crosses a fork.
+    #
+    # Sharing one socket rather than binding with SO_REUSEPORT per worker
+    # means connections spread across workers on every Unix (macOS doesn't
+    # load-balance SO_REUSEPORT), port 0 works, a bind error surfaces once,
+    # and connections waiting in the backlog survive a worker's death.
+    #
+    # Lifecycle:
+    # - startup fails if a worker exits before it's serving (usually a
+    #   configuration or boot error, which a retry wouldn't fix)
+    # - a worker that dies later is logged and replaced, with backoff if
+    #   replacements keep failing to boot
+    # - stopping (TERM/INT or Server#stop) closes the supervisor's copy of
+    #   the socket and sends TERM to every worker, which flips its health to
+    #   NOT_SERVING and drains; workers still running after `drain_timeout`
+    #   plus a margin are killed
+    # - a worker whose supervisor disappears stops itself
+    class Cluster
+      # Seconds to wait beyond drain_timeout before killing a worker.
+      STOP_MARGIN = 5
+      MAX_BACKOFF = 30
+
+      Worker = Struct.new(:index, :pid, :ready_io, :ready)
+
+      def initialize(server, configuration, stop_signal)
+        @server = server
+        @configuration = configuration
+        @stop_signal = stop_signal
+        @workers = []
+        @failures = Hash.new(0)
+        @respawn_at = {}
+      end
+
+      # Run the workers until stopped.
+      # @yield once every worker is serving
+      def run(install_signal_handlers:)
+        @listener = Socket.for_fd(TonicRails::Native.bind_listener(@configuration.bind_address))
+        @listener.autoclose = true
+        previous_handlers = install_signal_handlers ? trap_signals : {}
+        @configuration.processes.times { |index| @workers << spawn(index) }
+        return unless booted?
+
+        @started = true
+        yield if block_given?
+        supervise
+      ensure
+        @listener&.close
+        stop_workers
+        previous_handlers&.each { |signal, handler| Signal.trap(signal, handler || "DEFAULT") }
+      end
+
+      private
+
+      def logger = @configuration.logger
+
+      def trap_signals
+        server = @server
+        %w[TERM INT].to_h { |signal| [signal, Signal.trap(signal) { server.stop }] }
+      end
+
+      def spawn(index)
+        reader, writer = IO.pipe
+        pid = fork do
+          reader.close
+          @workers.each { |worker| worker&.ready_io&.close }
+          run_worker(index, writer)
+        end
+        writer.close
+        Worker.new(index, pid, reader, false)
+      end
+
+      # In the worker process.
+      def run_worker(index, ready)
+        Process.setproctitle("tonic-rails worker #{index}")
+        supervisor = Process.ppid
+        Thread.new do
+          sleep 1 while Process.ppid == supervisor
+          @server.stop
+        end
+        @server.run_worker(@listener, index) do
+          ready.write("1")
+          ready.close
+        end
+      rescue StandardError => e
+        Tonic::Rails.log_exception(e, "worker #{index}")
+        exit 1
+      end
+
+      # Wait until every worker is serving: true once they are, false if a
+      # stop was requested first.  Raises if a worker exited before serving.
+      def booted?
+        until @workers.all?(&:ready)
+          return false if @stop_signal.pop(timeout: 0.05)
+
+          @workers.each do |worker|
+            next if ready?(worker)
+
+            status = reap(worker)
+            raise Error, "tonic-rails worker #{worker.index} exited during startup (#{describe(status)})" if status
+          end
+        end
+        true
+      end
+
+      def supervise
+        loop do
+          break if @stop_signal.pop(timeout: 0.5)
+
+          @workers.each_index { |index| supervise_worker(index) }
+        end
+      end
+
+      def supervise_worker(index)
+        worker = @workers[index]
+        if worker.nil?
+          @workers[index] = spawn(index) if monotonic >= @respawn_at[index]
+          return
+        end
+
+        ready?(worker)
+        status = reap(worker)
+        return unless status
+
+        replace(worker, status)
+      end
+
+      # A worker died after startup.  Replace it right away if it had been
+      # serving; if replacements keep dying before they serve, back off.
+      def replace(worker, status)
+        index = worker.index
+        @failures[index] = worker.ready ? 0 : @failures[index] + 1
+        delay = @failures[index].zero? ? 0 : [2**(@failures[index] - 1), MAX_BACKOFF].min
+        logger&.error(
+          "tonic-rails: worker #{index} (pid #{worker.pid}) exited unexpectedly (#{describe(status)}); " \
+          "starting a replacement#{" in #{delay}s" if delay.positive?}",
+        )
+        @workers[index] = nil
+        @respawn_at[index] = monotonic + delay
+      end
+
+      def ready?(worker)
+        return true if worker.ready
+
+        case worker.ready_io.read_nonblock(1, exception: false)
+        when String
+          worker.ready = true
+          worker.ready_io.close
+          logger&.info("tonic-rails: worker #{worker.index} (pid #{worker.pid}) serving") if @started
+          true
+        else
+          false
+        end
+      end
+
+      # The worker's exit status if it has exited, otherwise nil.
+      def reap(worker)
+        _, status = Process.waitpid2(worker.pid, Process::WNOHANG)
+        worker.ready_io.close if status
+        status
+      rescue Errno::ECHILD
+        worker.ready_io.close
+        :unknown
+      end
+
+      def stop_workers
+        live = @workers.compact
+        return if live.empty?
+
+        logger&.info(
+          "tonic-rails: shutting down #{live.size} workers, draining for up to #{@configuration.drain_timeout}s",
+        )
+        live.each { |worker| signal(worker, :TERM) }
+        deadline = monotonic + @configuration.drain_timeout.to_f + STOP_MARGIN
+        until (live = live.reject { |worker| reap(worker) }).empty?
+          if monotonic > deadline
+            logger&.warn("tonic-rails: #{live.size} worker(s) still running after the drain timeout; killing them")
+            live.each { |worker| kill(worker) }
+            break
+          end
+          sleep 0.05
+        end
+        @workers = []
+        logger&.info("tonic-rails: stopped")
+      end
+
+      def kill(worker)
+        signal(worker, :KILL)
+        Process.wait(worker.pid)
+      rescue Errno::ECHILD
+        nil
+      end
+
+      def signal(worker, name)
+        Process.kill(name, worker.pid)
+      rescue Errno::ESRCH
+        nil
+      end
+
+      def describe(status)
+        return "status unknown" unless status.is_a?(Process::Status)
+        return "signal #{Signal.signame(status.termsig)}" if status.signaled?
+
+        "exit status #{status.exitstatus}"
+      end
+
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/tonic/rails/configuration.rb

@@ -26,6 +26,22 @@ module Tonic
       # (RAILS_MAX_THREADS).  Default 4.
       attr_accessor :dispatch_threads
 
+      # Server processes.  Ruby runs one thread at a time per process, so a
+      # CPU-bound service uses one core however many dispatch threads it
+      # has; N processes use N.  Above 1, the app is loaded once and forked
+      # into N workers that share the listening socket, supervised by the
+      # process that started the server.  Unix only.  Default 1.
+      attr_accessor :processes
+
+      # Called in each worker process after it's forked, with the worker's
+      # index (multi-process mode only), to reopen connections that can't
+      # be shared across fork:
+      #
+      #   config.on_worker_boot = ->(index) { Redis.current.disconnect! }
+      #
+      # Active Record reconnects by itself.  Default nil.
+      attr_accessor :on_worker_boot
+
       # RPCs that may wait for a free dispatch thread.  Beyond this the
       # server answers RESOURCE_EXHAUSTED immediately.  Default 128.
       attr_accessor :dispatch_queue_size
@@ -66,6 +82,25 @@ module Tonic
       # API schema; keep it off in production.  Default false.
       attr_accessor :reflection
 
+      # Accept gRPC-Web requests, so browser apps can call services
+      # directly (unary and server-streaming RPCs).  Also enables HTTP/1.1,
+      # which browsers use when there's no TLS.  Default false.
+      attr_accessor :grpc_web
+
+      # Browser origins allowed to call gRPC-Web services (CORS), e.g.
+      # ["https://app.example.com"].  Empty = same-origin only.  "*" allows
+      # any origin, without credentials (cookies).  Default [].
+      attr_accessor :grpc_web_origins
+
+      # Extra request headers browsers may send (beyond content-type,
+      # x-grpc-web, x-user-agent, grpc-timeout and authorization).
+      attr_accessor :grpc_web_allowed_headers
+
+      # Extra response headers browsers may read, e.g. custom response
+      # metadata (grpc-status, grpc-message and grpc-status-details-bin are
+      # always exposed).
+      attr_accessor :grpc_web_exposed_headers
+
       # HTTP/2 PING interval and ack timeout, in seconds.  Defaults 15 / 5.
       attr_accessor :keepalive_interval, :keepalive_timeout
 
@@ -91,6 +126,8 @@ module Tonic
         @logger = Logger.new($stdout)
         @worker_threads = nil
         @dispatch_threads = 4
+        @processes = 1
+        @on_worker_boot = nil
         @dispatch_queue_size = 128
         @tls_cert_path = nil
         @tls_key_path = nil
@@ -105,10 +142,18 @@ module Tonic
         @keepalive_interval = 15
         @keepalive_timeout = 5
         @reload_handlers = false
+        @grpc_web = false
+        @grpc_web_origins = []
+        @grpc_web_allowed_headers = []
+        @grpc_web_exposed_headers = []
         @health_check = nil
         @health_check_interval = 5
       end
 
+      def multi_process?
+        processes.is_a?(Integer) && processes > 1
+      end
+
       def tls?
         !tls_cert_path.nil? && !tls_key_path.nil?
       end
@@ -117,6 +162,7 @@ module Tonic
       def validate!
         positive_integer!(:dispatch_threads)
         positive_integer!(:dispatch_queue_size)
+        positive_integer!(:processes)
         positive_integer!(:max_message_size)
         non_negative_integer!(:max_connections)
         non_negative_integer!(:concurrency_limit_per_connection)
@@ -128,14 +174,33 @@ module Tonic
         raise ArgumentError, "tls_client_ca_path requires tls_cert_path and tls_key_path" if tls_client_ca_path && !tls?
 
         validate_callables!
+        validate_grpc_web!
+        validate_processes!
 
         self
       end
 
       private
 
+      def validate_processes!
+        return unless multi_process?
+        return if Process.respond_to?(:fork)
+
+        raise ArgumentError, "processes > 1 needs fork(), which this platform lacks; run one server process per core instead"
+      end
+
+      def validate_grpc_web!
+        %i[grpc_web_origins grpc_web_allowed_headers grpc_web_exposed_headers].each do |name|
+          value = public_send(name)
+          next if value.is_a?(Array) && value.all?(String)
+
+          raise ArgumentError, "#{name} must be an Array of Strings, got #{value.inspect}"
+        end
+      end
+
       def validate_callables!
         raise ArgumentError, "health_check must respond to #call" if health_check && !health_check.respond_to?(:call)
+        raise ArgumentError, "on_worker_boot must respond to #call" if on_worker_boot && !on_worker_boot.respond_to?(:call)
         unless health_check_interval.is_a?(Numeric) && health_check_interval.positive?
           raise ArgumentError, "health_check_interval must be a positive number, got #{health_check_interval.inspect}"
         end

data/lib/tonic/rails/railtie.rb

@@ -31,6 +31,11 @@ module Tonic
         # tasks, or test runs.  With Puma, prefer `plugin :tonic_rails`
         # (lib/puma/plugin/tonic_rails.rb), which also covers cluster mode.
         if configuration.auto_start && defined?(::Rails::Server)
+          if configuration.multi_process?
+            raise Error, "auto_start can't run multiple processes (processes = #{configuration.processes}); " \
+                         "use `plugin :tonic_rails` in config/puma.rb or `bin/rails tonic_rails:serve`"
+          end
+
           server = Tonic::Rails.server
           thread = Thread.new do
             Thread.current.name = "tonic-rails"

data/lib/tonic/rails/server.rb

@@ -36,8 +36,9 @@ module Tonic
       # Start serving and block until stopped.
       # @param install_signal_handlers [Boolean] trap TERM and INT to stop.
       #   Pass false when embedding in a process that owns its signals.
-      # @yield once the server is accepting connections
-      def start(install_signal_handlers: true)
+      # @yield once the server is accepting connections (with
+      #   `processes > 1`, once every worker is)
+      def start(install_signal_handlers: true, &)
         @lock.synchronize do
           raise Error, "server is already running" unless @state == :stopped
 
@@ -50,40 +51,31 @@ module Tonic
 
           @configuration.validate!
           Tonic::Rails.native_extension!
-          Tonic::Rails._set_shutting_down(false)
           # A Queue rather than a self-pipe: pushing to it is safe from trap
           # handlers, and unlike pipes it can be waited on with a timeout
           # on every platform (Windows select() only handles sockets).
           @stop_signal = Thread::Queue.new
           stop if @stop_requested # requested while we were starting up
-          @native = build_native_server
-          @native.start_server
-          log_pump = spawn_log_pump
-          @health.attach(@native)
-          @state = :running
-
-          request_log = subscribe_request_logger
-          previous_handlers = install_signal_handlers ? trap_signals : {}
-          workers = Array.new(@configuration.dispatch_threads) { |i| spawn_worker(i) }
-          log_startup
-          yield self if block_given?
-
-          wait_for_stop(workers)
-          @health.detach
-          shutdown(workers)
+          if @configuration.multi_process?
+            run_cluster(install_signal_handlers, &)
+          else
+            serve(install_signal_handlers: install_signal_handlers, &)
+          end
         ensure
-          ActiveSupport::Notifications.unsubscribe(request_log) if request_log
-          previous_handlers&.each { |signal, handler| Signal.trap(signal, handler || "DEFAULT") }
-          @health.detach
-          @native&.stop_server
-          stop_log_pump(log_pump)
-          @native = nil
           @stop_signal = nil
-          Tonic::Rails._set_shutting_down(false)
           @state = :stopped
         end
       end
 
+      # @api private
+      # The body of a worker process in multi-process mode (see Cluster):
+      # serve on the listening socket the parent bound.
+      def run_worker(listener, index, &)
+        @worker_index = index
+        @configuration.on_worker_boot&.call(index)
+        serve(install_signal_handlers: true, listener: listener, &)
+      end
+
       # Request a graceful stop.  Safe to call from signal handlers and
       # other threads; returns immediately.
       def stop
@@ -125,24 +117,84 @@ module Tonic
 
       private
 
+      def run_cluster(install_signal_handlers)
+        @state = :running
+        Cluster.new(self, @configuration, @stop_signal).run(install_signal_handlers: install_signal_handlers) do
+          log_startup
+          yield self if block_given?
+        end
+      end
+
+      def serve(install_signal_handlers:, listener: nil)
+        Tonic::Rails._set_shutting_down(false)
+        @native = build_native_server
+        @native.set_listener_fd(listener.fileno) if listener
+        @native.start_server
+        # The transport holds its own copy now; let go of ours, so the
+        # socket closes once every worker has stopped accepting.
+        listener&.close
+        log_pump = spawn_log_pump
+        @health.attach(@native)
+        @state = :running
+
+        request_log = subscribe_request_logger
+        previous_handlers = install_signal_handlers ? trap_signals : {}
+        workers = Array.new(@configuration.dispatch_threads) { |i| spawn_worker(i) }
+        log_startup unless worker?
+        yield self if block_given?
+
+        wait_for_stop(workers)
+        @health.detach
+        shutdown(workers)
+      ensure
+        ActiveSupport::Notifications.unsubscribe(request_log) if request_log
+        previous_handlers&.each { |signal, handler| Signal.trap(signal, handler || "DEFAULT") }
+        @health.detach
+        @native&.stop_server
+        stop_log_pump(log_pump)
+        @native = nil
+        Tonic::Rails._set_shutting_down(false)
+      end
+
+      # True in a worker process of a multi-process server, whose parent
+      # logs startup and shutdown for all of them.
+      def worker?
+        !@worker_index.nil?
+      end
+
+      def worker_label
+        worker? ? "worker #{@worker_index}: " : ""
+      end
+
       def build_native_server
         config = @configuration
         native = TonicRails::Native::Server.new(config.bind_address, config.max_message_size)
         native.on_request(build_callback)
         native.set_routes(@router.paths)
-        if config.tls?
-          native.set_tls(config.tls_cert_path, config.tls_key_path)
-          native.set_tls_client_ca(config.tls_client_ca_path) if config.tls_client_ca_path
-        end
+        apply_connection_settings(native, config)
+        apply_features(native, config)
+        native
+      end
+
+      def apply_connection_settings(native, config)
         native.set_max_connections(config.max_connections)
         native.set_concurrency_limit_per_connection(config.concurrency_limit_per_connection)
         native.set_worker_threads(config.worker_threads || 0)
         native.set_keepalive(config.keepalive_interval.to_f, config.keepalive_timeout.to_f)
         native.set_dispatch_queue_size(config.dispatch_queue_size)
+      end
+
+      def apply_features(native, config)
+        if config.tls?
+          native.set_tls(config.tls_cert_path, config.tls_key_path)
+          native.set_tls_client_ca(config.tls_client_ca_path) if config.tls_client_ca_path
+        end
         native.set_compression(config.compression ? true : false)
         native.set_reflection(config.reflection ? true : false)
         native.set_reflection_descriptors(Reflection.file_descriptors(@router.service_names)) if config.reflection
-        native
+        return unless config.grpc_web
+
+        native.set_grpc_web(config.grpc_web_origins, config.grpc_web_allowed_headers, config.grpc_web_exposed_headers)
       end
 
       # The proc the transport calls for every RPC:
@@ -256,13 +308,15 @@ module Tonic
 
       def shutdown(workers)
         logger = @configuration.logger
+        # In a worker, the parent logs shutdown once for all of them.
+        lifecycle = worker? ? nil : logger
         @state = :stopping
         Tonic::Rails._set_shutting_down(true)
-        logger&.info("tonic-rails: shutting down, draining for up to #{@configuration.drain_timeout}s")
+        lifecycle&.info("tonic-rails: shutting down, draining for up to #{@configuration.drain_timeout}s")
 
         @native.begin_shutdown
         unless @native.wait_for_drain(@configuration.drain_timeout.to_f)
-          logger&.warn("tonic-rails: drain timeout expired; closing remaining connections")
+          logger&.warn("tonic-rails: #{worker_label}drain timeout expired; closing remaining connections")
         end
         @native.stop_workers
         workers.each do |worker|
@@ -270,7 +324,17 @@ module Tonic
         rescue Exception # rubocop:disable Lint/RescueException
           # Already logged by the worker.
         end
-        logger&.info("tonic-rails: stopped")
+        lifecycle&.info("tonic-rails: stopped")
+      end
+
+      def log_grpc_web(logger, config)
+        return unless config.grpc_web
+
+        origins = config.grpc_web_origins
+        logger.info("tonic-rails: gRPC-Web enabled (#{origins.empty? ? 'same-origin only' : "origins: #{origins.join(', ')}"})")
+        return unless origins.include?("*")
+
+        logger.warn("tonic-rails: gRPC-Web allows any origin; any website can call these services from a visitor's browser")
       end
 
       def log_startup
@@ -284,10 +348,10 @@ module Tonic
           logger.warn("tonic-rails: TLS is not configured; gRPC traffic is plaintext")
         end
         logger.info("tonic-rails: reflection enabled") if config.reflection
-        logger.info(
-          "tonic-rails: serving #{@router.service_names.join(', ')} on #{config.bind_address} " \
-          "(#{config.dispatch_threads} dispatch threads)",
-        )
+        log_grpc_web(logger, config)
+        threads = "#{config.dispatch_threads} dispatch threads"
+        threads = "#{config.processes} processes × #{threads} each" if config.multi_process?
+        logger.info("tonic-rails: serving #{@router.service_names.join(', ')} on #{config.bind_address} (#{threads})")
       end
     end
   end

data/lib/tonic/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Tonic
   module Rails
-    VERSION = "0.3.0"
+    VERSION = "0.5.0"
   end
 end

data/lib/tonic-rails.rb

@@ -19,6 +19,7 @@ require "tonic/rails/instrumentation"
 require "tonic/rails/base"
 require "tonic/rails/health"
 require "tonic/rails/reflection"
+require "tonic/rails/cluster"
 require "tonic/rails/server"
 
 module Tonic

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tonic-rails
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: x86_64-linux-gnu
 authors:
 - Matt Tanous
@@ -67,6 +67,7 @@ files:
 - lib/tonic/rails/3.4/tonic_rails_native.so
 - lib/tonic/rails/4.0/tonic_rails_native.so
 - lib/tonic/rails/base.rb
+- lib/tonic/rails/cluster.rb
 - lib/tonic/rails/configuration.rb
 - lib/tonic/rails/health.rb
 - lib/tonic/rails/instrumentation.rb