tether 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f4bb93cf37cafd3c8d5c716e840583e7e393533606648c59ec8b4c001ac9eecf
+  data.tar.gz: 59be9816c6773a4404207b8bccba9bff98eb764911432118e7fada6e7db5cc3e
+SHA512:
+  metadata.gz: 6d3d29e1be6c242d9ca6f19c8b59be5154c8fbe5d29910349463f17663c3f77e1d82be4ba9e402f7104d122e559bd4b26d1779ad4d2a07e5e9b61d794cb771bc
+  data.tar.gz: fe088501f0b7a9e6df145034c118529efe7803cc52395e92c4135006873a64231b00790753a1b28c539e78352a5e2241f3731bf4a7dc93791bb7c89f9f1d7087

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dmitry Vorotilin
+
+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,5 @@
+# Tether
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+desc "Validate RBS signatures"
+task :rbs do
+  sh "rbs -I sig -r uri validate"
+end
+
+task default: %i[spec rubocop rbs]

data/lib/tether/client.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Tether
+  # A connection to a NATS server.
+  #
+  # One reader thread parses the socket and enqueues to subscriptions; each
+  # subscription runs its callback on its own worker. Writes take a lock that
+  # spans a whole frame. Nothing here uses `Timeout.timeout` or `Thread#raise`.
+  class Client
+    DEFAULT_URI = "nats://127.0.0.1:4222"
+    DEFAULT_CONNECT_TIMEOUT = 2
+    DEFAULT_FLUSH_TIMEOUT = 10
+    DEFAULT_REQUEST_TIMEOUT = 2
+
+    # @return [Hash, nil] the INFO the server sent on connect
+    attr_reader :server_info
+
+    # @return [Symbol] :disconnected, :connected, or :closed
+    attr_reader :status
+
+    # @return [Exception, nil] the last asynchronous error seen
+    attr_reader :last_error
+
+    # Connects and returns a client, yielding it and closing after if a block is given.
+    #
+    # Connects, and when a block is given yields the client and closes it after.
+    #
+    # @param uri [String, nil]
+    # @param options [Hash{Symbol => Object}] CONNECT overrides, plus :connect_timeout and :max_pending
+    # @return [Client, Object] the client, or the block's value
+    # @raise [ConnectionError] if the server cannot be reached
+    def self.connect(uri = nil, **options)
+      client = new(uri, **options)
+      client.connect
+      return client unless block_given?
+
+      begin
+        yield client
+      ensure
+        client.close
+      end
+    end
+
+    # Builds a client without opening a socket. Call {#connect}, or use
+    # {.connect} to do both.
+    #
+    # @param uri [String, nil]
+    # @param options [Hash{Symbol => Object}]
+    def initialize(uri = nil, **options)
+      @uri = uri || ENV.fetch("NATS_URL", DEFAULT_URI)
+      @options = options
+      @status = :disconnected
+      @sid_counter = 0
+      @lock = Mutex.new
+      @pongs = Thread::Queue.new
+      @error_handlers = []
+      @dispatcher = build_dispatcher
+      @parser = Protocol::Parser.new(@dispatcher)
+    end
+
+    # Opens the socket, exchanges INFO and CONNECT, and starts the reader.
+    #
+    # @param timeout [Numeric, nil]
+    # @return [self]
+    def connect(timeout: @options.fetch(:connect_timeout, DEFAULT_CONNECT_TIMEOUT))
+      deadline = Deadline.after(timeout)
+      @transport = Transport.connect(@uri, deadline: deadline)
+      read_server_info(deadline)
+      @transport.write(Protocol::Encoder.connect(connect_options))
+      @status = :connected
+      start_reader
+      flush(timeout: deadline.remaining)
+      self
+    end
+
+    # Publishes a message.
+    #
+    # Fire and forget: the server sends no acknowledgement, so a successful
+    # return means the frame reached the socket, not that the server processed
+    # it. Follow with {#flush} when you need that guarantee.
+    #
+    # @param subject [String]
+    # @param payload [String, nil]
+    # @param reply_to [String, nil]
+    # @param headers [Headers, nil]
+    # @return [void]
+    # @raise [MaxPayloadError] if the frame exceeds what the server advertised
+    def publish(subject, payload = nil, reply_to: nil, headers: nil)
+      ensure_connected!
+      frame = if headers
+                Protocol::Encoder.hpub(subject, payload, headers, reply_to)
+              else
+                Protocol::Encoder.pub(subject, payload, reply_to)
+              end
+      check_payload_size!(subject, frame)
+      @transport.write(frame)
+      nil
+    end
+
+    # Subscribes, delivering to the block on a worker thread when one is given.
+    #
+    # @param subject [String]
+    # @param queue [String, nil] queue group
+    # @param max_pending [Integer]
+    # @return [Subscription]
+    def subscribe(subject, queue: nil, max_pending: Subscription::DEFAULT_MAX_PENDING, &callback)
+      ensure_connected!
+      subscription = Subscription.new(
+        sid: next_sid, subject: subject, queue_group: queue, max_pending: max_pending,
+        on_slow_consumer: method(:report_slow_consumer), responder: self, &callback
+      )
+      @dispatcher.add(subscription)
+      @transport.write(Protocol::Encoder.sub(subject, subscription.sid, queue: queue))
+      subscription
+    end
+
+    # Cancels a subscription.
+    #
+    # With max_msgs the server keeps delivering until that many more messages
+    # have arrived, so the subscription stays registered and its worker keeps
+    # running until then.
+    #
+    # @param subscription [Subscription]
+    # @param max_msgs [Integer, nil] unsubscribe only after this many more messages
+    # @return [void]
+    def unsubscribe(subscription, max_msgs = nil)
+      @transport.write(Protocol::Encoder.unsub(subscription.sid, max_msgs)) unless @transport.closed?
+      return if max_msgs
+
+      @dispatcher.remove(subscription.sid)
+      subscription.close
+      nil
+    end
+
+    # Publishes a request and waits for the first reply.
+    #
+    # Every request on a connection shares one inbox subscription; replies are
+    # demultiplexed in memory, so N concurrent requests cost one subscription.
+    #
+    # @param subject [String]
+    # @param payload [String, nil]
+    # @param timeout [Numeric, nil]
+    # @param headers [Headers, nil]
+    # @return [Msg]
+    # @raise [NoRespondersError] if nobody is subscribed to the subject
+    # @raise [TimeoutError] if no reply arrives in time
+    def request(subject, payload = nil, timeout: DEFAULT_REQUEST_TIMEOUT, headers: nil)
+      ensure_connected!
+      inbox_mux.request(subject, payload, deadline: Deadline.after(timeout), headers: headers)
+    end
+
+    # Builds a reply subject for a subscribe-then-publish exchange, which is
+    # what you want when a single request may draw several replies.
+    #
+    # @return [String] a fresh inbox subject, unrelated to the shared request inbox
+    def new_inbox
+      "#{InboxMux::INBOX_PREFIX}.#{NUID.next}"
+    end
+
+    # Round trips a PING, which the server answers only after everything sent
+    # before it has been processed.
+    #
+    # @param timeout [Numeric, nil]
+    # @return [true]
+    # @raise [TimeoutError]
+    def flush(timeout: DEFAULT_FLUSH_TIMEOUT)
+      ensure_connected!
+      @transport.write(Protocol::PING)
+      raise TimeoutError, "flush timed out after #{timeout}s" if @pongs.pop(timeout: timeout).nil?
+
+      true
+    end
+
+    # Closes the socket, which unblocks the reader's pending read so it can
+    # exit on its own. Nothing is killed: a thread stopped mid-parse would
+    # leave shared state in whatever shape the interrupt found it.
+    #
+    # @return [void]
+    def close
+      return if @status == :closed
+
+      @status = :closed
+      @inbox_mux&.close
+      @transport&.close
+      @reader.join(1) if @reader && @reader != Thread.current
+      @dispatcher.clear
+      @pongs.close
+      nil
+    end
+
+    # @return [Boolean] whether the handshake completed and the socket is live
+    def connected? = @status == :connected
+
+    # @return [Boolean] whether {#close} has run; a closed client cannot be reopened
+    def closed? = @status == :closed
+
+    # Registers a handler for errors that arrive outside any call.
+    #
+    # Errors are never raised into a caller's thread: they are recorded and
+    # passed here, on the reader thread.
+    #
+    # @yieldparam error [Exception]
+    # @return [void]
+    def on_error(&handler)
+      @error_handlers << handler
+      nil
+    end
+
+    # Counts live subscriptions. Request/reply adds exactly one, however many
+    # requests are in flight.
+    #
+    # @return [Integer] subscriptions currently registered, including the shared request inbox
+    def subscription_count = @dispatcher.size
+
+    # The ceiling the server advertised in INFO. {#publish} refuses anything
+    # larger rather than letting the server close the connection over it.
+    #
+    # @return [Integer] largest payload the server accepts
+    def max_payload = @server_info&.fetch("max_payload", nil)
+
+    private
+
+    def inbox_mux
+      @lock.synchronize { @inbox_mux ||= InboxMux.new(self, max_pending: @options.fetch(:max_pending, Subscription::DEFAULT_MAX_PENDING)) }
+    end
+
+    def build_dispatcher
+      Dispatcher.new(
+        ping: -> { @transport.write(Protocol::PONG) },
+        pong: -> { @pongs.push(true) unless @pongs.closed? },
+        info: ->(json) { @server_info = JSON.parse(json) },
+        error: ->(description) { record_error(ServerError.for(description)) },
+        protocol_error: ->(message) { record_error(ProtocolError.new(message)) }
+      )
+    end
+
+    def read_server_info(deadline)
+      @parser << @transport.read(deadline) until @server_info
+      @parser.max_payload = @server_info["max_payload"]
+    end
+
+    def connect_options
+      allowed = @options.except(:connect_timeout, :max_pending)
+      allowed.merge(name: @options[:name] || "tether")
+    end
+
+    def start_reader
+      @reader = Thread.new do
+        Thread.current.name = "tether:reader"
+        read_loop
+      end
+    end
+
+    def read_loop
+      until @transport.closed? || @parser.broken?
+        data = @transport.read
+        break if data.nil?
+
+        @parser << data
+      end
+    rescue ConnectionClosedError, TimeoutError => e
+      record_error(e) unless @status == :closed
+    rescue StandardError => e
+      record_error(e)
+    ensure
+      @pongs.close unless @pongs.closed?
+    end
+
+    def next_sid
+      @lock.synchronize { (@sid_counter += 1).to_s }
+    end
+
+    def check_payload_size!(subject, frame)
+      limit = max_payload
+      return unless limit && frame.bytesize > limit
+
+      raise MaxPayloadError, "payload for #{subject} exceeds the server's max_payload of #{limit}"
+    end
+
+    def report_slow_consumer(subscription)
+      record_error(SlowConsumerError.new("dropped a message on #{subscription.subject}"))
+    end
+
+    def record_error(error)
+      @last_error = error
+      @error_handlers.each { |handler| handler.call(error) }
+    rescue StandardError
+      nil
+    end
+
+    def ensure_connected!
+      raise ConnectionClosedError, "connection is closed" if @status == :closed
+      raise ConnectionError, "not connected" unless @status == :connected
+    end
+  end
+end

