respondo-grpc 1.0.0

data/lib/respondo_grpc/proto_mapper.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "time"
+
+module RespondoGrpc
+  # Converts between the Hash built by ResponseBuilder and the
+  # respondo.v1.Response protobuf message — in both directions.
+  module ProtoMapper
+    PAGINATION_KEYS = %i[current_page per_page total_pages total_count next_page prev_page].freeze
+
+    module_function
+
+    # @param hash [Hash] output of ResponseBuilder#build
+    # @return [Respondo::V1::Response]
+    def to_proto(hash)
+      response = ::Respondo::V1::Response.new(success: hash[:success] ? true : false,
+                                              message: hash[:message].to_s)
+
+      if hash[:payload]
+        response.payload = ::Google::Protobuf::Any.pack(hash[:payload])
+      elsif !hash[:data].nil?
+        response.data = ::Google::Protobuf::Value.from_ruby(jsonable(hash[:data]))
+      end
+
+      (hash[:errors] || {}).each do |field, messages|
+        response.errors << ::Respondo::V1::FieldError.new(field: field.to_s,
+                                                          messages: Array(messages).map(&:to_s))
+      end
+
+      response.meta = meta_to_proto(hash[:meta] || {})
+      response
+    end
+
+    # @param response [Respondo::V1::Response]
+    # @return [Hash] { success:, message:, data:, payload:, errors:, meta: }
+    #   `data` comes back as plain Ruby (String keys; every number is a Float,
+    #   because google.protobuf.Value has a single number type). `payload` stays a
+    #   Google::Protobuf::Any — call `.unpack(MyMessage)` on it.
+    def to_h(response)
+      hash = { success: response.success, message: response.message }
+      hash[:data]    = response.data.to_ruby(true) if response.has_data?
+      hash[:payload] = response.payload if response.has_payload?
+
+      errors = response.errors.each_with_object({}) do |error, memo|
+        memo[error.field.to_sym] = error.messages.to_a
+      end
+      hash[:errors] = errors unless errors.empty?
+      hash[:meta]   = meta_to_h(response.meta) if response.has_meta?
+      hash
+    end
+
+    # Wire bytes of the message — what goes into the trailing metadata.
+    def encode(response)
+      ::Respondo::V1::Response.encode(response)
+    end
+
+    def decode(bytes)
+      ::Respondo::V1::Response.decode(bytes)
+    end
+
+    def meta_to_proto(meta)
+      meta  = meta.dup
+      attrs = {}
+
+      attrs[:request_id] = meta.delete(:request_id).to_s if meta.key?(:request_id)
+      attrs[:timestamp]  = meta.delete(:timestamp).to_s  if meta.key?(:timestamp)
+      attrs[:code]       = meta.delete(:code).to_i       if meta.key?(:code)
+      attrs[:status]     = meta.delete(:status).to_s     if meta.key?(:status)
+      attrs[:grpc_code]  = meta.delete(:grpc_code).to_i  if meta.key?(:grpc_code)
+      attrs[:error_code] = meta.delete(:error_code).to_s if meta.key?(:error_code)
+
+      pagination = meta.delete(:pagination)
+      attrs[:pagination] = pagination_to_proto(pagination) if pagination.is_a?(Hash)
+
+      proto = ::Respondo::V1::Meta.new(**attrs)
+      proto.extra = ::Google::Protobuf::Struct.from_hash(jsonable(meta)) unless meta.empty?
+      proto
+    end
+
+    def meta_to_h(meta)
+      hash = {}
+      hash[:request_id] = meta.request_id unless meta.request_id.empty?
+      hash[:timestamp]  = meta.timestamp  unless meta.timestamp.empty?
+      hash[:code]       = meta.code       unless meta.code.zero?
+      hash[:status]     = meta.status     unless meta.status.empty?
+      hash[:grpc_code]  = meta.grpc_code  unless meta.grpc_code.zero?
+      hash[:error_code] = meta.error_code unless meta.error_code.empty?
+      hash[:pagination] = pagination_to_h(meta.pagination) if meta.has_pagination?
+      hash[:extra]      = meta.extra.to_h if meta.has_extra?
+      hash
+    end
+
+    def pagination_to_proto(pagination)
+      values = PAGINATION_KEYS.each_with_object({}) do |key, memo|
+        value = pagination[key] || pagination[key.to_s]
+        memo[key] = value.to_i unless value.nil?
+      end
+      ::Respondo::V1::Pagination.new(**values)
+    end
+
+    def pagination_to_h(pagination)
+      hash = {
+        current_page: pagination.current_page,
+        per_page:     pagination.per_page,
+        total_pages:  pagination.total_pages,
+        total_count:  pagination.total_count
+      }
+      hash[:next_page] = pagination.next_page if pagination.has_next_page?
+      hash[:prev_page] = pagination.prev_page if pagination.has_prev_page?
+      hash
+    end
+
+    # google.protobuf.Value accepts only nil, true/false, Numeric, String, Array
+    # and Hash (String keys). Normalize anything else that can show up in a
+    # payload: Symbols, Times, Dates, BigDecimals, ...
+    def jsonable(object)
+      case object
+      when nil, true, false, String, Integer, Float then object
+      when Hash   then object.each_with_object({}) { |(key, value), memo| memo[key.to_s] = jsonable(value) }
+      when Array  then object.map { |item| jsonable(item) }
+      when Symbol then object.to_s
+      when Time   then object.utc.iso8601
+      else
+        if object.respond_to?(:iso8601) then object.iso8601
+        elsif defined?(::BigDecimal) && object.is_a?(::BigDecimal) then object.to_f
+        elsif object.respond_to?(:to_h) then jsonable(object.to_h)
+        else object.to_s
+        end
+      end
+    end
+  end
+end

