tether 0.1.0

data/lib/tether/transport.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "socket"
+require "uri"
+
+module Tether
+  # The socket a connection reads and writes.
+  #
+  # Deadlines are applied with `IO#timeout=`, which raises `IO::TimeoutError` at
+  # the point the operating system reports the socket is not ready, rather than
+  # at an arbitrary bytecode boundary the way `Timeout.timeout` would.
+  class Transport
+    DEFAULT_PORT = 4222
+    READ_SIZE = 64 * 1024
+
+    # @return [URI::Generic] the server this transport is connected to
+    attr_reader :uri
+
+    # Opens a TCP connection.
+    #
+    # @param uri [String, URI::Generic]
+    # @param deadline [Deadline] bounds the connect and every later read
+    # @return [Transport]
+    # @raise [ConnectionError] if the server cannot be reached
+    def self.connect(uri, deadline: Deadline.infinite)
+      new(uri).tap { _1.open(deadline) }
+    end
+
+    # Prepares a transport without opening it.
+    #
+    # @param uri [String, URI::Generic] a bare host:port is treated as nats://
+    def initialize(uri)
+      @uri = normalize(uri)
+      @lock = Mutex.new
+    end
+
+    # Opens the socket with TCP_NODELAY set, since the protocol is latency
+    # sensitive and frames are already written whole.
+    #
+    # @param deadline [Deadline]
+    # @return [self]
+    # @raise [ConnectionError]
+    def open(deadline = Deadline.infinite)
+      @socket = Socket.tcp(@uri.host, @uri.port, connect_timeout: deadline.remaining)
+      @socket.sync = true
+      @socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, true)
+      self
+    rescue SystemCallError, IO::TimeoutError => e
+      raise ConnectionError, "could not connect to #{@uri}: #{e.message}"
+    end
+
+    # Reads whatever is available.
+    #
+    # @param deadline [Deadline]
+    # @return [String, nil] bytes, or nil at end of stream
+    # @raise [TimeoutError] if the deadline passes with nothing readable
+    def read(deadline = Deadline.infinite)
+      socket = @socket or raise ConnectionClosedError, "transport is closed"
+      socket.timeout = deadline.remaining
+      socket.readpartial(READ_SIZE)
+    rescue EOFError
+      nil
+    rescue IO::TimeoutError
+      raise TimeoutError, "timed out reading from #{@uri}"
+    rescue IOError, SystemCallError => e
+      raise ConnectionClosedError, "read failed on #{@uri}: #{e.message}"
+    end
+
+    # Writes one complete frame.
+    #
+    # The lock spans the whole frame rather than each write, so frames from
+    # different threads cannot interleave on the wire.
+    #
+    # @param frame [String] a complete, already encoded frame
+    # @return [Integer] bytes written
+    def write(frame)
+      @lock.synchronize do
+        socket = @socket or raise ConnectionClosedError, "transport is closed"
+        socket.write(frame)
+      end
+    rescue IOError, SystemCallError => e
+      raise ConnectionClosedError, "write failed on #{@uri}: #{e.message}"
+    end
+
+    # Closes the socket, which also unblocks a read waiting on it.
+    #
+    # @return [void]
+    def close
+      @lock.synchronize do
+        @socket&.close
+        @socket = nil
+      end
+    rescue IOError, SystemCallError
+      @socket = nil
+    end
+
+    # @return [Boolean] whether the socket is gone; every read and write raises after this
+    def closed?
+      @socket.nil? || @socket.closed?
+    end
+
+    private
+
+    def normalize(uri)
+      parsed = uri.is_a?(URI::Generic) ? uri : URI.parse(coerce_scheme(uri.to_s))
+      parsed.port ||= DEFAULT_PORT
+      parsed
+    end
+
+    def coerce_scheme(value)
+      value.include?("://") ? value : "nats://#{value}"
+    end
+  end
+end

data/lib/tether/version.rb

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