data/lib/tether/deadline.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Tether
+  # An absolute point in time on the monotonic clock, threaded through every
+  # blocking call in tether instead of a bare number of seconds.
+  #
+  # A Deadline is only ever consumed by primitives that interrupt themselves
+  # (`Queue#pop(timeout:)`, `IO#timeout=`, `ConditionVariable#wait`). It is never
+  # handed to `Timeout.timeout`, which raises at an arbitrary bytecode boundary
+  # and can leave a half-written frame on the wire or a mutex locked forever.
+  class Deadline
+    # A deadline that never expires.
+    NONE = nil
+
+    # @return [Float, nil] the monotonic instant this deadline expires at, or nil if it never does
+    attr_reader :at
+
+    # Builds a deadline that expires after a duration from now.
+    #
+    # @param seconds [Numeric, nil] duration in seconds, or nil for a deadline that never expires
+    # @return [Deadline]
+    def self.after(seconds)
+      new(seconds.nil? ? nil : now + seconds)
+    end
+
+    # Builds a deadline that never expires.
+    #
+    # @return [Deadline]
+    def self.infinite
+      new(nil)
+    end
+
+    # Accepts whatever a caller passed for a timeout and returns a Deadline.
+    #
+    # @param value [Deadline, Numeric, nil]
+    # @return [Deadline]
+    def self.coerce(value)
+      return value if value.is_a?(self)
+
+      after(value)
+    end
+
+    # Reads the monotonic clock, which never jumps backwards when the system
+    # clock is adjusted.
+    #
+    # @return [Float] the current monotonic clock reading
+    def self.now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # Wraps an absolute monotonic instant. Prefer {.after}, which takes a
+    # duration.
+    #
+    # @param at [Float, nil] a monotonic instant, or nil for a deadline that never expires
+    def initialize(at)
+      @at = at
+      freeze
+    end
+
+    # An infinite deadline reports nil remaining, which every blocking
+    # primitive in Ruby already reads as "wait forever".
+    #
+    # @return [Boolean] whether this deadline can never expire
+    def infinite?
+      @at.nil?
+    end
+
+    # Seconds left before expiry, clamped at zero.
+    #
+    # Returns nil for an infinite deadline, which is what every blocking
+    # primitive in Ruby already interprets as "wait forever".
+    #
+    # @return [Float, nil]
+    def remaining
+      return nil if infinite?
+
+      left = @at - self.class.now
+      left.negative? ? 0.0 : left
+    end
+
+    # @return [Boolean] whether the instant has passed; always false when infinite
+    def expired?
+      return false if infinite?
+
+      @at <= self.class.now
+    end
+
+    # Raises if this deadline has already expired.
+    #
+    # @param subject [String, nil] included in the error message for context
+    # @raise [TimeoutError]
+    # @return [void]
+    def check!(subject = nil)
+      return unless expired?
+
+      raise TimeoutError, subject ? "deadline expired: #{subject}" : "deadline expired"
+    end
+
+    # Narrows this deadline, never widens it.
+    #
+    # @param seconds [Numeric, nil]
+    # @return [Deadline] the earlier of this deadline and now + seconds
+    def with_at_most(seconds)
+      return self if seconds.nil?
+
+      candidate = self.class.now + seconds
+      infinite? || candidate < @at ? self.class.new(candidate) : self
+    end
+
+    # Returns the earlier of two deadlines.
+    #
+    # @param other [Deadline]
+    # @return [Deadline]
+    def earliest(other)
+      return other if infinite?
+      return self if other.infinite?
+
+      other.at < @at ? other : self
+    end
+
+    # @return [String] shows time remaining rather than the absolute instant,
+    #   which is meaningless out of context
+    def inspect
+      infinite? ? "#<Tether::Deadline infinite>" : format("#<Tether::Deadline remaining=%.3fs>", remaining)
+    end
+  end
+end