data/lib/respondo_grpc/response_builder.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "time"
+
+module RespondoGrpc
+  # Builds the standardized response as a plain Hash. ProtoMapper converts it
+  # into the respondo.v1.Response protobuf message.
+  #
+  #   {
+  #     success: Boolean,
+  #     message: String,
+  #     data:    Object | Array | nil,     # JSON-like payload
+  #     payload: <protobuf message>,       # only when a protobuf message was passed as data
+  #     errors:  { field: ["msg", ...] },  # only when present
+  #     meta:    { request_id:, timestamp:, ...extra, pagination:, code:, status:, grpc_code:, error_code: }
+  #   }
+  #
+  # A protobuf message passed as `data` is kept as-is (and later packed into a
+  # google.protobuf.Any) instead of being flattened into a Hash, so clients can
+  # unpack it into a real class.
+  class ResponseBuilder
+    # @param success    [Boolean]
+    # @param data       [Object]    anything — serialized automatically
+    # @param message    [String]
+    # @param meta       [Hash]      caller-supplied extra meta (merged in)
+    # @param errors     [Hash]      field-level errors, e.g. { email: ["is invalid"] }
+    # @param pagination [Hash, nil] e.g. { current_page: 1, per_page: 25, total_pages: 4,
+    #                               total_count: 100, next_page: 2, prev_page: nil }
+    # @param call       [Object]    the gRPC call (for the request id in its metadata)
+    def initialize(success:, data: nil, message: nil, meta: {}, errors: nil,
+                   pagination: nil, call: nil)
+      @success    = success
+      @raw_data   = data
+      @message    = message
+      @extra_meta = meta || {}
+      @errors     = errors
+      @pagination = pagination
+      @call       = call
+    end
+
+    # @return [Hash] the complete response payload
+    def build
+      payload = { success: @success, message: resolve_message }
+
+      if typed_payload?(@raw_data)
+        payload[:data]    = nil
+        payload[:payload] = @raw_data
+      else
+        payload[:data] = Serializer.call(@raw_data)
+      end
+
+      payload[:errors] = @errors if @errors.is_a?(Hash) && !@errors.empty?
+      payload[:meta]   = build_meta
+      payload
+    end
+
+    private
+
+    def resolve_message
+      return @message if @message && !@message.empty?
+
+      @success ? RespondoGrpc.config.default_success_message : RespondoGrpc.config.default_error_message
+    end
+
+    def typed_payload?(object)
+      defined?(::Google::Protobuf::MessageExts) && object.is_a?(::Google::Protobuf::MessageExts)
+    end
+
+    def build_meta
+      config = RespondoGrpc.config
+      meta   = {}
+
+      # 1. Request ID first (opt-in)
+      id = request_id
+      meta[:request_id] = id if config.include_request_id && id
+
+      # 2. Timestamp second
+      meta[:timestamp] = current_timestamp
+
+      # 3. Global defaults (lowest priority), then caller-supplied meta
+      meta.merge!(config.default_meta)
+      meta.merge!(@extra_meta)
+
+      # 4. Pagination — plain hash from the caller
+      meta[:pagination] = @pagination if @pagination.is_a?(Hash) && !@pagination.empty?
+
+      # 5. Re-pin the status fields to the very end
+      %i[code status grpc_code error_code].each do |key|
+        meta[key] = meta.delete(key) if meta.key?(key)
+      end
+
+      meta
+    end
+
+    # The id the client sent in its request metadata (x-request-id by default).
+    def request_id
+      return nil unless @call.respond_to?(:metadata)
+
+      metadata = @call.metadata
+      return nil unless metadata.respond_to?(:[])
+
+      key = RespondoGrpc.config.request_id_key.to_s
+      metadata[key] || metadata[key.to_sym]
+    end
+
+    def current_timestamp
+      if Time.respond_to?(:current)
+        Time.current.utc.iso8601
+      else
+        Time.now.utc.iso8601
+      end
+    end
+  end
+end

