respondo-grpc 1.0.0

data/lib/respondo_grpc/status_map.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module RespondoGrpc
+  # Maps the HTTP-style codes used by every Respondo helper (404, 422, ...) onto
+  # gRPC status codes. The numbers are the canonical ones from the gRPC spec
+  # (GRPC::Core::StatusCodes), kept here so this file needs no gRPC dependency.
+  #
+  # The table follows the usual HTTP <-> gRPC correspondence (see the gRPC
+  # status-code docs and Google's API design guide). Codes with no natural gRPC
+  # twin are mapped to the closest meaning. Override any of them:
+  #
+  #   RespondoGrpc.configure { |c| c.status_map = { 409 => :aborted } }
+  module StatusMap
+    CODES = {
+      ok:                  0,
+      cancelled:           1,
+      unknown:             2,
+      invalid_argument:    3,
+      deadline_exceeded:   4,
+      not_found:           5,
+      already_exists:      6,
+      permission_denied:   7,
+      resource_exhausted:  8,
+      failed_precondition: 9,
+      aborted:             10,
+      out_of_range:        11,
+      unimplemented:       12,
+      internal:            13,
+      unavailable:         14,
+      data_loss:           15,
+      unauthenticated:     16
+    }.freeze
+
+    HTTP_TO_GRPC = {
+      400 => :invalid_argument,
+      401 => :unauthenticated,
+      402 => :failed_precondition,
+      403 => :permission_denied,
+      404 => :not_found,
+      405 => :unimplemented,
+      406 => :invalid_argument,
+      407 => :unauthenticated,
+      408 => :deadline_exceeded,
+      409 => :already_exists,
+      410 => :not_found,
+      411 => :invalid_argument,
+      412 => :failed_precondition,
+      413 => :resource_exhausted,
+      414 => :invalid_argument,
+      415 => :invalid_argument,
+      416 => :out_of_range,
+      417 => :failed_precondition,
+      418 => :unknown,
+      421 => :failed_precondition,
+      422 => :invalid_argument,
+      423 => :failed_precondition,
+      424 => :failed_precondition,
+      425 => :failed_precondition,
+      426 => :failed_precondition,
+      428 => :failed_precondition,
+      429 => :resource_exhausted,
+      431 => :resource_exhausted,
+      451 => :permission_denied,
+      500 => :internal,
+      501 => :unimplemented,
+      502 => :unavailable,
+      503 => :unavailable,
+      504 => :deadline_exceeded,
+      505 => :unimplemented,
+      506 => :internal,
+      507 => :resource_exhausted,
+      508 => :internal,
+      510 => :unimplemented,
+      511 => :unauthenticated
+    }.freeze
+
+    module_function
+
+    # @param http_code [Integer] e.g. 404
+    # @return [Integer] gRPC status code, e.g. 5
+    def grpc_code_for(http_code)
+      name = RespondoGrpc.config.status_map[http_code] || HTTP_TO_GRPC[http_code] || fallback_for(http_code)
+      resolve(name)
+    end
+
+    # @param value [Integer, Symbol, String] 5, :not_found or "NOT_FOUND"
+    # @return [Integer]
+    def resolve(value)
+      return value if value.is_a?(Integer)
+
+      CODES.fetch(value.to_s.downcase.to_sym) do
+        raise ArgumentError, "Unknown gRPC status #{value.inspect}. Use one of: #{CODES.keys.join(', ')}"
+      end
+    end
+
+    # Name for a gRPC status code, e.g. 5 -> :not_found
+    def name_for(grpc_code)
+      CODES.key(grpc_code)
+    end
+
+    def fallback_for(http_code)
+      case http_code
+      when 200..299 then :ok
+      when 400..499 then :invalid_argument
+      when 500..599 then :internal
+      else :unknown
+      end
+    end
+  end
+end

data/lib/respondo_grpc/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RespondoGrpc
+  VERSION = "1.0.0"
+end

