nats-async 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14ba43d9d274e8b3bf2ed955560a480dcc9bf5c6668949b1007db1ebf17f02e8
-  data.tar.gz: fb0aa3853cbe25ddc1c61882b3e74031de3e916c6366d4450a7c750d4b27bdb7
+  metadata.gz: 5b1258fa795e1c8f2c02e93508469053ceac348404b146b56d9a158f86cdb864
+  data.tar.gz: 89f6419e4e219c23a4b2c3a266cd9d13adedd17604cebd1ff5426a1b68f19270
 SHA512:
-  metadata.gz: 3d95c6affdcd42236c16e1f1264dfb1ef4c9cde64bf90fdfe775fceac5f90924bc3e9126b8590d8683fb369121a294a71e9cf8c901b27520c25e0ea814520ee9
-  data.tar.gz: cf6213706289cb5b3b6e97d6b2a1ac94c8d75053d50cf7dc9c746f22bc6ff465cc21207e086f2c17498c00ca83d152d761f9fa01e2ad7a23cdeb6c40fbff0e0a
+  metadata.gz: 56005624768a4523e441dc2a2e36438f4f911fbc21f73cb08b686bc9b5fbb7e6edbacaf022ddaa7eb8655c2211877e9f942b5321b8fb048ff31216380e463301
+  data.tar.gz: 915d66b577c8c9f332c5134e065460547b36ea07a7b7755e31813d3f2a84f5397f2f459bd918045fe893ae64c860ce55d965029fd168b411bc5349d71e92bdf1

data/.github/workflows/docs.yml

@@ -0,0 +1,36 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: withastro/action@v5
+        with:
+          path: docs-site
+          node-version: 24
+          package-manager: npm@11.6.2
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

data/README.md

@@ -21,14 +21,18 @@ gem install nats-async
 ```ruby
 require "nats-async"
 
-connector = NatsAsync::SimpleConnector.new(url: "nats://127.0.0.1:4222", verbose: false)
-connector.run(duration: 1) do |client, task|
+Async do |task|
+  client = NatsAsync::Client.new(url: "nats://127.0.0.1:4222", verbose: false)
+  client.start(task: task)
+
   client.subscribe("demo.subject") do |message|
     puts "received: #{message.data}"
-    task.stop
   end
 
   client.publish("demo.subject", "hello")
+  client.flush
+ensure
+  client&.close
 end
 ```
 
@@ -37,7 +41,7 @@ end
 Core pub/sub:
 
 ```bash
-bundle exec ruby examples/basic_pub_sub.rb
+bundle exec ruby examples/core_lifecycle.rb
 ```
 
 JetStream publish and pull:
@@ -48,6 +52,16 @@ bundle exec ruby examples/jetstream_roundtrip.rb
 
 The integration spec boots the bundled [`bin/nats-server`](bin/nats-server) and runs these examples locally.
 
