service_mesh 0.4.4 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d1c22ba40201e6531617371be60f030c23976f3a31d06a536114a388c59a9f0
-  data.tar.gz: c3e7fd9aedbc639cde6d3727e028799fa51d3222a0006826655084e9f6cb36ea
+  metadata.gz: 643fe078e4376b1f4d19e3e45e0dbbe7e8b61e620e96591f67c7b0ed18865a50
+  data.tar.gz: 57c88b02dd056895234d1536b16f00973202cdec9b6600f7ab31621452e52d93
 SHA512:
-  metadata.gz: d9ebe5643e51f2aebb1ddb7896344b7db28ec0bced10a6cb759db597ffafea1c558dd7612daa9297d4fb4d36c413349c3b085a692770ea0c60742a892d1beffa
-  data.tar.gz: a5d57ce5d40a07b3ce478ba55dead8115c62c7f6bb678115e90fce513ef27128e851d33f71dd408d318fae5411a1eb53b086d1b539b867bec225934ed7558071
+  metadata.gz: 56f15b80a1db1ad69e0e95105e8ed221b873b4ae762ff85296e576ad7cb1625b22209d5bf13aad4e85b903a2144b08bd9f6bdfef0169b49860f6c3350ebcdc4d
+  data.tar.gz: 7be31a262f4c7cf55b5a2f7661c69baf7922e2261a5924a59537bbb3e0c0c3141eb0247977aca65941ed033a5eeb6dd66f5a900978e980d4a28d66cff6cc3aff

data/README.md

@@ -23,8 +23,12 @@ 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`,
-  `CONSUMER_GROUP_KEY`, and the value `CONSUMER_GROUP_NONE`.
+- 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 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
@@ -72,6 +76,18 @@ RSpec.describe MyTransport do
 end
 ```
 
+A transport that needs its own settings for the suite to pass supplies any of
+four optional lets, each defaulting to an empty Hash:
+
+```ruby
+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 `endpoint_metadata` and `subscriber_metadata`.
+
 The suite covers:
 
 - kind checks

data/lib/service_mesh/rspec.rb

@@ -16,6 +16,12 @@ 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(: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 +31,25 @@ require_relative "../service_mesh"
 RSpec.shared_examples "a service mesh transport" do
   let(:service_map) { ServiceMesh::ServiceMap.new }
   let(:wait) { 3 }
+  let(:endpoint_metadata) { {} }
+  let(:subscriber_metadata) { {} }
+  let(:request_options) { {} }
+  let(:publish_options) { {} }
 
   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, metadata: {})
-    ServiceMesh::Subscriber.new(target: target, handler: handler, metadata: metadata)
+    ServiceMesh::Subscriber.new(target: target, handler: handler, metadata: subscriber_metadata.merge(metadata))
+  end
+
+  def request(msg, via: client)
+    via.request(msg, request_options)
+  end
+
+  def publish(msg, via: client)
+    via.publish(msg, publish_options)
   end
 
   def message(target, metadata: {}, payload: "")
@@ -72,11 +90,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 +125,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 +137,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 +147,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)
@@ -153,7 +171,7 @@ RSpec.shared_examples "a service mesh transport" do
           serve(config_for(groups[i]), subscribers: [subscriber(topic_target, ->(_) { count << true }, metadata: metadata[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
@@ -161,14 +179,18 @@ RSpec.shared_examples "a service mesh transport" do
       end
     end
 
-    it "honours a group set on the target rather than the binding" 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})
         serve(config_for("same"), subscribers: [subscriber(t, ->(_) { count << true })])
       end
-      client.publish(message(topic_target))
-      wait_until { count.size == 2 }
+
+      publish(message(topic_target))
+
+      wait_until { count.size >= 1 }
+      sleep 0.1 # let an unwanted extra delivery show up
+      expect(count.size).to eq(1)
     end
   end
 
@@ -177,9 +199,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
 
@@ -193,9 +215,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
 
@@ -230,7 +252,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 }
 
@@ -252,7 +274,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

@@ -4,11 +4,43 @@ module ServiceMesh
   KINDS = %i[route topic].freeze
 
   # Configuration keys the specification defines. Everything else belongs to
-  # a transport.
+  # 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.
   DEPLOYMENT_GROUP_KEY = "deployment_group"
   CONSUMER_GROUP_KEY = "consumer_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.
   Target = Data.define(:segments, :kind, :metadata) do
@@ -31,7 +63,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)

data/lib/service_mesh/version.rb

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

metadata

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