service_mesh_nats 0.5.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20a1213855e080bc361b292f2708b4f023ba38a5051c3ebddffc39cf55b91f7c
-  data.tar.gz: fd6939fad816e2beb146fbd8c3697b1221dabb3938a08bdbd73c23664488d71f
+  metadata.gz: 8766fe267e81c95787f56181bf3124d3a4a12de3f88da6acf7eb6297f181b6fb
+  data.tar.gz: 558e29c69edc0287eca76e4ba26963551d6f9670937b5fc98d0fca00dfdf06ee
 SHA512:
-  metadata.gz: 411c35df69a5c8bf43b9ce66e088d666e129c34e64e93a6be3408a471775813f427cb32813a1e47a49bdbaa0e69f56e449ee8e73ee720c397646a70b187c6c0e
-  data.tar.gz: 9fbde8fda5e37e58e4d08b0ffe9fe341098bdf5f84d241ddba5bace38003fcf974517bd2cd009deeb5f28cf45f828e3f1f79aa48f2593e1eec4c8f2355dd5f55
+  metadata.gz: f10332c9b690bf5d33606d588ad142a31e484e6ef70e8dc63d66dee5183e1fbf07dcfe8f0018ed75a230202f8cf8a6720255c7155404e395aca44422eca5e8eb
+  data.tar.gz: 7fd4f7fad61c811ccdd388e966cd9da91f504945691926d957dab6b77fcdc900a5ca7f4fc40549638039a2dda6c88fc2d829c97f8775b887349540fd34afe914

data/README.md

@@ -1,9 +1,20 @@
 # service-mesh-nats-ruby
 
