service_mesh 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edccbfa1e181934bed8df91ecb53d15849335cb10730450e088fee1e28ac44ef
-  data.tar.gz: 64cbe1ba2b464e7ccd1dc840066eedf2dd0cd4639804af86e0fde65615cf064c
+  metadata.gz: 966f879206d92063d0a9fb94576db740746b6809e629548df3cad531547b543f
+  data.tar.gz: 0e411f07db7f14c1fd9e7bbe483a8d44d75c8bc13df6b111eb4ffdd8b0377d7e
 SHA512:
-  metadata.gz: bdff9e8e86405e3fcca5df769e800d317df47307d4974c88f9161728c165242ecfa7acf72880bfb41b2606f310c30a6fd6cf35dbb56d22dab202d27e1201725f
-  data.tar.gz: c3513ecbc6ae3832509419f8f3b9e9c93c637199eb6d8fd9b9183ef4046bf75d53dd3cc1cc73ee6d16dcaa2b116626956068ce3e3569404aba69bb90e0bc3e7a
+  metadata.gz: 9590a21777d4afacd500e6e294042a44ad31581a8688d32119e51d547e4c4917ecb7e5149b834862785971a8942e071f406ab590eb65aa3c81f1c9859f6e7a21
+  data.tar.gz: 374757753729d92f5e20930aaef9739676f600a75eb6d9fbdfecf3194590e03c29c9c9f11a0d748105b645b9fdf94438412c276083a13716a321ec732faa166f

data/README.md

@@ -1,5 +1,7 @@
 # service-mesh-ruby
 
+This version implements the Service Mesh API Specification v0.4.0.
+
 service-mesh-ruby is the Ruby contract for the
 [Service Mesh API Specification](https://github.com/Paymentbox-com/service-mesh-api).
 It is packaged as the gem `service_mesh`. It holds what every transport and every
@@ -23,9 +25,13 @@ Requires Ruby 3.3 or newer. The gem has no runtime dependencies.
   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` is runtime
-  configuration. `CONSUMER_GROUP_KEY`, with the value `CONSUMER_GROUP_NONE`, is `Endpoint` and
-  `Subscriber` metadata.
+- The configuration key the specification defines, `DEPLOYMENT_GROUP_KEY`, which is runtime
+  configuration.
+- The consumer group is the `consumer_group` member of `Endpoint` and `Subscriber`, defaulting to
+  `nil`. `CONSUMER_GROUP_NONE` is the value for no group.
+- The reserved metadata prefix `RESERVED_PREFIX` (`Mesh-`).
+- The metadata keys the specification defines: `HANDLER_ERROR_KEY`, `TIMEOUT_KEY`, `DEADLINE_KEY`,
+  `DELIVERY_ATTEMPT_KEY`, and `MESSAGE_ID_KEY`.
 - The errors defined by the specification as `ServiceMesh::Error`: `ServiceMesh::KindMismatch`,
   `ServiceMesh::InvalidTarget`, and `ServiceMesh::NoDeploymentGroup`.
 - A conformance suite a transport runs against its own `Client` and
@@ -73,6 +79,20 @@ RSpec.describe MyTransport do
 end
 ```
 
+A transport that needs its own settings for the suite to pass supplies any of
+five optional lets, each defaulting to an empty Hash:
+
+```ruby
+let(:target_metadata) { {...} }     # merged under the metadata of every Target the suite builds
+let(:endpoint_metadata) { {...} }   # merged under the metadata of every Endpoint the suite builds
+let(:subscriber_metadata) { {...} } # merged under the metadata of every Subscriber the suite builds
+let(:request_options) { {...} }     # the options of every request the suite makes
+let(:publish_options) { {...} }     # the options of every publish the suite makes
+```
+
+Metadata an example sets itself wins over `target_metadata`, `endpoint_metadata`, and
+`subscriber_metadata`.
+
 The suite covers:
 
 - kind checks

data/lib/service_mesh/rspec.rb

@@ -16,6 +16,13 @@ require_relative "../service_mesh"
 #       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) }
+#
+#       # Optional, each defaulting to an empty Hash.
+#       let(:target_metadata)     { {...} } # merged under the metadata of each Target the suite builds
+#       let(:endpoint_metadata)   { {...} } # merged under each Endpoint's metadata
+#       let(:subscriber_metadata) { {...} } # merged under each Subscriber's metadata
+#       let(:request_options)     { {...} } # options for every request
+#       let(:publish_options)     { {...} } # options for every publish
 #     end
 #   end
 #
@@ -25,13 +32,30 @@ require_relative "../service_mesh"
 RSpec.shared_examples "a service mesh transport" do
   let(:service_map) { ServiceMesh::ServiceMap.new }
   let(:wait) { 3 }
+  let(:target_metadata) { {} }
+  let(:endpoint_metadata) { {} }
+  let(:subscriber_metadata) { {} }
+  let(:request_options) { {} }
+  let(:publish_options) { {} }
+
+  def target(segments, kind, metadata: {})
+    ServiceMesh::Target.new(segments: segments, kind: kind, metadata: target_metadata.merge(metadata))
+  end
 
   def endpoint(target, handler, metadata: {})
-    ServiceMesh::Endpoint.new(target: target, handler: handler, metadata: metadata)
+    ServiceMesh::Endpoint.new(target: target, handler: handler, metadata: endpoint_metadata.merge(metadata))
+  end
+
+  def subscriber(target, handler, consumer_group: nil, metadata: {})
+    ServiceMesh::Subscriber.new(target: target, handler: handler, consumer_group: consumer_group, metadata: subscriber_metadata.merge(metadata))
+  end
+
+  def request(msg, via: client)
+    via.request(msg, request_options)
   end
 
-  def subscriber(target, handler, metadata: {})
-    ServiceMesh::Subscriber.new(target: target, handler: handler, metadata: metadata)
+  def publish(msg, via: client)
+    via.publish(msg, publish_options)
   end
 
   def message(target, metadata: {}, payload: "")
@@ -72,11 +96,11 @@ RSpec.shared_examples "a service mesh transport" do
 
   describe "kind checks" do
     it "rejects a request to a topic" do
-      expect { client.request(message(topic_target)) }.to raise_error(ServiceMesh::KindMismatch)
+      expect { 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)
+      expect { publish(message(route_target)) }.to raise_error(ServiceMesh::KindMismatch)
     end
 
     it "rejects an endpoint on a topic" do
@@ -107,7 +131,7 @@ RSpec.shared_examples "a service mesh transport" do
         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"))
+      reply = 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")
@@ -119,7 +143,7 @@ RSpec.shared_examples "a service mesh transport" do
 
     it "carries an empty payload with no metadata" do
       serve(endpoints: [endpoint(route_target, ->(m) { m })])
-      reply = client.request(message(route_target))
+      reply = request(message(route_target))
       expect([reply.payload, reply.metadata]).to eq(["", {}])
     end
   end
@@ -129,7 +153,7 @@ RSpec.shared_examples "a service mesh transport" do
       got = Queue.new
       serve(subscribers: [subscriber(topic_target, ->(m) { got << m })])
 
-      client.publish(message(topic_target, metadata: {"Event-Id" => "42"}, payload: "created"))
+      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)
@@ -138,22 +162,22 @@ RSpec.shared_examples "a service mesh transport" do
   end
 
   describe "consumer groups" do
