respondo-grpc 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 20ddd7ac619ee059822fee6c9bbf1c7fc18e18c3df7ba2c3da5b59aece58384e
+  data.tar.gz: 83995bb81bf937e308e8cdebe9112fff5f010f352416c2c801232b03f71730a6
+SHA512:
+  metadata.gz: f79102dc1bdffc70993c3007186fc84b6b4c2eabc0b43ace8fc83d34922c625cfa0ca4b770172e421cdd8ffb72fbbe3611b25f3cf61ec20b238e4674739f55a6
+  data.tar.gz: e77ab17701a23da42c6d97396bc86cff1ac367427f239ceeeab33f4573657f4f2103dd657b7924d4fb572205c54109429a8d1256c40d77c056b32d5630b389c4

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## [1.0.0] — Initial release
+
+### Added
+- `respondo.v1.Response` protobuf envelope (`proto/respondo/v1/response.proto`):
+  `success`, `message`, `data` (`google.protobuf.Value`), `payload` (`google.protobuf.Any`),
+  `errors` (`FieldError`), `meta` (`request_id`, `timestamp`, `code`, `status`, `grpc_code`,
+  `error_code`, `pagination`, `extra`).
+- `RespondoGrpc::ServiceHelpers`: `render_grpc_*` helpers for every 2xx / 4xx / 5xx situation
+  (same names and codes as the respondo-graphql helpers, with `call:` for the request id).
+  Success helpers return the envelope; error helpers raise `GRPC::BadStatus` with the mapped
+  gRPC status and the envelope in the `respondo-response-bin` trailing metadata.
+- `RespondoGrpc::ShortHelpers`: opt-in short names (`render_ok`, `render_not_found`, …).
+- `RespondoGrpc::StatusMap`: HTTP-style code → gRPC status table, overridable with
+  `config.status_map`.
+- `RespondoGrpc::ClientHelpers`: `to_h`, `error_response` and `error_hash` for reading replies
+  and failures on the client.
+- Protobuf messages passed as `data:` travel as typed payloads (`Any`); hashes, arrays and
+  ActiveRecord records travel as JSON-like `data`.
+- Configuration: `default_success_message`, `default_error_message`, `include_request_id`,
+  `request_id_key`, `serializer`, `default_meta`, `always_ok`, `status_map`.

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Shailendra Kumar
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,200 @@
+<div align="center">
+
+# Respondo gRPC 🛰️
+
+**Consistent response envelopes for gRPC services — real status codes, structured errors, one line per reply.**
+
+[![CI Suite](https://github.com/spatelpatidar/respondo-grpc/actions/workflows/ci.yml/badge.svg)](https://github.com/spatelpatidar/respondo-grpc/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/respondo-grpc.svg)](https://rubygems.org/gems/respondo-grpc)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache2.0-green.svg)](LICENSE)
+[![Ruby](https://img.shields.io/badge/Ruby-2.7%2B-red)](https://www.ruby-lang.org/)
+
+</div>
+
+---
+
+`respondo-grpc` is the gRPC sibling of [`respondo`](https://github.com/spatelpatidar/respondo) (JSON) and [`respondo-graphql`](https://github.com/spatelpatidar/respondo-graphql). It is a **standalone gem** with its own namespace (`RespondoGrpc`), config and protobuf message. Install any of the three, or all of them.
+
+Same idea, same helper names and codes: one expressive helper per situation (`render_grpc_ok`, `render_grpc_not_found`, `render_grpc_unprocessable`, …). What changes is the transport:
+
+| | respondo (JSON) | respondo-graphql | respondo-grpc |
+|---|---|---|---|
+| Envelope | `success, message, data, errors, meta` | `data, errors, extensions` | `respondo.v1.Response` message |
+| Failure signal | HTTP status | `errors[]` (+ HTTP status) | **gRPC status code** + envelope |
+| Typed payloads | no | no | yes (`google.protobuf.Any`) |
+
+## Install
+
+```ruby
+# Gemfile
+gem "respondo-grpc"
+```
+
+```bash
+bundle install
+```
+
+## Use the envelope in your `.proto`
+
+The gem ships `proto/respondo/v1/response.proto`. Import it and return it from any rpc:
+
+```proto
+syntax = "proto3";
+package example.users.v1;
+
+import "respondo/v1/response.proto";
+
+service UserService {
+  rpc GetUser(GetUserRequest) returns (respondo.v1.Response);
+}
+```
+
+Compile your protos with the gem's `proto/` directory on the include path:
+
+```bash
+GEM_PROTO="$(bundle exec ruby -e 'puts File.join(Gem.loaded_specs["respondo-grpc"].full_gem_path, "proto")')"
+grpc_tools_ruby_protoc -I proto -I "$GEM_PROTO" --ruby_out=gen --grpc_out=gen proto/users/v1/users.proto
+```
+
+The compiled `Respondo::V1::Response` class comes with the gem; you do not compile it yourself.
+
+## Usage
+
+```ruby
+class UserService < Example::Users::V1::UserService::Service
+  include RespondoGrpc::ServiceHelpers
+
+  def get_user(request, call)
+    user = User.find_by(id: request.id)
+    return render_grpc_not_found(message: "User not found", call: call) unless user
+
+    render_grpc_ok(data: user, message: "User fetched", call: call)
+  end
+
+  def create_user(request, call)
+    user = User.new(name: request.name, email: request.email)
+    if user.save
+      render_grpc_created(data: user, message: "Account created", call: call)
+    else
+      render_grpc_unprocessable(message: "Validation failed", errors: user.errors, call: call)
+    end
+  end
+end
+```
+
+* **Success helpers return** the `Respondo::V1::Response`. Make the call the last expression of the rpc.
+* **Error helpers raise** `GRPC::BadStatus` with the mapped gRPC status (`NOT_FOUND`, `INVALID_ARGUMENT`, …). The message is the status detail, and the whole envelope rides in the `respondo-response-bin` trailing metadata. `return render_grpc_not_found(...)` reads naturally and works in both modes (see `always_ok`).
+* `call:` is optional. Pass the rpc's second argument to let `include_request_id` copy the client's `x-request-id` into `meta`.
+
+**What the client receives** for `render_grpc_ok(data: { id: 1 }, message: "User fetched")` (shown as JSON):
+
+```json
+{
+  "success": true,
+  "message": "User fetched",
+  "data": { "id": 1 },
+  "meta": { "timestamp": "2026-10-26T10:30:00Z", "code": 200, "status": "ok" }
+}
+```
+
+and for `render_grpc_unprocessable(message: "Validation failed", errors: { email: ["is invalid"] })`, a call that finishes with `INVALID_ARGUMENT` (3) and this envelope in its trailers:
+
+```json
+{
+  "message": "Validation failed",
+  "errors": [{ "field": "email", "messages": ["is invalid"] }],
+  "meta": { "timestamp": "2026-10-26T10:30:00Z", "code": 422, "status": "unprocessable_content", "grpcCode": 3 }
+}
+```
+
+### What goes where
+
+| You pass | Where it ends up |
+|---|---|
+| `data:` hash / array / scalar / ActiveRecord | `Response.data` (`google.protobuf.Value`) |
+| `data:` a **protobuf message** | `Response.payload` (`google.protobuf.Any`), so the client can unpack a real class |
+| `message:` | `Response.message`, and the gRPC status detail on failure |
+| `errors: { field: [...] }` / `ActiveModel::Errors` | `Response.errors[]` (`field`, `messages`) |
+| `pagination: { current_page:, per_page:, total_pages:, total_count:, next_page:, prev_page: }` | `Response.meta.pagination` (other keys are ignored) |
+| `meta: { ... }` and `config.default_meta` | `Response.meta.extra` (`google.protobuf.Struct`) |
+
+`google.protobuf.Value` has a single number type, so numbers inside `data` come back as floats (`1.0`). Use a typed payload when exact integers matter.
+
+## Reading replies on the client
+
+```ruby
+stub = Example::Users::V1::UserService::Stub.new("localhost:50051", :this_channel_is_insecure)
+
+begin
+  response = stub.get_user(Example::Users::V1::GetUserRequest.new(id: 42),
+                           metadata: { "x-request-id" => "abc-123" })
+
+  user = response.payload.unpack(Example::Users::V1::User)    # typed payload
+  RespondoGrpc::ClientHelpers.to_h(response)[:data]           # JSON-like data, as plain Ruby
+rescue GRPC::BadStatus => e
+  failure = RespondoGrpc::ClientHelpers.error_hash(e)
+  failure[:message]            # => "User not found"
+  failure[:errors]             # => { email: ["is invalid"] }
+  failure[:meta][:grpc_code]   # => 5
+end
+```
+
+`error_hash` falls back to the status details when the server sent no envelope, so there is always a message to show.
+
+## Helpers
+
+Every helper takes `message:`, `meta:` and `call:`. Success helpers also take `data:` and `pagination:`; error helpers take `errors:`.
+
+| Kind | Helpers |
+|---|---|
+| Success (2xx) | `render_grpc_ok`, `_created`, `_accepted`, `_non_authoritative`, `_partial_content`, `_multi_status`, `_already_reported`, `_im_used`; without `data:`: `_no_content`, `_reset_content` |
+| Client errors (4xx) | `render_grpc_bad_request`, `_unauthorized`, `_forbidden`, `_not_found`, `_conflict`, `_gone`, `_unprocessable`, `_too_many_requests`, … (all 29) |
+| Server errors (5xx) | `render_grpc_server_error`, `_not_implemented`, `_bad_gateway`, `_service_unavailable`, `_gateway_timeout`, … (all 11) |
+
+The names and numeric codes match `respondo-graphql`, so `meta.code` means the same thing in every envelope. 1xx and 3xx helpers are not provided: they are HTTP transport concepts with no meaning in gRPC.
+
+Prefer shorter names? `include RespondoGrpc::ShortHelpers` gives you `render_ok`, `render_not_found`, … as aliases. They are never mixed in automatically, because those are the names the JSON gem uses in controllers.
+
+### HTTP code → gRPC status
+
+| HTTP-style code | gRPC status | | HTTP-style code | gRPC status |
+|---|---|---|---|---|
+| 400, 406, 411, 414, 415, 422 | `INVALID_ARGUMENT` (3) | | 409 | `ALREADY_EXISTS` (6) |
+| 401, 407, 511 | `UNAUTHENTICATED` (16) | | 402, 412, 417, 421, 423–426, 428 | `FAILED_PRECONDITION` (9) |
+| 403, 451 | `PERMISSION_DENIED` (7) | | 413, 429, 431, 507 | `RESOURCE_EXHAUSTED` (8) |
+| 404, 410 | `NOT_FOUND` (5) | | 416 | `OUT_OF_RANGE` (11) |
+| 408, 504 | `DEADLINE_EXCEEDED` (4) | | 405, 501, 505, 510 | `UNIMPLEMENTED` (12) |
+| 500, 506, 508 | `INTERNAL` (13) | | 502, 503 | `UNAVAILABLE` (14) |
+| 418 | `UNKNOWN` (2) | | | |
+
+Disagree with one? `config.status_map = { 409 => :aborted }`.
+
+## Configuration
+
+```ruby
+RespondoGrpc.configure do |config|
+  config.default_success_message = "Success"
+  config.default_error_message   = "An error occurred"
+  config.include_request_id      = false          # copy x-request-id into meta.request_id
+  config.request_id_key          = "x-request-id" # metadata key to read it from
+  config.always_ok               = false          # see below
+  config.status_map              = {}             # e.g. { 409 => :aborted }
+  config.default_meta            = { api_version: "v1" }
+  config.serializer              = ->(obj) { MySerializer.new(obj).as_json }
+end
+```
+
+**`always_ok`** — by default failures finish the call with a real gRPC status code, which is what interceptors, retries, load balancers and monitoring understand. Set `config.always_ok = true` to answer failures as a normal reply (status `OK`) with `success: false` and `meta.grpc_code` in the message, if your clients only look at the message body.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec          # specs
+bundle exec rake proto     # recompile the .proto files (needs grpc-tools)
+bundle exec rake publish   # spec → build → push
+```
+
+## License
+
+Apache-2.0

data/lib/respondo/v1/response_pb.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+# Descriptor compiled from respondo/v1/response.proto with protoc 35.1; same layout as `protoc --ruby_out`.
+# Regenerate with grpc_tools_ruby_protoc (see README), it produces an equivalent file.
+# source: respondo/v1/response.proto
+
+require 'google/protobuf'
+
+require 'google/protobuf/any_pb'
+require 'google/protobuf/struct_pb'
+
+descriptor_data = "\n\x1arespondo/v1/response.proto\x12\x0brespondo.v1\x1a\x19google/protobuf/any.proto\x1a\x1cgoogle/protobuf/struct.proto\"\xf2\x01\n\x08Response\x12\x18\n\x07success\x18\x01 \x01(\x08R\x07success\x12\x18\n\x07message\x18\x02 \x01(\x09R\x07message\x12*\n\x04data\x18\x03 \x01(\x0b2\x16.google.protobuf.ValueR\x04data\x12.\n\x07payload\x18\x04 \x01(\x0b2\x14.google.protobuf.AnyR\x07payload\x12/\n\x06errors\x18\x05 \x03(\x0b2\x17.respondo.v1.FieldErrorR\x06errors\x12%\n\x04meta\x18\x06 \x01(\x0b2\x11.respondo.v1.MetaR\x04meta\">\n\nFieldError\x12\x14\n\x05field\x18\x01 \x01(\x09R\x05field\x12\x1a\n\x08messages\x18\x02 \x03(\x09R\x08messages\"\x93\x02\n\x04Meta\x12\x1d\n\nrequest_id\x18\x01 \x01(\x09R\x09requestId\x12\x1c\n\x09timestamp\x18\x02 \x01(\x09R\x09timestamp\x12\x12\n\x04code\x18\x03 \x01(\x05R\x04code\x12\x16\n\x06status\x18\x04 \x01(\x09R\x06status\x12\x1b\n\x09grpc_code\x18\x05 \x01(\x05R\x08grpcCode\x12\x1d\n\nerror_code\x18\x06 \x01(\x09R\x09errorCode\x127\n\npagination\x18\x07 \x01(\x0b2\x17.respondo.v1.PaginationR\npagination\x12-\n\x05extra\x18\x08 \x01(\x0b2\x17.google.protobuf.StructR\x05extra\"\xec\x01\n\nPagination\x12!\n\x0ccurrent_page\x18\x01 \x01(\x05R\x0bcurrentPage\x12\x19\n\x08per_page\x18\x02 \x01(\x05R\x07perPage\x12\x1f\n\x0btotal_pages\x18\x03 \x01(\x05R\ntotalPages\x12\x1f\n\x0btotal_count\x18\x04 \x01(\x05R\ntotalCount\x12 \n\x09next_page\x18\x05 \x01(\x05H\x00R\x08nextPage\x88\x01\x01\x12 \n\x09prev_page\x18\x06 \x01(\x05H\x01R\x08prevPage\x88\x01\x01B\x0c\n\n_next_pageB\x0c\n\n_prev_pageb\x06proto3".b
+
+pool = Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Respondo
+  module V1
+    Response = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("respondo.v1.Response").msgclass
+    FieldError = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("respondo.v1.FieldError").msgclass
+    Meta = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("respondo.v1.Meta").msgclass
+    Pagination = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("respondo.v1.Pagination").msgclass
+  end
+end

data/lib/respondo-grpc.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Lets `gem "respondo-grpc"` be auto-required by Bundler.require
+# (Bundler requires the gem's own name, hyphen included).
+require_relative "respondo_grpc"

data/lib/respondo_grpc/client_helpers.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module RespondoGrpc
+  # Client-side helpers: read a respondo.v1.Response, or the one a failed call
+  # carries in its trailing metadata.
+  #
+  #   begin
+  #     response = stub.get_user(Example::Users::V1::GetUserRequest.new(id: 42))
+  #     result   = RespondoGrpc::ClientHelpers.to_h(response)
+  #     result[:data]            # plain Ruby, for hash-style payloads
+  #     response.payload.unpack(Example::Users::V1::User)   # typed payloads
+  #   rescue GRPC::BadStatus => e
+  #     failure = RespondoGrpc::ClientHelpers.error_hash(e)
+  #     failure[:message]        # => "User not found"
+  #     failure[:errors]         # => { email: ["is invalid"] }
+  #     failure[:meta][:grpc_code]
+  #   end
+  module ClientHelpers
+    module_function
+
+    # @param response [Respondo::V1::Response]
+    # @return [Hash] { success:, message:, data:, payload:, errors:, meta: }
+    def to_h(response)
+      ProtoMapper.to_h(response)
+    end
+
+    # The envelope a failed call carried, or nil when the server did not send one
+    # (a plain gRPC error, a transport failure, ...).
+    #
+    # @param bad_status [GRPC::BadStatus]
+    # @return [Respondo::V1::Response, nil]
+    def error_response(bad_status)
+      metadata = bad_status.respond_to?(:metadata) ? bad_status.metadata : nil
+      bytes    = metadata && metadata[RespondoGrpc::METADATA_KEY]
+      return nil if bytes.nil? || bytes.empty?
+
+      ProtoMapper.decode(bytes)
+    rescue ::Google::Protobuf::ParseError
+      nil
+    end
+
+    # Same as error_response, as a Hash. Falls back to the status details when
+    # there is no envelope, so there is always something to show.
+    #
+    # @param bad_status [GRPC::BadStatus]
+    # @return [Hash]
+    def error_hash(bad_status)
+      response = error_response(bad_status)
+      return ProtoMapper.to_h(response) if response
+
+      { success: false, message: bad_status.details.to_s, meta: { grpc_code: bad_status.code } }
+    end
+  end
+end

data/lib/respondo_grpc/configuration.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module RespondoGrpc
+  # Global configuration for RespondoGrpc.
+  #
+  # @example
+  #   RespondoGrpc.configure do |config|
+  #     config.default_success_message = "OK"
+  #     config.include_request_id      = true
+  #     config.always_ok               = false
+  #     config.default_meta            = { api_version: "v1" }
+  #   end
+  class Configuration
+    # Message used when none is supplied to a success helper
+    attr_accessor :default_success_message
+
+    # Message used when none is supplied to an error helper
+    attr_accessor :default_error_message
+
+    # When true, copies the request id from the call's metadata into every
+    # response's meta block (see request_id_key). Needs `call:` on the helper.
+    attr_accessor :include_request_id
+
+    # Request metadata key the request id is read from (gRPC keys are lowercase).
+    attr_accessor :request_id_key
+
+    # Custom serializer callable — receives (object) and returns a Hash/Array.
+    # Defaults to nil (built-in serialization strategy is used).
+    # @example config.serializer = ->(obj) { MySerializer.new(obj).as_json }
+    attr_accessor :serializer
+
+    # Static key-value pairs merged into every response's `meta.extra` block.
+    # @example config.default_meta = { api_version: "v1" }
+    attr_accessor :default_meta
+
+    # By default an error helper raises GRPC::BadStatus, so the call finishes
+    # with a real gRPC status code (NOT_FOUND, INVALID_ARGUMENT, ...) and the
+    # envelope rides in the trailing metadata. When true, error helpers return
+    # the envelope as a normal reply and the call finishes with status OK;
+    # clients then read `success` / `meta.grpc_code` from the message.
+    attr_accessor :always_ok
+
+    # Overrides for the HTTP-code -> gRPC-status table, e.g. { 409 => :aborted }.
+    # Values are status names (see StatusMap::CODES) or integers.
+    attr_accessor :status_map
+
+    def initialize
+      @default_success_message = "Success"
+      @default_error_message   = "An error occurred"
+      @include_request_id      = false
+      @request_id_key          = "x-request-id"
+      @serializer              = nil
+      @default_meta            = {}
+      @always_ok               = false
+      @status_map              = {}
+    end
+  end
+end