-`service_mesh_nats` is the NATS transport implementation in Ruby for the
-[Service Mesh API Specification](https://github.com/Paymentbox-com/service-mesh-api).
-
-This gem depends on the contract types and errors in [service-mesh-ruby](https://github.com/Paymentbox-com/service-mesh-ruby).
+service-mesh-nats-ruby is the Ruby implementation of the
+[Service Mesh API Specification](https://github.com/Paymentbox-com/service-mesh-api)
+over NATS. It implements the Ruby contract in the `service_mesh` gem, from
+[service-mesh-ruby](https://github.com/Paymentbox-com/service-mesh-ruby), on
+top of the `nats-pure` client.
+
+The `ServiceMeshNats` module provides:
+* `Client`, which implements the contract's `Client` over one NATS connection
+* `Runtime`, which implements the contract's `Runtime` on a `Client`'s connection
+* the configuration keys it reads
+* the errors it defines
+
+The contract types it works with, such as `ServiceMesh::Target`,
+`ServiceMesh::Message`, `ServiceMesh::Endpoint`, and `ServiceMesh::Subscriber`,
+come from the `service_mesh` gem.
 
 ## Install
 
@@ -12,7 +23,7 @@ This gem depends on the contract types and errors in [service-mesh-ruby](https:/
 gem "service_mesh_nats"
 ```
 
-Requires Ruby 3.3 or newer and a reachable NATS server. Depends on
+Requires Ruby 3.3 or newer and a reachable NATS server. The gem depends on
 `service_mesh` and `nats-pure`.
 
 ## Usage
@@ -49,15 +60,14 @@ reply = client.request(ServiceMesh::Message.new(target: echo, payload: "hi"))
 client.publish(ServiceMesh::Message.new(target: created, payload: "order 42"))
 ```
 
-The client is the runtime's connection. `runtime.client` returns it, and
-`runtime.stop` closes it. A process that only requests and
-publishes builds a client itself and calls `close` when done.
-`runtime.service_map` and `client.service_map` return the map the client was
-built with.
+The client is the runtime's connection. `runtime.client` returns it in every
+state, and `runtime.stop` closes it. A process that only requests and publishes
+builds a client itself and calls `close` when done. `runtime.service_map` and
+`client.service_map` return the map the client was built with.
 
 ## Documentation
 
 - [Examples](docs/examples.md): a server process, a call-only client process, and consumer groups
-- [Public API](docs/public-api.md): the constants this gem exposes and how `Client` and `Runtime` behave
-- [What the NATS Runtime Decides](docs/runtime-behavior.md): targets, configuration, metadata, delivery, handler failure, timeouts, concurrency, lifecycle, and transport errors
+- [Public API](docs/public-api.md): every public constant and method in `ServiceMeshNats`
+- [Transport Specific Implementation](docs/transport-specific-implementation.md): subjects, configuration, metadata, delivery, handler failure, timeouts, concurrency, lifecycle, and errors
 - [Development](docs/development.md): the recipes and the tests

data/lib/service_mesh_nats/runtime.rb

@@ -9,7 +9,7 @@ module ServiceMeshNats
   # connection and runs their handlers on a bounded thread pool.
   class Runtime
     # A validated Endpoint or Subscriber. queue nil means a plain subscription.
-    Binding = Data.define(:subject, :queue, :target, :handler, :replies)
+    Subscription = Data.define(:subject, :queue, :target, :handler, :replies)
 
     FLUSH_BUDGET = 5.0
 
@@ -19,13 +19,13 @@ module ServiceMeshNats
     # Reads ServiceMesh::DEPLOYMENT_GROUP_KEY and CONCURRENCY_KEY from +config+;
     # connection keys are ignored, the client carries them. Raises
     # ServiceMesh::NoDeploymentGroup, BadConfig, ServiceMesh::KindMismatch, or
-    # ServiceMesh::InvalidTarget. Two bindings on one subject become two
-    # subscriptions. The connection is not touched until start.
+    # ServiceMesh::InvalidTarget. Two endpoints or subscribers on one subject
+    # become two subscriptions. The connection is not touched until start.
     def initialize(client, config, endpoints: [], subscribers: [], logger: Logger.new($stderr))
       @settings = RuntimeSettings.parse(config)
       @client = client
       @logger = logger
-      @bindings = bind_all(endpoints, subscribers)
+      @subscriptions = prepare_all(endpoints, subscribers)
 
       @lock = Mutex.new
       @state = :created
@@ -42,11 +42,11 @@ module ServiceMeshNats
       @client.service_map
     end
 
-    # Subscribes every binding on the client's connection and begins
+    # Subscribes every endpoint and subscriber on the client's connection and begins
     # receiving. Raises AlreadyStarted on a running runtime, Stopped after
     # stop, and Closed when the client has been closed. A failure while
-    # subscribing closes the client, marks the runtime stopped, and passes
-    # through.
+    # subscribing or flushing unsubscribes what was subscribed, leaves the
+    # runtime and the client as they were, and passes through.
     def start
       @lock.synchronize do
         raise AlreadyStarted if @state == :running
@@ -57,7 +57,7 @@ module ServiceMeshNats
         pool = Concurrent::FixedThreadPool.new(@settings.concurrency, name: "service_mesh_nats")
         subs = []
         begin
-          @bindings.each do |b|
+          @subscriptions.each do |b|
             opts = b.queue ? {queue: b.queue} : {}
             subs << nc.subscribe(b.subject, opts) { |msg| dispatch(pool, nc, b, msg) }
           end
@@ -66,8 +66,6 @@ module ServiceMeshNats
         rescue => e
           subs.each { |s| s.unsubscribe rescue nil } # rubocop:disable Style/RescueModifier
           pool.kill
-          @client.close
-          @state = :stopped
           raise e
         end
 
@@ -113,41 +111,41 @@ module ServiceMeshNats
       @logger.warn("service_mesh_nats: flush during stop failed: #{e.message}")
     end
 
-    def bind_all(endpoints, subscribers)
-      bind = lambda do |target, want, use, metadata, handler, replies|
+    def prepare_all(endpoints, subscribers)
+      prepare = lambda do |target, want, use, metadata, handler, replies|
         Subject.check_kind!(target, want, use)
         subject = Subject.format(target)
         raise ArgumentError, "#{use} #{subject} handler must respond to call" unless handler.respond_to?(:call)
 
-        queue = Subject.consumer_group(metadata, target.metadata, @settings.deployment_group)
-        Binding.new(subject: subject, queue: queue, target: target, handler: handler, replies: replies)
+        queue = Subject.consumer_group(metadata, @settings.deployment_group)
+        Subscription.new(subject: subject, queue: queue, target: target, handler: handler, replies: replies)
       end
 
-      endpoints.map { |e| bind.call(e.target, :route, "Endpoint", e.metadata, e.handler, true) } +
-        subscribers.map { |s| bind.call(s.target, :topic, "Subscriber", s.metadata, s.handler, false) }
+      endpoints.map { |e| prepare.call(e.target, :route, "Endpoint", e.metadata, e.handler, true) } +
+        subscribers.map { |s| prepare.call(s.target, :topic, "Subscriber", s.metadata, s.handler, false) }
     end
 
     # Runs on nats-pure's subscription thread; hands the message to the pool.
-    def dispatch(pool, nc, binding, msg)
-      pool.post { serve(nc, binding, msg) }
+    def dispatch(pool, nc, subscription, msg)
+      pool.post { serve(nc, subscription, msg) }
     rescue Concurrent::RejectedExecutionError
       # The pool is shutting down; the subscription is already gone.
     end
 
-    def serve(nc, binding, msg)
-      inbound = ServiceMesh::Message.new(target: binding.target, metadata: msg.header || {}, payload: msg.data.to_s)
+    def serve(nc, subscription, msg)
+      inbound = ServiceMesh::Message.new(target: subscription.target, metadata: msg.header || {}, payload: msg.data.to_s)
 
-      out = binding.handler.call(inbound)
-      return unless binding.replies && msg.reply
+      out = subscription.handler.call(inbound)
+      return unless subscription.replies && msg.reply
 
       unless out.is_a?(ServiceMesh::Message)
-        raise TypeError, "endpoint #{binding.subject} handler returned #{out.class}, expected ServiceMesh::Message"
+        raise TypeError, "endpoint #{subscription.subject} handler returned #{out.class}, expected ServiceMesh::Message"
       end
 
       reply(nc, msg.reply, out.metadata, out.payload)
     rescue => e
-      @logger.error("service_mesh_nats: handler failed on #{binding.subject}: #{e.class}: #{e.message}")
-      reply(nc, msg.reply, {HANDLER_ERROR_HEADER => e.message}, "") if binding.replies && msg.reply
+      @logger.error("service_mesh_nats: handler failed on #{subscription.subject}: #{e.class}: #{e.message}")
+      reply(nc, msg.reply, {HANDLER_ERROR_HEADER => e.message}, "") if subscription.replies && msg.reply
     end
 
     def reply(nc, subject, metadata, payload)

data/lib/service_mesh_nats/subject.rb

@@ -33,19 +33,15 @@ module ServiceMeshNats
       raise ServiceMesh::KindMismatch, "#{use} requires a #{want} target, got #{target.kind}"
     end
 
-    # The queue group for a binding. Binding metadata wins, then target
-    # metadata, then the deployment group. nil means a plain subscription.
-    def consumer_group(binding_metadata, target_metadata, deployment_group)
-      [binding_metadata, target_metadata].each do |md|
-        next unless md.key?(ServiceMesh::CONSUMER_GROUP_KEY)
-
-        value = md[ServiceMesh::CONSUMER_GROUP_KEY].to_s
-        next if value.empty?
-        return nil if value == ServiceMesh::CONSUMER_GROUP_NONE
-
-        return value
-      end
-      deployment_group
+    # The queue group of an Endpoint or Subscriber, from its metadata, falling
+    # back to the runtime's deployment group. nil means a plain subscription.
+    # A Target carries no consumer group, so its metadata is not read.
+    def consumer_group(metadata, deployment_group)
+      value = metadata[ServiceMesh::CONSUMER_GROUP_KEY].to_s
+      return deployment_group if value.empty?
+      return nil if value == ServiceMesh::CONSUMER_GROUP_NONE
+
+      value
     end
   end
 end

data/lib/service_mesh_nats/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: service_mesh_nats
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.7.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-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nats-pure
@@ -31,14 +31,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.5'
 description:
 email:
 - bryantreadmorrill@gmail.com