tonic-rails 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f526af49b4f7647168bcdf7d64131c00c63880d3372f0355d60aa7e347240856
-  data.tar.gz: 7698d7d70a8e3c75ef3ee63ec46ce032267688e12cb86fbca35bf74e41f6f29f
+  metadata.gz: df7cc56c6ca7ca2594bc38ab5e676d9c68f6dbcd6464155d14b3d7a83ef98ef2
+  data.tar.gz: 9763e38411184f3c9a796f9e72bf9238ae3e20c16c7687cefa3792192cba7516
 SHA512:
-  metadata.gz: ad814eb2ab41e6009649bd5307a8f304e3f1baab030f00a25045b65ec0bd1279aa7eceac041d141932281073ce650172191e0fcfbec9c74066f5c224b64e811c
-  data.tar.gz: b1cc149c6beb0f3bb2f99579cc5b4ef4e13964654a93969b431bf0032a25f9fa624f5888748eb0fe37fef1c13762146b881aec6d3347cbc27fe0fee468990275
+  metadata.gz: d2bf2cad63a78055da0874e0a934a44f41a015c9dd98d2512b1b8ef8b6830cfdb64d262d65c55fad5b532574ec6b7a63f4777f79b6f13e7d23dd06808417c46c
+  data.tar.gz: 04df783ef65a2eb4d8a717d4643e4e406a0040a053289d5c2841014c6bb69ec267223e2bf52b9323dc1314b179969e7bb6da2606fee8bf4f93121b2932f5ce2a

data/CHANGELOG.md

@@ -7,6 +7,47 @@ minor versions may contain breaking changes.
 
 ## [Unreleased]
 
+## [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
+
+- Generators: `rails g tonic_rails:install` (initializer, proto and
+  generated-code directories, Puma plugin) and `rails g tonic_rails:service
+  Item GetItem ListItems:server` (proto, handler with a stub per RPC,
+  registration, and an RSpec or Minitest test).
+- Controller-style callbacks for handlers: `before_rpc`, `after_rpc` and
+  `around_rpc` with `only:` / `except:`, plus `current_rpc` and `request`
+  accessors.
+- `rescue_from` (ActiveSupport::Rescuable) with a `code:` shorthand that maps
+  an exception class to a gRPC status.
+- `peer` in handlers: the client's address and, with mutual TLS, its
+  certificate (`peer.certificate`, an `OpenSSL::X509::Certificate`).
+  `Testing.call`/`invoke` accept `peer:`.
+- App-controlled health: `config.health_check` (polled every
+  `health_check_interval` seconds inside the Rails executor) and
+  `Tonic::Rails.server.serving!` / `not_serving!` for the whole server or
+  individual services, so readiness probes reflect real dependency health.
+- Test helpers: the `raise_grpc_error(code).with_message(...)` RSpec matcher
+  (`require "tonic/rails/testing/rspec"`) and `assert_grpc_error` for Minitest
+  (`Tonic::Rails::Testing::Assertions`). Both accept `Tonic::Rails::RpcError`
+  and the grpc gem's `GRPC::BadStatus`.
+
+### Changed
+
+- `tonic_rails:compile_protos` requires protoc 22 or newer and says so,
+  instead of generating code google-protobuf 4 can't load (older protoc,
+  such as Ubuntu's 3.21 package, emits a Ruby DSL that google-protobuf 4
+  removed).
+
 ## [0.2.0] - 2026-10-11
 
 ### Added
