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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b80385e6e34361d398f683ec43379d519558c45f7762280c278bb52c545316f6
-  data.tar.gz: 1f25a57bf202c59274c178981967aeee274d33ab85aaf6517ca3261ae115a8ae
+  metadata.gz: 3b594b6ba6699510bedb286cab5e05fc8fa3578d200fdb704fd8335529ee0105
+  data.tar.gz: df3ddc7f65ca300dce59a26855fcadfd88f573c9f892039afa727ec16a3dc01e
 SHA512:
-  metadata.gz: 9a6f385bfd4b2fe956e225888cca22663302b31f6a8c3ca97c3edb3a6f6b5ec13ba1224cc37788724ababd4c518e9eaf06f6234c4aa9d380ec6aeffc9b959af1
-  data.tar.gz: a9e4c94967a476ceb84d11135fe3c6a0755219c3808736692d656df6683587d8e362dd00bb3b8f6b8f1ddddf8a0625fdc0bf6c0918c1529b5e97d9a24152baad
+  metadata.gz: 0d8da9f21bc78c95c31b708a0349d54f23e9a5395bad4de0d46937ec1fae721bd6590a74d498dd523e087b1a1c90b23af6a10c93f2cfaab262d554e3c74272a0
+  data.tar.gz: a67219c39168b2eeae48a638b73ebdfa65a4c5a0300138577088f214868db989e36196647639753563584e49dfb256da0175f2b13aac0b8526d30cb9cee38f44

data/CHANGELOG.md

@@ -7,7 +7,75 @@ minor versions may contain breaking changes.
 
 ## [Unreleased]
 
-## [0.1.0]
+## [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
+
+- Instrumentation: every RPC publishes a `process_rpc.tonic_rails`
+  ActiveSupport::Notifications event (path, service, rpc, metadata, status,
+  code) for APM agents, OpenTelemetry and custom subscribers. With no
+  subscribers it costs nothing measurable.
+- Response metadata: handlers set `response_metadata` (headers) and
+  `trailing_metadata` (trailers, sent on success or failure).
+- Rich errors: `RpcError.new(..., metadata:, details:)` sends trailing
+  metadata and a `google.rpc.Status` with packed details in
+  `grpc-status-details-bin`, which official gRPC clients decode.
+- Puma plugin: `plugin :tonic_rails` in `config/puma.rb` runs the gRPC
+  server as a child process of Puma, in single and cluster mode, with
+  graceful stop and restart, and a shutdown if either side dies.
+- Windows: precompiled `x64-mingw-ucrt` gems, tested in CI.
+- `Tonic::Rails::Testing.invoke` returns the response together with its
+  headers and trailers.
+
+### Changed
+
+- Response headers are sent with the handler's first output instead of
+  before the handler runs, so handlers can set them. The client deadline
+  applies while waiting.
+- `log_requests` logs one line per RPC through the configured (Rails)
+  logger instead of stderr.
+- Transport events from the native extension (rejected calls, expired
+  deadlines, refused connections, faults) go through the configured (Rails)
+  logger with severities instead of stderr. Handler outcomes, such as a
+  `NOT_FOUND` raised by a handler, are no longer logged by the transport;
+  use `log_requests` or the instrumentation event for those.
+- `Server#stop` signals shutdown through a queue instead of a pipe, so
+  signal handling works the same on every platform.
+- Dependencies: magnus 0.9, google-protobuf 4.36.
+
+## [0.1.0] - 2026-10-10
 
 First public release.
 