data/lib/tether/dispatcher.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Tether
+  # Routes parsed frames to subscriptions and to connection level handlers.
+  #
+  # This is the parser's sink. It knows nothing about sockets or reconnection,
+  # so the parser stays testable without a client.
+  class Dispatcher
+    # Wires up the connection level events the parser will report.
+    #
+    # @param handlers [Hash{Symbol => Proc}] :ping, :pong, :info, :error, :protocol_error
+    def initialize(**handlers)
+      @handlers = handlers
+      @subscriptions = {}
+      @lock = Mutex.new
+    end
+
+    # Registers a subscription so messages carrying its sid reach it.
+    #
+    # @param subscription [Subscription]
+    # @return [Subscription]
+    def add(subscription)
+      @lock.synchronize { @subscriptions[subscription.sid] = subscription }
+      subscription
+    end
+
+    # Stops routing to a subscription. Messages already in flight for it are
+    # dropped when they arrive.
+    #
+    # @param sid [String]
+    # @return [Subscription, nil] the subscription that was registered, if any
+    def remove(sid)
+      @lock.synchronize { @subscriptions.delete(sid) }
+    end
+
+    # Looks up a subscription by the token the server echoed back.
+    #
+    # @param sid [String]
+    # @return [Subscription, nil] nil once the subscription has been removed
+    def [](sid)
+      @lock.synchronize { @subscriptions[sid] }
+    end
+
+    # @return [Array<Subscription>] a snapshot, safe to iterate while others subscribe
+    def subscriptions
+      @lock.synchronize { @subscriptions.values }
+    end
+
+    # @return [Integer] how many subscriptions are registered
+    def size
+      @lock.synchronize { @subscriptions.size }
+    end
+
+    # Closes every subscription and empties the registry.
+    #
+    # @return [void]
+    def clear
+      @lock.synchronize { @subscriptions.values.tap { @subscriptions.clear } }.each(&:close)
+    end
+
+    # Routes a message to its subscription, on the reader thread.
+    #
+    # A message whose sid is unknown, because the subscription was cancelled
+    # while it was in flight, is dropped rather than raised over.
+    #
+    # @return [void]
+    def on_msg(subject, sid, reply_to, header_bytes, payload)
+      subscription = self[sid] or return
+
+      subscription.deliver(
+        Msg.new(subject: subject, data: payload, reply_to: reply_to,
+                header_bytes: header_bytes, subscription: subscription)
+      )
+      nil
+    end
+
+    # The connection must answer promptly or the server drops it as stale.
+    #
+    # @return [void]
+    def on_ping = @handlers[:ping]&.call
+
+    # Completes a {Client#flush}.
+    #
+    # @return [void]
+    def on_pong = @handlers[:pong]&.call
+
+    # Ignored: tether turns off verbose mode, so the server sends these only if
+    # a caller asked for them explicitly.
+    #
+    # @return [void]
+    def on_ok = nil
+
+    # Arrives once at connect and again whenever cluster topology changes.
+    #
+    # @return [void]
+    def on_info(json) = @handlers[:info]&.call(json)
+
+    # An `-ERR` line, which may or may not be followed by the server closing
+    # the connection. See {ServerError.fatal?}.
+    #
+    # @return [void]
+    def on_error(description) = @handlers[:error]&.call(description)
+
+    # The parser gave up on the stream; the connection is no longer usable.
+    #
+    # @return [void]
+    def on_protocol_error(message) = @handlers[:protocol_error]&.call(message)
+  end
+end