tether 0.1.0

data/lib/tether/errors.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module Tether
+  # Base class for every error raised by tether.
+  class Error < StandardError; end
+
+  # Raised when the server sends bytes that violate the client protocol.
+  class ProtocolError < Error; end
+
+  # Raised when a {Deadline} expires before an operation completes.
+  class TimeoutError < Error; end
+
+  # Raised when a request reaches a subject that has no subscribers.
+  class NoRespondersError < Error; end
+
+  # Raised when a payload exceeds the server's advertised max_payload.
+  class MaxPayloadError < Error; end
+
+  # Raised when a subscription's pending queue overflows.
+  class SlowConsumerError < Error; end
+
+  # Raised when a subject or queue group is not a valid NATS token sequence.
+  class InvalidSubjectError < Error; end
+
+  # Base class for errors about the state of the connection itself.
+  class ConnectionError < Error; end
+
+  # Raised when an operation is attempted on a closed connection.
+  class ConnectionClosedError < ConnectionError; end
+
+  # Raised when an operation is attempted on a connection that is draining.
+  class ConnectionDrainingError < ConnectionError; end
+
+  # Raised when an operation cannot be served while reconnecting.
+  class ConnectionReconnectingError < ConnectionError; end
+
+  # Raised when no server in the pool could be reached.
+  class NoServersError < ConnectionError; end
+
+  # An `-ERR` line received from the server.
+  #
+  # Every entry below is taken from the nats-server source (v2.14) rather than
+  # from documentation. The server writes `-ERR '<description>'` from exactly
+  # three places (`sendErr`, and two raw writes for a stale connection), and its
+  # casing is inconsistent — `Authorization Violation` is title case while
+  # `maximum control line exceeded` is not — so lookup is case insensitive.
+  # Several descriptions embed context (`Permissions Violation for Publish to
+  # "orders.new"`), so lookup is by substring, ordered specific first.
+  class ServerError < Error
+    MAPPING = {
+      "permissions violation" => :PermissionsViolationError,
+      "authorization violation" => :AuthorizationError,
+      "authentication expired" => :AuthenticationExpiredError,
+      "authentication revoked" => :AuthenticationRevokedError,
+      "authentication timeout" => :AuthenticationTimeoutError,
+      "stale connection" => :StaleConnectionError,
+      "maximum account active connections exceeded" => :MaxAccountConnectionsError,
+      "maximum connections exceeded" => :MaxConnectionsError,
+      "maximum subscriptions exceeded" => :MaxSubscriptionsError,
+      "maximum payload violation" => :MaxPayloadViolationError,
+      "maximum control line exceeded" => :MaxControlLineError,
+      "invalid publish subject" => :InvalidPublishSubjectError,
+      "invalid subject" => :ServerInvalidSubjectError,
+      "failed account registration" => :FailedAccountRegistrationError,
+      "no responders requires headers support" => :NoRespondersRequiresHeadersError,
+      "connection throttling is active" => :ConnectionThrottledError,
+      "secure connection - tls required" => :TLSRequiredError,
+      "invalid client protocol" => :InvalidClientProtocolError,
+      "unknown protocol operation" => :UnknownProtocolError,
+      "attempted to connect to route port" => :WrongPortError,
+      "attempted to connect to leaf node port" => :WrongPortError,
+      "attempted to connect to gateway port" => :WrongPortError
+    }.freeze
+
+    # Builds the most specific {ServerError} subclass for an `-ERR` description.
+    #
+    # @param description [String] the text between the quotes of an `-ERR` line
+    # @return [ServerError]
+    def self.for(description)
+      normalized = description.to_s.downcase
+      name = MAPPING[normalized] || MAPPING.find { |text, _| normalized.include?(text) }&.last
+      klass = name ? Tether.const_get(name) : self
+      klass.new(description)
+    end
+
+    # Whether the server is expected to close the connection after this error.
+    #
+    # Advisory only, and never a substitute for the connection state itself.
+    # The server sends `maximum subscriptions exceeded` from two paths that are
+    # indistinguishable on the wire: one leaves the connection up, the other
+    # closes it 20ms later. Reconnect must therefore be driven by the socket
+    # reaching EOF; this predicate only says whether to expect that.
+    #
+    # @return [Boolean]
+    def self.fatal?
+      true
+    end
+
+    # @return [Boolean] whether the server is expected to close the connection
+    #   after this error; see {ServerError.fatal?} for why it is advisory
+    def fatal?
+      self.class.fatal?
+    end
+  end
+
+  # Raised when the account presented at connect time is not authorized.
+  class AuthorizationError < ServerError; end
+
+  # Raised when the credentials presented at connect time have expired.
+  # Covers both the user scoped and account scoped descriptions.
+  class AuthenticationExpiredError < ServerError; end
+
+  # Raised when the credentials presented at connect time have been revoked.
+  # Distinct from expiry: retrying with the same credentials cannot succeed.
+  class AuthenticationRevokedError < ServerError; end
+
+  # Raised when the server times out waiting for authentication.
+  class AuthenticationTimeoutError < ServerError; end
+
+  # Raised when the server drops a connection that stopped answering PING.
+  class StaleConnectionError < ServerError; end
+
+  # Raised when the server's global connection limit is reached.
+  class MaxConnectionsError < ServerError; end
+
+  # Raised when the account's active connection limit is reached.
+  class MaxAccountConnectionsError < ServerError; end
+
+  # Raised when the server rejects a payload larger than max_payload.
+  class MaxPayloadViolationError < ServerError; end
+
+  # Raised when a control line exceeds the server's limit.
+  class MaxControlLineError < ServerError; end
+
+  # Raised when CONNECT asks for no_responders without headers support.
+  class NoRespondersRequiresHeadersError < ServerError; end
+
+  # Raised when the server is shedding load and the client should back off.
+  class ConnectionThrottledError < ServerError; end
+
+  # Raised when the server requires TLS and the client did not upgrade.
+  class TLSRequiredError < ServerError; end
+
+  # Raised when the CONNECT payload is rejected by the server.
+  class InvalidClientProtocolError < ServerError; end
+
+  # Raised when the server cannot parse a command the client sent.
+  class UnknownProtocolError < ServerError; end
+
+  # Raised when the client connected to a route, leafnode, or gateway port
+  # instead of the client port. Reconnecting cannot help.
+  class WrongPortError < ServerError; end
+
+  # Raised when a subscription names a subject the server rejects.
+  # The server does not close the connection for this error: its parser
+  # deliberately swallows the error so a bad subject is not a parse failure.
+  class ServerInvalidSubjectError < ServerError
+    # @return [Boolean] false: the server's parser deliberately swallows this so a bad
+    #   subject is not treated as a parse failure
+    def self.fatal?
+      false
+    end
+  end
+
+  # Raised when a publish names a malformed subject, in pedantic mode.
+  # The server does not close the connection for this error.
+  class InvalidPublishSubjectError < ServerError
+    # @return [Boolean] false: the server returns without closing
+    def self.fatal?
+      false
+    end
+  end
+
+  # Raised when the server fails to register the connection's account.
+  # The server does not close the connection for this error.
+  class FailedAccountRegistrationError < ServerError
+    # @return [Boolean] false: the server reports it and carries on
+    def self.fatal?
+      false
+    end
+  end
+
+  # Raised when the subscription limit is reached.
+  #
+  # Reported as non fatal because the ordinary over-limit SUB leaves the
+  # connection usable, but the account limit path sends the same text and then
+  # closes. See {ServerError.fatal?}.
+  class MaxSubscriptionsError < ServerError
+    # @return [Boolean] false for the ordinary over-limit SUB, but see {ServerError.fatal?}:
+    #   the account limit path sends the same text and then closes
+    def self.fatal?
+      false
+    end
+  end
+
+  # Raised when publishing to or subscribing to a subject the user cannot access.
+  # The server does not close the connection for any of its seven variants.
+  class PermissionsViolationError < ServerError
+    # @return [Boolean] false for all seven variants the server can send
+    def self.fatal?
+      false
+    end
+  end
+end

