service_mesh_nats 0.5.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 20a1213855e080bc361b292f2708b4f023ba38a5051c3ebddffc39cf55b91f7c
+  data.tar.gz: fd6939fad816e2beb146fbd8c3697b1221dabb3938a08bdbd73c23664488d71f
+SHA512:
+  metadata.gz: 411c35df69a5c8bf43b9ce66e088d666e129c34e64e93a6be3408a471775813f427cb32813a1e47a49bdbaa0e69f56e449ee8e73ee720c397646a70b187c6c0e
+  data.tar.gz: 9fbde8fda5e37e58e4d08b0ffe9fe341098bdf5f84d241ddba5bace38003fcf974517bd2cd009deeb5f28cf45f828e3f1f79aa48f2593e1eec4c8f2355dd5f55

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,63 @@
+# 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).
+
+## Install
+
+```ruby
+# Gemfile
+gem "service_mesh_nats"
+```
+
+Requires Ruby 3.3 or newer and a reachable NATS server. Depends on
+`service_mesh` and `nats-pure`.
+
+## Usage
+
+```ruby
+require "service_mesh_nats"
+
+echo    = ServiceMesh::Target.new(segments: %w[demo echo], kind: :route)
+created = ServiceMesh::Target.new(segments: %w[demo created], kind: :topic)
+map     = ServiceMesh::ServiceMap.new(targets: [echo, created])
+
+config = {
+  "url" => "nats://127.0.0.1:4222",
+  "deployment_group" => "demo"
+}
+
+client = ServiceMeshNats::Client.new(config, map)
+# Connects. Raises BadConfig or the connection failure.
+
+runtime = ServiceMeshNats::Runtime.new(client, config,
+  endpoints: [
+    ServiceMesh::Endpoint.new(target: echo, handler: ->(m) { ServiceMesh::Message.new(target: echo, payload: m.payload) })
+  ],
+  subscribers: [
+    ServiceMesh::Subscriber.new(target: created, handler: ->(m) { puts "created: #{m.payload}" })
+  ])
+# Raises NoDeploymentGroup, BadConfig, KindMismatch, or InvalidTarget, and
+# ArgumentError for a handler that does not respond to call.
+
+runtime.start
+at_exit { runtime.stop(10) }
+
+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.
+
+## 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
+- [Development](docs/development.md): the recipes and the tests

data/lib/service_mesh_nats/client.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "nats/io/client"
+
+module ServiceMeshNats
+  # Owns one NATS connection and sends messages over it. A Runtime is built
+  # from a client and subscribes through its connection.
+  class Client
+    # The map this client was built with. The client does not otherwise use
+    # it.
+    attr_reader :service_map
+
+    # Parses the connection keys of +config+ (every other key is ignored) and
+    # opens the connection. A connection failure passes through unchanged.
+    # Connection errors reported by nats-pure after that are logged to
+    # +logger+ when one is given.
+    def initialize(config, service_map, logger: nil)
+      @settings = ClientSettings.parse(config)
+      @service_map = service_map
+      @lock = Mutex.new
+      @closed = false
+      @nc = NATS::IO::Client.new
+      @nc.on_error { |e| logger.warn("service_mesh_nats: #{e.class}: #{e.message}") } if logger
+      @nc.connect(@settings.connect_options)
+    end
+
+    # Closes the connection and marks the client closed. Returns nil.
+    # Idempotent.
+    def close
+      @lock.synchronize do
+        return nil if @closed
+
+        @nc.close
+        @closed = true
+      end
+      nil
+    end
+
+    # The NATS::IO::Client this client owns. Used by Runtime. Raises Closed
+    # after close.
+    def connection
+      raise Closed if @closed
+
+      @nc
+    end
+
+    # Sends +message+ to a route target and returns the reply.
+    #
+    # +opts+ may carry REQUEST_TIMEOUT_KEY to override the configured request
+    # timeout for this call. Expiry raises NATS::Timeout; no receiver raises
+    # NATS::IO::NoRespondersError.
+    def request(message, opts = {})
+      Subject.check_kind!(message.target, :route, "request")
+      subject = Subject.format(message.target)
+      timeout = Settings.duration(opts.to_h, REQUEST_TIMEOUT_KEY, @settings.request_timeout)
+      nc = connection
+
+      reply = nc.request_msg(nats_msg(subject, message), timeout: timeout)
+      header = reply.header || {}
+      raise HandlerError.new(header[HANDLER_ERROR_HEADER].to_s) if header.key?(HANDLER_ERROR_HEADER)
+
+      ServiceMesh::Message.new(target: message.target, metadata: header, payload: reply.data.to_s)
+    end
+
+    # Sends +message+ to a topic target. +opts+ is accepted for the interface
+    # and not read.
+    def publish(message, opts = {})
+      Subject.check_kind!(message.target, :topic, "publish")
+      subject = Subject.format(message.target)
+      connection.publish_msg(nats_msg(subject, message))
+      nil
+    end
+
+    private
+
+    def nats_msg(subject, message)
+      header = message.metadata.empty? ? nil : message.metadata.transform_keys(&:to_s).transform_values(&:to_s)
+      NATS::Msg.new(subject: subject, data: message.payload, header: header)
+    end
+  end
+end

data/lib/service_mesh_nats/errors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ServiceMeshNats
+  # This transport's errors. The contract errors are ServiceMesh::KindMismatch,
+  # ServiceMesh::InvalidTarget, and ServiceMesh::NoDeploymentGroup.
+  class Error < StandardError; end
+
+  class BadConfig < Error; end
+
+  class Closed < Error
+    def initialize(msg = "client has been closed") = super
+  end
+
+  class AlreadyStarted < Error
+    def initialize(msg = "runtime already started") = super
+  end
+
+  class Stopped < Error
+    def initialize(msg = "runtime has been stopped; it is not restartable") = super
+  end
+
+  # Raised by Client#request when the serving handler raised. +text+ is the
+  # handler's error message as sent by the serving runtime.
+  class HandlerError < Error
+    attr_reader :text
+
+    def initialize(text)
+      @text = text
+      super("handler failed: #{text}")
+    end
+  end
+
+  # Reply header set when an endpoint handler fails. Application metadata
+  # should not use this key.
+  HANDLER_ERROR_HEADER = "Mesh-Handler-Error"
+end

data/lib/service_mesh_nats/runtime.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "concurrent"
+require "logger"
+require "nats/io/client"
+
+module ServiceMeshNats
+  # The service process: subscribes endpoints and subscribers on one NATS
+  # 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)
+
+    FLUSH_BUDGET = 5.0
+
+    # The client this runtime was built from, in every state.
+    attr_reader :client
+
+    # 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.
+    def initialize(client, config, endpoints: [], subscribers: [], logger: Logger.new($stderr))
+      @settings = RuntimeSettings.parse(config)
+      @client = client
+      @logger = logger
+      @bindings = bind_all(endpoints, subscribers)
+
+      @lock = Mutex.new
+      @state = :created
+      @subs = []
+      @pool = nil
+    end
+
+    def running?
+      @state == :running
+    end
+
+    # The client's service map.
+    def service_map
+      @client.service_map
+    end
+
+    # Subscribes every binding 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.
+    def start
+      @lock.synchronize do
+        raise AlreadyStarted if @state == :running
+        raise Stopped if @state == :stopped
+
+        nc = @client.connection
+
+        pool = Concurrent::FixedThreadPool.new(@settings.concurrency, name: "service_mesh_nats")
+        subs = []
+        begin
+          @bindings.each do |b|
+            opts = b.queue ? {queue: b.queue} : {}
+            subs << nc.subscribe(b.subject, opts) { |msg| dispatch(pool, nc, b, msg) }
+          end
+          # Ensure the server has every subscription before start returns.
+          nc.flush(FLUSH_BUDGET)
+        rescue => e
+          subs.each { |s| s.unsubscribe rescue nil } # rubocop:disable Style/RescueModifier
+          pool.kill
+          @client.close
+          @state = :stopped
+          raise e
+        end
+
+        @subs = subs
+        @pool = pool
+        @state = :running
+      end
+      nil
+    end
+
+    # Stops receiving, waits up to +drain+ seconds for in-flight handlers,
+    # flushes, then closes the client. Returns true when every handler
+    # finished, false when some were abandoned. A runtime that is not running
+    # returns true and leaves the client as it is. A client the caller closed
+    # directly is treated as gone: nothing is flushed and the drain result is
+    # still returned.
+    def stop(drain)
+      drain = Float(drain)
+      raise ArgumentError, "drain must be non-negative" if drain.negative?
+
+      @lock.synchronize do
+        return true unless @state == :running
+
+        @state = :stopped
+        @subs.each { |s| s.unsubscribe rescue nil } # rubocop:disable Style/RescueModifier
+
+        @pool.shutdown
+        finished = @pool.wait_for_termination(drain)
+        flush if finished
+        @client.close
+        @subs = []
+        finished
+      end
+    end
+
+    private
+
+    def flush
+      @client.connection.flush(FLUSH_BUDGET)
+    rescue Closed
+      # The caller closed the client directly; there is nothing to flush.
+    rescue => e
+      @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|
+        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)
+      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) }
+    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) }
+    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)
+
+      out = binding.handler.call(inbound)
+      return unless binding.replies && msg.reply
+
+      unless out.is_a?(ServiceMesh::Message)
+        raise TypeError, "endpoint #{binding.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
+    end
+
+    def reply(nc, subject, metadata, payload)
+      header = metadata.empty? ? nil : metadata.transform_keys(&:to_s).transform_values(&:to_s)
+      nc.publish_msg(NATS::Msg.new(subject: subject, data: payload.to_s.b, header: header))
+    rescue => e
+      @logger.error("service_mesh_nats: reply failed: #{e.class}: #{e.message}")
+    end
+  end
+end

data/lib/service_mesh_nats/settings.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "etc"
+
+module ServiceMeshNats
+  # Configuration keys this transport reads beyond ServiceMesh::DEPLOYMENT_GROUP_KEY.
+  # Every value is a string. Durations are seconds, such as "5" or "0.25".
+  URL_KEY = "url"
+  NAME_KEY = "name"
+  CONNECT_TIMEOUT_KEY = "connect_timeout"
+  REQUEST_TIMEOUT_KEY = "request_timeout"
+  CONCURRENCY_KEY = "concurrency"
+
+  DEFAULT_URL = "nats://127.0.0.1:4222"
+  DEFAULT_CONNECT_TIMEOUT = 5.0
+  DEFAULT_REQUEST_TIMEOUT = 30.0
+
+  # Value parsers shared by the two settings types.
+  module Settings
+    module_function
+
+    # Reads +key+ as a positive number of seconds, or returns +fallback+ when
+    # absent.
+    def duration(hash, key, fallback)
+      return fallback unless hash.key?(key)
+
+      value = Float(hash[key], exception: false)
+      raise BadConfig, "#{key}=#{hash[key].inspect} must be a positive number of seconds" if value.nil? || value <= 0
+
+      value
+    end
+
+    def positive_integer(hash, key, fallback)
+      return fallback unless hash.key?(key)
+
+      value = Integer(hash[key], 10, exception: false)
+      raise BadConfig, "#{key}=#{hash[key].inspect} must be a positive integer" if value.nil? || value <= 0
+
+      value
+    end
+  end
+
+  # The keys a Client reads. Any other key is ignored.
+  ClientSettings = Data.define(:url, :name, :connect_timeout, :request_timeout) do
+    def self.parse(config)
+      config = config.to_h
+      new(
+        url: config.fetch(URL_KEY, DEFAULT_URL).then { |v| v.to_s.empty? ? DEFAULT_URL : v },
+        name: config[NAME_KEY],
+        connect_timeout: Settings.duration(config, CONNECT_TIMEOUT_KEY, DEFAULT_CONNECT_TIMEOUT),
+        request_timeout: Settings.duration(config, REQUEST_TIMEOUT_KEY, DEFAULT_REQUEST_TIMEOUT)
+      )
+    end
+
+    def connect_options
+      opts = {servers: [url], connect_timeout: connect_timeout}
+      opts[:name] = name if name && !name.empty?
+      opts
+    end
+  end
+
+  # The keys a Runtime reads. Connection keys in a runtime's config are
+  # ignored; the runtime's client carries them.
+  RuntimeSettings = Data.define(:deployment_group, :concurrency) do
+    def self.parse(config)
+      config = config.to_h
+      deployment_group = config[ServiceMesh::DEPLOYMENT_GROUP_KEY].to_s
+      raise ServiceMesh::NoDeploymentGroup if deployment_group.empty?
+
+      new(
+        deployment_group: deployment_group,
+        concurrency: Settings.positive_integer(config, CONCURRENCY_KEY, Etc.nprocessors)
+      )
+    end
+  end
+end

data/lib/service_mesh_nats/subject.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ServiceMeshNats
+  # Assembles targets into NATS subjects and resolves queue groups.
+  module Subject
+    module_function
+
+    # Joins segments with "." or raises InvalidTarget with the reason.
+    def format(target)
+      raise ServiceMesh::InvalidTarget, "no segments" if target.segments.empty?
+
+      target.segments.each_with_index do |seg, i|
+        reason = segment_problem(seg)
+        raise ServiceMesh::InvalidTarget, "segment #{i} #{seg.inspect}: #{reason}" if reason
+      end
+      target.segments.join(".")
+    end
+
+    def segment_problem(seg)
+      return "empty" if seg.empty?
+      return "contains '.'" if seg.include?(".")
+      return "contains wildcard" if seg.include?("*") || seg.include?(">")
+      return "contains whitespace" if seg.match?(/\s/)
+      return "contains non-printable character" if seg.match?(/[^[:print:]]/)
+
+      nil
+    end
+
+    # Raises KindMismatch unless the target's kind is +want+.
+    def check_kind!(target, want, use)
+      return if target.kind == want
+
+      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
+    end
+  end
+end

data/lib/service_mesh_nats/version.rb

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

data/lib/service_mesh_nats.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "service_mesh"
+
+require_relative "service_mesh_nats/version"
+require_relative "service_mesh_nats/errors"
+require_relative "service_mesh_nats/settings"
+require_relative "service_mesh_nats/subject"
+require_relative "service_mesh_nats/client"
+require_relative "service_mesh_nats/runtime"
+
+# NATS transport for the Service Mesh API Specification. The contract types
+# and errors come from the service_mesh gem.
+module ServiceMeshNats
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: service_mesh_nats
+version: !ruby/object:Gem::Version
+  version: 0.5.1
+platform: ruby
+authors:
+- Bryant Morrill
+- Paymentbox
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nats-pure
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: service_mesh
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+description:
+email:
+- bryantreadmorrill@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/service_mesh_nats.rb
+- lib/service_mesh_nats/client.rb
+- lib/service_mesh_nats/errors.rb
+- lib/service_mesh_nats/runtime.rb
+- lib/service_mesh_nats/settings.rb
+- lib/service_mesh_nats/subject.rb
+- lib/service_mesh_nats/version.rb
+homepage: https://github.com/Paymentbox-com/service-mesh-nats-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Paymentbox-com/service-mesh-nats-ruby
+  source_code_uri: https://github.com/Paymentbox-com/service-mesh-nats-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 implementation of the Service Mesh API Specification over NATS
+test_files: []