service_mesh 0.4.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fef05ef9dacd492215d76304b8f1938056e862e35c0e0450f7b120213bf7e8d7
+  data.tar.gz: 97cb3e42dc4797d618d3eacf61aa3d2ba994887aa94ee88d37d90b6b04211fb6
+SHA512:
+  metadata.gz: c7da5185432f80a50b73ec3942c736367455bc337918b7afba2b8393a1575353e54a9fbdb54d98aeaf03c7b0922766490a8da075c8daf4d2a58087044e1e448b
+  data.tar.gz: 4418d34275bc4dd1d532b4b84f48361967601275181c64c50c5cb7ca7177ddecd9ebdedbb773d813d07e55307efeb24b63c2753a8c6881ea66803e1e619f3127

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,106 @@
+# service-mesh-ruby
+
+The Ruby contract for the
+[Service Mesh API Specification](https://github.com/Paymentbox-com/service-mesh-api),
+packaged as the gem `service_mesh`. It holds what every transport and every
+caller must agree on, and nothing that moves bytes. Transports are separate
+gems that depend on it and implement `Client` and `Runtime`.
+
+The [gRPC Service Mesh API](https://github.com/Paymentbox-com/grpc-service-mesh-api) is a protocol layer that generates code against this contract from protobuf
+definitions, through its Ruby library [grpc-service-mesh-ruby](https://github.com/Paymentbox-com/grpc-service-mesh-ruby). Other protocol layers may be implemented 
+to do the same. 
+
+## Install
+
+```ruby
+# Gemfile
+gem "service_mesh"
+```
+
+Requires Ruby 3.3 or newer. The gem has no runtime dependencies.
+
+## What it Implements
+
+- The value types from the specification: `ServiceMesh::Target`, `ServiceMesh::ServiceMap`, 
+  `ServiceMesh::Message`, `ServiceMesh::Endpoint` and `ServiceMesh::Subscriber`.
+- Target Kinds are implemented as `:route` and `:topic`. A `Target` built with a kind outside the two
+  raises `KindMismatch`.
+- `Message#payload` is always `Encoding::BINARY`.
+- `Target#same_channel?` compares segments and kind and ignores metadata. 
+- The configuration keys the specification defines: `DEPLOYMENT_GROUP_KEY`,
+  `CONSUMER_GROUP_KEY`, and the value `CONSUMER_GROUP_NONE`.
+- The errors defined by the specification as `ServiceMesh::Error`: `ServiceMesh::KindMismatch`,
+  `ServiceMesh::InvalidTarget`, `ServiceMesh::NoDeploymentGroup`.
+- A conformance suite a transport runs against its own `Client` and
+  `Runtime`.
+
+`Client` and `Runtime` are duck types. The specification names their methods;
+a transport satisfies the contract by responding to them and by passing the
+conformance suite.
+
+## Transports
+
+- NATS: [service-mesh-nats-ruby](https://github.com/Paymentbox-com/service-mesh-nats-ruby),
+  gem `service_mesh_nats`.
+
+The Go counterpart of this gem is
+[service-mesh-go](https://github.com/Paymentbox-com/service-mesh-go).
+
+## Usage
+
+A transport that implements Client and Runtime according to the specification will used the
+types defined here.
+
+```ruby
+require "service_mesh"
+
+TARGET = ServiceMesh::Target.new(segments: %w[accounts lookup], kind: :route)
+
+def lookup(client, id)
+  reply = client.request(ServiceMesh::Message.new(target: TARGET, payload: id))
+  reply.payload
+end
+```
+
+## Conformance
+
+A transport implemented to use these types should include the shared examples defined in this
+library in its own spec suite and supply its own constructors and a pair of valid targets:
+
+```ruby
+require "service_mesh/rspec"
+
+RSpec.describe MyTransport do
+  it_behaves_like "a service mesh transport" do
+    let(:new_runtime) do
+      ->(client, config, endpoints:, subscribers:) { MyTransport::Runtime.new(client, config, endpoints:, subscribers:) }
+    end
+    let(:new_client) { ->(config, map) { MyTransport::Client.new(config, map) } }
+    let(:runtime_config) { {"deployment_group" => "test", "url" => url} }
+    let(:client_config) { {"url" => url} }
+    let(:route_target) { ServiceMesh::Target.new(segments: %w[test echo], kind: :route) }
+    let(:topic_target) { ServiceMesh::Target.new(segments: %w[test event], kind: :topic) }
+  end
+end
+```
+
+The suite covers kind checks, the deployment group requirement, request and
+reply with metadata both ways, publish, the consumer-group delivery
+permutations across two runtimes, a standalone client refusing requests after
+close, the runtime's client being the one it was given and closed by stop, the lifecycle state machine, and drain completing and expiring.
+Anything that names a transport's own errors, config keys, or address syntax
+stays in the transport's specs.
+
+## Development
+
+```
+mise install
+just install
+just check      # lint, test, build
+```
+
+## Tests
+
+```
+just test
+```

data/lib/service_mesh/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ServiceMesh
+  class Error < StandardError; end
+
+  # Raised for misuse of the contract. Transport errors pass through as the
+  # transport library's own exceptions.
+  class KindMismatch < Error; end
+
+  class InvalidTarget < Error; end
+
+  class NoDeploymentGroup < Error
+    def initialize(msg = "config #{DEPLOYMENT_GROUP_KEY} is required") = super
+  end
+end

data/lib/service_mesh/rspec.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require "rspec"
+require "timeout"
+require_relative "../service_mesh"
+
+# Conformance suite. A transport includes it from its own specs:
+#
+#   require "service_mesh/rspec"
+#
+#   RSpec.describe MyTransport do
+#     it_behaves_like "a service mesh transport" do
+#       let(:new_runtime)    { ->(client, config, endpoints:, subscribers:) { MyTransport::Runtime.new(client, config, endpoints:, subscribers:) } }
+#       let(:new_client)     { ->(config, map) { MyTransport::Client.new(config, map) } }
+#       let(:runtime_config) { {"deployment_group" => "test", ...transport keys...} }
+#       let(:client_config)  { {...transport keys...} }
+#       let(:route_target)   { ServiceMesh::Target.new(segments: %w[test echo], kind: :route) }
+#       let(:topic_target)   { ServiceMesh::Target.new(segments: %w[test event], kind: :topic) }
+#     end
+#   end
+#
+# Every example here follows from the specification alone. Anything that
+# names a transport's own errors, config keys, or address syntax belongs in
+# the transport's specs.
+RSpec.shared_examples "a service mesh transport" do
+  let(:service_map) { ServiceMesh::ServiceMap.new }
+  let(:wait) { 3 }
+
+  def endpoint(target, handler, metadata: {})
+    ServiceMesh::Endpoint.new(target: target, handler: handler, metadata: metadata)
+  end
+
+  def subscriber(target, handler, metadata: {})
+    ServiceMesh::Subscriber.new(target: target, handler: handler, metadata: metadata)
+  end
+
+  def message(target, metadata: {}, payload: "")
+    ServiceMesh::Message.new(target: target, metadata: metadata, payload: payload)
+  end
+
+  def config_for(group)
+    runtime_config.merge(ServiceMesh::DEPLOYMENT_GROUP_KEY => group)
+  end
+
+  def build(config = runtime_config, endpoints: [], subscribers: [])
+    new_runtime.call(new_client.call(client_config, service_map), config, endpoints: endpoints, subscribers: subscribers)
+  end
+
+  def serve(config = runtime_config, endpoints: [], subscribers: [])
+    rt = build(config, endpoints: endpoints, subscribers: subscribers)
+    rt.start
+    @conformance_runtimes << rt
+    rt
+  end
+
+  def wait_until
+    Timeout.timeout(wait) { sleep 0.01 until yield }
+  end
+
+  before do
+    @conformance_runtimes = []
+    @conformance_threads = []
+  end
+
+  after do
+    @conformance_threads.each(&:kill)
+    @conformance_runtimes.each { |rt| rt.stop(wait) }
+  end
+
+  let(:client) { new_client.call(client_config, service_map) }
+  after { client.close }
+
+  describe "kind checks" do
+    it "rejects a request to a topic" do
+      expect { client.request(message(topic_target)) }.to raise_error(ServiceMesh::KindMismatch)
+    end
+
+    it "rejects a publish to a route" do
+      expect { client.publish(message(route_target)) }.to raise_error(ServiceMesh::KindMismatch)
+    end
+
+    it "rejects an endpoint on a topic" do
+      expect { build(endpoints: [endpoint(topic_target, ->(m) { m })]) }.to raise_error(ServiceMesh::KindMismatch)
+    end
+
+    it "rejects a subscriber on a route" do
+      expect { build(subscribers: [subscriber(route_target, ->(m) { m })]) }.to raise_error(ServiceMesh::KindMismatch)
+    end
+  end
+
+  describe "configuration" do
+    it "requires a deployment group" do
+      without = runtime_config.reject { |k, _| k == ServiceMesh::DEPLOYMENT_GROUP_KEY }
+      expect { build(without) }.to raise_error(ServiceMesh::NoDeploymentGroup)
+    end
+
+    it "rejects an empty deployment group" do
+      expect { build(config_for("")) }.to raise_error(ServiceMesh::NoDeploymentGroup)
+    end
+  end
+
+  describe "request and reply" do
+    it "round-trips payload and metadata both ways and ignores the reply's target" do
+      seen = nil
+      serve(endpoints: [endpoint(route_target, lambda { |m|
+        seen = m
+        message(topic_target, metadata: {"Reply-Key" => "reply-value"}, payload: m.payload.upcase)
+      })])
+
+      reply = client.request(message(route_target, metadata: {"Request-Key" => "request-value"}, payload: "hello"))
+
+      expect(seen.target.same_channel?(route_target)).to be(true)
+      expect(seen.metadata["Request-Key"]).to eq("request-value")
+      expect(reply.payload).to eq("HELLO")
+      expect(reply.payload.encoding).to eq(Encoding::BINARY)
+      expect(reply.metadata["Reply-Key"]).to eq("reply-value")
+      expect(reply.target.same_channel?(route_target)).to be(true)
+    end
+
+    it "carries an empty payload with no metadata" do
+      serve(endpoints: [endpoint(route_target, ->(m) { m })])
+      reply = client.request(message(route_target))
+      expect([reply.payload, reply.metadata]).to eq(["", {}])
+    end
+  end
+
+  describe "publish" do
+    it "reaches a subscriber with payload and metadata" do
+      got = Queue.new
+      serve(subscribers: [subscriber(topic_target, ->(m) { got << m })])
+
+      client.publish(message(topic_target, metadata: {"Event-Id" => "42"}, payload: "created"))
+
+      m = Timeout.timeout(wait) { got.pop }
+      expect(m.target.same_channel?(topic_target)).to be(true)
+      expect([m.payload, m.metadata["Event-Id"]]).to eq(["created", "42"])
+    end
+  end
+
+  describe "consumer groups" do
+    none = {ServiceMesh::CONSUMER_GROUP_KEY => ServiceMesh::CONSUMER_GROUP_NONE}
+    shared = {ServiceMesh::CONSUMER_GROUP_KEY => "order-consumers"}
+
+    [
+      ["same deployment, key absent: one instance handles it", %w[billing billing], [{}, {}], 1],
+      ["different deployments, key absent: each deployment handles it", %w[billing audit], [{}, {}], 2],
+      ["same deployment, none: every instance handles it", %w[billing billing], [none, none], 2],
+      ["different deployments, shared named group: one instance handles it", %w[billing audit], [shared, shared], 1]
+    ].each do |name, groups, metadata, want|
+      it name do
+        count = Queue.new
+        2.times do |i|
+          serve(config_for(groups[i]), subscribers: [subscriber(topic_target, ->(_) { count << true }, metadata: metadata[i])])
+        end
+
+        client.publish(message(topic_target))
+
+        wait_until { count.size >= want }
+        sleep 0.1 # let an unwanted extra delivery show up
+        expect(count.size).to eq(want)
+      end
+    end
+
+    it "honours a group set on the target rather than the binding" do
+      count = Queue.new
+      %w[a b].each do |group|
+        t = ServiceMesh::Target.new(segments: topic_target.segments, kind: :topic, metadata: {ServiceMesh::CONSUMER_GROUP_KEY => group})
+        serve(config_for("same"), subscribers: [subscriber(t, ->(_) { count << true })])
+      end
+      client.publish(message(topic_target))
+      wait_until { count.size == 2 }
+    end
+  end
+
+  describe "a standalone client" do
+    it "accepts no requests after close" do
+      serve(endpoints: [endpoint(route_target, ->(m) { m })])
+      own = new_client.call(client_config, service_map)
+
+      expect(own.request(message(route_target)).payload).to eq("")
+      own.close
+      expect { own.request(message(route_target)) }.to raise_error(StandardError)
+    end
+  end
+
+  describe "the runtime's client" do
+    it "is the client the runtime was given, and stop closes it" do
+      given = new_client.call(client_config, service_map)
+      rt = new_runtime.call(given, runtime_config, endpoints: [endpoint(route_target, ->(m) { m })], subscribers: [])
+      @conformance_runtimes << rt
+      req = message(route_target)
+
+      expect(rt.client).to equal(given)
+      expect(rt.service_map).to equal(service_map)
+      rt.start
+      expect(given.request(req).payload).to eq("")
+      rt.stop(1)
+      expect { given.request(req) }.to raise_error(StandardError)
+    end
+  end
+
+  describe "lifecycle" do
+    it "moves created -> running -> stopped and does not restart" do
+      rt = build
+      @conformance_runtimes << rt
+
+      expect(rt.running?).to be(false)
+      expect(rt.stop(0)).to be(true)
+      rt.start
+      expect(rt.running?).to be(true)
+      expect { rt.start }.to raise_error(StandardError)
+      expect(rt.stop(1)).to be(true)
+      expect(rt.running?).to be(false)
+      expect(rt.stop(0)).to be(true)
+      expect { rt.start }.to raise_error(StandardError)
+    end
+
+    it "rejects a negative drain" do
+      expect { build.stop(-1) }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe "stop" do
+    it "waits for an in-flight handler and the requester still gets the reply" do
+      entered = Queue.new
+      release = Queue.new
+      rt = serve(endpoints: [endpoint(route_target, lambda { |_|
+        entered << true
+        release.pop
+        message(route_target, payload: "done")
+      })])
+
+      reply = Thread.new { client.request(message(route_target)) }
+      @conformance_threads << reply
+      Timeout.timeout(wait) { entered.pop }
+
+      stopped = Thread.new { rt.stop(wait) }
+      sleep 0.2
+      expect(stopped.alive?).to be(true)
+
+      release << true
+      expect(stopped.value).to be(true)
+      expect(reply.value.payload).to eq("done")
+    end
+
+    it "returns false when the drain expires with a handler still running" do
+      entered = Queue.new
+      release = Queue.new
+      rt = serve(endpoints: [endpoint(route_target, lambda { |_|
+        entered << true
+        release.pop
+        message(route_target)
+      })])
+
+      @conformance_threads << Thread.new { client.request(message(route_target)) rescue nil } # rubocop:disable Style/RescueModifier
+      Timeout.timeout(wait) { entered.pop }
+
+      expect(rt.stop(0.1)).to be(false)
+      release << true
+    end
+  end
+end

data/lib/service_mesh/types.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ServiceMesh
+  KINDS = %i[route topic].freeze
+
+  # Configuration keys the specification defines. Everything else belongs to
+  # a transport.
+  DEPLOYMENT_GROUP_KEY = "deployment_group"
+  CONSUMER_GROUP_KEY = "consumer_group"
+  CONSUMER_GROUP_NONE = "none"
+
+  # Identifies a receiving channel on the mesh. A transport assembles the
+  # segments into its own address; that string never leaves the transport.
+  Target = Data.define(:segments, :kind, :metadata) do
+    def initialize(segments:, kind:, metadata: {})
+      raise KindMismatch, "kind must be one of #{KINDS.inspect}, got #{kind.inspect}" unless KINDS.include?(kind)
+
+      super(segments: Array(segments).map(&:to_s).freeze, kind: kind, metadata: metadata.to_h.freeze)
+    end
+
+    # Same channel: same segments and kind. Metadata is configuration.
+    def same_channel?(other)
+      segments == other.segments && kind == other.kind
+    end
+  end
+
+  # Every Target reachable over one transport.
+  ServiceMap = Data.define(:targets) do
+    def initialize(targets: [])
+      super(targets: Array(targets).freeze)
+    end
+  end
+
+  # What travels between services. Payload is always BINARY encoded.
+  Message = Data.define(:target, :metadata, :payload) do
+    def initialize(target:, metadata: {}, payload: "")
+      super(target: target, metadata: metadata.to_h.freeze, payload: payload.to_s.b.freeze)
+    end
+  end
+
+  # A route target paired with a handler that returns a Message.
+  Endpoint = Data.define(:target, :metadata, :handler) do
+    def initialize(target:, handler:, metadata: {})
+      super(target: target, metadata: metadata.to_h.freeze, handler: handler)
+    end
+  end
+
+  # A topic target paired with a handler whose return value is ignored.
+  Subscriber = Data.define(:target, :metadata, :handler) do
+    def initialize(target:, handler:, metadata: {})
+      super(target: target, metadata: metadata.to_h.freeze, handler: handler)
+    end
+  end
+end

data/lib/service_mesh/version.rb

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

data/lib/service_mesh.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "service_mesh/version"
+require_relative "service_mesh/types"
+require_relative "service_mesh/errors"
+
+# Ruby contract for the Service Mesh API Specification. Transports implement
+# Client and Runtime against these types; see service_mesh/rspec for the
+# conformance suite a transport runs.
+module ServiceMesh
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: service_mesh
+version: !ruby/object:Gem::Version
+  version: 0.4.1
+platform: ruby
+authors:
+- Paymentbox
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-25 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/service_mesh.rb
+- lib/service_mesh/errors.rb
+- lib/service_mesh/rspec.rb
+- lib/service_mesh/types.rb
+- lib/service_mesh/version.rb
+homepage: https://github.com/Paymentbox-com/service-mesh-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Paymentbox-com/service-mesh-ruby
+  source_code_uri: https://github.com/Paymentbox-com/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 contract for the Service Mesh API Specification
+test_files: []