data/lib/tether.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "tether/version"
+require_relative "tether/errors"
+require_relative "tether/deadline"
+require_relative "tether/nuid"
+require_relative "tether/headers"
+require_relative "tether/protocol"
+require_relative "tether/protocol/encoder"
+require_relative "tether/protocol/parser"
+require_relative "tether/msg"
+require_relative "tether/transport"
+require_relative "tether/subscription"
+require_relative "tether/dispatcher"
+require_relative "tether/inbox_mux"
+require_relative "tether/client"
+
+# A NATS client for Ruby.
+module Tether
+  # Connects to a NATS server.
+  #
+  # @param uri [String, nil] defaults to NATS_URL, then nats://127.0.0.1:4222
+  # @param options [Hash{Symbol => Object}] CONNECT overrides plus :connect_timeout
+  # @return [Client, Object] the client, or the block's value when a block is given
+  def self.connect(uri = nil, **options, &)
+    Client.connect(uri, **options, &)
+  end
+end

data/sig/tether/client.rbs

@@ -0,0 +1,45 @@
+module Tether
+  def self.connect: (?String? uri, **untyped options) ?{ (Client) -> untyped } -> untyped
+
+  class Client
+    DEFAULT_URI: String
+    DEFAULT_CONNECT_TIMEOUT: Integer
+    DEFAULT_FLUSH_TIMEOUT: Integer
+    DEFAULT_REQUEST_TIMEOUT: Integer
+
+    attr_reader server_info: Hash[String, untyped]?
+    attr_reader status: Symbol
+    attr_reader last_error: Exception?
+
+    def self.connect: (?String? uri, **untyped options) ?{ (Client) -> untyped } -> untyped
+
+    def initialize: (?String? uri, **untyped options) -> void
+    def connect: (?timeout: Numeric?) -> self
+    def publish: (String subject, ?String? payload, ?reply_to: String?, ?headers: Headers?) -> void
+    def subscribe: (String subject, ?queue: String?, ?max_pending: Integer) ?{ (Msg) -> void } -> Subscription
+    def unsubscribe: (Subscription subscription, ?Integer? max_msgs) -> void
+    def request: (String subject, ?String? payload, ?timeout: Numeric?, ?headers: Headers?) -> Msg
+    def new_inbox: () -> String
+    def flush: (?timeout: Numeric?) -> bool
+    def close: () -> void
+    def connected?: () -> bool
+    def closed?: () -> bool
+    def on_error: () { (Exception) -> void } -> void
+    def subscription_count: () -> Integer
+    def max_payload: () -> Integer?
+
+    private
+
+    def inbox_mux: () -> InboxMux
+    def build_dispatcher: () -> Dispatcher
+    def read_server_info: (Deadline deadline) -> void
+    def connect_options: () -> Hash[Symbol, untyped]
+    def start_reader: () -> Thread
+    def read_loop: () -> void
+    def next_sid: () -> String
+    def check_payload_size!: (String subject, String frame) -> void
+    def report_slow_consumer: (Subscription subscription) -> void
+    def record_error: (Exception error) -> void
+    def ensure_connected!: () -> void
+  end
+end

data/sig/tether/deadline.rbs

@@ -0,0 +1,21 @@
+module Tether
+  class Deadline
+    NONE: nil
+
+    attr_reader at: Float?
+
+    def self.after: (Numeric? seconds) -> Deadline
+    def self.infinite: () -> Deadline
+    def self.coerce: (Deadline | Numeric | nil value) -> Deadline
+    def self.now: () -> Float
+
+    def initialize: (Float? at) -> void
+    def infinite?: () -> bool
+    def remaining: () -> Float?
+    def expired?: () -> bool
+    def check!: (?String? subject) -> void
+    def with_at_most: (Numeric? seconds) -> Deadline
+    def earliest: (Deadline other) -> Deadline
+    def inspect: () -> String
+  end
+end

data/sig/tether/dispatcher.rbs

@@ -0,0 +1,19 @@
+module Tether
+  class Dispatcher
+    def initialize: (**^(*untyped) -> void handlers) -> void
+    def add: (Subscription subscription) -> Subscription
+    def remove: (String sid) -> Subscription?
+    def []: (String sid) -> Subscription?
+    def subscriptions: () -> Array[Subscription]
+    def size: () -> Integer
+    def clear: () -> void
+
+    def on_msg: (String subject, String sid, String? reply_to, String? header_bytes, String payload) -> void
+    def on_ping: () -> void
+    def on_pong: () -> void
+    def on_ok: () -> void
+    def on_info: (String json) -> void
+    def on_error: (String description) -> void
+    def on_protocol_error: (String message) -> void
+  end
+end

data/sig/tether/errors.rbs

