proto_service_mesh 0.18.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fb343f9b59bc8db10b06a8466222d6a808477cc0753480a83384c940a9e9696b
+  data.tar.gz: cf701b106b97be15a829e464010985bd58c6252ccbd45ca6acff91a0c1621593
+SHA512:
+  metadata.gz: a3360b9dea587ed75a43062f8f5664bdb5fe7d81cbe74763c113c59f566eb85cfde7dc515b69d22be1b8f65212958010f97244ce2707ae9c7a280d64d6a3650b
+  data.tar.gz: 93641536186e764ac6e48bc0f0051b1b1dfc04cf4620d68a3f546289a9e2e630451bbc53a57081ccd834f4a3baf47d7243e186bc98417af3203cec6798a2a334

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paymentbox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,59 @@
+# proto-service-mesh-ruby
+
+proto-service-mesh-ruby is the Ruby implementation of the
+[Proto Service Mesh API](https://github.com/Paymentbox-com/proto-service-mesh-api).
+It carries protobuf messages over any transport that implements the
+[Service Mesh API Specification](https://github.com/Paymentbox-com/service-mesh-api)
+through the Ruby contract in the `service_mesh` gem, from
+[service-mesh-ruby](https://github.com/Paymentbox-com/service-mesh-ruby).
+
+The `ProtoServiceMesh` module holds the specification's non-generated types:
+* `TransportRouter`
+* `Registry`
+* `RPCRuntime`
+* `MeshError`
+
+It also holds the two base classes that generated code builds on:
+* `RPCService`
+* `RPCClient`
+
+Generated code comes from `proto-service-mesh-gen` in the specification
+repository and lives in a definitions project.
+
+## Install
+
+```ruby
+# Gemfile
+gem "proto_service_mesh"
+```
+
+Requires Ruby 3.3 or newer. The gem depends on `service_mesh`,
+`google-protobuf`, and `googleapis-common-protos-types`. The last of these
+provides `Google::Rpc::Status`, `Google::Rpc::Code`, and the detail types in
+`google/rpc/error_details.proto`.
+
+No transport is a dependency. The application adds the transport gem it uses.
+
+## Usage
+
+An application uses this library through the generated code that depends on it. The
+[Proto Service Mesh API](https://github.com/Paymentbox-com/proto-service-mesh-api) describes how Ruby code is
+generated from `.proto` files.
+
+### Reference Examples
+
+The examples in these docs use the reference definitions in `spec/support/definitions/`. They declare
+`shop.OrderService`, with a `ROUTE` method `Place` and a `TOPIC` method `Placed`, in deployment group `shop` over the
+transport named `mem`, the in-memory transport the specs use. The generated module is `Shop`, and the generated
+per-transport maps are in `ServiceMaps`. The generated code is in `spec/support/testproto/`, written by
+`proto-service-mesh-gen` as a consumer would generate it, and described under [Generated Code](docs/generated-code.md).
+
+## Documentation
+
+- [Setup](docs/setup.md): configuring the `TransportRouter`, registering services, and running an `RPCRuntime`
+- [Handlers](docs/handlers.md): implementing an `RPCService`, endpoint and subscriber handlers, returning errors, reply metadata, and message metadata
+- [Calling](docs/calling.md): calling generated clients, metadata and transport options, reply metadata, and the wire format
+- [MeshError](docs/mesherror.md): constructing and reading `MeshError`, and the errors the library raises
+- [Generated Code](docs/generated-code.md): the generated reference output for Ruby, and what generated code relies on in this library
+- [Public API](docs/public-api.md): every public constant and method in `ProtoServiceMesh`
+- [Development](docs/development.md): the specification protos, the recipes, and the tests

data/lib/mesh/options_pb.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: mesh/options.proto
+
+require 'google/protobuf'
+
+require 'google/protobuf/descriptor_pb'
+
+
+descriptor_data = "\n\x12mesh/options.proto\x12\x04mesh\x1a google/protobuf/descriptor.proto*\x1c\n\x04Kind\x12\t\n\x05ROUTE\x10\x00\x12\t\n\x05TOPIC\x10\x01::\n\x04kind\x12\x1e.google.protobuf.MethodOptions\x18\xd1\x86\x03 \x01(\x0e\x32\n.mesh.Kind:8\n\x0e\x63onsumer_group\x12\x1e.google.protobuf.MethodOptions\x18\xd2\x86\x03 \x01(\t:1\n\ttransport\x12\x1c.google.protobuf.FileOptions\x18\xd4\x86\x03 \x01(\t:3\n\x0broot_prefix\x12\x1c.google.protobuf.FileOptions\x18\xd5\x86\x03 \x01(\tB=Z;github.com/Paymentbox-com/proto-service-mesh-go/meshoptionsb\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Mesh
+  Kind = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("mesh.Kind").enummodule
+end

data/lib/proto_service_mesh/errors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ProtoServiceMesh
+  # Base of the errors this library raises for misuse of its own contract.
+  # MeshError is an application error and stands apart from this tree.
+  class Error < StandardError; end
+
+  # A Target's transport metadata names a transport the router does not hold.
+  class UnknownTransport < Error
+    def initialize(name) = super("unknown transport #{name.inspect}")
+  end
+
+  # TransportRouter#close could not close one or more clients. +failures+ maps
+  # each transport name to the exception its client's close raised.
+  class CloseFailed < Error
+    attr_reader :failures
+
+    def initialize(failures)
+      @failures = failures
+      super(failures.map { |name, e| "#{name}: #{e.message}" }.join("; "))
+    end
+  end
+end

data/lib/proto_service_mesh/mesh_error.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "google/protobuf"
+require "google/protobuf/well_known_types"
+require "google/rpc/code_pb"
+require "google/rpc/status_pb"
+require "google/rpc/error_details_pb"
+
+module ProtoServiceMesh
+  # The application error. A ROUTE handler raises it; the caller rescues it.
+  # It wraps a google.rpc.Status and carries the message metadata of the
+  # reply that reports it.
+  class MeshError < StandardError
+    include Metadata
+
+    attr_reader :proto
+
+    # MeshError.new(code, message, *details, mesh_metadata: {}). Returns the
+    # subclass for the code when one exists; a subclass called directly takes
+    # (message, *details, mesh_metadata: {}) and builds itself.
+    def self.new(*args, mesh_metadata: {})
+      if equal?(MeshError)
+        unless args.first.is_a?(Symbol) || args.first.is_a?(Integer)
+          raise ArgumentError, "MeshError.new takes a Google::Rpc::Code first, such as MeshError.new(:NOT_FOUND, \"no such order\"); " \
+            "UnknownError.new(message) raises an UNKNOWN error"
+        end
+        klass = BY_CODE[code_number(args.first)]
+        return klass.new(*args.drop(1), mesh_metadata: mesh_metadata) if klass
+      end
+      super
+    end
+
+    # What +raise Klass, "msg"+ calls; builds the error as new does.
+    def self.exception(*args, **kwargs)
+      new(*args, **kwargs)
+    end
+
+    # Wraps an existing Google::Rpc::Status.
+    def self.from_proto(status)
+      new(status.code, status.message, *status.details)
+    end
+
+    # +code+ is a Google::Rpc::Code name (:NOT_FOUND) or number (5).
+    # +details+ are protobuf messages, packed into Google::Protobuf::Any,
+    # or Any values already packed. +mesh_metadata+ is the metadata the
+    # error reply carries.
+    def initialize(code, message, *details, mesh_metadata: {})
+      text = message.to_s
+      @proto = Google::Rpc::Status.new(
+        code: self.class.code_number(code),
+        message: text,
+        details: details.map { |d| pack(d) }
+      )
+      self.mesh_metadata = mesh_metadata
+      super(text)
+    end
+
+    # The Google::Rpc::Code name, or the number when it has no name.
+    def code
+      Google::Rpc::Code.lookup(@proto.code) || @proto.code
+    end
+
+    # The wrapped Status's details, as Google::Protobuf::Any values.
+    def details
+      @proto.details.to_a
+    end
+
+    private def pack(detail)
+      return detail if detail.is_a?(Google::Protobuf::Any)
+      unless detail.class.respond_to?(:descriptor)
+        raise TypeError, "a detail must be a protobuf message, got #{detail.class}"
+      end
+
+      Google::Protobuf::Any.pack(detail)
+    end
+
+    def self.code_number(code)
+      case code
+      when Integer then code
+      when Symbol
+        Google::Rpc::Code.resolve(code) or raise ArgumentError, "unknown Google::Rpc::Code #{code.inspect}"
+      else
+        raise ArgumentError, "code must be a Google::Rpc::Code name or number, got #{code.inspect}"
+      end
+    end
+  end
+
+  # One subclass per Google::Rpc::Code other than OK, each fixing its code.
+  # MeshError.new and from_proto return the subclass for the code.
+  {
+    CancelledError: :CANCELLED,
+    UnknownError: :UNKNOWN,
+    InvalidArgumentError: :INVALID_ARGUMENT,
+    DeadlineExceededError: :DEADLINE_EXCEEDED,
+    NotFoundError: :NOT_FOUND,
+    AlreadyExistsError: :ALREADY_EXISTS,
+    PermissionDeniedError: :PERMISSION_DENIED,
+    UnauthenticatedError: :UNAUTHENTICATED,
+    ResourceExhaustedError: :RESOURCE_EXHAUSTED,
+    FailedPreconditionError: :FAILED_PRECONDITION,
+    AbortedError: :ABORTED,
+    OutOfRangeError: :OUT_OF_RANGE,
+    UnimplementedError: :UNIMPLEMENTED,
+    InternalError: :INTERNAL,
+    UnavailableError: :UNAVAILABLE,
+    DataLossError: :DATA_LOSS
+  }.each do |name, code|
+    klass = Class.new(MeshError) do
+      const_set(:CODE, code)
+
+      def self.new(message, *details, mesh_metadata: {})
+        super(self::CODE, message, *details, mesh_metadata: mesh_metadata)
+      end
+    end
+    const_set(name, klass)
+  end
+
+  MeshError::BY_CODE = MeshError.subclasses.to_h { |k| [MeshError.code_number(k::CODE), k] }.freeze
+end

data/lib/proto_service_mesh/metadata.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ProtoServiceMesh
+  # Message metadata carried on a message object. Generated code includes it
+  # into every message class an rpc takes or returns; MeshError includes it
+  # too. The library sets it on the objects it builds and reads it from the
+  # objects the application gives it, and never writes to an object the
+  # application built.
+  module Metadata
+    EMPTY = {}.freeze
+    private_constant :EMPTY
+
+    # The metadata Hash of this object. On first read it is a new empty Hash
+    # stored on the object, so keys can be written into it directly. A frozen
+    # object with none set has a frozen empty Hash.
+    def mesh_metadata
+      return @mesh_metadata if instance_variable_defined?(:@mesh_metadata) && @mesh_metadata
+      return EMPTY if frozen?
+
+      @mesh_metadata = {}
+    end
+
+    # Sets the metadata. Takes a Hash, or nil for none.
+    def mesh_metadata=(metadata)
+      @mesh_metadata = Hash(metadata)
+    end
+  end
+end

data/lib/proto_service_mesh/registry.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ProtoServiceMesh
+  # Collects every Endpoint and Subscriber the process serves. The process
+  # registry is ProtoServiceMesh.registry.
+  class Registry
+    def initialize
+      @endpoints = []
+      @subscribers = []
+    end
+
+    # Adds the endpoints and subscribers of +service+, an RPCService
+    # instance. +consumer_groups+ maps a target of the service to the
+    # consumer group of its endpoint or subscriber, replacing the one the
+    # generated code carries. "" removes it, so the runtime's deployment group
+    # applies, and ServiceMesh::CONSUMER_GROUP_NONE means no group. Raises
+    # ArgumentError, and registers nothing, when a target is not one of the
+    # service's. Every endpoint and subscriber is kept, so two registrations of
+    # one target hand the transport two of them.
+    def register(service, consumer_groups: {})
+      endpoints = service.endpoints
+      subscribers = service.subscribers
+      consumer_groups.each do |target, group|
+        found = false
+        apply = lambda do |served|
+          next served unless served.target.same_channel?(target)
+
+          found = true
+          with_group(served, group)
+        end
+        endpoints = endpoints.map(&apply)
+        subscribers = subscribers.map(&apply)
+        raise ArgumentError, "consumer_groups names target #{target.segments.inspect}, which is not an rpc method of #{service.class}" unless found
+      end
+      @endpoints.concat(endpoints)
+      @subscribers.concat(subscribers)
+      nil
+    end
+
+    # Every registered Endpoint.
+    attr_reader :endpoints
+
+    # Every registered Subscriber.
+    attr_reader :subscribers
+
+    private
+
+    def with_group(served, group)
+      metadata = served.metadata.to_h.except(ServiceMesh::CONSUMER_GROUP_KEY)
+      metadata[ServiceMesh::CONSUMER_GROUP_KEY] = group unless group.to_s.empty?
+      served.with(metadata: metadata)
+    end
+  end
+end

data/lib/proto_service_mesh/rpc.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ProtoServiceMesh
+  # One rpc method as the generated code declares it. +owner+ is the class
+  # the declaration appeared in. +consumer_group+ is the method's
+  # consumer_group option, or nil when it has none.
+  Rpc = Data.define(:name, :target, :input, :output, :kind, :owner, :consumer_group) do
+    def initialize(name:, target:, input:, kind:, owner:, output: nil, consumer_group: nil)
+      raise ServiceMesh::KindMismatch, "rpc #{name}: declared #{kind}, target is #{target.kind}" unless kind == target.kind
+
+      super(name: name, target: target, input: input, output: output, kind: kind, owner: owner, consumer_group: consumer_group)
+    end
+
+    def route? = kind == :route
+  end
+
+  # Class-level declaration of rpcs, extended by RPCService and RPCClient.
+  module RpcDSL
+    # Declares one rpc. +name+ is the Ruby method name, +target+ the
+    # ServiceMesh::Target, +input+ and +output+ the message classes, +kind+
+    # :route or :topic, and +consumer_group+ the method's consumer_group
+    # option. +output+ is not used for a topic.
+    def rpc(name, target:, input:, kind:, output: nil, consumer_group: nil)
+      rpc = Rpc.new(name: name, target: target, input: input, output: output, kind: kind, owner: self, consumer_group: consumer_group)
+      own_rpcs[rpc.name] = rpc
+      define_rpc(rpc)
+      rpc
+    end
+
+    # Every declared rpc by name, including those of superclasses.
+    def rpcs
+      inherited = superclass.respond_to?(:rpcs) ? superclass.rpcs : {}
+      inherited.merge(own_rpcs)
+    end
+
+    private
+
+    def own_rpcs
+      @own_rpcs ||= {}
+    end
+
+    def define_rpc(rpc)
+    end
+  end
+end

data/lib/proto_service_mesh/rpc_client.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module ProtoServiceMesh
+  # Base of every generated client class. Each declared rpc becomes a class
+  # method, +name(request)+, that resolves the transport's Client through the
+  # process router on every call. The request's mesh_metadata is read and left
+  # unchanged: its keys that start with OPTION_PREFIX are the transport
+  # options, with the prefix removed, and the other keys are the message
+  # metadata.
+  class RPCClient
+    extend RpcDSL
+
+    class << self
+      private
+
+      def define_rpc(rpc)
+        if rpc.route?
+          define_singleton_method(rpc.name) do |request|
+            RPCClient.request(rpc, request)
+          end
+        else
+          define_singleton_method(rpc.name) do |request|
+            RPCClient.publish(rpc, request)
+          end
+        end
+      end
+    end
+
+    # Sends +request+ to a route and returns the decoded response, whose
+    # mesh_metadata is the reply's metadata without keys that start with
+    # OPTION_PREFIX. Raises MeshError for a reply carrying Grpc-Status, or
+    # INTERNAL when either payload does not decode; either error's
+    # mesh_metadata is the same reply metadata.
+    def self.request(rpc, request)
+      message, options = outbound(rpc, request)
+      reply = client_for(rpc.target).request(message, options)
+      reply_metadata = Wire.without_options(reply.metadata)
+      begin
+        if reply_metadata.key?(Wire::GRPC_STATUS_KEY)
+          raise MeshError.from_proto(decode(Google::Rpc::Status, reply.payload))
+        end
+
+        response = decode(rpc.output, reply.payload)
+      rescue MeshError => e
+        e.mesh_metadata = reply_metadata
+        raise
+      end
+      response.mesh_metadata = reply_metadata
+      response
+    end
+
+    # Publishes +request+ to a topic. Returns nil.
+    def self.publish(rpc, request)
+      message, options = outbound(rpc, request)
+      client_for(rpc.target).publish(message, options)
+      nil
+    end
+
+    def self.client_for(target)
+      ProtoServiceMesh.transport_router.client(target.metadata["transport"])
+    end
+
+    # The message for +request+ and the transport options, split from the
+    # request's mesh_metadata.
+    def self.outbound(rpc, request)
+      raise TypeError, "#{rpc.name} takes a #{rpc.input}, got #{request.class}" unless request.is_a?(rpc.input)
+
+      metadata, options = Wire.split_options(request.mesh_metadata)
+      [ServiceMesh::Message.new(target: rpc.target, metadata: Wire.metadata(metadata), payload: request.to_proto), options]
+    end
+
+    def self.decode(klass, payload)
+      klass.decode(payload)
+    rescue Google::Protobuf::ParseError => e
+      raise MeshError.new(:INTERNAL, "reply does not decode as #{klass.descriptor.name}: #{e.message}")
+    end
+
+    private_class_method :client_for, :outbound, :decode
+  end
+end

data/lib/proto_service_mesh/rpc_runtime.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ProtoServiceMesh
+  # The service process for one transport and one deployment group. new
+  # takes the transport's client from the process router and every endpoint
+  # and subscriber in the process registry whose target is on that transport,
+  # and builds the transport's Runtime from them with the +runtime+
+  # constructor.
+  class RPCRuntime
+    attr_reader :transport, :deployment_group, :t_runtime
+
+    # +runtime+ is ->(client, config, endpoints:, subscribers:) returning the
+    # transport's Runtime. It receives +config+ with deployment_group set.
+    # Endpoints and subscribers of other transports are left for those
+    # transports' runtimes. Raises ArgumentError when +runtime+ is not
+    # callable, UnknownTransport, and whatever +runtime+ raises.
+    def initialize(transport:, deployment_group:, runtime:, config: {})
+      raise ArgumentError, "runtime: must be a callable that builds the transport's Runtime, got #{runtime.inspect}" unless runtime.respond_to?(:call)
+
+      registry = ProtoServiceMesh.registry
+      client = ProtoServiceMesh.transport_router.client(transport)
+      @transport = transport
+      @deployment_group = deployment_group
+      on_transport = ->(served) { served.target.metadata["transport"] == transport }
+      @t_runtime = runtime.call(
+        client,
+        config.to_h.merge(ServiceMesh::DEPLOYMENT_GROUP_KEY => deployment_group),
+        endpoints: registry.endpoints.select(&on_transport),
+        subscribers: registry.subscribers.select(&on_transport)
+      )
+    end
+
+    def start = @t_runtime.start
+
+    def stop(drain) = @t_runtime.stop(drain)
+
+    def running? = @t_runtime.running?
+
+    def client = @t_runtime.client
+  end
+end

data/lib/proto_service_mesh/rpc_service.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module ProtoServiceMesh
+  # Base of every generated service class. The generated subclass declares its
+  # rpcs; the application subclasses that and defines a method per rpc it
+  # serves, taking the decoded request, whose mesh_metadata is the inbound
+  # message metadata. A route method returns the response; the response's
+  # mesh_metadata, without keys that start with OPTION_PREFIX, is the reply's
+  # metadata. The same holds for a raised MeshError.
+  class RPCService
+    extend RpcDSL
+
+    # A ServiceMesh::Endpoint for each route rpc this instance implements,
+    # with the rpc's consumer_group in its metadata when it has one.
+    def endpoints
+      implemented.select(&:route?).map do |rpc|
+        ServiceMesh::Endpoint.new(target: rpc.target, handler: endpoint_handler(rpc), metadata: consumer_group_metadata(rpc))
+      end
+    end
+
+    # A ServiceMesh::Subscriber for each topic rpc this instance implements,
+    # with the rpc's consumer_group in its metadata when it has one.
+    def subscribers
+      implemented.reject(&:route?).map do |rpc|
+        ServiceMesh::Subscriber.new(target: rpc.target, handler: subscriber_handler(rpc), metadata: consumer_group_metadata(rpc))
+      end
+    end
+
+    private
+
+    def consumer_group_metadata(rpc)
+      rpc.consumer_group.nil? ? {} : {ServiceMesh::CONSUMER_GROUP_KEY => rpc.consumer_group}
+    end
+
+    # Rpcs whose method is defined in the declaring class or below it.
+    def implemented
+      self.class.rpcs.values.select do |rpc|
+        self.class.method_defined?(rpc.name) && self.class.instance_method(rpc.name).owner <= rpc.owner
+      end
+    end
+
+    def endpoint_handler(rpc)
+      lambda do |message|
+        request = begin
+          decode_inbound(rpc, message)
+        rescue Google::Protobuf::ParseError => e
+          next status_reply(message, MeshError.new(:INTERNAL, e.message))
+        end
+
+        response = public_send(rpc.name, request)
+        unless response.is_a?(rpc.output)
+          raise TypeError, "#{rpc.name} returned #{response.class}, expected #{rpc.output}"
+        end
+
+        metadata = Wire.metadata(Wire.without_options(response.mesh_metadata).except(Wire::GRPC_STATUS_KEY))
+        ServiceMesh::Message.new(target: message.target, metadata: metadata, payload: response.to_proto)
+      rescue MeshError => e
+        status_reply(message, e)
+      rescue => e
+        status_reply(message, MeshError.new(:UNKNOWN, e.message))
+      end
+    end
+
+    def subscriber_handler(rpc)
+      lambda do |message|
+        public_send(rpc.name, decode_inbound(rpc, message))
+        nil
+      end
+    end
+
+    # The decoded payload carrying the message's metadata. A payload that
+    # does not decode raises Google::Protobuf::ParseError naming the input
+    # type.
+    def decode_inbound(rpc, message)
+      request = begin
+        rpc.input.decode(message.payload)
+      rescue Google::Protobuf::ParseError => e
+        raise Google::Protobuf::ParseError, "request does not decode as #{rpc.input.descriptor.name}: #{e.message}"
+      end
+      request.mesh_metadata = message.metadata
+      request
+    end
+
+    def status_reply(message, error)
+      ServiceMesh::Message.new(target: message.target, metadata: Wire.status_metadata(error, Wire.without_options(error.mesh_metadata)), payload: error.proto.to_proto)
+    end
+  end
+end

data/lib/proto_service_mesh/transport_router.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ProtoServiceMesh
+  # Holds one Client per transport name: the transport-specific Client the
+  # application built and owns. The process router is
+  # ProtoServiceMesh.transport_router. Clients are added at boot; client is a
+  # hash read.
+  class TransportRouter
+    def initialize
+      @clients = {}
+    end
+
+    # Adds a client. Adding under a name already present replaces the client.
+    def add(name, client)
+      @clients[name] = client
+      nil
+    end
+
+    def names
+      @clients.keys
+    end
+
+    # The Client for +name+. Raises UnknownTransport.
+    def client(name)
+      @clients.fetch(name) { raise UnknownTransport.new(name) }
+    end
+
+    # Closes every client, even when some fail to close. Returns nil, or
+    # raises CloseFailed carrying each client's exception by transport name.
+    def close
+      failures = {}
+      @clients.each do |name, client|
+        client.close
+      rescue => e
+        failures[name] = e
+      end
+      raise CloseFailed.new(failures) unless failures.empty?
+
+      nil
+    end
+  end
+end

data/lib/proto_service_mesh/version.rb

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

data/lib/proto_service_mesh/wire.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ProtoServiceMesh
+  # The start of an outgoing metadata key that is a transport option. A client
+  # method passes each such key, with the prefix removed, to the transport's
+  # request or publish options, and sends the other keys as message metadata.
+  # Reply metadata never carries such keys. The match is exact and
+  # case-sensitive.
+  OPTION_PREFIX = "Mesh-Option-"
+
+  # Metadata keys and values the specification fixes on every message.
+  module Wire
+    CONTENT_TYPE_KEY = "Content-Type"
+    CONTENT_TYPE = "application/x-protobuf"
+    GRPC_STATUS_KEY = "Grpc-Status"
+
+    # Metadata for a message carrying a payload of the method's type.
+    def self.metadata(extra = {})
+      extra.to_h.merge(CONTENT_TYPE_KEY => CONTENT_TYPE)
+    end
+
+    # Splits +metadata+ into the message metadata and the transport options:
+    # the keys that start with OPTION_PREFIX become options with the prefix
+    # removed. Returns [metadata, options], both new Hashes.
+    def self.split_options(metadata)
+      options = {}
+      rest = {}
+      metadata.to_h.each do |key, value|
+        if key.to_s.start_with?(OPTION_PREFIX)
+          options[key.to_s.delete_prefix(OPTION_PREFIX)] = value
+        else
+          rest[key] = value
+        end
+      end
+      [rest, options]
+    end
+
+    # A copy of +metadata+ without the keys that start with OPTION_PREFIX.
+    def self.without_options(metadata)
+      split_options(metadata).first
+    end
+
+    # Metadata for a reply whose payload is an encoded google.rpc.Status.
+    def self.status_metadata(error, extra = {})
+      extra.to_h.merge(CONTENT_TYPE_KEY => CONTENT_TYPE, GRPC_STATUS_KEY => error.proto.code.to_s)
+    end
+  end
+end

data/lib/proto_service_mesh.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "service_mesh"
+
+require_relative "proto_service_mesh/version"
+require_relative "proto_service_mesh/errors"
+require_relative "proto_service_mesh/wire"
+require_relative "proto_service_mesh/metadata"
+require_relative "proto_service_mesh/mesh_error"
+require_relative "proto_service_mesh/transport_router"
+require_relative "proto_service_mesh/registry"
+require_relative "proto_service_mesh/rpc"
+require_relative "proto_service_mesh/rpc_service"
+require_relative "proto_service_mesh/rpc_client"
+require_relative "proto_service_mesh/rpc_runtime"
+
+# Ruby library for the Proto Service Mesh API. Generated code declares rpcs on
+# RPCService and RPCClient subclasses; the application configures the process
+# TransportRouter, registers its services, and starts an RPCRuntime.
+module ProtoServiceMesh
+  class << self
+    # The process TransportRouter.
+    def transport_router
+      @transport_router ||= TransportRouter.new
+    end
+
+    # The process Registry.
+    def registry
+      @registry ||= Registry.new
+    end
+
+    # Shortcut for transport_router.add.
+    def add_transport(name, client)
+      transport_router.add(name, client)
+    end
+
+    # Shortcut for registry.register.
+    def register(service, consumer_groups: {})
+      registry.register(service, consumer_groups: consumer_groups)
+    end
+  end
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: proto_service_mesh
+version: !ruby/object:Gem::Version
+  version: 0.18.0
+platform: ruby
+authors:
+- Bryant Morrill
+- Paymentbox
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: google-protobuf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.26'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.26'
+- !ruby/object:Gem::Dependency
+  name: googleapis-common-protos-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: service_mesh
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+description:
+email:
+- bryantreadmorrill@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/mesh/options_pb.rb
+- lib/proto_service_mesh.rb
+- lib/proto_service_mesh/errors.rb
+- lib/proto_service_mesh/mesh_error.rb
+- lib/proto_service_mesh/metadata.rb
+- lib/proto_service_mesh/registry.rb
+- lib/proto_service_mesh/rpc.rb
+- lib/proto_service_mesh/rpc_client.rb
+- lib/proto_service_mesh/rpc_runtime.rb
+- lib/proto_service_mesh/rpc_service.rb
+- lib/proto_service_mesh/transport_router.rb
+- lib/proto_service_mesh/version.rb
+- lib/proto_service_mesh/wire.rb
+homepage: https://github.com/Paymentbox-com/proto-service-mesh-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Paymentbox-com/proto-service-mesh-ruby
+  source_code_uri: https://github.com/Paymentbox-com/proto-service-mesh-ruby
+  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: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby library for the Proto Service Mesh API
+test_files: []