data/lib/tether/headers.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+module Tether
+  # NATS message headers, plus the optional status and description that the
+  # server encodes on the version line (`NATS/1.0 503`).
+  #
+  # Keys are case sensitive and used exactly as given: JetStream relies on
+  # literal names such as `Nats-Msg-Id` and `Nats-Expected-Last-Sequence`.
+  # A key may carry several values, as in Go's `nats.Header`.
+  class Headers
+    VERSION = "NATS/1.0"
+    CRLF = "\r\n"
+
+    # Status codes the server puts on the version line. Taken from the
+    # nats-server source rather than from HTTP: the numbers overlap with HTTP
+    # but the meanings are the server's own.
+    CONTROL = 100
+    NO_CONTENT = 204
+    BAD_REQUEST = 400
+    NOT_FOUND = 404
+    REQUEST_TIMEOUT = 408
+    CONFLICT = 409
+    REQUIRED_API_LEVEL = 412
+    TOO_MANY_RESULTS = 413
+    PIN_ID_MISMATCH = 423
+    TOO_MANY_REQUESTS = 429
+    INTERNAL_ERROR = 500
+    NO_RESPONDERS = 503
+
+    # A header name is an RFC 7230 token. A value may not contain CR or LF:
+    # the server does not validate the block it forwards, so an unescaped CRLF
+    # in a value forges a header line that its own lookup will honor.
+    TOKEN = /\A[!#$%&'*+\-.^_`|~0-9A-Za-z]+\z/
+    FORBIDDEN_IN_VALUE = /[\r\n]/
+    private_constant :CRLF, :TOKEN, :FORBIDDEN_IN_VALUE
+
+    # @return [Integer, nil] status code from the version line
+    attr_reader :status
+
+    # @return [String, nil] status description from the version line
+    attr_reader :description
+
+    # Parses a header block as it appears on the wire, including the trailing
+    # blank line.
+    #
+    # @param bytes [String] the header section of an HMSG or HPUB frame
+    # @return [Headers]
+    # @raise [ProtocolError] if the version line is missing or malformed
+    def self.parse(bytes)
+      lines = bytes.to_s.split(CRLF, -1)
+      version = lines.shift.to_s
+      raise ProtocolError, "invalid header version line: #{version.inspect}" unless version.start_with?(VERSION)
+
+      status, description = parse_version_line(version)
+      headers = new(status: status, description: description)
+      lines.each do |line|
+        next if line.empty?
+
+        key, _, value = line.partition(":")
+        raise ProtocolError, "invalid header line: #{line.inspect}" if value.empty? && !line.include?(":")
+
+        headers.add(key.strip, value.strip)
+      end
+      headers
+    end
+
+    # @return [Array(Integer, nil), Array(nil, nil)]
+    def self.parse_version_line(version)
+      remainder = version[VERSION.length..].to_s.strip
+      return [nil, nil] if remainder.empty?
+
+      code, _, text = remainder.partition(" ")
+      [Integer(code, exception: false), text.strip.empty? ? nil : text.strip]
+    end
+    private_class_method :parse_version_line
+
+    # Builds headers from a hash, so the common case needs no braces.
+    #
+    # @param entries [Hash{String => String, Array<String>}]
+    # @return [Headers]
+    def self.[](entries)
+      new(entries: entries)
+    end
+
+    # Builds a header set. Prefer {.[]} for the common case of a plain hash.
+    #
+    # @param entries [Hash{String => String, Array<String>}] initial headers
+    # @param status [Integer, nil]
+    # @param description [String, nil]
+    # @raise [ArgumentError] if a key is not a token or a value spans lines
+    def initialize(entries: {}, status: nil, description: nil)
+      @entries = {}
+      @status = status
+      @description = description && validate_value(description)
+      entries.each { |key, value| Array(value).each { |item| add(key.to_s, item.to_s) } }
+    end
+
+    # @param key [String]
+    # @return [String, nil] the first value for the key
+    def [](key)
+      @entries[key]&.first
+    end
+
+    # Replaces every value for a key.
+    #
+    # @param key [String]
+    # @param value [String]
+    # @return [String]
+    # @raise [ArgumentError] if the key is not a token or the value spans lines
+    def []=(key, value)
+      @entries[validate_key(key)] = [validate_value(value)]
+      value
+    end
+
+    # Appends a value, keeping any already present for the key.
+    #
+    # Repeated keys are legal on the wire, but every server side lookup stops at
+    # the first match, so a second value for a `Nats-` header is silently
+    # ignored by the server rather than merged.
+    #
+    # @param key [String]
+    # @param value [String]
+    # @return [self]
+    # @raise [ArgumentError] if the key is not a token or the value spans lines
+    def add(key, value)
+      (@entries[validate_key(key)] ||= []) << validate_value(value)
+      self
+    end
+
+    # Every value for a key. Note the server reads only the first: repeated
+    # keys are legal on the wire but its lookups stop at the first match.
+    #
+    # @param key [String]
+    # @return [Array<String>]
+    def values(key)
+      @entries.fetch(key, []).dup
+    end
+
+    # Removes a key and all of its values.
+    #
+    # @param key [String]
+    # @return [Array<String>, nil] the removed values
+    def delete(key)
+      @entries.delete(key)
+    end
+
+    # Matched exactly, including case.
+    #
+    # @param key [String]
+    # @return [Boolean]
+    def key?(key)
+      @entries.key?(key)
+    end
+
+    # Yields each key once per value, so a repeated key is yielded repeatedly,
+    # which is how it is written to the wire.
+    #
+    # @yieldparam key [String]
+    # @yieldparam value [String]
+    # @return [Enumerator, self]
+    def each(&block)
+      return to_enum(:each) unless block
+
+      @entries.each { |key, values| values.each { |value| block.call(key, value) } }
+      self
+    end
+
+    # @return [Array<String>] each key once, however many values it carries
+    def keys
+      @entries.keys
+    end
+
+    # A frame can carry a status with no headers at all, so this is not the
+    # same as having no header block.
+    #
+    # @return [Boolean] whether there are no headers, status, or description
+    def empty?
+      @entries.empty? && @status.nil? && @description.nil?
+    end
+
+    # Sent by the server only when the client asked for it in CONNECT.
+    #
+    # @return [Boolean] whether the server reported that nobody is listening
+    def no_responders?
+      @status == NO_RESPONDERS
+    end
+
+    # Whether this is a JetStream control frame of either kind.
+    #
+    # @return [Boolean]
+    def control?
+      @status == CONTROL
+    end
+
+    # An idle heartbeat carries no reply subject and must not be answered,
+    # unless it carries `Nats-Consumer-Stalled`, whose value is a subject to
+    # publish to. Distinguished from flow control by description, not by code,
+    # because both are status 100.
+    #
+    # @return [Boolean]
+    def idle_heartbeat?
+      control? && @description.to_s.start_with?("Idle")
+    end
+
+    # A flow control request carries a reply subject and the consumer stalls
+    # until the client publishes to it.
+    #
+    # @return [Boolean]
+    def flow_control?
+      control? && @description.to_s.start_with?("Flow")
+    end
+
+    # @return [Hash{String => Array<String>}] a copy; mutating it does not affect these headers
+    def to_h
+      @entries.transform_values(&:dup)
+    end
+
+    # Encodes the header block for the wire, including the trailing blank line.
+    #
+    # @return [String] binary encoded header section
+    def to_wire
+      out = "#{VERSION}#{status_suffix}#{CRLF}"
+      each { |key, value| out << key << ": " << value << CRLF }
+      out << CRLF
+      out.force_encoding(Encoding::BINARY)
+    end
+
+    # @return [String] shows the status alongside the headers, since a status
+    #   only frame has no entries at all
+    def inspect
+      "#<Tether::Headers status=#{@status.inspect} #{to_h.inspect}>"
+    end
+
+    private
+
+    def validate_key(key)
+      key = key.to_s
+      raise ArgumentError, "invalid header name: #{key.inspect}" unless key.match?(TOKEN)
+
+      key
+    end
+
+    def validate_value(value)
+      value = value.to_s
+      raise ArgumentError, "header value may not span lines: #{value.inspect}" if value.match?(FORBIDDEN_IN_VALUE)
+
+      value
+    end
+
+    def status_suffix
+      return "" if @status.nil?
+
+      @description ? " #{@status} #{@description}" : " #{@status}"
+    end
+  end
+end

data/lib/tether/inbox_mux.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Tether
+  # Request/reply over a single wildcard inbox subscription.
+  #
+  # A new SUB/UNSUB pair per request would make every request a round trip to
+  # the server before the payload even goes out. Instead one subscription on
+  # `_INBOX.<nuid>.*` covers the whole connection and replies are demultiplexed
+  # in memory by the last subject token.
+  class InboxMux
+    INBOX_PREFIX = "_INBOX"
+
+    # @return [String] the subject prefix this connection's replies arrive on
+    attr_reader :prefix
+
+    # Builds the mux without subscribing; {#start} runs on the first request.
+    #
+    # @param client [Client]
+    # @param prefix [String, nil] defaults to a fresh `_INBOX.<nuid>`
+    # @param max_pending [Integer] queue depth for the shared inbox subscription
+    def initialize(client, prefix: nil, max_pending: Subscription::DEFAULT_MAX_PENDING)
+      @client = client
+      @prefix = prefix || "#{INBOX_PREFIX}.#{NUID.next}"
+      @max_pending = max_pending
+      @pending = {}
+      @lock = Mutex.new
+      @counter = 0
+    end
+
+    # Publishes a request and waits for the first reply.
+    #
+    # @param subject [String]
+    # @param payload [String, nil]
+    # @param deadline [Deadline]
+    # @param headers [Headers, nil]
+    # @return [Msg]
+    # @raise [NoRespondersError] if the server reports nobody is subscribed
+    # @raise [TimeoutError] if the deadline passes first
+    def request(subject, payload = nil, deadline: Deadline.infinite, headers: nil)
+      start
+      token = next_token
+      waiter = Thread::Queue.new
+      @lock.synchronize { @pending[token] = waiter }
+
+      @client.publish(subject, payload, reply_to: "#{@prefix}.#{token}", headers: headers)
+      await(waiter, subject, deadline)
+    ensure
+      @lock.synchronize { @pending.delete(token) } if token
+    end
+
+    # Subscribes the shared inbox, once.
+    #
+    # @return [Subscription]
+    def start
+      @lock.synchronize do
+        return @subscription if @subscription
+
+        @subscription = @client.subscribe("#{@prefix}.*", max_pending: @max_pending) { |msg| resolve(msg) }
+      end
+    end
+
+    # The inbox is subscribed lazily, on the first request, so a connection
+    # that never makes one costs nothing.
+    #
+    # @return [Boolean] whether the shared inbox subscription exists yet
+    def started?
+      @lock.synchronize { !@subscription.nil? }
+    end
+
+    # Should return to zero once requests settle; a number that only grows is
+    # a leak.
+    #
+    # @return [Integer] requests currently waiting for a reply
+    def pending
+      @lock.synchronize { @pending.size }
+    end
+
+    # Releases every waiting request, so callers blocked in {#request} raise
+    # rather than waiting out their deadlines.
+    #
+    # @return [void]
+    def close
+      waiters = @lock.synchronize { @pending.values.tap { @pending.clear } }
+      waiters.each(&:close)
+      nil
+    end
+
+    private
+
+    def await(waiter, subject, deadline)
+      msg = waiter.pop(timeout: deadline.remaining)
+      raise ConnectionClosedError, "connection closed while waiting on #{subject}" if msg.nil? && waiter.closed?
+      raise TimeoutError, "no reply to #{subject} within the deadline" if msg.nil?
+      raise NoRespondersError, "no responders for #{subject}" if msg.no_responders?
+
+      msg
+    end
+
+    # Runs on the inbox subscription's worker. A reply whose token has already
+    # timed out finds no waiter and is dropped rather than raising.
+    def resolve(msg)
+      token = msg.subject[(@prefix.length + 1)..]
+      waiter = @lock.synchronize { @pending[token] }
+      waiter&.push(msg)
+    rescue ClosedQueueError
+      nil
+    end
+
+    def next_token
+      @lock.synchronize { (@counter += 1).to_s(36) }
+    end
+  end
+end

data/lib/tether/msg.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Tether
+  # A message delivered to a subscription or returned from a request.
+  #
+  # Headers are parsed on first use, on whichever thread touches them, so the
+  # reader thread never pays for a header block it may not need.
+  class Msg
+    # @return [String]
+    attr_reader :subject
+
+    # @return [String] the payload, always binary
+    attr_reader :data
+
+    # @return [String, nil] the subject a reply should be published to
+    attr_reader :reply_to
+
+    # @return [Subscription, nil]
+    attr_reader :subscription
+
+    # Built by the dispatcher on the reader thread, so it does no work beyond
+    # holding references.
+    #
+    # @param subject [String]
+    # @param data [String]
+    # @param reply_to [String, nil]
+    # @param header_bytes [String, nil] the unparsed header block
+    # @param subscription [Subscription, nil]
+    def initialize(subject:, data:, reply_to: nil, header_bytes: nil, subscription: nil)
+      @subject = subject
+      @data = data
+      @reply_to = reply_to
+      @header_bytes = header_bytes
+      @subscription = subscription
+    end
+
+    # Parses the header block on first use, on whichever thread asks for it.
+    #
+    # @return [Headers, nil] nil when the message arrived without a header block
+    # @raise [ProtocolError] if the block is malformed
+    def headers
+      return @headers if defined?(@headers)
+
+      @headers = @header_bytes && Headers.parse(@header_bytes)
+    end
+
+    # JetStream and no-responders both report through this rather than `-ERR`.
+    #
+    # @return [Integer, nil] the status the server put on the header line
+    def status
+      headers&.status
+    end
+
+    # True on the empty 503 the server sends back when a request reaches a
+    # subject with no subscribers.
+    #
+    # @return [Boolean] whether the server reported that nobody is listening
+    def no_responders?
+      headers&.no_responders? || false
+    end
+
+    # Publishes back to this message's reply subject.
+    #
+    # @param payload [String, nil]
+    # @param headers [Headers, nil]
+    # @return [void]
+    # @raise [Error] if the message carries no reply subject
+    def respond(payload = nil, headers: nil)
+      raise Error, "message on #{@subject} has no reply subject" unless @reply_to
+
+      responder = @subscription&.responder
+      raise Error, "message on #{@subject} is not attached to a connection" unless responder
+
+      responder.publish(@reply_to, payload, headers: headers)
+    end
+
+    # Status only frames, such as a heartbeat or a 503, carry no payload.
+    #
+    # @return [Boolean] whether this carries no payload
+    def empty?
+      @data.nil? || @data.empty?
+    end
+
+    # @return [String] reports the payload's size rather than its bytes, which
+    #   may be binary and large
+    def inspect
+      "#<Tether::Msg subject=#{@subject.inspect} reply_to=#{@reply_to.inspect} bytes=#{@data.bytesize}>"
+    end
+  end
+end