data/lib/respondo_grpc/serializer.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module RespondoGrpc
+  # Responsible for converting any Ruby object into a plain Hash / Array / primitive.
+  # (ProtoMapper later turns the result into a google.protobuf.Value.)
+  #
+  # Priority order:
+  #   1. Custom serializer from RespondoGrpc.config (if set)
+  #   2. ActiveRecord::Relation
+  #   3. Arrays — each element is serialized recursively
+  #   4. ActiveRecord::Base
+  #   5. ActiveModel::Errors
+  #   6. Exceptions
+  #   7. Hashes — values are serialized recursively
+  #   8. Objects responding to #as_json or #to_h
+  #   9. Primitives — returned as-is
+  module Serializer
+    module_function
+
+    # @param object [Object] anything — AR model, collection, error, hash, array, primitive
+    # @return [Hash, Array, String, Numeric, nil]
+    def call(object)
+      return nil if object.nil?
+
+      # 1. Custom serializer wins
+      return RespondoGrpc.config.serializer.call(object) if RespondoGrpc.config.serializer
+
+      # 2. ActiveRecord::Relation (lazy collection)
+      return object.map { |record| serialize_record(record) } if ar_relation?(object)
+
+      # 3. Array — recurse
+      return object.map { |item| call(item) } if object.is_a?(Array)
+
+      # 4. ActiveRecord model instance
+      return serialize_record(object) if ar_model?(object)
+
+      # 5. ActiveModel::Errors object
+      return serialize_errors(object) if active_model_errors?(object)
+
+      # 6. Exception / StandardError
+      return { message: object.message } if object.is_a?(Exception)
+
+      # 7. Hash — recursively serialize values
+      return object.transform_values { |value| call(value) } if object.is_a?(Hash)
+
+      # 8. Responds to #as_json (ActiveSupport), then #to_h
+      return object.as_json if object.respond_to?(:as_json)
+      return object.to_h if object.respond_to?(:to_h)
+
+      # 9. Primitive — return as-is
+      object
+    end
+
+    def ar_relation?(object)
+      defined?(ActiveRecord::Relation) && object.is_a?(ActiveRecord::Relation)
+    end
+
+    def ar_model?(object)
+      defined?(ActiveRecord::Base) && object.is_a?(ActiveRecord::Base)
+    end
+
+    def active_model_errors?(object)
+      defined?(ActiveModel::Errors) && object.is_a?(ActiveModel::Errors)
+    end
+
+    def serialize_record(record)
+      if record.respond_to?(:as_json)
+        record.as_json
+      elsif record.respond_to?(:to_h)
+        record.to_h
+      else
+        record
+      end
+    end
+
+    def serialize_errors(errors)
+      if errors.respond_to?(:to_hash)
+        errors.to_hash
+      elsif errors.respond_to?(:messages)
+        errors.messages
+      else
+        {}
+      end
+    end
+  end
+end

