connectrpc-ruby is an unofficial Ruby implementation of the
Connect protocol. You describe a
service in a .proto file, generate typed Ruby clients and handler maps, and
serve the same handlers from Rack, Rails, Async or Falcon. The same
declarations also speak native gRPC and server-side
gRPC-Web.
-
Typed on both sides.
protoc-gen-connectrpc-rubygenerates service modules alongside Google's official_pb.rbmessages, so clients and handlers exchange protobuf objects instead of hashes. -
Plain HTTP. A Connect unary call is an HTTP POST with a protobuf or JSON
body, so
curland ordinary HTTP tooling work. Methods declared free of side effects can opt into GET. - Host-neutral handlers. A handler is a callable that takes a request and a context. The same handler runs in Rack middleware, a Rails controller, the standalone Async HTTP/2 host, Falcon workers, or an in-process test transport.
-
No runtime dependencies in core.
require "connectrpc"loads no other gems. Protobuf, Rack, Rails, Async, Falcon and OpenTelemetry support are explicit opt-ins. - Streaming and gRPC where the host supports them. Async and Falcon HTTP/2 hosts serve all four RPC shapes over Connect and gRPC.
Warning
This project is experimental. Every gem is published on RubyGems, but no release is declared supported or production ready yet. The supported 0.x contract defines the target profile. Adoption depends on the open #26 findings and release qualification.
Quick start
This walkthrough builds a one-method service, serves it with Rack and calls it
from Ruby and from curl. You need CRuby 3.4 or newer, Bundler, and
protoc on your PATH. The project
verifies with protoc 36.2.
-
Add the core gem, the Rack integration, Google's protobuf runtime and a Rack server to your Gemfile, then run
bundle install:gem "connectrpc", "~> 0.1.0" gem "connectrpc-rack", "~> 0.1.0" gem "google-protobuf", ">= 4.36.2", "< 5" gem "rackup" gem "webrick"
-
Describe the service in
proto/greet/v1/greet.proto:syntax = "proto3"; package greet.v1; message GreetRequest { string name = 1; } message GreetResponse { string greeting = 1; } service GreetService { rpc Greet(GreetRequest) returns (GreetResponse); }
-
Generate the messages and the service module into
lib/. Running protoc throughbundle execputs the gem'sprotoc-gen-connectrpc-rubyplugin on PATH:mkdir -p lib bundle exec protoc -I proto --ruby_out=lib --connectrpc-ruby_out=lib greet/v1/greet.protoThis writes
lib/greet/v1/greet_pb.rbandlib/greet/v1/greet_connect.rb. Commit them or regenerate them in your build; don't edit them by hand. -
Implement the handler and mount it in
config.ru:$LOAD_PATH.unshift(File.expand_path("lib", __dir__)) require "connectrpc/rack" require "connectrpc/bindings/google_protobuf" require "greet/v1/greet_connect" service = Greet::V1::GreetService greet = lambda do |request, _context| Greet::V1::GreetResponse.new(greeting: "Hello, #{request.name}!") end server = ConnectRPC::Server.new( services: [service::SERVICE], binding: ConnectRPC::Bindings::GoogleProtobuf.new, handlers: service.handlers(greet: greet) ) run ConnectRPC::Rack.new(server: server)
-
Start the server:
bundle exec rackup --host 127.0.0.1 --port 9292 -
From another terminal, call it with
curl. Connect accepts JSON as well as binary protobuf:$ curl -H "Content-Type: application/json" -d '{"name":"curl"}' \ http://127.0.0.1:9292/greet.v1.GreetService/Greet {"greeting":"Hello, curl!"}
-
Call it from Ruby with the generated client. Save this as
client.rband runbundle exec ruby client.rb:$LOAD_PATH.unshift(File.expand_path("lib", __dir__)) require "connectrpc" require "connectrpc/bindings/google_protobuf" require "greet/v1/greet_connect" core = ConnectRPC::Client.new( base_url: "http://127.0.0.1:9292", binding: ConnectRPC::Bindings::GoogleProtobuf.new ) client = Greet::V1::GreetService::Client.new(client: core) response = client.greet(Greet::V1::GreetRequest.new(name: "Ruby"), timeout: 2) puts response.message.greeting # => Hello, Ruby!
The core client uses Net::HTTP and binary protobuf by default. Pass
codec: :json for JSON, or transport: to use another transport. Each call
accepts metadata:, timeout: (30 seconds by default) and cancellation:.
Handlers raise ConnectRPC::Error to return a typed error code to the caller.
Next steps:
- The unary guide covers generation options, GET, gzip, metadata, errors, limits, deadlines and cancellation.
- The runnable examples pair Rack, Rails, Async and Falcon servers with Net::HTTP and Async clients, including mutual TLS.
- The streaming guide covers server, client and bidirectional streaming.
Packages
Every package is a separate gem. Install the core gem and add only the integrations you use:
| Gem | Use it when | Require |
|---|---|---|
connectrpc |
Always. Core client, Net::HTTP transport, host-neutral server, Google protobuf binding and the protoc-gen-connectrpc-ruby generator |
connectrpc, connectrpc/bindings/google_protobuf
|
connectrpc-rack |
You serve unary RPCs from any Rack 3 application or server | connectrpc/rack |
connectrpc-on-rails |
You want handlers to run as Rails controller actions, with callbacks, rescue_from and Rails instrumentation |
connectrpc/on_rails |
connectrpc-async |
You need a standalone HTTP/2 host, streaming, gRPC, a pooled HTTP/2 or HTTP/1.1 client, or a shared HTTP/2 client for threaded apps such as Puma and Sidekiq | connectrpc/async |
connectrpc-falcon |
You host on Falcon workers and want native HTTP/1.1 and HTTP/2 RPC next to an ordinary Rack or Rails app, with managed TLS | connectrpc/falcon |
connectrpc-testing |
You want real encoded client/server round trips in tests without opening sockets | connectrpc/testing |
connectrpc-otel |
You want OpenTelemetry CLIENT and SERVER spans for each RPC | connectrpc/otel |
Use the same version of connectrpc and every ConnectRPC gem in an
application. Their ~> dependency ranges allow patch versions to differ, but the
support policy
requires matching versions.
Protocol and host support
U means unary, SS server streaming, CS client streaming and bidi bidirectional streaming. H1 is HTTP/1.1 and H2 is HTTP/2.
| Server | Connect | Native gRPC | gRPC-Web |
|---|---|---|---|
| Rack middleware | U over H1 | No | U, binary and text |
| Rails controller | U | No | U, binary and text |
Async Host
|
U/SS/CS/bidi over H2 (h2c, TLS, mTLS) | U/SS/CS/bidi | U/SS over H2 |
| Falcon | U/SS/CS over H1; U/SS/CS/bidi over H2 (TCP, TLS, mTLS) | U/SS/CS/bidi over H2 | U/SS over H1 and H2 |
| Testing transport | U, in process | No | U, manually encoded |
| Client transport | Connect | Native gRPC |
|---|---|---|
| Net::HTTP (core default) | U over H1, TCP or verified TLS | No |
Async Transport
|
U/SS/CS/bidi over H2 (h2c, TLS, mTLS) | U/SS/CS/bidi |
Async ThreadedTransport
|
U over H2, callable from any thread | No |
Async HTTP1Transport
|
U/SS/CS over H1 (TCP, TLS, mTLS) | No |
Connect is the default protocol. Connect supports binary protobuf
(application/proto) and protobuf JSON (application/json), identity or
opt-in gzip encoding, and opt-in GET for safe unary methods. Native gRPC uses
protobuf with identity or gzip. gRPC-Web is server-only and must be enabled
explicitly; there is no Ruby gRPC-Web client.
These limits apply across the matrix:
- Streaming and gRPC from ordinary threads are not implemented yet; see
issue #29.
ThreadedTransportcovers Connect unary only. - The standalone Async
Hostis H2-only. Falcon is the Ruby H1 streaming host. - Native Connect streaming clients apply a one-second HTTP tail policy, even without an RPC deadline. See the streaming guide.
- There is no H1 bidi, HTTP/3, protocol fallback or RPC replay. Faraday is
unsupported. The Async H2
Transportresends a Connect unary call once only when the server provably never processed its stream; see client connection management.
The support contract lists the evidence behind each row, the qualified Ruby and dependency versions, and the remaining adoption gates. CRuby 3.4 or newer is required; project verification targets Ruby 3.4.12 and 4.0.9 on Linux x64.
Documentation
| Guide | Covers |
|---|---|
| Unary RPC | Code generation, manual declarations, GET, gzip, metadata, errors, limits, deadlines, cancellation and instrumentation |
| Streaming | Server, client and bidirectional streaming, completion policy and bounds |
| Native gRPC | gRPC clients and servers on the Async and Falcon HTTP/2 hosts |
| gRPC-Web | Server-side gRPC-Web, CORS and browser clients |
| Signatures (RBS) | Shipped RBS signatures, generated .rbs files and Steep setup |
| Support contract | Target 0.x protocol, host, platform and API compatibility |
| Design | Internal boundaries, wire behavior and extension seams |
| Runnable examples | Two-terminal servers and clients for every host and transport |
| Development | Setup, verification tiers, coverage, updates and PR guidance |
| Releasing | The synchronized release train and trusted publishing |
Development
Install Mise 2026.9.14 or newer and the Ruby source-build prerequisites, then run:
mise run setup
mise run example
mise run verify
mise run rack:verifyThe example starts Rack on an ephemeral loopback port,
calls a typed handler through real Net::HTTP in both codecs, prints the results,
and closes the host and its workers. Its schema comes from the shared
descriptor fixture. Go is needed only for interop
and final verification, and those tasks install its project pin separately.
mise tasks lists every task, and the development guide
explains the verification tiers.
License and releases
Original project work is licensed under the MIT License, copyright 2026 Jim Myhrberg. Every gem archive includes the complete license. Third-party dependencies and imported fixtures retain their own licenses and notices, including the separately licensed conformance schemas.
The gems pin allowed_push_host to https://rubygems.org and require MFA for
manual pushes. Releases are published only by the tag-triggered
release workflow, using RubyGems trusted publishing with
Sigstore attestations.