@@ -0,0 +1,110 @@
+module Tether
+  class Error < StandardError
+  end
+
+  class ProtocolError < Error
+  end
+
+  class TimeoutError < Error
+  end
+
+  class NoRespondersError < Error
+  end
+
+  class MaxPayloadError < Error
+  end
+
+  class SlowConsumerError < Error
+  end
+
+  class InvalidSubjectError < Error
+  end
+
+  class ConnectionError < Error
+  end
+
+  class ConnectionClosedError < ConnectionError
+  end
+
+  class ConnectionDrainingError < ConnectionError
+  end
+
+  class ConnectionReconnectingError < ConnectionError
+  end
+
+  class NoServersError < ConnectionError
+  end
+
+  class ServerError < Error
+    MAPPING: Hash[String, Symbol]
+
+    def self.for: (String? description) -> ServerError
+    def self.fatal?: () -> bool
+    def fatal?: () -> bool
+  end
+
+  class AuthorizationError < ServerError
+  end
+
+  class AuthenticationExpiredError < ServerError
+  end
+
+  class AuthenticationRevokedError < ServerError
+  end
+
+  class AuthenticationTimeoutError < ServerError
+  end
+
+  class StaleConnectionError < ServerError
+  end
+
+  class MaxConnectionsError < ServerError
+  end
+
+  class MaxAccountConnectionsError < ServerError
+  end
+
+  class MaxPayloadViolationError < ServerError
+  end
+
+  class MaxControlLineError < ServerError
+  end
+
+  class NoRespondersRequiresHeadersError < ServerError
+  end
+
+  class ConnectionThrottledError < ServerError
+  end
+
+  class TLSRequiredError < ServerError
+  end
+
+  class InvalidClientProtocolError < ServerError
+  end
+
+  class UnknownProtocolError < ServerError
+  end
+
+  class WrongPortError < ServerError
+  end
+
+  class ServerInvalidSubjectError < ServerError
+    def self.fatal?: () -> bool
+  end
+
+  class InvalidPublishSubjectError < ServerError
+    def self.fatal?: () -> bool
+  end
+
+  class FailedAccountRegistrationError < ServerError
+    def self.fatal?: () -> bool
+  end
+
+  class MaxSubscriptionsError < ServerError
+    def self.fatal?: () -> bool
+  end
+
+  class PermissionsViolationError < ServerError
+    def self.fatal?: () -> bool
+  end
+end

data/sig/tether/headers.rbs

@@ -0,0 +1,50 @@
+module Tether
+  class Headers
+    type entries = Hash[String, String | Array[String]]
+
+    VERSION: String
+    CONTROL: Integer
+    NO_CONTENT: Integer
+    BAD_REQUEST: Integer
+    NOT_FOUND: Integer
+    REQUEST_TIMEOUT: Integer
+    CONFLICT: Integer
+    REQUIRED_API_LEVEL: Integer
+    TOO_MANY_RESULTS: Integer
+    PIN_ID_MISMATCH: Integer
+    TOO_MANY_REQUESTS: Integer
+    INTERNAL_ERROR: Integer
+    NO_RESPONDERS: Integer
+
+    attr_reader status: Integer?
+    attr_reader description: String?
+
+    def self.parse: (String? bytes) -> Headers
+    def self.[]: (entries) -> Headers
+
+    def initialize: (?entries: entries, ?status: Integer?, ?description: String?) -> void
+    def []: (String key) -> String?
+    def []=: (String key, String value) -> String
+    def add: (String key, String value) -> self
+    def values: (String key) -> Array[String]
+    def delete: (String key) -> Array[String]?
+    def key?: (String key) -> bool
+    def each: () { (String, String) -> void } -> self
+             | () -> Enumerator[[String, String], self]
+    def keys: () -> Array[String]
+    def empty?: () -> bool
+    def no_responders?: () -> bool
+    def control?: () -> bool
+    def idle_heartbeat?: () -> bool
+    def flow_control?: () -> bool
+    def to_h: () -> Hash[String, Array[String]]
+    def to_wire: () -> String
+    def inspect: () -> String
+
+    private
+
+    def validate_key: (untyped key) -> String
+    def validate_value: (untyped value) -> String
+    def status_suffix: () -> String
+  end
+end

data/sig/tether/inbox_mux.rbs