data/lib/respondo_grpc/service_helpers.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+module RespondoGrpc
+  # Mixed into a gRPC service class to answer every rpc with the respondo.v1.Response
+  # envelope, using expressive, status-aware helpers.
+  #
+  #   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
+  #
+  # Success helpers RETURN the Response message — make the call the last
+  # expression of the rpc method.
+  #
+  # Error helpers RAISE GRPC::BadStatus with the mapped gRPC status code (NOT_FOUND,
+  # INVALID_ARGUMENT, ...) and the envelope in the trailing metadata, unless
+  # config.always_ok is true, in which case they return the envelope as a normal
+  # reply. Writing `return render_grpc_not_found(...)` works in both modes.
+  #
+  # Every helper is prefixed (render_grpc_*) so this module can sit next to the
+  # respondo (JSON) and respondo-graphql helpers without name clashes.
+  #
+  # Success helpers (2xx) — accept data:, message:, meta:, pagination:, call:
+  #   render_grpc_ok, render_grpc_created, render_grpc_accepted, render_grpc_non_authoritative,
+  #   render_grpc_partial_content, render_grpc_multi_status, render_grpc_already_reported,
+  #   render_grpc_im_used
+  #
+  # Success helpers (2xx) without a payload — accept message:, meta:, pagination:, call:
+  #   render_grpc_no_content, render_grpc_reset_content
+  #
+  # Error helpers (4xx / 5xx) — accept message:, errors:, meta:, call:
+  #   render_grpc_bad_request, render_grpc_unauthorized, render_grpc_payment_required,
+  #   render_grpc_forbidden, render_grpc_not_found, render_grpc_method_not_allowed,
+  #   render_grpc_not_acceptable, render_grpc_proxy_auth_required, render_grpc_request_timeout,
+  #   render_grpc_conflict, render_grpc_gone, render_grpc_length_required,
+  #   render_grpc_precondition_failed, render_grpc_payload_too_large, render_grpc_uri_too_long,
+  #   render_grpc_unsupported_media_type, render_grpc_range_not_satisfiable,
+  #   render_grpc_expectation_failed, render_grpc_im_a_teapot, render_grpc_misdirected_request,
+  #   render_grpc_unprocessable, render_grpc_locked, render_grpc_failed_dependency,
+  #   render_grpc_too_early, render_grpc_upgrade_required, render_grpc_precondition_required,
+  #   render_grpc_too_many_requests, render_grpc_request_header_fields_too_large,
+  #   render_grpc_unavailable_for_legal_reasons, render_grpc_server_error,
+  #   render_grpc_not_implemented, render_grpc_bad_gateway, render_grpc_service_unavailable,
+  #   render_grpc_gateway_timeout, render_grpc_http_version_not_supported,
+  #   render_grpc_variant_also_negotiates, render_grpc_insufficient_storage,
+  #   render_grpc_loop_detected, render_grpc_not_extended,
+  #   render_grpc_network_authentication_required
+  #
+  # 1xx (informational) and 3xx (redirect) helpers are intentionally not
+  # provided: they are HTTP transport concepts with no meaning in gRPC.
+  module ServiceHelpers
+    # name => { code: HTTP-style code, status: status name, message: default message, data: takes data? }
+    SUCCESS_HELPERS = {
+      ok:                { code: 200, status: :ok,                            message: nil,                                       data: true  },
+      created:           { code: 201, status: :created,                       message: "Created successfully",                    data: true  },
+      accepted:          { code: 202, status: :accepted,                      message: "Request accepted and is being processed", data: true  },
+      non_authoritative: { code: 203, status: :non_authoritative_information, message: "Non-authoritative information",           data: true  },
+      no_content:        { code: 204, status: :no_content,                    message: "Deleted successfully",                    data: false },
+      reset_content:     { code: 205, status: :reset_content,                 message: "Reset content",                           data: false },
+      partial_content:   { code: 206, status: :partial_content,               message: "Partial content returned",                data: true  },
+      multi_status:      { code: 207, status: :multi_status,                  message: "Multi-status response",                   data: true  },
+      already_reported:  { code: 208, status: :already_reported,              message: "Already reported",                        data: true  },
+      im_used:           { code: 226, status: :im_used,                       message: "IM used",                                 data: true  }
+    }.freeze
+
+    # name => { code: HTTP-style code, status: status name, message: default message }
+    ERROR_HELPERS = {
+      bad_request:                     { code: 400, status: :bad_request,                     message: "Bad request" },
+      unauthorized:                    { code: 401, status: :unauthorized,                    message: "Unauthorized" },
+      payment_required:                { code: 402, status: :payment_required,                message: "Payment required to access this resource" },
+      forbidden:                       { code: 403, status: :forbidden,                       message: "You do not have permission to perform this action" },
+      not_found:                       { code: 404, status: :not_found,                       message: "Resource not found" },
+      method_not_allowed:              { code: 405, status: :method_not_allowed,              message: "Method not allowed" },
+      not_acceptable:                  { code: 406, status: :not_acceptable,                  message: "Requested format not acceptable" },
+      proxy_auth_required:             { code: 407, status: :proxy_authentication_required,   message: "Proxy authentication required" },
+      request_timeout:                 { code: 408, status: :request_timeout,                 message: "Request timed out" },
+      conflict:                        { code: 409, status: :conflict,                        message: "Resource conflict" },
+      gone:                            { code: 410, status: :gone,                            message: "Resource no longer available" },
+      length_required:                 { code: 411, status: :length_required,                 message: "Content length required" },
+      precondition_failed:             { code: 412, status: :precondition_failed,             message: "Precondition failed" },
+      payload_too_large:               { code: 413, status: :payload_too_large,               message: "Payload too large" },
+      uri_too_long:                    { code: 414, status: :uri_too_long,                    message: "URI too long" },
+      unsupported_media_type:          { code: 415, status: :unsupported_media_type,          message: "Unsupported media type" },
+      range_not_satisfiable:           { code: 416, status: :range_not_satisfiable,           message: "Range not satisfiable" },
+      expectation_failed:              { code: 417, status: :expectation_failed,              message: "Expectation failed" },
+      im_a_teapot:                     { code: 418, status: :im_a_teapot,                     message: "I'm a teapot" },
+      misdirected_request:             { code: 421, status: :misdirected_request,             message: "Misdirected request" },
+      unprocessable:                   { code: 422, status: :unprocessable_content,           message: "Validation failed" },
+      locked:                          { code: 423, status: :locked,                          message: "Resource is locked" },
+      failed_dependency:               { code: 424, status: :failed_dependency,               message: "Failed dependency" },
+      too_early:                       { code: 425, status: :too_early,                       message: "Too early" },
+      upgrade_required:                { code: 426, status: :upgrade_required,                message: "Upgrade required" },
+      precondition_required:           { code: 428, status: :precondition_required,           message: "Precondition required" },
+      too_many_requests:               { code: 429, status: :too_many_requests,               message: "Too many requests. Please slow down." },
+      request_header_fields_too_large: { code: 431, status: :request_header_fields_too_large, message: "Request header fields too large" },
+      unavailable_for_legal_reasons:   { code: 451, status: :unavailable_for_legal_reasons,   message: "Unavailable for legal reasons" },
+      server_error:                    { code: 500, status: :internal_server_error,           message: "An unexpected error occurred" },
+      not_implemented:                 { code: 501, status: :not_implemented,                 message: "This feature is not yet implemented" },
+      bad_gateway:                     { code: 502, status: :bad_gateway,                     message: "Bad gateway — upstream service error" },
+      service_unavailable:             { code: 503, status: :service_unavailable,             message: "Service temporarily unavailable" },
+      gateway_timeout:                 { code: 504, status: :gateway_timeout,                 message: "Gateway timeout — upstream service did not respond" },
+      http_version_not_supported:      { code: 505, status: :http_version_not_supported,      message: "Version not supported" },
+      variant_also_negotiates:         { code: 506, status: :variant_also_negotiates,         message: "Variant also negotiates" },
+      insufficient_storage:            { code: 507, status: :insufficient_storage,            message: "Insufficient storage" },
+      loop_detected:                   { code: 508, status: :loop_detected,                   message: "Loop detected" },
+      not_extended:                    { code: 510, status: :not_extended,                    message: "Not extended" },
+      network_authentication_required: { code: 511, status: :network_authentication_required, message: "Network authentication required" }
+    }.freeze
+
+    # status name => HTTP-style code, so render_grpc_error(status: :not_found) resolves to 404
+    HTTP_CODE_BY_STATUS = ERROR_HELPERS.each_value.with_object({}) do |spec, memo|
+      memo[spec[:status]] = spec[:code]
+    end.freeze
+
+    SUCCESS_HELPERS.each do |name, spec|
+      default_message = spec[:message]
+
+      if spec[:data]
+        # e.g. render_grpc_ok(data: @user, message: "User fetched", meta: {}, pagination: nil, call: call)
+        define_method(:"render_grpc_#{name}") do |data: nil, message: default_message, meta: {}, pagination: nil, call: nil|
+          render_grpc_success(data: data, message: message, meta: meta, pagination: pagination,
+                              code: spec[:code], status: spec[:status], call: call)
+        end
+      else
+        # e.g. render_grpc_no_content(message: "Deleted", meta: {}, pagination: nil, call: call)
+        define_method(:"render_grpc_#{name}") do |message: default_message, meta: {}, pagination: nil, call: nil|
+          render_grpc_success(data: nil, message: message, meta: meta, pagination: pagination,
+                              code: spec[:code], status: spec[:status], call: call)
+        end
+      end
+    end
+
+    ERROR_HELPERS.each do |name, spec|
+      default_message = spec[:message]
+
+      # e.g. render_grpc_not_found(message: "User not found", errors: nil, meta: {}, call: call)
+      define_method(:"render_grpc_#{name}") do |message: default_message, errors: nil, meta: {}, call: nil|
+        render_grpc_error(message: message, errors: errors, meta: meta,
+                          code: spec[:code], status: spec[:status], call: call)
+      end
+    end
+
+    private
+
+    # =========================================================================
+    # Core DSL — every helper delegates to these two
+    # =========================================================================
+
+    # Build a successful envelope.
+    #
+    # @param data       [Object]          payload — AR model, collection, Hash, Array, protobuf message, nil
+    # @param message    [String]          human-readable description
+    # @param meta       [Hash]            extra fields merged into meta
+    # @param pagination [Hash, nil]       pagination hash built by the caller
+    # @param code       [Integer, nil]    HTTP-style code recorded in meta (200, 201, ...)
+    # @param status     [Symbol]          status name recorded in meta
+    # @param call       [Object]          the rpc's call argument (for the request id)
+    # @return [Respondo::V1::Response]
+    def render_grpc_success(data: nil, message: nil, meta: {}, code: nil, pagination: nil, status: :ok, call: nil)
+      merged_meta = code ? meta.merge(code: code, status: status.to_s) : meta
+
+      hash = ResponseBuilder.new(
+        success:    true,
+        data:       data,
+        message:    message,
+        meta:       merged_meta,
+        pagination: pagination,
+        call:       call
+      ).build
+
+      ProtoMapper.to_proto(hash)
+    end
+
+    # Build a failed envelope and finish the call with the mapped gRPC status.
+    #
+    # @param message [String]                      human-readable error description
+    # @param errors  [Hash, ActiveModel::Errors]   field-level errors
+    # @param code    [Integer, String, nil]        HTTP-style code (Integer) or machine-readable code (String)
+    # @param meta    [Hash]                        extra fields merged into meta
+    # @param status  [Symbol, Integer]             status name (default :unprocessable_content) or HTTP-style code
+    # @param call    [Object]                      the rpc's call argument (for the request id)
+    # @raise [GRPC::BadStatus] unless config.always_ok, in which case the envelope is returned
+    # @return [Respondo::V1::Response]
+    def render_grpc_error(message: nil, errors: nil, code: nil, meta: {}, status: :unprocessable_content, call: nil)
+      http_code = respondo_grpc_http_code(code, status)
+      grpc_code = StatusMap.grpc_code_for(http_code)
+
+      status_meta = { code: http_code, status: status.to_s, grpc_code: grpc_code }
+      status_meta[:error_code] = code if code.is_a?(String) && !code.empty?
+
+      hash = ResponseBuilder.new(
+        success: false,
+        data:    nil,
+        message: message,
+        meta:    meta.merge(status_meta),
+        errors:  extract_grpc_errors(errors),
+        call:    call
+      ).build
+
+      response = ProtoMapper.to_proto(hash)
+      return response if RespondoGrpc.config.always_ok
+
+      raise RespondoGrpc.bad_status(grpc_code, hash[:message], RespondoGrpc::METADATA_KEY => ProtoMapper.encode(response))
+    end
+
+    # An Integer code wins, then an Integer status, then the status name's
+    # HTTP-style code; 500 when nothing matches.
+    def respondo_grpc_http_code(code, status)
+      return code   if code.is_a?(Integer)
+      return status if status.is_a?(Integer)
+
+      HTTP_CODE_BY_STATUS.fetch(status.to_sym, 500)
+    end
+
+    # Normalize errors into a plain Hash regardless of source type.
+    def extract_grpc_errors(errors)
+      return nil if errors.nil?
+      return errors.to_hash if defined?(ActiveModel::Errors) && errors.is_a?(ActiveModel::Errors)
+      return errors if errors.is_a?(Hash)
+      return { base: errors } if errors.is_a?(Array)
+      return { base: [errors] } if errors.is_a?(String)
+
+      nil
+    end
+  end
+end

