tonic-rails 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1578d591791ff33ce8365ae3fe5b5a6bb5dfbac8759e4f9762c7c511e71057a
-  data.tar.gz: e23782ccd2cf964d5db2cf25c98547780525e20d7880f0dab85a0c4c956b45cd
+  metadata.gz: df7cc56c6ca7ca2594bc38ab5e676d9c68f6dbcd6464155d14b3d7a83ef98ef2
+  data.tar.gz: 9763e38411184f3c9a796f9e72bf9238ae3e20c16c7687cefa3792192cba7516
 SHA512:
-  metadata.gz: 616f736a4e29cd3fcf8fd4297d6159d9abb145f3973b27a08f6f2c153bf7f5ae87422870ef304dab552e62f8ef7b3037716432c89bfd5d12088ef97e1ae58166
-  data.tar.gz: 07a9749e9188700473883761291731a3f0b947bcdf4d986cd55df81dcb658229863149cfda1174a186a0cfe321e8e09810b7c1113232fefdc38c0ca2f1bba962
+  metadata.gz: d2bf2cad63a78055da0874e0a934a44f41a015c9dd98d2512b1b8ef8b6830cfdb64d262d65c55fad5b532574ec6b7a63f4777f79b6f13e7d23dd06808417c46c
+  data.tar.gz: 04df783ef65a2eb4d8a717d4643e4e406a0040a053289d5c2841014c6bb69ec267223e2bf52b9323dc1314b179969e7bb6da2606fee8bf4f93121b2932f5ce2a

data/CHANGELOG.md

@@ -7,6 +7,15 @@ 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
@@ -116,7 +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.3.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.3.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

@@ -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
@@ -441,6 +479,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 |

data/ext/tonic_rails_native/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tonic_rails_native"
-version = "0.3.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/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",

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,

data/lib/tonic/rails/configuration.rb

@@ -66,6 +66,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
 
@@ -105,6 +124,10 @@ 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
@@ -128,12 +151,22 @@ 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!
 
         self
       end
 
       private
 
+      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)
         unless health_check_interval.is_a?(Numeric) && health_check_interval.positive?

data/lib/tonic/rails/server.rb

@@ -130,19 +130,30 @@ module Tonic
         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:
@@ -273,6 +284,16 @@ module Tonic
         logger&.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
         config = @configuration
         logger = config.logger
@@ -284,6 +305,7 @@ module Tonic
           logger.warn("tonic-rails: TLS is not configured; gRPC traffic is plaintext")
         end
         logger.info("tonic-rails: reflection enabled") if config.reflection
+        log_grpc_web(logger, config)
         logger.info(
           "tonic-rails: serving #{@router.service_names.join(', ')} on #{config.bind_address} " \
           "(#{config.dispatch_threads} dispatch threads)",

data/lib/tonic/rails/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tonic-rails
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Matt Tanous