@@ -48,5 +116,7 @@ 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.1.0...HEAD
+[Unreleased]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.3.0...HEAD
+[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

@@ -30,10 +30,11 @@ end
 
 ## Why tonic-rails
 
-- **Fast where it counts.** Transport overhead is small: an empty RPC
-  runs at roughly 75–80% of a pure-Rust tonic server's throughput. I/O-bound
-  handlers scale with dispatch threads because Ruby releases the GVL
-  while waiting. See [PERF.md](PERF.md).
+- **Fast where it counts.** Inside a Rails app, light RPCs ran at 5–6×
+  the throughput of an equivalent Rails JSON endpoint and 1.4–3× the
+  official `grpc` gem, and server streaming at 4–7× the `grpc` gem.
+  Handlers dominated by slow queries or heavy object building see smaller
+  gains. See [PERF.md](PERF.md).
 - **All four RPC kinds.** Unary, server streaming, client streaming and
   bidirectional streaming, with backpressure in both directions.
 - **Production defaults.** Graceful draining on SIGTERM, health checks
@@ -44,7 +45,7 @@ end
   Reflection is off unless you turn it on. TLS problems stop the server
   instead of silently falling back to plaintext.
 - **No Rust toolchain needed** on the platforms we ship precompiled gems
-  for (Linux and macOS, x86_64 and arm64).
+  for: Linux and macOS (x86_64 and arm64) and Windows (x64).
 
 ## Installation
 
@@ -59,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
@@ -139,7 +161,8 @@ bin/rails tonic_rails:routes   # lists registered methods
 ```
 
 Run it as its own process (a separate Procfile entry, container or
-Kubernetes deployment) next to your web server.
+Kubernetes deployment) next to your web server, or let Puma run it for
+you (see [Running with Puma](#running-with-puma)).
 
 The [example app](example/) is a complete, runnable version of all of the
 above.
@@ -234,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
@@ -248,6 +314,39 @@ end
 When the deadline passes, the client gets `DEADLINE_EXCEEDED` right away;
 check `deadline_exceeded?` in long loops to stop wasted work.
 
+### Response metadata
+
+Set response headers and trailers from a handler:
+
+```ruby
+def get_item(request)
+  response_metadata["x-cache"] = "hit"           # headers
+  trailing_metadata["x-cost-ms"] = "3"           # trailers, sent with the status
+  response_metadata["x-trace-bin"] = trace_bytes # -bin names take binary values
+  Demo::V1::Item.new(id: request.id)
+end
+```
+
+For streaming responses, set headers before the first message is sent.
+Trailers are sent whether the call succeeds or fails.
+
+### Rich errors
+
+`RpcError` can carry trailing metadata and
+[rich error details](https://grpc.io/docs/guides/error/#richer-error-model):
+protobuf messages packed into a `google.rpc.Status` in the standard
+`grpc-status-details-bin` trailer, which official gRPC clients decode for
+you.
+
+```ruby
+raise Tonic::Rails::RpcError.new(
+  "invalid item",
+  code: :invalid_argument,
+  metadata: { "x-request-id" => request_id },
+  details: [Google::Rpc::BadRequest.new(field_violations: violations)],
+)
+```
+
 ### Interceptors
 
 Interceptors wrap every call, outermost first. Call `next_call` to
@@ -280,6 +379,35 @@ expect { Tonic::Rails::Testing.call(ItemService, :GetItem, { id: 0 }) }
 
 # Streaming: pass an Array of requests, get an Array of responses
 Tonic::Rails::Testing.call(ItemService, :ImportItems, [{ name: "a" }, { name: "b" }])
+
+# Response metadata
+result = Tonic::Rails::Testing.invoke(ItemService, :GetItem, { id: 1 })
+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
@@ -313,11 +441,13 @@ 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 |
+| `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) |
-| `log_requests` | `false` | Log every call to stderr (errors are always logged) |
-| `auto_start` | `false` | Start inside `rails server` (see below) |
+| `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
 
@@ -328,31 +458,92 @@ 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.
 
+### Running with Puma
+
+Add the plugin to `config/puma.rb`:
+
+```ruby
+plugin :tonic_rails
+```
+
+Puma then runs the gRPC server as one child process, in single and cluster
+mode alike, so gRPC gets its own process and GVL instead of competing with
+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.)
+
+For larger deployments, a dedicated `bin/rails tonic_rails:serve` process
+(scaled separately) is still the most flexible option.
+
 ### auto_start
 
 `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 prefer a dedicated `tonic_rails:serve`
-process: forking servers such as Puma in cluster mode would need to
-start one per worker.
+development; in production use the Puma plugin or a dedicated process.
+Don't combine it with the plugin.
 
 ## Operations
 
 - **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.
 - **Load shedding.** When every dispatch thread is busy and the queue is
   full, new calls fail fast with `RESOURCE_EXHAUSTED` instead of piling up.