+## Documentation
+
+The documentation site is an Astro/Starlight project in [`docs-site`](docs-site).
+
+```bash
+npm --prefix docs-site install
+bundle exec rake docs:dev
+npm --prefix docs-site run build
+```
+
 ## Development
 
 ```bash

data/Rakefile

@@ -25,6 +25,32 @@ task :readme do
   File.write("./README.md", renderer.result)
 end
 
+def npm_bin
+  return ENV["NPM_BIN"] if ENV["NPM_BIN"] && !ENV["NPM_BIN"].empty?
+
+  ENV["PATH"].to_s.split(File::PATH_SEPARATOR).each do |path|
+    candidate = File.join(path, "npm")
+    return candidate if File.executable?(candidate)
+  end
+
+  Dir[File.join(Dir.home, ".nvm/versions/node/*/bin/npm")].sort.last
+end
+
+namespace :docs do
+  desc "Run documentation development server"
+  task :dev do
+    npm = npm_bin
+    abort "npm was not found. Install Node.js or run with NPM_BIN=/path/to/npm." unless npm
+
+    npm_path = File.dirname(npm)
+    env = {"PATH" => [npm_path, ENV["PATH"]].compact.join(File::PATH_SEPARATOR)}
+
+    Dir.chdir("docs-site") do
+      exec env, npm, "run", "dev"
+    end
+  end
+end
+
 desc "Build&push new version"
 task push: %i[spec readme] do
   puts "Build&push new version"

data/examples/backend_detection.rb

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "nats-async"
+
+Async do |task|
+  client = NatsAsync::Client.new(url: ENV.fetch("NATS_URL", "nats://127.0.0.1:4222"))
+  client.start(task: task)
+
+  client.jetstream.add_stream?("inference", subjects: ["jobs.>"])
+  backend = client.resolve_backend(mode: :auto, stream: "inference")
+  puts "using #{backend}"
+ensure
+  client&.close
+end

data/examples/core_lifecycle.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "nats-async"
+
+Async do |task|
+  client = NatsAsync::Client.new(url: ENV.fetch("NATS_URL", "nats://127.0.0.1:4222"))
+  client.start(task: task)
+  done = Async::Condition.new
+
+  client.subscribe("demo.>") do |message|
+    puts "#{message.subject}: #{message.data}"
+    done.signal
+  end
+  client.publish("demo.created", "hello")
+  done.wait
+ensure
+  client&.close
+end

data/examples/headers_and_binary.rb

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "nats-async"
+
+headers = {"traceparent" => "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"}
+payload = "\x00frame\xFF".b
+
+Async do |task|
+  client = NatsAsync::Client.new(url: ENV.fetch("NATS_URL", "nats://127.0.0.1:4222"))
+  client.start(task: task)
+  done = Async::Condition.new
+
+  client.subscribe("tcp.frames") do |message|
+    puts "#{message.headers["traceparent"]}: #{message.data.bytesize} bytes"
+    done.signal
+  end
+  client.publish("tcp.frames", payload, headers: headers)
+  done.wait
+ensure
+  client&.close
+end

data/examples/jetstream_management.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "nats-async"
+
+Async do |task|
+  client = NatsAsync::Client.new(url: ENV.fetch("NATS_URL", "nats://127.0.0.1:4222"))
+  client.start(task: task)
+
+  js = client.jetstream
+  js.add_stream?("inference", subjects: ["jobs.>"])
+  puts js.stream_exists?("inference")
+  js.add_consumer?("inference", durable_name: "worker", ack_policy: "explicit", filter_subject: "jobs.>")
+  puts js.consumer_info("inference", "worker").dig(:config, :durable_name)
+ensure
+  client&.close
+end

data/examples/jetstream_publish.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "nats-async"
+
+Async do |task|
+  client = NatsAsync::Client.new(url: ENV.fetch("NATS_URL", "nats://127.0.0.1:4222"))
+  client.start(task: task)
+
+  js = client.jetstream
+  js.add_stream?("jobs", subjects: ["jobs.>"])
+
+  ack = js.publish("jobs.render", "payload", headers: {"x-id" => "42"})
+  puts "stored in #{ack.stream}##{ack.seq}"
+ensure
+  client&.close
+end

data/examples/jetstream_pull_consumer.rb

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "nats-async"
+
+Async do |task|
+  client = NatsAsync::Client.new(url: ENV.fetch("NATS_URL", "nats://127.0.0.1:4222"))
+  client.start(task: task)
+
+  js = client.jetstream
+  js.add_stream?("inference", subjects: ["jobs.>"])
+  sub = js.pull_subscribe("jobs.>", stream: "inference", durable: "worker")
+  js.publish("jobs.render", "payload")
+
+  sub.fetch(batch: 5, timeout: 1).each do |message|
+    puts message.data
+    message.ack
+  rescue StandardError
+    message.nak
+  end
+ensure
+  sub&.unsubscribe
+  client&.close
+end

data/examples/jetstream_roundtrip.rb

@@ -11,51 +11,33 @@ consumer = ENV.fetch("JS_CONSUMER", "example_consumer")
 payload = ENV.fetch("JS_PAYLOAD", "hello jetstream")
 js_api_prefix = ENV.fetch("JS_API_PREFIX", "$JS.API")
 
-connector = NatsAsync::SimpleConnector.new(
-  url: url,
-  verbose: true,
-  js_api_prefix: js_api_prefix
-)
-
-connector.run(duration: 3, ping_every: 1, ping_timeout: 1) do |client, _task|
-  client.request(
-    client.js_api_subject("STREAM.CREATE", stream_name),
-    {
-      name: stream_name,
-      subjects: [subject]
-    },
-    timeout: 2
+Async do |task|
+  client = NatsAsync::Client.new(
+    url: url,
+    verbose: true,
+    js_api_prefix: js_api_prefix,
+    ping_interval: 1,
+    ping_timeout: 1
   )
+  client.start(task: task)
 
-  client.request(
-    client.js_api_subject("CONSUMER.CREATE", stream_name, consumer),
-    {
-      stream_name: stream_name,
-      config: {
-        name: consumer,
-        durable_name: consumer,
-        ack_policy: "explicit",
-        deliver_policy: "new",
-        filter_subject: subject
-      }
-    },
-    timeout: 2
-  )
+  js = client.jetstream
+  js.add_stream?(stream_name, subjects: [subject])
+  sub = js.pull_subscribe(subject, stream: stream_name, durable: consumer)
 
-  pub_ack = client.request(subject, payload, timeout: 2)
-  puts "published seq=#{pub_ack[:seq]} stream=#{pub_ack[:stream]}"
+  pub_ack = js.publish(subject, payload)
+  puts "published seq=#{pub_ack.seq} stream=#{pub_ack.stream}"
 
-  message = client.request(
-    client.js_api_subject("CONSUMER.MSG.NEXT", stream_name, consumer),
-    {batch: 1, expires: 1_000_000_000},
-    timeout: 2,
-    parse_json: false
-  )
+  message = sub.fetch(batch: 1, timeout: 2).first
 
   puts "received subject=#{message.subject} data=#{message.data.inspect}"
   puts "metadata=#{message.metadata.inspect}"
-  message.ack if message.reply
-
-  client.request(client.js_api_subject("CONSUMER.DELETE", stream_name, consumer), {}, timeout: 2)
-  client.request(client.js_api_subject("STREAM.DELETE", stream_name), {}, timeout: 2)
+  message.ack
+
+  sub.unsubscribe
+  js.delete_consumer(stream_name, consumer)
+  js.delete_stream(stream_name)
+ensure
+  sub&.unsubscribe
+  client&.close
 end

data/examples/queue_group.rb

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "nats-async"
+
+Async do |task|
+  client = NatsAsync::Client.new(url: ENV.fetch("NATS_URL", "nats://127.0.0.1:4222"))
+  client.start(task: task)
+  done = Async::Condition.new
+
+  client.subscribe("jobs.render", queue: "renderers") do |message|
+    puts "worker got #{message.data}"
+    done.signal
+  end
+
+  client.publish("jobs.render", "job-1")
+  done.wait
+ensure
+  client&.drain(timeout: 5)
+end

data/examples/request_reply.rb

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "nats-async"
+
+Async do |task|
+  client = NatsAsync::Client.new(url: ENV.fetch("NATS_URL", "nats://127.0.0.1:4222"))
+  client.start(task: task)
+
+  client.subscribe("math.double") { |message| client.publish(message.reply, message.data.to_i * 2) }
+  puts client.request("math.double", "21", timeout: 1)
+ensure
+  client&.close
+end

data/lib/nats-async.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
 
 require_relative "version"
-require_relative "nats_async/simple_connector"
+require_relative "nats_async/client"
+require_relative "nats_async/jetstream"

data/lib/nats_async/{simple_connector.rb → client.rb}

@@ -15,8 +15,9 @@ require "base64"
 require "openssl"
 
 module NatsAsync
-  class SimpleConnector
+  class Client
     CR_LF = "\r\n"
+    HEADER_LINE = "NATS/1.0"
 
     class AckError < StandardError; end
     class MsgAlreadyAcked < AckError; end
@@ -25,19 +26,34 @@ module NatsAsync
     class ResponseParseError < RequestError; end
     class ProtocolError < StandardError; end
 
+    class Headers < Hash
+      def self.wrap(values)
+        new.tap { |headers| values.each { |key, value| headers[key] = value } }
+      end
+
+      def [](key)
+        return super if key?(key)
+
+        match = keys.find { |existing| existing.to_s.casecmp?(key.to_s) }
+        match ? super(match) : nil
+      end
+    end
+
     class Message
       ACK = "+ACK"
       NAK = "-NAK"
       TERM = "+TERM"
       WPI = "+WPI"
 
-      attr_reader :subject, :sid, :reply, :data
+      attr_reader :subject, :sid, :reply, :data, :headers
+      alias header headers
 
-      def initialize(subject:, sid:, reply:, data:, connector:)
+      def initialize(subject:, sid:, reply:, data:, connector:, headers: {})
         @subject = subject
         @sid = sid
         @reply = reply
         @data = data
+        @headers = Headers.wrap(headers)
         @connector = connector
         @acked = false
       end
@@ -58,6 +74,14 @@ module NatsAsync
         publish_ack(WPI, timeout: timeout)
       end
 
+      def ackable?
+        !reply.to_s.empty?
+      end
+
+      def acked?
+        @acked
+      end
+
       def metadata
         return unless reply&.start_with?("$JS.ACK.")
 
@@ -119,6 +143,8 @@ module NatsAsync
       url: "nats://127.0.0.1:4222",
       verbose: true,
       js_api_prefix: "$JS.API",
+      ping_interval: 30,
+      ping_timeout: 5,
       tls: nil,
       tls_verify: true,
       tls_ca_file: nil,
@@ -134,6 +160,8 @@ module NatsAsync
       @url = URI(url)
       @verbose = verbose
       @js_api_prefix = normalize_subject_prefix(js_api_prefix)
+      @ping_interval = ping_interval
+      @ping_timeout = ping_timeout
       @tls_enabled = tls.nil? ? %w[tls nats+tls].include?(@url.scheme) : tls
       @tls_verify = tls_verify
       @tls_ca_file = presence(tls_ca_file)
@@ -154,7 +182,10 @@ module NatsAsync
       @server_info = nil
 
       @read_task = nil
+      @ping_task = nil
       @read_error = nil
+      @started = false
+      @closed = true
       @write_lock = Async::Semaphore.new(1)
       @pong_condition = Async::Condition.new
       @sid_seq = 0
@@ -163,32 +194,89 @@ module NatsAsync
 
     attr_reader :received_pings, :received_pongs, :sent_pings, :server_info, :js_api_prefix
 
-    def run(duration: 10, ping_every: 2, ping_timeout: 2)
-      Async do |task|
-        connect!
-        read_initial_info!
-        send_connect!
+    def start(task:)
+      return self if connected?
+
+      connect!
+      read_initial_info!
+      send_connect!
+      @read_task = task.async { read_loop }
+      @started = true
+      @closed = false
+      ping!(timeout: @ping_timeout)
+      start_ping_loop(task)
+      self
+    rescue StandardError
+      stop
+      @started = false
+      @closed = true
+      raise
+    end
 
-        @read_task = task.async { read_loop }
-        ping!(timeout: ping_timeout)
-        yield self, task if block_given?
+    def close
+      return true if closed?
 
-        deadline = monotonic_now + duration
-        while monotonic_now < deadline
-          task.sleep(ping_every)
-          ping!(timeout: ping_timeout)
-        end
-      ensure
-        stop
-      end.wait
+      stop
+      @started = false
+      @closed = true
+      true
+    end
+
+    def resolve_backend(mode: :auto, stream: nil)
+      mode = mode.to_sym
+      return :core if mode == :core
+
+      raise ArgumentError, "stream is required for #{mode} backend" if stream.to_s.empty?
+
+      case mode
+      when :jetstream
+        jetstream.stream_info(stream)
+        :jetstream
+      when :auto
+        jetstream.stream_exists?(stream) ? :jetstream : :core
+      else
+        raise ArgumentError, "unsupported backend mode: #{mode.inspect}"
+      end
+    rescue JetStream::Error
+      raise if mode == :jetstream
+
+      :core
+    end
+
+    def drain(timeout: 5)
+      @ping_task&.stop
+      @ping_task = nil
+      flush(timeout: timeout) if connected?
+      true
+    ensure
+      close
     end
 
     def stop
+      @ping_task&.stop
       @read_task&.stop
       safe_close_stream
+      @ping_task = nil
       @read_task = nil
     end
 
+    def flush(timeout: 2)
+      ping!(timeout: timeout)
+      true
+    end
+
+    def connected?
+      @started && !@closed && !@stream.nil?
+    end
+
+    def closed?
+      @closed
+    end
+
+    def last_error
+      @read_error
+    end
+
     def ping!(timeout: 2)
       expected_pongs = @received_pongs + 1
 
@@ -200,8 +288,10 @@ module NatsAsync
       })
     end
 
-    def publish(subject, payload = "", reply: nil)
+    def publish(subject, payload = "", reply: nil, headers: nil)
       payload = payload.to_s
+      return publish_with_headers(subject, payload, headers, reply: reply) if headers && !headers.empty?
+
       command = build_pub_command(subject, payload.bytesize, reply: reply)
       @logger.debug("C->S #{command}")
 
@@ -230,20 +320,20 @@ module NatsAsync
       true
     end
 
-    def request(subject, payload = "", timeout: 0.5, parse_json: true)
-      response = request_message(subject, payload, timeout: timeout)
-      result = parse_json ? parse_json_response(subject, response.data) : response
+    def request(subject, payload = "", timeout: 0.5, parse_json: false, headers: nil)
+      response = request_message(subject, payload, timeout: timeout, headers: headers)
+      result = parse_json ? parse_json_response(subject, response.data) : response.data
       ensure_request_ok!(subject, result) if parse_json
       block_given? ? yield(result) : result
     end
 
-    def request_message(subject, payload = "", timeout: 0.5)
+    def request_message(subject, payload = "", timeout: 0.5, headers: nil)
       inbox = "_INBOX.#{rand(1 << 30)}.#{next_sid}"
       response = nil
       condition = Async::Condition.new
       on_response = ->(msg) { response = msg; condition.signal }
       with_temp_subscription(inbox, handler: on_response) do
-        publish(subject, request_payload(payload), reply: inbox)
+        publish(subject, request_payload(payload), reply: inbox, headers: headers)
         await(timeout: timeout, condition: condition, timeout_message: "request timeout after #{timeout}s", predicate: lambda {
           raise @read_error if @read_error
           !response.nil?
@@ -257,8 +347,29 @@ module NatsAsync
       [js_api_prefix, *tokens.flatten].compact.map(&:to_s).reject(&:empty?).join(".")
     end
 
+    def jetstream
+      @jetstream ||= JetStream.new(self)
+    end
+
     private
 
+    def start_ping_loop(task)
+      return unless @ping_interval && @ping_interval.positive?
+
+      @ping_task = task.async { |ping_task| ping_loop(ping_task) }
+    end
+
+    def ping_loop(task)
+      loop do
+        task.sleep(@ping_interval)
+        ping!(timeout: @ping_timeout)
+      end
+    rescue StandardError => e
+      @read_error ||= e
+      @logger.error("ping loop error: #{e.class}: #{e.message}")
+      safe_close_stream
+    end
+
     def connect!
       host = @url.host || "127.0.0.1"
       port = @url.port || 4222
@@ -286,6 +397,7 @@ module NatsAsync
         lang: "ruby",
         version: "nats-async-playground",
         protocol: 1,
+        headers: true,
         echo: true
       }
       payload.merge!(auth_connect_fields)
@@ -307,6 +419,8 @@ module NatsAsync
           raise ProtocolError, "server error: #{line}"
         when /\AINFO\s+/
           @server_info = parse_info_line(line)
+        when /\AHMSG\s+/
+          dispatch_hmsg(line)
         when /\AMSG\s+/
           dispatch_msg(line)
         end
@@ -390,17 +504,36 @@ module NatsAsync
       suffix = @stream.read_exactly(CR_LF.bytesize)
       raise ProtocolError, "malformed MSG payload ending: #{suffix.inspect}" unless suffix == CR_LF
 
-      msg = Message.new(subject: subject, sid: sid, reply: reply, data: payload, connector: self)
-      handler = @subscriptions[sid]
-      protocol_payload_in(payload)
+      dispatch_message(Message.new(subject: subject, sid: sid, reply: reply, data: payload, connector: self))
+    rescue StandardError => e
+      @logger.error("message dispatch error: #{e.class}: #{e.message}")
+    end
+
+    def dispatch_hmsg(control_line)
+      subject, sid, reply, header_size, total_size = parse_hmsg_control_line(control_line)
+      raise ProtocolError, "HMSG header size exceeds total size" if header_size > total_size
+
+      data = @stream.read_exactly(total_size)
+      suffix = @stream.read_exactly(CR_LF.bytesize)
+      raise ProtocolError, "malformed HMSG payload ending: #{suffix.inspect}" unless suffix == CR_LF
+
+      header_block = data.byteslice(0, header_size) || +""
+      payload = data.byteslice(header_size, total_size - header_size) || +""
+      headers = parse_header_block(header_block)
+      dispatch_message(Message.new(subject: subject, sid: sid, reply: reply, data: payload, connector: self, headers: headers))
+    rescue StandardError => e
+      @logger.error("header message dispatch error: #{e.class}: #{e.message}")
+    end
+
+    def dispatch_message(message)
+      handler = @subscriptions[message.sid]
+      protocol_payload_in(message.data)
 
       if handler
-        handler.call(msg)
+        handler.call(message)
       else
-        @logger.warn("no subscription handler for sid=#{sid}")
+        @logger.warn("no subscription handler for sid=#{message.sid}")
       end
-    rescue StandardError => e
-      @logger.error("message dispatch error: #{e.class}: #{e.message}")
     end
 
     def parse_msg_control_line(control_line)
@@ -419,6 +552,80 @@ module NatsAsync
       raise ProtocolError, "invalid MSG control values: #{e.message}"
     end
 
+    def parse_hmsg_control_line(control_line)
+      tokens = control_line.split(" ")
+      raise ProtocolError, "malformed HMSG line: #{control_line.inspect}" unless tokens.first == "HMSG"
+
+      case tokens.length
+      when 5
+        [tokens[1], Integer(tokens[2]), nil, Integer(tokens[3]), Integer(tokens[4])]
+      when 6
+        [tokens[1], Integer(tokens[2]), tokens[3], Integer(tokens[4]), Integer(tokens[5])]
+      else
+        raise ProtocolError, "unexpected HMSG control tokens: #{tokens.length}"
+      end
+    rescue ArgumentError => e
+      raise ProtocolError, "invalid HMSG control values: #{e.message}"
+    end
+
+    def publish_with_headers(subject, payload, headers, reply: nil)
+      header_block = build_header_block(headers)
+      command = build_hpub_command(subject, header_block.bytesize, header_block.bytesize + payload.bytesize, reply: reply)
+      @logger.debug("C->S #{command}")
+
+      @write_lock.acquire do
+        @stream.write("#{command}#{CR_LF}", flush: false)
+        @stream.write(header_block, flush: false)
+        @stream.write(payload, flush: false)
+        @stream.write(CR_LF, flush: true)
+      end
+      protocol_payload_out(payload)
+    end
+
+    def build_header_block(headers)
+      lines = [HEADER_LINE]
+      headers.each do |key, value|
+        header_name = validate_header_name(key)
+        Array(value).each do |item|
+          lines << "#{header_name}: #{validate_header_value(item)}"
+        end
+      end
+
+      "#{lines.join(CR_LF)}#{CR_LF}#{CR_LF}".b
+    end
+
+    def parse_header_block(block)
+      lines = block.split(CR_LF)
+      status = lines.shift
+      raise ProtocolError, "invalid header block status: #{status.inspect}" unless status&.start_with?(HEADER_LINE)
+
+      lines.each_with_object({}) do |line, headers|
+        next if line.empty?
+
+        key, value = line.split(":", 2)
+        raise ProtocolError, "malformed header line: #{line.inspect}" unless key && value
+
+        value = value.sub(/\A[ \t]/, "")
+        existing = headers[key]
+        headers[key] = existing ? Array(existing).push(value) : value
+      end
+    end
+
+    def validate_header_name(key)
+      name = key.to_s
+      raise ArgumentError, "header name cannot be empty" if name.empty?
+      raise ArgumentError, "invalid header name: #{name.inspect}" if name.match?(/[:\r\n]/)
+
+      name
+    end
+
+    def validate_header_value(value)
+      string = value.to_s
+      raise ArgumentError, "invalid header value: #{string.inspect}" if string.match?(/[\r\n]/)
+
+      string
+    end
+
     def protocol_payload_out(payload)
       return if payload.empty?
 
@@ -442,6 +649,10 @@ module NatsAsync
       reply ? "PUB #{subject} #{reply} #{size}" : "PUB #{subject} #{size}"
     end
 
+    def build_hpub_command(subject, header_size, total_size, reply: nil)
+      reply ? "HPUB #{subject} #{reply} #{header_size} #{total_size}" : "HPUB #{subject} #{header_size} #{total_size}"
+    end
+
     def nkey_connect_fields
       return {} unless nkey_auth?
 

data/lib/nats_async/jetstream.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module NatsAsync
+  class JetStream
+    class Error < Client::RequestError
+      attr_reader :code, :err_code, :description
+
+      def initialize(message, code: nil, err_code: nil, description: nil)
+        super(message)
+        @code = code
+        @err_code = err_code
+        @description = description
+      end
+    end
+
+    class NotFound < Error; end
+    class ConsumerError < Error; end
+
+    PublishAck = Struct.new(:stream, :seq, :duplicate, keyword_init: true) do
+      def duplicate?
+        !!duplicate
+      end
+    end
+
+    class PullSubscription
+      def initialize(client:, stream:, consumer:)
+        @client = client
+        @stream = stream
+        @consumer = consumer
+        @inbox = "_INBOX.#{rand(1 << 30)}.#{object_id.abs}"
+        @sid = @client.subscribe(@inbox) { |message| receive(message) }
+      end
+
+      def fetch(batch: 1, timeout: 1)
+        @messages = []
+        @done = false
+        @batch = batch
+        @condition = Async::Condition.new
+
+        @client.publish(next_subject, JSON.generate({batch: batch, expires: seconds_to_nanoseconds(timeout)}), reply: @inbox)
+        wait_for_messages(timeout)
+        @messages
+      ensure
+        @messages = nil
+        @condition = nil
+        @batch = nil
+        @done = false
+      end
+
+      def unsubscribe
+        return true unless @sid
+
+        @client.unsubscribe(@sid)
+        @sid = nil
+        true
+      end
+
+      private
+
+      def receive(message)
+        return unless @condition
+
+        if status_message?(message)
+          @done = true
+        else
+          @messages << message
+        end
+
+        @condition.signal if @done || @messages.size >= @batch
+      end
+
+      def wait_for_messages(timeout)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+
+        until @done || @messages.size >= @batch
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          break if remaining <= 0
+
+          begin
+            Async::Task.current.with_timeout(remaining) { @condition.wait }
+          rescue Timeout::Error, Async::TimeoutError
+            break
+          end
+        end
+      end
+
+      def status_message?(message)
+        !message.headers["Status"].to_s.empty?
+      end
+
+      def next_subject
+        @client.js_api_subject("CONSUMER.MSG.NEXT", @stream, @consumer)
+      end
+
+      def seconds_to_nanoseconds(value)
+        (value.to_f * 1_000_000_000).to_i
+      end
+    end
+
+    def initialize(client)
+      @client = client
+    end
+
+    def stream_info(name)
+      api_request("STREAM.INFO", name)
+    rescue Error => e
+      raise not_found_error(e) if not_found?(e)
+
+      raise
+    end
+
+    def available?
+      account_info
+      true
+    rescue Error
+      false
+    end
+
+    def account_info
+      api_request("INFO")
+    end
+
+    def stream_exists?(name)
+      stream_info(name)
+      true
+    rescue NotFound
+      false
+    end
+
+    def add_stream(name, config = nil, **options)
+      config = merge_config(config, options).merge(name: name)
+      api_request("STREAM.CREATE", name, config)
+    end
+
+    def add_stream?(name, config = nil, **options)
+      return false if stream_exists?(name)
+
+      add_stream(name, config, **options)
+      true
+    end
+
+    def delete_stream(name)
+      api_request("STREAM.DELETE", name, {})
+    end
+
+    def consumer_info(stream, consumer)
+      api_request("CONSUMER.INFO", stream, consumer)
+    rescue Error => e
+      raise not_found_error(e) if not_found?(e)
+
+      raise
+    end
+
+    def consumer_exists?(stream, consumer)
+      consumer_info(stream, consumer)
+      true
+    rescue NotFound
+      false
+    end
+
+    def add_consumer(stream, config = nil, **options)
+      config = merge_config(config, options)
+      consumer = consumer_name(config)
+      subject = consumer ? @client.js_api_subject("CONSUMER.CREATE", stream, consumer) : @client.js_api_subject("CONSUMER.CREATE", stream)
+      api_request_subject(subject, {stream_name: stream, config: config})
+    rescue Error => e
+      raise ConsumerError.new(e.message, code: e.code, err_code: e.err_code, description: e.description)
+    end
+
+    def add_consumer?(stream, config = nil, **options)
+      config = merge_config(config, options)
+      consumer = consumer_name(config)
+      return false if consumer && consumer_exists?(stream, consumer)
+
+      add_consumer(stream, config)
+      true
+    end
+
+    def delete_consumer(stream, consumer)
+      api_request("CONSUMER.DELETE", stream, consumer, {})
+    end
+
+    def publish(subject, payload = "", headers: nil, timeout: 2)
+      response = @client.request_message(subject, payload, timeout: timeout, headers: headers)
+      result = JSON.parse(response.data, symbolize_names: true)
+      raise_api_error(subject, result[:error]) if result[:error]
+
+      PublishAck.new(stream: result[:stream], seq: result[:seq], duplicate: result[:duplicate])
+    rescue JSON::ParserError => e
+      raise Error, "JetStream publish returned invalid JSON for #{subject}: #{e.message}"
+    end
+
+    def pull_subscribe(subject, stream:, durable: nil, consumer: nil, config: {}, create: true)
+      config = merge_config(config, {})
+      config[:filter_subject] ||= subject
+      config[:ack_policy] ||= "explicit"
+      config[:durable_name] ||= durable if durable
+      config[:name] ||= consumer if consumer
+
+      consumer_name = consumer_name(config)
+      raise ArgumentError, "durable, consumer, config[:name], or config[:durable_name] is required" if consumer_name.to_s.empty?
+
+      add_consumer?(stream, config) if create
+      PullSubscription.new(client: @client, stream: stream, consumer: consumer_name)
+    end
+
+    private
+
+    def api_request(*tokens)
+      payload = tokens.last.is_a?(Hash) ? tokens.pop : {}
+      api_request_subject(@client.js_api_subject(*tokens), payload)
+    end
+
+    def api_request_subject(subject, payload)
+      response = @client.request_message(subject, payload, timeout: 2)
+      result = JSON.parse(response.data, symbolize_names: true)
+      raise_api_error(subject, result[:error]) if result[:error]
+
+      result
+    rescue JSON::ParserError => e
+      raise Error, "JetStream API returned invalid JSON for #{subject}: #{e.message}"
+    end
+
+    def raise_api_error(subject, error)
+      details = error.is_a?(Hash) ? error : {description: error.to_s}
+      code = details[:code]
+      err_code = details[:err_code]
+      description = details[:description] || details[:message] || details.inspect
+      klass = not_found_code?(code, description) ? NotFound : Error
+      raise klass.new("JetStream API request failed for #{subject}: #{description}", code: code, err_code: err_code, description: description)
+    end
+
+    def not_found?(error)
+      error.is_a?(NotFound) || not_found_code?(error.code, error.description)
+    end
+
+    def not_found_code?(code, description)
+      code.to_i == 404 || description.to_s.match?(/not found/i)
+    end
+
+    def not_found_error(error)
+      NotFound.new(error.message, code: error.code, err_code: error.err_code, description: error.description)
+    end
+
+    def merge_config(config, options)
+      (config || {}).transform_keys(&:to_sym).merge(options)
+    end
+
+    def consumer_name(config)
+      config[:name] || config[:durable_name]
+    end
+  end
+end

data/lib/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NatsAsync
-  VERSION = "0.1.3"
+  VERSION = "0.1.5"
 end

data/spec/examples_spec.rb

@@ -11,20 +11,6 @@ require "tempfile"
 require "tmpdir"
 
 RSpec.describe "example scripts" do
-  def report_server_start_failure(reason, log_path)
-    log = File.exist?(log_path) ? File.read(log_path) : "(log file missing)"
-    message = <<~MSG
-      nats-server example integration skipped: #{reason}
-      --- nats-server log ---
-      #{log}
-      --- end nats-server log ---
-    MSG
-
-    warn(message)
-    warn("::warning::#{message.gsub("\n", "%0A")}") if ENV["GITHUB_ACTIONS"] == "true"
-    skip(message)
-  end
-
   def project_path = File.expand_path("..", __dir__)
   def server_path = File.join(project_path, "bin", "nats-server")
 
@@ -44,11 +30,21 @@ RSpec.describe "example scripts" do
       return
     rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
       if Process.waitpid(server_pid, Process::WNOHANG)
-        report_server_start_failure("bundled nats-server exited before becoming ready", log_path)
+        raise <<~MSG
+          bundled nats-server exited before becoming ready
+          --- nats-server log ---
+          #{File.exist?(log_path) ? File.read(log_path) : "(log file missing)"}
+          --- end nats-server log ---
+        MSG
       end
 
       if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
-        report_server_start_failure("bundled nats-server did not start on port #{port}", log_path)
+        raise <<~MSG
+          bundled nats-server did not start on port #{port}
+          --- nats-server log ---
+          #{File.exist?(log_path) ? File.read(log_path) : "(log file missing)"}
+          --- end nats-server log ---
+        MSG
       end
 
       sleep 0.1
@@ -92,7 +88,14 @@ RSpec.describe "example scripts" do
 
           begin
             wait_for_server(port, server, log_path)
-            run_example("examples/basic_pub_sub.rb", {"NATS_URL" => url})
+            run_example("examples/core_lifecycle.rb", {"NATS_URL" => url})
+            run_example("examples/queue_group.rb", {"NATS_URL" => url})
+            run_example("examples/request_reply.rb", {"NATS_URL" => url})
+            run_example("examples/headers_and_binary.rb", {"NATS_URL" => url})
+            run_example("examples/jetstream_management.rb", {"NATS_URL" => url})
+            run_example("examples/jetstream_publish.rb", {"NATS_URL" => url})
+            run_example("examples/backend_detection.rb", {"NATS_URL" => url})
+            run_example("examples/jetstream_pull_consumer.rb", {"NATS_URL" => url})
             run_example(
               "examples/jetstream_roundtrip.rb",
               {

data/spec/nats_async_spec.rb

@@ -7,7 +7,7 @@ describe NatsAsync do
   #   expect(NatsAsync::VERSION).to eq("0.1.0")
   # end
 
-  it "loads the simple connector" do
-    expect(NatsAsync::SimpleConnector).to be_a(Class)
+  it "loads the client" do
+    expect(NatsAsync::Client).to be_a(Class)
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nats-async
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - Artem Borodkin
@@ -190,15 +190,24 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/docs.yml"
 - ".github/workflows/release.yml"
 - ".rspec"
 - ".rubocop.yml"
 - README.md
 - Rakefile
-- examples/basic_pub_sub.rb
+- examples/backend_detection.rb
+- examples/core_lifecycle.rb
+- examples/headers_and_binary.rb
+- examples/jetstream_management.rb
+- examples/jetstream_publish.rb
+- examples/jetstream_pull_consumer.rb
 - examples/jetstream_roundtrip.rb
+- examples/queue_group.rb
+- examples/request_reply.rb
 - lib/nats-async.rb
-- lib/nats_async/simple_connector.rb
+- lib/nats_async/client.rb
+- lib/nats_async/jetstream.rb
 - lib/version.rb
 - spec/examples_spec.rb
 - spec/nats_async_spec.rb

data/examples/basic_pub_sub.rb

@@ -1,21 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require "bundler/setup"
-require "nats-async"
-
-url = ENV.fetch("NATS_URL", "nats://127.0.0.1:4222")
-subject = ENV.fetch("NATS_SUBJECT", "demo.subject")
-payload = ENV.fetch("NATS_PAYLOAD", "hello from nats-async")
-
-connector = NatsAsync::SimpleConnector.new(url: url, verbose: true)
-
-connector.run(duration: 1.5, ping_every: 1, ping_timeout: 1) do |client, task|
-  sid = client.subscribe(subject) do |message|
-    puts "received subject=#{message.subject} data=#{message.data.inspect}"
-    client.unsubscribe(sid)
-    task.stop
-  end
-
-  client.publish(subject, payload)
-end