@@ -0,0 +1,20 @@
+module Tether
+  class InboxMux
+    INBOX_PREFIX: String
+
+    attr_reader prefix: String
+
+    def initialize: (Client client, ?prefix: String?, ?max_pending: Integer) -> void
+    def request: (String subject, ?String? payload, ?deadline: Deadline, ?headers: Headers?) -> Msg
+    def start: () -> Subscription
+    def started?: () -> bool
+    def pending: () -> Integer
+    def close: () -> void
+
+    private
+
+    def await: (Thread::Queue waiter, String subject, Deadline deadline) -> Msg
+    def resolve: (Msg msg) -> void
+    def next_token: () -> String
+  end
+end

data/sig/tether/msg.rbs

@@ -0,0 +1,16 @@
+module Tether
+  class Msg
+    attr_reader subject: String
+    attr_reader data: String
+    attr_reader reply_to: String?
+    attr_reader subscription: Subscription?
+
+    def initialize: (subject: String, data: String, ?reply_to: String?, ?header_bytes: String?, ?subscription: Subscription?) -> void
+    def headers: () -> Headers?
+    def status: () -> Integer?
+    def no_responders?: () -> bool
+    def respond: (?String? payload, ?headers: Headers?) -> void
+    def empty?: () -> bool
+    def inspect: () -> String
+  end
+end

data/sig/tether/nuid.rbs

@@ -0,0 +1,21 @@
+module Tether
+  class NUID
+    DIGITS: String
+    BASE: Integer
+    PREFIX_LENGTH: Integer
+    SEQUENCE_LENGTH: Integer
+    TOTAL_LENGTH: Integer
+    MAX_SEQUENCE: Integer
+    MIN_INCREMENT: Integer
+    MAX_INCREMENT: Integer
+
+    def self.next: () -> String
+
+    def initialize: () -> void
+    def next: () -> String
+
+    private
+
+    def reseed!: () -> void
+  end
+end

data/sig/tether/protocol/encoder.rbs

@@ -0,0 +1,13 @@
+module Tether
+  module Protocol
+    module Encoder
+      def self.pub: (String subject, ?String? payload, ?String? reply_to) -> String
+      def self.hpub: (String subject, String? payload, Headers | String headers, ?String? reply_to) -> String
+      def self.sub: (String subject, Integer | String sid, ?queue: String?) -> String
+      def self.unsub: (Integer | String sid, ?Integer? max_msgs) -> String
+      DEFAULT_CONNECT: Hash[Symbol, untyped]
+
+      def self.connect: (?Hash[Symbol | String, untyped] options) -> String
+    end
+  end
+end

data/sig/tether/protocol/parser.rbs

@@ -0,0 +1,43 @@
+module Tether
+  module Protocol
+    class Parser
+      COMPACT_THRESHOLD: Integer
+      SNIPPET_LIMIT: Integer
+      AWAITING_CONTROL_LINE: Symbol
+      AWAITING_PAYLOAD: Symbol
+
+      attr_reader state: Symbol
+      attr_accessor max_payload: Integer?
+
+      def initialize: (_ParserSink sink, ?max_control_line: Integer, ?max_payload: Integer?) -> void
+      def <<: (String? data) -> self
+      alias parse <<
+      def reset!: () -> void
+      def broken?: () -> bool
+      def pending_bytes: () -> Integer
+
+      private
+
+      def run: () -> void
+      def consume_control_line: () -> bool
+      def match_message_line: () -> bool?
+      def start_payload: (MatchData match, bool headers) -> bool
+      def dispatch: (Integer start, Integer line_end) -> bool
+      def dispatch_ping_pong: (Integer start, Integer line_end) -> bool
+      def dispatch_ok: (Integer start, Integer line_end) -> bool
+      def dispatch_err: (Integer start, Integer line_end) -> bool
+      def dispatch_info: (Integer start, Integer line_end) -> bool
+      def consume_payload: () -> bool
+      def payload_terminated?: () -> bool
+      def emit_message: () -> void
+      def verb?: (Integer start, Integer limit, String verb) -> bool
+      def trimmed: (Integer from, Integer to) -> String
+      def snippet: (Integer start, Integer line_end) -> String
+      def clear_frame: () -> void
+      def compact: () -> void
+      def malformed: (Integer start, Integer line_end) -> bool
+      def unknown_operation: (Integer start, Integer line_end) -> bool
+      def fail_protocol!: (String message) -> bool
+    end
+  end
+end