+- **Instrumentation.** Every RPC publishes a `process_rpc.tonic_rails`
+  event through `ActiveSupport::Notifications`, so APM agents,
+  OpenTelemetry and your own subscribers can trace calls. See
+  [Instrumentation](#instrumentation).
+- **Logs.** Everything goes through your (Rails) logger. With
+  `log_requests = true`, each RPC logs one line, e.g.
+  `gRPC /demo.v1.ItemService/GetItem OK in 1.4ms`. Calls the transport
+  rejects before reaching Ruby (unknown methods, a full queue, expired
+  deadlines, oversized messages, refused connections) are always logged,
+  at info for client-caused problems, warn for overload and error for faults.
 - **Stats.** `Tonic::Rails.server.stats` returns counters for totals,
   successes, errors, cancellations, deadline and resource errors, active
   connections and queued calls.
 - **Reflection.** Turn on `reflection` in development to use
   [grpcurl](https://github.com/fullstorydev/grpcurl) without proto files.
 
+## Instrumentation
+
+Every RPC is wrapped in an `ActiveSupport::Notifications` event, inside the
+Rails executor, so subscribers see the same context as your handler:
+
+```ruby
+ActiveSupport::Notifications.subscribe("process_rpc.tonic_rails") do |event|
+  event.payload[:path]      # "/demo.v1.ItemService/GetItem"
+  event.payload[:service]   # "demo.v1.ItemService"
+  event.payload[:rpc]       # "GetItem"
+  event.payload[:metadata]  # request metadata
+  event.payload[:status]    # :ok, :not_found, :internal, ...
+  event.payload[:code]      # numeric gRPC status
+  event.duration            # milliseconds
+end
+```
+
+When a call fails, `event.payload[:exception_object]` is the
+`Tonic::Rails::RpcError` sent to the client. If a handler raised something
+unexpected, that error's `cause` is the original exception.
+
 ## How it works
 
 ```

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

data/lib/generators/tonic_rails/install/templates/tonic_rails.rb.tt

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Ruby code generated from app/protos by `bin/rails tonic_rails:compile_protos`
+# lives in lib/grpc. Its files require each other by plain name, so put the
+# directory on the load path and keep Zeitwerk away from it.
+Rails.root.join("lib/grpc").then do |generated|
+  $LOAD_PATH.unshift(generated.to_s) unless $LOAD_PATH.include?(generated.to_s)
+  Rails.autoloaders.main.ignore(generated)
+end
+
+Tonic::Rails.configure do |config|
+  # config.bind_address = "0.0.0.0:50051"
+  # config.dispatch_threads = ENV.fetch("RAILS_MAX_THREADS", 5).to_i
+  # config.reflection = Rails.env.development?
+  # config.health_check = -> { ActiveRecord::Base.connection.active? }
+end
+
+# Handlers in app/grpc are autoloaded; register them here so they're
+# picked up again after code reloads.
+Rails.application.config.to_prepare do
+end

data/lib/generators/tonic_rails/service/service_generator.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module TonicRails
+  module Generators
+    # rails generate tonic_rails:service Item GetItem ListItems:server ImportItems:client Sync:bidi
+    #
+    # Creates a .proto with the service and its messages, a handler with a
+    # method per RPC, the handler's registration, and a test.
+    class ServiceGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      STREAM_KINDS = %w[unary server client bidi].freeze
+
+      argument :rpcs, type: :array, default: [], banner: "Rpc[:server|:client|:bidi] ..."
+
+      class_option :package, type: :string,
+                             desc: "Protobuf package (default: <app name>.v1)"
+
+      def check_rpcs
+        rpc_specs.each do |rpc|
+          next if rpc[:name].match?(/\A[A-Z][A-Za-z0-9]*\z/) && STREAM_KINDS.include?(rpc[:kind])
+
+          raise Thor::Error, "Invalid RPC #{rpc[:raw].inspect}: use CamelCase names, optionally :server, :client or :bidi"
+        end
+      end
+
+      def create_proto
+        template "service.proto.tt", "app/protos/#{package_path}/#{service_file}_service.proto"
+      end
+
+      def create_handler
+        template "handler.rb.tt", "app/grpc/#{service_file}_service.rb"
+      end
+
+      def register_handler
+        initializer = "config/initializers/tonic_rails.rb"
+        invoke "tonic_rails:install", [], skip_next_steps: true unless File.exist?(File.join(destination_root, initializer))
+        inject_into_file initializer, "  Tonic::Rails.server.register(#{service_class})\n",
+                         after: "Rails.application.config.to_prepare do\n"
+      end
+
+      def create_test
+        if File.directory?(File.join(destination_root, "spec"))
+          template "service_spec.rb.tt", "spec/grpc/#{service_file}_service_spec.rb"
+        else
+          template "service_test.rb.tt", "test/grpc/#{service_file}_service_test.rb"
+        end
+      end
+
+      def show_next_steps
+        say "\nNext: bin/rails tonic_rails:compile_protos, then fill in app/grpc/#{service_file}_service.rb", :green
+      end
+
+      private
+
+      # "Item" and "ItemService" both mean the service ItemService.
+      def service_base
+        class_name.delete_suffix("Service")
+      end
+
+      def service_file
+        service_base.underscore
+      end
+
+      def service_class
+        "#{service_base}Service"
+      end
+
+      def package
+        options[:package] || "#{app_name}.v1"
+      end
+
+      def app_name
+        app = defined?(::Rails.application) && ::Rails.application
+        name = app ? app.class.module_parent_name : File.basename(destination_root)
+        name.to_s.underscore.tr("-", "_").presence || "app"
+      end
+
+      def package_path
+        package.tr(".", "/")
+      end
+
+      def ruby_module
+        package.split(".").map(&:camelize).join("::")
+      end
+
+      def full_service_name
+        "#{package}.#{service_class}"
+      end
+
+      def rpc_specs
+        list = rpcs.empty? ? ["Get#{service_base}"] : rpcs
+        list.map do |raw|
+          name, kind = raw.split(":", 2)
+          { raw: raw, name: name.to_s, kind: kind || "unary", method: name.to_s.underscore }
+        end
+      end
+
+      def proto_rpc_line(rpc)
+        request = "#{rpc[:name]}Request"
+        response = "#{rpc[:name]}Response"
+        request = "stream #{request}" if %w[client bidi].include?(rpc[:kind])
+        response = "stream #{response}" if %w[server bidi].include?(rpc[:kind])
+        "rpc #{rpc[:name]}(#{request}) returns (#{response});"
+      end
+    end
+  end
+end

data/lib/generators/tonic_rails/service/templates/handler.rb.tt

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "<%= package_path %>/<%= service_file %>_service_pb"
+
+class <%= service_class %>
+  include Tonic::Rails::Base
+
+  rpc_service "<%= full_service_name %>"
+  request_format :message
+<% rpc_specs.each do |rpc| %>
+<% case rpc[:kind] -%>
+<% when "unary" -%>
+  # @param request [<%= ruby_module %>::<%= rpc[:name] %>Request]
+  # @return [<%= ruby_module %>::<%= rpc[:name] %>Response]
+  def <%= rpc[:method] %>(request)
+    raise Tonic::Rails::RpcError.new("<%= rpc[:name] %> is not implemented yet", code: :unimplemented)
+  end
+<% when "server" -%>
+  # @param request [<%= ruby_module %>::<%= rpc[:name] %>Request]
+  # @return [Enumerable<<%= ruby_module %>::<%= rpc[:name] %>Response>] each element is streamed as it's produced
+  def <%= rpc[:method] %>(request)
+    raise Tonic::Rails::RpcError.new("<%= rpc[:name] %> is not implemented yet", code: :unimplemented)
+  end
+<% when "client" -%>
+  # @param requests [Enumerator<<%= ruby_module %>::<%= rpc[:name] %>Request>] yields messages as they arrive
+  # @return [<%= ruby_module %>::<%= rpc[:name] %>Response]
+  def <%= rpc[:method] %>(requests)
+    raise Tonic::Rails::RpcError.new("<%= rpc[:name] %> is not implemented yet", code: :unimplemented)
+  end
+<% else -%>
+  # @param requests [Enumerator<<%= ruby_module %>::<%= rpc[:name] %>Request>] yields messages as they arrive
+  # @return [Enumerable<<%= ruby_module %>::<%= rpc[:name] %>Response>]
+  def <%= rpc[:method] %>(requests)
+    raise Tonic::Rails::RpcError.new("<%= rpc[:name] %> is not implemented yet", code: :unimplemented)
+  end
+<% end -%>
+<% end -%>
+end

data/lib/generators/tonic_rails/service/templates/service.proto.tt

@@ -0,0 +1,16 @@
+syntax = "proto3";
+
+package <%= package %>;
+
+service <%= service_class %> {
+<% rpc_specs.each do |rpc| -%>
+  <%= proto_rpc_line(rpc) %>
+<% end -%>
+}
+<% rpc_specs.each do |rpc| %>
+message <%= rpc[:name] %>Request {
+}
+
+message <%= rpc[:name] %>Response {
+}
+<% end -%>

data/lib/generators/tonic_rails/service/templates/service_spec.rb.tt

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+require "tonic/rails/testing/rspec"
+
+RSpec.describe <%= service_class %> do
+<% rpc_specs.each_with_index do |rpc, i| -%>
+<% if i.positive? %>
+<% end -%>
+  describe "<%= rpc[:name] %>" do
+    it "is not implemented yet" do
+      request = <%= %w[client bidi].include?(rpc[:kind]) ? "[#{ruby_module}::#{rpc[:name]}Request.new]" : "#{ruby_module}::#{rpc[:name]}Request.new" %>
+      expect { Tonic::Rails::Testing.call(described_class, :<%= rpc[:name] %>, request) }.to raise_grpc_error(:unimplemented)
+    end
+  end
+<% end -%>
+end

data/lib/generators/tonic_rails/service/templates/service_test.rb.tt

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "tonic/rails/testing/minitest"
+
+class <%= service_class %>Test < ActiveSupport::TestCase
+  include Tonic::Rails::Testing::Assertions
+<% rpc_specs.each do |rpc| %>
+  test "<%= rpc[:name] %> is not implemented yet" do
+    request = <%= %w[client bidi].include?(rpc[:kind]) ? "[#{ruby_module}::#{rpc[:name]}Request.new]" : "#{ruby_module}::#{rpc[:name]}Request.new" %>
+    assert_grpc_error(:unimplemented) { Tonic::Rails::Testing.call(<%= service_class %>, :<%= rpc[:name] %>, request) }
+  end
+<% end -%>
+end