data/lib/respondo_grpc.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "google/protobuf"
+require "google/protobuf/well_known_types"
+
+require_relative "respondo_grpc/version"
+require_relative "respondo_grpc/configuration"
+require_relative "respondo_grpc/status_map"
+require_relative "respondo_grpc/serializer"
+require_relative "respondo_grpc/response_builder"
+# The respondo.v1.Response message (compiled from proto/respondo/v1/response.proto).
+require_relative "respondo/v1/response_pb"
+require_relative "respondo_grpc/proto_mapper"
+require_relative "respondo_grpc/service_helpers"
+require_relative "respondo_grpc/short_helpers"
+require_relative "respondo_grpc/client_helpers"
+
+# RespondoGrpc — consistent response envelopes for gRPC services.
+#
+# @example Configure once in an initializer
+#   RespondoGrpc.configure do |config|
+#     config.include_request_id = true
+#     config.default_meta       = { api_version: "v1" }
+#     config.always_ok          = false   # failures finish with a real gRPC status
+#   end
+#
+# @example Use in a gRPC service
+#   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
+#   end
+#
+# @example Short names (opt-in)
+#   include RespondoGrpc::ShortHelpers   # render_ok, render_not_found, ...
+module RespondoGrpc
+  # Trailing-metadata key that carries the serialized respondo.v1.Response on a
+  # failed call. Keys ending in "-bin" are binary-safe in gRPC.
+  METADATA_KEY = "respondo-response-bin"
+
+  class << self
+    # @return [RespondoGrpc::Configuration]
+    def config
+      @config ||= Configuration.new
+    end
+
+    # @yield [RespondoGrpc::Configuration]
+    def configure
+      yield config
+    end
+
+    # Reset config (useful in tests)
+    def reset!
+      @config = Configuration.new
+    end
+
+    # Build the exception that finishes a call with `grpc_code`. Returns the
+    # matching subclass (GRPC::NotFound, GRPC::InvalidArgument, ...).
+    #
+    # @param grpc_code [Integer]
+    # @param details   [String]
+    # @param metadata  [Hash]
+    # @return [GRPC::BadStatus]
+    def bad_status(grpc_code, details, metadata = {})
+      require "grpc"
+      ::GRPC::BadStatus.new_status_exception(grpc_code, details, metadata)
+    end
+  end
+end

data/proto/respondo/v1/response.proto

@@ -0,0 +1,78 @@
+syntax = "proto3";
+
+package respondo.v1;
+
+import "google/protobuf/any.proto";
+import "google/protobuf/struct.proto";
+
+// The response envelope shared by the Respondo gems, as a protobuf message.
+//
+//   respondo (JSON)      { success, message, data, errors, meta }
+//   respondo-graphql     { data, errors, extensions }
+//   respondo-grpc        this message
+//
+// Use it as the return type of any rpc:
+//
+//   import "respondo/v1/response.proto";
+//
+//   service UserService {
+//     rpc GetUser(GetUserRequest) returns (respondo.v1.Response);
+//   }
+message Response {
+  bool success = 1;
+  string message = 2;
+
+  // JSON-like payload: a hash, array, scalar or null. Built from ActiveRecord
+  // records, hashes, arrays, ...
+  google.protobuf.Value data = 3;
+
+  // Typed payload. Set instead of `data` when the server passes a protobuf
+  // message, so the client can unpack it into a real class.
+  google.protobuf.Any payload = 4;
+
+  // Field-level errors, e.g. { field: "email", messages: ["is invalid"] }.
+  repeated FieldError errors = 5;
+
+  Meta meta = 6;
+}
+
+message FieldError {
+  string field = 1;
+  repeated string messages = 2;
+}
+
+message Meta {
+  // Copied from request metadata when config.include_request_id is on.
+  string request_id = 1;
+
+  // ISO 8601, UTC.
+  string timestamp = 2;
+
+  // HTTP-style code the helper stands for (200, 404, 422, ...). Same numbers
+  // as the respondo / respondo-graphql gems, so envelopes line up across all three.
+  int32 code = 3;
+
+  // Matching status name, e.g. "not_found".
+  string status = 4;
+
+  // gRPC status code (0 = OK, 5 = NOT_FOUND, ...). Always set on failures; this
+  // is the code to read when config.always_ok sends failures as a normal reply.
+  int32 grpc_code = 5;
+
+  // Custom machine-readable code, e.g. "AUTH_EXPIRED". Only set when supplied.
+  string error_code = 6;
+
+  Pagination pagination = 7;
+
+  // config.default_meta plus any extra keys passed through meta:.
+  google.protobuf.Struct extra = 8;
+}
+
+message Pagination {
+  int32 current_page = 1;
+  int32 per_page = 2;
+  int32 total_pages = 3;
+  int32 total_count = 4;
+  optional int32 next_page = 5;
+  optional int32 prev_page = 6;
+}