data/sig/tether/protocol.rbs

@@ -0,0 +1,22 @@
+module Tether
+  module Protocol
+    CRLF: String
+    CRLF_SIZE: Integer
+    EMPTY_PAYLOAD: String
+    PING: String
+    PONG: String
+    DEFAULT_MAX_CONTROL_LINE: Integer
+    BINARY: Encoding
+
+    # The contract {Parser} delivers frames to. Implemented by {Dispatcher}.
+    interface _ParserSink
+      def on_msg: (String subject, String sid, String? reply_to, String? headers, String payload) -> void
+      def on_ping: () -> void
+      def on_pong: () -> void
+      def on_ok: () -> void
+      def on_info: (String json) -> void
+      def on_error: (String description) -> void
+      def on_protocol_error: (String message) -> void
+    end
+  end
+end

data/sig/tether/subscription.rbs

@@ -0,0 +1,24 @@
+module Tether
+  class Subscription
+    DEFAULT_MAX_PENDING: Integer
+
+    attr_reader sid: String
+    attr_reader subject: String
+    attr_reader queue_group: String?
+    attr_reader delivered: Integer
+    attr_reader dropped: Integer
+    attr_reader responder: Client?
+
+    def initialize: (sid: String, subject: String, ?queue_group: String?, ?max_pending: Integer, ?on_slow_consumer: (^(Subscription) -> void)?, ?responder: Client?) ?{ (Msg) -> void } -> void
+    def deliver: (Msg msg) -> bool
+    def next_message: (?Deadline deadline) -> Msg
+    def pending: () -> Integer
+    def closed?: () -> bool
+    def close: () -> void
+
+    private
+
+    def start_worker: () -> Thread
+    def invoke: (Msg msg) -> void
+  end
+end

data/sig/tether/transport.rbs

@@ -0,0 +1,22 @@
+module Tether
+  class Transport
+    DEFAULT_PORT: Integer
+    READ_SIZE: Integer
+
+    attr_reader uri: URI::Generic
+
+    def self.connect: (String | URI::Generic uri, ?deadline: Deadline) -> Transport
+
+    def initialize: (String | URI::Generic uri) -> void
+    def open: (?Deadline deadline) -> self
+    def read: (?Deadline deadline) -> String?
+    def write: (String frame) -> Integer
+    def close: () -> void
+    def closed?: () -> bool
+
+    private
+
+    def normalize: (String | URI::Generic uri) -> URI::Generic
+    def coerce_scheme: (String value) -> String
+  end
+end

data/sig/tether/version.rbs

@@ -0,0 +1,3 @@
+module Tether
+  VERSION: String
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: tether
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dmitry Vorotilin
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A NATS and JetStream client for Ruby, built around explicit deadlines
+  and per-subscription dispatch so concurrent use of one connection is safe by design.
+email:
+- d.vorotilin@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/tether.rb
+- lib/tether/client.rb
+- lib/tether/deadline.rb
+- lib/tether/dispatcher.rb
+- lib/tether/errors.rb
+- lib/tether/headers.rb
+- lib/tether/inbox_mux.rb
+- lib/tether/msg.rb
+- lib/tether/nuid.rb
+- lib/tether/protocol.rb
+- lib/tether/protocol/encoder.rb
+- lib/tether/protocol/parser.rb
+- lib/tether/subscription.rb
+- lib/tether/transport.rb
+- lib/tether/version.rb
+- sig/tether/client.rbs
+- sig/tether/deadline.rbs
+- sig/tether/dispatcher.rbs
+- sig/tether/errors.rbs
+- sig/tether/headers.rbs
+- sig/tether/inbox_mux.rbs
+- sig/tether/msg.rbs
+- sig/tether/nuid.rbs
+- sig/tether/protocol.rbs
+- sig/tether/protocol/encoder.rbs
+- sig/tether/protocol/parser.rbs
+- sig/tether/subscription.rbs
+- sig/tether/transport.rbs
+- sig/tether/version.rbs
+homepage: https://github.com/bitsbeam/tether
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/bitsbeam/tether
+  source_code_uri: https://github.com/bitsbeam/tether
+  changelog_uri: https://github.com/bitsbeam/tether/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.12
+specification_version: 4
+summary: A NATS client for Ruby
+test_files: []