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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b594b6ba6699510bedb286cab5e05fc8fa3578d200fdb704fd8335529ee0105
-  data.tar.gz: df3ddc7f65ca300dce59a26855fcadfd88f573c9f892039afa727ec16a3dc01e
+  metadata.gz: 06cf21277f2b5442bae8386269a576c89515959d2144d9d8ed3e171b24e73c7d
+  data.tar.gz: 9862766277deb1548e0e6e88d48e611746282d430578b198d1f81430e759cf69
 SHA512:
-  metadata.gz: 0d8da9f21bc78c95c31b708a0349d54f23e9a5395bad4de0d46937ec1fae721bd6590a74d498dd523e087b1a1c90b23af6a10c93f2cfaab262d554e3c74272a0
-  data.tar.gz: a67219c39168b2eeae48a638b73ebdfa65a4c5a0300138577088f214868db989e36196647639753563584e49dfb256da0175f2b13aac0b8526d30cb9cee38f44
+  metadata.gz: 9a72581a9b168d58c71402037b41e0df2650dcad092fa1163b0bf738508da03d3db6babf9c0651b58636fe989be50431231176152b1e7ed894838871a8a706e5
+  data.tar.gz: 5397e3379da5008ccc472b4b3d6f3f88e649675e0290b271dde7a2cfeb1843f45287cbd4d0776750304d12bcb19179c7c2206ef0c05cd7af1744721e6d57c790

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/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/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: x86_64-linux-gnu
 authors:
 - Matt Tanous