-    none = {ServiceMesh::CONSUMER_GROUP_KEY => ServiceMesh::CONSUMER_GROUP_NONE}
-    shared = {ServiceMesh::CONSUMER_GROUP_KEY => "order-consumers"}
+    none = ServiceMesh::CONSUMER_GROUP_NONE
+    shared = "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, group unset: one instance handles it", %w[billing billing], [nil, nil], 1],
+      ["different deployments, group unset: each deployment handles it", %w[billing audit], [nil, nil], 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|
+    ].each do |name, groups, consumer_groups, 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])])
+          serve(config_for(groups[i]), subscribers: [subscriber(topic_target, ->(_) { count << true }, consumer_group: consumer_groups[i])])
         end
 
-        client.publish(message(topic_target))
+        publish(message(topic_target))
 
         wait_until { count.size >= want }
         sleep 0.1 # let an unwanted extra delivery show up
@@ -164,11 +188,11 @@ RSpec.shared_examples "a service mesh transport" do
     it "ignores a group set on the target, which carries none" 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})
+        t = target(topic_target.segments, :topic, metadata: {"consumer_group" => group})
         serve(config_for("same"), subscribers: [subscriber(t, ->(_) { count << true })])
       end
 
-      client.publish(message(topic_target))
+      publish(message(topic_target))
 
       wait_until { count.size >= 1 }
       sleep 0.1 # let an unwanted extra delivery show up
@@ -181,9 +205,9 @@ RSpec.shared_examples "a service mesh transport" 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("")
+      expect(request(message(route_target), via: own).payload).to eq("")
       own.close
-      expect { own.request(message(route_target)) }.to raise_error(StandardError)
+      expect { request(message(route_target), via: own) }.to raise_error(StandardError)
     end
   end
 
@@ -197,9 +221,9 @@ RSpec.shared_examples "a service mesh transport" do
       expect(rt.client).to equal(given)
       expect(rt.service_map).to equal(service_map)
       rt.start
-      expect(given.request(req).payload).to eq("")
+      expect(request(req, via: given).payload).to eq("")
       rt.stop(1)
-      expect { given.request(req) }.to raise_error(StandardError)
+      expect { request(req, via: given) }.to raise_error(StandardError)
     end
   end
 
@@ -234,7 +258,7 @@ RSpec.shared_examples "a service mesh transport" do
         message(route_target, payload: "done")
       })])
 
-      reply = Thread.new { client.request(message(route_target)) }
+      reply = Thread.new { request(message(route_target)) }
       @conformance_threads << reply
       Timeout.timeout(wait) { entered.pop }
 