@@ -84,6 +125,8 @@ 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.2.0...HEAD
+[Unreleased]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.4.0...HEAD
+[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/Cargo.lock

@@ -1021,9 +1021,27 @@ dependencies = [
  "tonic-prost",
 ]
 
+[[package]]
+name = "tonic-web"
+version = "0.14.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b5e6a1b6319ca4b61a4c0f0c94d439c8f3ed344cca56fe0df40e1fe4be11380b"
+dependencies = [
+ "base64",
+ "bytes",
+ "http",
+ "http-body",
+ "pin-project",
+ "tokio-stream",
+ "tonic",
+ "tower-layer",
+ "tower-service",
+ "tracing",
+]
+
 [[package]]
 name = "tonic_rails_native"
-version = "0.2.0"
+version = "0.4.0"
 dependencies = [
  "axum",
  "bytes",
@@ -1043,7 +1061,9 @@ dependencies = [
  "tonic",
  "tonic-health",
  "tonic-reflection",
+ "tonic-web",
  "tower",
+ "tower-http",
 ]
 
 [[package]]
@@ -1065,6 +1085,20 @@ dependencies = [
  "tracing",
 ]
 
+[[package]]
+name = "tower-http"
+version = "0.6.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840"
+dependencies = [
+ "bitflags",
+ "bytes",
+ "http",
+ "pin-project-lite",
+ "tower-layer",
+ "tower-service",
+]
+
 [[package]]
 name = "tower-layer"
 version = "0.3.3"

data/README.md

@@ -60,10 +60,31 @@ On platforms without a precompiled gem, installation builds the
 extension from source, which needs a [Rust toolchain](https://rustup.rs).
 
 To generate Ruby classes from your `.proto` files you also need `protoc`
-(the Protocol Buffers compiler) during development.
+(the Protocol Buffers compiler) **22.0 or newer** during development.
+Older versions, such as Ubuntu's `protobuf-compiler` package (3.21),
+generate code that google-protobuf 4 can't load; install a current
+release from the [protobuf releases page](https://github.com/protocolbuffers/protobuf/releases)
+or Homebrew.
 
 ## Quick start
 
+The generators set everything up:
+
+```sh
+bin/rails generate tonic_rails:install
+bin/rails generate tonic_rails:service Item GetItem ListItems:server
+bin/rails tonic_rails:compile_protos
+```
+
+`install` adds `config/initializers/tonic_rails.rb` (load path for
+generated code, configuration, handler registration), `app/protos/`,
+`lib/grpc/`, and the Puma plugin. `service` writes the `.proto`, a handler
+in `app/grpc/` with a stub per RPC, its registration, and a spec (or
+Minitest test). RPCs take an optional `:server`, `:client` or `:bidi`
+streaming kind.
+
+The rest of this section shows the same steps by hand.
+
 ### 1. Define the service
 
 ```protobuf
@@ -236,11 +257,54 @@ Any other exception becomes `INTERNAL` with the message `internal error`.
 The real exception is logged and passed to `Rails.error.report`, so your
 error tracker sees it.
 
+### Callbacks and rescue_from
+
+Handlers get controller-style callbacks and exception mapping:
+
+```ruby
+class ItemService
+  include Tonic::Rails::Base
+  rpc_service "demo.v1.ItemService"
+
+  before_rpc :authenticate, except: :ListItems
+  around_rpc :with_tenant
+  after_rpc { StatsD.increment("grpc.#{current_rpc}") }
+
+  rescue_from ActiveRecord::RecordNotFound, code: :not_found
+  rescue_from ActiveRecord::RecordInvalid, code: :invalid_argument, message: ->(e) { e.record.errors.full_messages.join(", ") }
+  rescue_from Pundit::NotAuthorizedError, with: :forbidden
+
+  private
+
+  def authenticate
+    @user = User.from_token(grpc_metadata["authorization"])
+    raise Tonic::Rails::RpcError.new("invalid token", code: :unauthenticated) unless @user
+  end
+
+  def with_tenant(&) = Tenant.switch(@user.tenant, &)
+
+  def forbidden(_e) = raise(Tonic::Rails::RpcError.new("not allowed", code: :permission_denied))
+end
+```
+
+- `before_rpc`, `after_rpc` and `around_rpc` accept method names or a
+  block, plus `only:` / `except:` with RPC names (`:GetItem` or
+  `:get_item`). Raising in a `before_rpc` stops the call.
+- `current_rpc` is the RPC being handled and `request` the decoded
+  request, so callbacks can inspect it.
+- `after_rpc` runs once a streamed response has been fully sent.
+- `rescue_from` covers the handler and its callbacks. With `code:`, the
+  exception's message is sent to the client unless you pass `message:`.
+  Handlers given with `with:` or a block must raise an `RpcError`.
+  Anything unmapped becomes `INTERNAL`, as before.
+
 ### Metadata, deadlines and shutdown
 
 ```ruby
 def get_item(request)
   token = grpc_metadata["authorization"]   # request headers, lower-case
+  peer.ip                                    # client address ("10.0.4.17")
+  peer.certificate&.subject                  # client certificate, with mutual TLS
   deadline_ms                                # ms left before the client's deadline, or nil
   deadline_exceeded?                         # true once it has passed
   cancelled?                                 # true while the server shuts down
@@ -299,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
@@ -322,6 +424,30 @@ result.headers["x-cache"]    # => "hit"
 result.trailers["x-cost-ms"] # => "3"
 ```
 
+Matchers for gRPC statuses work with `Testing.call` and with the official
+`grpc` client's errors:
+
+```ruby
+# spec/rails_helper.rb
+require "tonic/rails/testing/rspec"
+
+expect { Tonic::Rails::Testing.call(ItemService, :GetItem, { id: 0 }) }
+  .to raise_grpc_error(:not_found).with_message(/0/)
+```
+
+```ruby
+# Minitest
+require "tonic/rails/testing/minitest"
+
+class ItemServiceTest < ActiveSupport::TestCase
+  include Tonic::Rails::Testing::Assertions
+
+  test "missing items" do
+    assert_grpc_error(:not_found) { Tonic::Rails::Testing.call(ItemService, :GetItem, { id: 0 }) }
+  end
+end
+```
+
 ## Configuration
 
 Set options in `config/application.rb` or an environment file:
@@ -353,6 +479,11 @@ 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 |
 | `reflection` | `false` | Serve `grpc.reflection.v1`; exposes your schema |
 | `interceptors` | `[]` | See [Interceptors](#interceptors) |
@@ -399,7 +530,19 @@ Don't combine it with the plugin.
 - **Health checks.** `grpc.health.v1.Health` reports `SERVING` for the
   server (`""`) and every registered service, and flips to `NOT_SERVING`
   as soon as shutdown begins. Point your load balancer or Kubernetes
-  gRPC probes at it.
+  gRPC probes at it. To make readiness reflect your dependencies, add a
+  check that runs every `health_check_interval` seconds (default 5):
+
+  ```ruby
+  config.health_check = -> { ActiveRecord::Base.connection.active? }
+  ```
+
+  While it returns false or raises, the server reports `NOT_SERVING`
+  (calls are still served). You can also mark the server or a service
+  yourself, for example during maintenance:
+  `Tonic::Rails.server.not_serving!("demo.v1.ItemService")` and
+  `serving!`. A service is `SERVING` only while the check passes and it
+  isn't marked otherwise.
 - **Graceful shutdown.** On SIGTERM or SIGINT the server stops
   accepting connections, tells clients to go away (HTTP/2 GOAWAY), lets
   in-flight calls finish for up to `drain_timeout` seconds, then exits.

data/ext/tonic_rails_native/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tonic_rails_native"
-version = "0.2.0"
+version = "0.4.0"
 edition = "2024"
 rust-version = "1.88"
 publish = false
@@ -28,6 +28,8 @@ rb-sys = "0.9"
 tonic = { version = "0.14", default-features = false, features = ["transport", "router", "server", "tls-ring"] }
 tonic-reflection = { version = "0.14", default-features = false, features = ["server"] }
 tonic-health = { version = "0.14", default-features = false }
+tonic-web = { version = "0.14", default-features = false }
+tower-http = { version = "0.6", default-features = false, features = ["cors"] }
 axum = { version = "0.8", default-features = false }
 tokio = { version = "1", features = ["rt-multi-thread", "net", "sync", "macros", "time"] }
 tokio-stream = { version = "0.1", features = ["net"] }

data/ext/tonic_rails_native/src/dispatch.rs

@@ -21,10 +21,11 @@ use magnus::{Value, value::Opaque};
 use tokio::sync::mpsc;
 use tonic::Code;
 use tonic::body::Body as TonicBody;
+use tonic::transport::server::{TcpConnectInfo, TlsConnectInfo};
 
 use crate::body::{ErrorBody, ResponseBody, ServerStats};
 use crate::framing::{MessageReader, append_metadata, parse_grpc_timeout};
-use crate::gvl::{DispatchContext, RequestError, StreamMessage};
+use crate::gvl::{DispatchContext, Peer, RequestError, StreamMessage};
 use crate::log::Level;
 
 /// Messages buffered per direction before backpressure applies.
@@ -166,6 +167,7 @@ impl DispatchInner {
             request_rx,
             request_error: request_error.clone(),
             log: self.stats.log.clone(),
+            peer: peer_of(&req),
         });
 
         match self.request_tx.try_send(ctx) {
@@ -241,6 +243,26 @@ impl DispatchInner {
     }
 }
 
+/// The client's address and, if it presented one over TLS, its
+/// certificate chain.  tonic records both on the request.
+fn peer_of<B>(req: &Request<B>) -> Peer {
+    let address = req
+        .extensions()
+        .get::<TcpConnectInfo>()
+        .and_then(TcpConnectInfo::remote_addr)
+        .map(|addr| addr.to_string());
+    let certificates = req
+        .extensions()
+        .get::<TlsConnectInfo<TcpConnectInfo>>()
+        .and_then(TlsConnectInfo::peer_certs)
+        .map(|chain| chain.iter().map(|der| der.to_vec()).collect())
+        .unwrap_or_default();
+    Peer {
+        address,
+        certificates,
+    }
+}
+
 /// Read the request body and forward each unframed message to the
 /// handler.  Dropping `tx` signals end of stream; errors are recorded
 /// in `error` first so the reader can distinguish them.

data/ext/tonic_rails_native/src/gvl.rs

@@ -369,6 +369,15 @@ pub struct DispatchContext {
     pub request_rx: mpsc::Receiver<Vec<u8>>,
     pub request_error: Arc<RequestError>,
     pub log: LogSink,
+    pub peer: Peer,
+}
+
+/// The client connection: remote address and, with mutual TLS, its
+/// certificate chain (DER, leaf first).
+#[derive(Default)]
+pub struct Peer {
+    pub address: Option<String>,
+    pub certificates: Vec<Vec<u8>>,
 }
 
 /// Bounds on how long one thread keeps the GVL to drain a busy queue.
@@ -441,6 +450,7 @@ fn run_handler(ctx: DispatchContext) {
         request_rx,
         request_error,
         log,
+        peer,
     } = ctx;
 
     let trailers = Arc::new(Mutex::new(Metadata::new()));
@@ -454,6 +464,7 @@ fn run_handler(ctx: DispatchContext) {
         request_rx,
         request_error,
         trailers.clone(),
+        &peer,
     );
     let end = StreamMessage::End {
         status: result.err().map(|e| error_status(&e, &log)),
@@ -474,6 +485,7 @@ fn call_handler(
     request_rx: mpsc::Receiver<Vec<u8>>,
     request_error: Arc<RequestError>,
     trailers: Arc<Mutex<Metadata>>,
+    peer: &Peer,
 ) -> Result<(), Error> {
     let md = ruby.hash_new_capa(metadata.len());
     for (k, v) in metadata {
@@ -496,6 +508,16 @@ fn call_handler(
     if let Some(ms) = timeout_ms {
         call.aset(ruby.to_symbol("timeout_ms"), ms as u64)?;
     }
+    if let Some(address) = &peer.address {
+        call.aset(ruby.to_symbol("peer_address"), ruby.str_new(address))?;
+    }
+    if !peer.certificates.is_empty() {
+        let certificates = ruby.ary_new_capa(peer.certificates.len());
+        for der in &peer.certificates {
+            certificates.push(ruby.str_from_slice(der))?;
+        }
+        call.aset(ruby.to_symbol("peer_certificates"), certificates)?;
+    }
 
     let callback = ruby.get_inner(callback);
     let result = callback.funcall::<_, _, Value>("call", (ruby.str_new(path), md, call));

data/ext/tonic_rails_native/src/lib.rs

@@ -64,6 +64,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     )?;
     class.define_method("set_compression", method!(NativeServer::set_compression, 1))?;
     class.define_method("set_reflection", method!(NativeServer::set_reflection, 1))?;
+    class.define_method("set_grpc_web", method!(NativeServer::set_grpc_web, 3))?;
     class.define_method("set_routes", method!(NativeServer::set_routes, 1))?;
     class.define_method(
         "set_reflection_descriptors",
@@ -71,6 +72,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     )?;
     class.define_method("start_server", method!(NativeServer::start_server, 0))?;
     class.define_method("serve_worker", method!(NativeServer::serve_worker, 0))?;
+    class.define_method("set_health", method!(NativeServer::set_health, 2))?;
     class.define_method("begin_shutdown", method!(NativeServer::begin_shutdown, 0))?;
     class.define_method("wait_for_drain", method!(NativeServer::wait_for_drain, 1))?;
     class.define_method("stop_workers", method!(NativeServer::stop_workers, 0))?;

data/ext/tonic_rails_native/src/server.rs

@@ -29,6 +29,9 @@ use tokio::sync::{Semaphore, watch};
 use tonic_health::ServingStatus;
 use tonic_health::server::HealthReporter;
 
+use http::{HeaderName, HeaderValue, Method};
+use tower_http::cors::{AllowOrigin, CorsLayer};
+
 use crate::body::ServerStats;
 use crate::dispatch::{DispatchInner, DispatchService};
 use crate::gvl::{self, Cancel, DispatchContext};
@@ -47,6 +50,7 @@ struct Options {
     keepalive_interval: Duration,
     keepalive_timeout: Duration,
     reflection: bool,
+    grpc_web: Option<GrpcWebOptions>,
     dispatch_queue_size: usize,
     routes: Vec<String>,
     descriptors: Vec<Vec<u8>>,
@@ -63,6 +67,7 @@ impl Default for Options {
             keepalive_interval: Duration::from_secs(15),
             keepalive_timeout: Duration::from_secs(5),
             reflection: false,
+            grpc_web: None,
             dispatch_queue_size: 128,
             routes: Vec::new(),
             descriptors: Vec::new(),
@@ -70,6 +75,76 @@ impl Default for Options {
     }
 }
 
+/// gRPC-Web and the CORS policy browsers need to use it.
+struct GrpcWebOptions {
+    /// Allowed browser origins; empty = same-origin only; ["*"] = any.
+    origins: Vec<String>,
+    allow_headers: Vec<String>,
+    expose_headers: Vec<String>,
+}
+
+/// Request headers gRPC-Web clients send, beyond the CORS-safelisted ones.
+const GRPC_WEB_REQUEST_HEADERS: [&str; 5] = [
+    "content-type",
+    "x-grpc-web",
+    "x-user-agent",
+    "grpc-timeout",
+    "authorization",
+];
+/// Response headers browsers must be allowed to read for gRPC-Web.
+const GRPC_WEB_RESPONSE_HEADERS: [&str; 3] = ["grpc-status", "grpc-message", "grpc-status-details-bin"];
+
+fn header_names(ruby: &Ruby, defaults: &[&str], extra: &[String]) -> Result<Vec<HeaderName>, Error> {
+    defaults
+        .iter()
+        .map(|name| name.to_string())
+        .chain(extra.iter().map(|name| name.to_ascii_lowercase()))
+        .map(|name| {
+            HeaderName::from_bytes(name.as_bytes())
+                .map_err(|_| arg_error(ruby, format!("invalid gRPC-Web header name: {name:?}")))
+        })
+        .collect()
+}
+
+/// None when no cross-origin access is configured (same-origin only).
+fn cors_layer(ruby: &Ruby, web: &GrpcWebOptions) -> Result<Option<CorsLayer>, Error> {
+    if web.origins.is_empty() {
+        return Ok(None);
+    }
+    let layer = CorsLayer::new()
+        .allow_methods([Method::POST])
+        .allow_headers(header_names(ruby, &GRPC_WEB_REQUEST_HEADERS, &web.allow_headers)?)
+        .expose_headers(header_names(
+            ruby,
+            &GRPC_WEB_RESPONSE_HEADERS,
+            &web.expose_headers,
+        )?)
+        .max_age(Duration::from_secs(24 * 60 * 60));
+    if web.origins.iter().any(|origin| origin == "*") {
+        if web.origins.len() > 1 {
+            return Err(arg_error(
+                ruby,
+                "grpc_web_origins: \"*\" can't be combined with other origins",
+            ));
+        }
+        // Browsers refuse credentials with a wildcard origin, so none here.
+        return Ok(Some(layer.allow_origin(AllowOrigin::any())));
+    }
+    let origins = web
+        .origins
+        .iter()
+        .map(|origin| {
+            HeaderValue::from_str(origin.trim_end_matches('/'))
+                .map_err(|_| arg_error(ruby, format!("invalid gRPC-Web origin: {origin:?}")))
+        })
+        .collect::<Result<Vec<_>, _>>()?;
+    Ok(Some(
+        layer
+            .allow_origin(AllowOrigin::list(origins))
+            .allow_credentials(true),
+    ))
+}
+
 /// State that exists only while the server is running.
 struct Running {
     runtime: Runtime,
@@ -199,6 +274,20 @@ impl NativeServer {
         self.compression.store(enabled, Ordering::Relaxed);
     }
 
+    /// Enable gRPC-Web (and HTTP/1.1, which browsers use without TLS).
+    pub fn set_grpc_web(
+        &self,
+        origins: Vec<String>,
+        allow_headers: Vec<String>,
+        expose_headers: Vec<String>,
+    ) {
+        self.options.lock().grpc_web = Some(GrpcWebOptions {
+            origins,
+            allow_headers,
+            expose_headers,
+        });
+    }
+
     pub fn set_reflection(&self, enabled: bool) {
         self.options.lock().reflection = enabled;
     }
@@ -347,7 +436,17 @@ impl NativeServer {
                 .tls_config(tls)
                 .map_err(|e| runtime_error(ruby, format!("invalid TLS configuration: {e}")))?;
         }
-        let router = builder.add_routes(grpc_routes);
+        // CORS outermost, so preflight requests are answered before the
+        // gRPC-Web translation sees them.  Both are no-ops when disabled.
+        let (cors, grpc_web) = match &options.grpc_web {
+            Some(web) => (cors_layer(ruby, web)?, Some(tonic_web::GrpcWebLayer::new())),
+            None => (None, None),
+        };
+        let router = builder
+            .accept_http1(options.grpc_web.is_some())
+            .layer(tower::util::option_layer(cors))
+            .layer(tower::util::option_layer(grpc_web))
+            .add_routes(grpc_routes);
 
         let permits = match options.max_connections {
             0 => Semaphore::MAX_PERMITS,
@@ -409,6 +508,27 @@ impl NativeServer {
         Ok(())
     }
 
+    /// Set the grpc.health.v1 status of one service ("" = the whole
+    /// server).  Returns false if the server isn't running.
+    pub fn set_health(&self, service: String, serving: bool) -> bool {
+        let Some(r) = self
+            .running
+            .lock()
+            .as_ref()
+            .map(|r| (r.runtime.handle().clone(), r.health.clone()))
+        else {
+            return false;
+        };
+        let (handle, health) = r;
+        let status = if serving {
+            ServingStatus::Serving
+        } else {
+            ServingStatus::NotServing
+        };
+        handle.block_on(health.set_service_status(service, status));
+        true
+    }
+
     /// Mark everything NOT_SERVING and stop accepting new connections.
     /// Existing connections receive GOAWAY; in-flight RPCs continue.
     pub fn begin_shutdown(&self) {

data/lib/generators/tonic_rails/install/install_generator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module TonicRails
+  module Generators
+    # rails generate tonic_rails:install
+    #
+    # Sets an app up for gRPC: an initializer (load path for generated
+    # protobuf code, configuration, handler registration), the proto and
+    # generated-code directories, and the Puma plugin.
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :skip_puma, type: :boolean, default: false,
+                               desc: "Don't add `plugin :tonic_rails` to config/puma.rb"
+      class_option :skip_next_steps, type: :boolean, default: false, hide: true
+
+      def create_initializer
+        template "tonic_rails.rb.tt", "config/initializers/tonic_rails.rb"
+      end
+
+      def create_directories
+        create_file "app/protos/.keep"
+        create_file "lib/grpc/.keep"
+      end
+
+      def add_puma_plugin
+        return if options[:skip_puma]
+
+        puma = "config/puma.rb"
+        return unless File.exist?(File.join(destination_root, puma))
+        return if File.read(File.join(destination_root, puma)).match?(/plugin\s+:tonic_rails/)
+
+        append_to_file puma, "\n# Run the tonic-rails gRPC server alongside Puma.\nplugin :tonic_rails\n"
+      end
+
+      def show_next_steps
+        return if options[:skip_next_steps]
+
+        say "\nNext: rails generate tonic_rails:service Item GetItem ListItems:server", :green
+      end
+    end
+  end
+end