data/respondo-grpc.gemspec

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "lib/respondo_grpc/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "respondo-grpc"
+  spec.version       = RespondoGrpc::VERSION
+  spec.authors       = ["shailendra Kumar"]
+  spec.email         = ["shailendrapatidar00@gmail.com"]
+
+  spec.summary       = "Consistent response envelopes for gRPC services — data, errors, meta, real status codes."
+  spec.description   = <<~DESC
+    RespondoGrpc standardizes the responses your gRPC services send. Every rpc can
+    return one protobuf envelope (respondo.v1.Response: success, message, data,
+    errors, meta), built from the same expressive helpers as its siblings
+    (render_grpc_ok, render_grpc_not_found, render_grpc_unprocessable, ...).
+    Failures finish the call with the matching gRPC status code (NOT_FOUND,
+    INVALID_ARGUMENT, ...) and carry the envelope in the trailing metadata, so
+    clients get both a proper status and structured field errors. Protobuf messages
+    travel as typed payloads, hashes and ActiveRecord records as JSON-like data.
+    Standalone gem — it does not depend on respondo (JSON) or respondo-graphql.
+  DESC
+  spec.homepage      = "https://github.com/spatelpatidar/respondo-grpc"
+  spec.license       = "Apache-2.0"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata = {
+    "homepage_uri"          => spec.homepage,
+    "source_code_uri"       => spec.homepage,
+    "changelog_uri"         => "#{spec.homepage}/blob/main/CHANGELOG.md",
+    "bug_tracker_uri"       => "#{spec.homepage}/issues",
+    "rubygems_mfa_required" => "true"
+  }
+
+  spec.files = Dir["lib/**/*.rb", "proto/**/*.proto", "README.md", "LICENSE", "CHANGELOG.md", "respondo-grpc.gemspec"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "google-protobuf", ">= 3.25"
+  spec.add_dependency "grpc",            ">= 1.60"
+
+  spec.add_development_dependency "grpc-tools",  ">= 1.60"
+  spec.add_development_dependency "rspec",       "~> 3.12"
+  spec.add_development_dependency "rake",        "~> 13.0"
+  spec.add_development_dependency "simplecov",   "~> 0.22"
+end

metadata

@@ -0,0 +1,159 @@
+--- !ruby/object:Gem::Specification
+name: respondo-grpc
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- shailendra Kumar
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-11-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: google-protobuf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.25'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.25'
+- !ruby/object:Gem::Dependency
+  name: grpc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.60'
+- !ruby/object:Gem::Dependency
+  name: grpc-tools
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.60'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: |
+  RespondoGrpc standardizes the responses your gRPC services send. Every rpc can
+  return one protobuf envelope (respondo.v1.Response: success, message, data,
+  errors, meta), built from the same expressive helpers as its siblings
+  (render_grpc_ok, render_grpc_not_found, render_grpc_unprocessable, ...).
+  Failures finish the call with the matching gRPC status code (NOT_FOUND,
+  INVALID_ARGUMENT, ...) and carry the envelope in the trailing metadata, so
+  clients get both a proper status and structured field errors. Protobuf messages
+  travel as typed payloads, hashes and ActiveRecord records as JSON-like data.
+  Standalone gem — it does not depend on respondo (JSON) or respondo-graphql.
+email:
+- shailendrapatidar00@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/respondo-grpc.rb
+- lib/respondo/v1/response_pb.rb
+- lib/respondo_grpc.rb
+- lib/respondo_grpc/client_helpers.rb
+- lib/respondo_grpc/configuration.rb
+- lib/respondo_grpc/proto_mapper.rb
+- lib/respondo_grpc/response_builder.rb
+- lib/respondo_grpc/serializer.rb
+- lib/respondo_grpc/service_helpers.rb
+- lib/respondo_grpc/short_helpers.rb
+- lib/respondo_grpc/status_map.rb
+- lib/respondo_grpc/version.rb
+- proto/respondo/v1/response.proto
+- respondo-grpc.gemspec
+homepage: https://github.com/spatelpatidar/respondo-grpc
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/spatelpatidar/respondo-grpc
+  source_code_uri: https://github.com/spatelpatidar/respondo-grpc
+  changelog_uri: https://github.com/spatelpatidar/respondo-grpc/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/spatelpatidar/respondo-grpc/issues
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.1
+signing_key: 
+specification_version: 4
+summary: Consistent response envelopes for gRPC services — data, errors, meta, real
+  status codes.
+test_files: []