service_mesh 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 643fe078e4376b1f4d19e3e45e0dbbe7e8b61e620e96591f67c7b0ed18865a50
-  data.tar.gz: 57c88b02dd056895234d1536b16f00973202cdec9b6600f7ab31621452e52d93
+  metadata.gz: 966f879206d92063d0a9fb94576db740746b6809e629548df3cad531547b543f
+  data.tar.gz: 0e411f07db7f14c1fd9e7bbe483a8d44d75c8bc13df6b111eb4ffdd8b0377d7e
 SHA512:
-  metadata.gz: 56f15b80a1db1ad69e0e95105e8ed221b873b4ae762ff85296e576ad7cb1625b22209d5bf13aad4e85b903a2144b08bd9f6bdfef0169b49860f6c3350ebcdc4d
-  data.tar.gz: 7be31a262f4c7cf55b5a2f7661c69baf7922e2261a5924a59537bbb3e0c0c3141eb0247977aca65941ed033a5eeb6dd66f5a900978e980d4a28d66cff6cc3aff
+  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,10 @@ 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`.
@@ -77,16 +80,18 @@ 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:
+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 `endpoint_metadata` and `subscriber_metadata`.
+Metadata an example sets itself wins over `target_metadata`, `endpoint_metadata`, and
+`subscriber_metadata`.
 
 The suite covers:
 

data/lib/service_mesh/rspec.rb

@@ -18,6 +18,7 @@ require_relative "../service_mesh"
 #       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
@@ -31,17 +32,22 @@ 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: endpoint_metadata.merge(metadata))
   end
 
-  def subscriber(target, handler, metadata: {})
-    ServiceMesh::Subscriber.new(target: target, handler: handler, metadata: subscriber_metadata.merge(metadata))
+  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)
@@ -156,19 +162,19 @@ 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
 
         publish(message(topic_target))
@@ -182,7 +188,7 @@ 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
 

data/lib/service_mesh/types.rb

@@ -3,13 +3,12 @@
 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
@@ -43,6 +42,13 @@ module ServiceMesh
 
   # 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)
@@ -73,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.6.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.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Bryant Morrill