data/lib/respondo_grpc/short_helpers.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RespondoGrpc
+  # Short names: `render_ok`, `render_not_found`, ... Each one simply calls its
+  # render_grpc_* twin.
+  #
+  # Opt-in per service. The names are the same ones the respondo (JSON) gem uses
+  # in controllers, so they are never mixed in automatically:
+  #
+  #   class UserService < Example::Users::V1::UserService::Service
+  #     include RespondoGrpc::ShortHelpers
+  #
+  #     def get_user(request, call)
+  #       render_ok(data: User.find(request.id), call: call)   # same as render_grpc_ok
+  #     end
+  #   end
+  module ShortHelpers
+    def self.included(base)
+      base.include(ServiceHelpers)
+      return unless defined?(::Respondo::ControllerHelpers) && base.ancestors.include?(::Respondo::ControllerHelpers)
+
+      warn "[respondo-grpc] #{base} includes RespondoGrpc::ShortHelpers while respondo's JSON helpers " \
+           "are available: render_ok & co. now answer in gRPC in this class. " \
+           "Use render_grpc_* everywhere if it also needs JSON."
+    end
+
+    (ServiceHelpers::SUCCESS_HELPERS.keys + ServiceHelpers::ERROR_HELPERS.keys).each do |name|
+      define_method(:"render_#{name}") do |**options|
+        public_send(:"render_grpc_#{name}", **options)
+      end
+    end
+  end
+end