@@ -256,7 +280,7 @@ RSpec.shared_examples "a service mesh transport" do
         message(route_target)
       })])
 
-      @conformance_threads << Thread.new { client.request(message(route_target)) rescue nil } # rubocop:disable Style/RescueModifier
+      @conformance_threads << Thread.new { request(message(route_target)) rescue nil } # rubocop:disable Style/RescueModifier
       Timeout.timeout(wait) { entered.pop }
 
       expect(rt.stop(0.1)).to be(false)

data/lib/service_mesh/types.rb

@@ -3,17 +3,52 @@
 module ServiceMesh
   KINDS = %i[route topic].freeze
 
-  # Configuration keys the specification defines. Everything else belongs to
-  # a transport. DEPLOYMENT_GROUP_KEY is runtime configuration, and nothing
-  # else carries it. CONSUMER_GROUP_KEY is Endpoint and Subscriber metadata;
-  # when it is unset or empty, the runtime's deployment group applies, and
-  # CONSUMER_GROUP_NONE means no group. A Target carries neither.
+  # The configuration key the specification defines. Everything else belongs
+  # to a transport. DEPLOYMENT_GROUP_KEY is runtime configuration, and nothing
+  # else carries it.
   DEPLOYMENT_GROUP_KEY = "deployment_group"
-  CONSUMER_GROUP_KEY = "consumer_group"
+
+  # The Endpoint and Subscriber consumer_group value that requests no group.
   CONSUMER_GROUP_NONE = "none"
 
+  # Metadata keys that start with RESERVED_PREFIX belong to transports and
+  # protocol layers, and application code does not set them. A key a
+  # transport defines for itself continues with the transport's name, such as
+  # "Mesh-Nats-". A transport may use any of the keys below, and one that does
+  # follows the meaning and format given here.
+  RESERVED_PREFIX = "Mesh-"
+
+  # Set by the serving transport on a reply when the Endpoint's handler
+  # failed. The value is the failure's text.
+  HANDLER_ERROR_KEY = "Mesh-Handler-Error"
+
+  # Set by the requesting transport on a request. The value is how long the
+  # caller waits for the reply, as a whole number of milliseconds.
+  TIMEOUT_KEY = "Mesh-Timeout"
+
+  # Set by the receiving transport on a message it hands to a handler. The
+  # value is when the handler's result stops mattering, in RFC 3339 with
+  # fractional seconds.
+  DEADLINE_KEY = "Mesh-Deadline"
+
+  # Set by the receiving transport on a message it hands to a handler. The
+  # value is which delivery of the message this is, starting at 1. It is
+  # absent when the transport does not track deliveries.
+  DELIVERY_ATTEMPT_KEY = "Mesh-Delivery-Attempt"
+
+  # Set by the publisher or caller. The value is an ID that stays the same
+  # when the same message is sent again, so handlers can recognize repeats.
+  MESSAGE_ID_KEY = "Mesh-Message-Id"
+
   # Identifies a receiving channel on the mesh. A transport assembles the
   # segments into its own address; that string never leaves the transport.
+  # Metadata holds addressing and the default transport settings for the
+  # target, and never a deployment group or consumer group.
+  #
+  # A transport reads each of its settings from the first of these that has a
+  # value: the per-call options of request or publish, the Endpoint's or
+  # Subscriber's metadata, the Target's metadata, and the transport's own
+  # default.
   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)
@@ -34,7 +69,9 @@ module ServiceMesh
     end
   end
 
-  # What travels between services. Payload is always BINARY encoded.
+  # What travels between services. Payload is always BINARY encoded. Metadata
+  # keys that start with RESERVED_PREFIX belong to transports and protocol
+  # layers.
   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)
@@ -42,16 +79,26 @@ module ServiceMesh
   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)
+  #
+  # consumer_group names the logical group the endpoint joins. When it is nil
+  # or empty, the runtime's deployment group applies. CONSUMER_GROUP_NONE means
+  # no group, so every instance handles every message. Any other value names
+  # the group, and one handler in that group handles each message.
+  #
+  # Metadata holds transport settings for the endpoint, which override the
+  # target's.
+  Endpoint = Data.define(:target, :consumer_group, :metadata, :handler) do
+    def initialize(target:, handler:, consumer_group: nil, metadata: {})
+      super(target: target, consumer_group: consumer_group, 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)
+  # consumer_group has the same meaning as on Endpoint. Metadata holds
+  # transport settings for the subscriber, which override the target's.
+  Subscriber = Data.define(:target, :consumer_group, :metadata, :handler) do
+    def initialize(target:, handler:, consumer_group: nil, metadata: {})
+      super(target: target, consumer_group: consumer_group, metadata: metadata.to_h.freeze, handler: handler)
     end
   end
 end

data/lib/service_mesh/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: service_mesh
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Bryant Morrill
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-30 00:00:00.000000000 Z
+date: 2026-10-08 00:00:00.000000000 Z
 dependencies: []
 description:
 email: