nats-pure 2.5.0 → 2.7.0

data/lib/nats/io/jetstream/api.rb

@@ -41,6 +41,27 @@ module NATS
         end
       end
 
+      # PriorityGroupState is the state of a priority group of a consumer
+      # (requires nats-server v2.11.0).
+      #
+      # @!attribute group
+      #   @return [String] Name of the group.
+      # @!attribute pinned_client_id
+      #   @return [String, nil] With the pinned_client priority policy, the
+      #     pin id of the subscription that the group is pinned to.
+      # @!attribute pinned_ts
+      #   @return [Time, nil] When the group was pinned.
+      PriorityGroupState = Struct.new(:group, :pinned_client_id, :pinned_ts,
+        keyword_init: true) do
+        def initialize(opts = {})
+          opts[:pinned_ts] = JS.parse_time(opts[:pinned_ts])
+          rem = opts.keys - members
+          opts.delete_if { |k| rem.include?(k) }
+          super
+          freeze
+        end
+      end
+
       # ConsumerInfo is the current status of a JetStream consumer.
       #
       # @!attribute stream_name
@@ -64,21 +85,43 @@ module NATS
       # @!attribute num_pending
       #   @return [Integer]
       # @!attribute cluster
-      #   @return [Hash]
+      #   The cluster of a clustered consumer, such as its leader, its
+      #   replicas and, as leader_since, when the leader was elected
+      #   (requires nats-server v2.12.0); nil on a standalone server. The
+      #   values are the server's: leader_since is a String, and the
+      #   active of the replicas is in nanoseconds.
+      #   @return [Hash, nil]
+      # @!attribute ts
+      #   When the server reported this info (requires nats-server v2.10.0).
+      #   @return [Time]
+      # @!attribute paused
+      #   True while the consumer is paused (requires nats-server v2.11.0).
+      #   @return [Boolean, nil]
+      # @!attribute pause_remaining
+      #   Seconds until a paused consumer resumes, rounded down, so 0 in its
+      #   last second (requires nats-server v2.11.0).
+      #   @return [Integer, nil]
+      # @!attribute priority_groups
+      #   State of the consumer's priority groups (requires nats-server v2.11.0).
+      #   @return [Array<PriorityGroupState>, nil]
       ConsumerInfo = Struct.new(:type, :stream_name, :name, :created,
         :config, :delivered, :ack_floor,
         :num_ack_pending, :num_redelivered, :num_waiting,
-        :num_pending, :cluster, :push_bound,
+        :num_pending, :cluster, :push_bound, :ts,
+        :paused, :pause_remaining, :priority_groups,
         keyword_init: true) do
         def initialize(opts = {})
           opts[:created] = Time.parse(opts[:created])
+          opts[:ts] = Time.parse(opts[:ts]) if opts[:ts]
+          opts[:pause_remaining] = opts[:pause_remaining] / ::NATS::NANOSECONDS if opts[:pause_remaining]
+          opts[:priority_groups] = opts[:priority_groups].map { |state| PriorityGroupState.new(state) } if opts[:priority_groups]
           opts[:ack_floor] = SequenceInfo.new(opts[:ack_floor])
           opts[:delivered] = SequenceInfo.new(opts[:delivered])
-          opts[:config][:ack_wait] = opts[:config][:ack_wait] / ::NATS::NANOSECONDS
+          opts[:config][:ack_wait] = opts[:config][:ack_wait] / ::NATS::NANOSECONDS if opts[:config][:ack_wait]
           opts[:config][:inactive_threshold] = opts[:config][:inactive_threshold] / ::NATS::NANOSECONDS if opts[:config][:inactive_threshold]
           opts[:config][:idle_heartbeat] = opts[:config][:idle_heartbeat] / ::NATS::NANOSECONDS if opts[:config][:idle_heartbeat]
+          opts[:config][:priority_timeout] = opts[:config][:priority_timeout] / ::NATS::NANOSECONDS if opts[:config][:priority_timeout]
           opts[:config] = ConsumerConfig.new(opts[:config])
-          opts.delete(:cluster)
           # Filter unrecognized fields just in case.
           rem = opts.keys - members
           opts.delete_if { |k| rem.include?(k) }
@@ -96,7 +139,8 @@ module NATS
       # @!attribute ack_policy
       #   @return [String]
       # @!attribute ack_wait
-      #   @return [Integer]
+      #   Seconds; nil when the server omits it, as for consumers that do not ack.
+      #   @return [Integer, nil]
       # @!attribute max_deliver
       #   @return [Integer]
       # @!attribute replay_policy
@@ -105,6 +149,27 @@ module NATS
       #   @return [Integer]
       # @!attribute max_ack_pending
       #   @return [Integer]
+      # @!attribute pause_until
+      #   Time until which the consumer delivers no messages, as a Time or
+      #   as an RFC 3339 String; a fetched config has a String. The server
+      #   takes it only when it creates the consumer: updates keep the pause,
+      #   which pause_consumer and resume_consumer change. Requires
+      #   nats-server v2.11.0; older ones create the consumer unpaused.
+      #   @return [Time, String, nil]
+      # @!attribute priority_policy
+      #   How the consumer serves the pulls of its priority groups: "none",
+      #   "overflow", "pinned_client", or "prioritized" (requires
+      #   nats-server v2.11.0, and v2.12.0 for "prioritized").
+      #   @return [String, nil]
+      # @!attribute priority_groups
+      #   Names of the consumer's priority groups, one of which each pull
+      #   has to name (requires nats-server v2.11.0).
+      #   @return [Array<String>, nil]
+      # @!attribute priority_timeout
+      #   With the pinned_client priority policy, seconds after which a
+      #   pinned subscription that stops pulling is unpinned
+      #   (requires nats-server v2.11.0).
+      #   @return [Integer, nil]
       ConsumerConfig = Struct.new(:name, :durable_name, :description,
         :deliver_policy, :opt_start_seq, :opt_start_time,
         :ack_policy, :ack_wait, :max_deliver, :backoff,
@@ -124,6 +189,8 @@ module NATS
         :mem_storage,
         # NATS v2.10 features
         :metadata, :filter_subjects, :max_bytes,
+        # NATS v2.11 features
+        :pause_until, :priority_policy, :priority_groups, :priority_timeout,
         keyword_init: true) do
         def initialize(opts = {})
           # Filter unrecognized fields just in case.
@@ -133,8 +200,54 @@ module NATS
         end
       end
 
+      # ConsumerPauseResponse is the result of pausing or resuming a consumer
+      # (requires nats-server v2.11.0).
+      #
+      # @!attribute paused
+      #   @return [Boolean] Whether the consumer is paused.
+      # @!attribute pause_until
+      #   @return [Time, nil] When the consumer resumes; nil once resumed. A time
+      #     in the past does not pause the consumer, and paused is then false.
+      # @!attribute pause_remaining
+      #   @return [Integer, nil] Seconds until the consumer resumes, rounded down,
+      #     so 0 in its last second; nil when it is not paused.
+      ConsumerPauseResponse = Struct.new(:paused, :pause_until, :pause_remaining,
+        keyword_init: true) do
+        def initialize(opts = {})
+          opts[:pause_until] = JS.parse_time(opts[:pause_until])
+          opts[:pause_remaining] = opts[:pause_remaining] / ::NATS::NANOSECONDS if opts[:pause_remaining]
+          rem = opts.keys - members
+          opts.delete_if { |k| rem.include?(k) }
+          super
+          freeze
+        end
+      end
+
+      # ConsumerResetResponse is the result of resetting a consumer
+      # (requires nats-server v2.14.0).
+      #
+      # @!attribute info
+      #   @return [ConsumerInfo] The consumer after the reset.
+      # @!attribute reset_seq
+      #   @return [Integer] Stream sequence the consumer delivers from. The next
+      #     message it delivers can come later, as the first one from there that
+      #     matches its filter.
+      ConsumerResetResponse = Struct.new(:info, :reset_seq,
+        keyword_init: true) do
+        def initialize(opts = {})
+          reset_seq = opts[:reset_seq]
+          super(info: ConsumerInfo.new(opts), reset_seq: reset_seq)
+          freeze
+        end
+      end
+
       # StreamConfig represents the configuration of a stream from JetStream.
       #
+      # Settings left nil are not sent, and neither are the settings of
+      # nats-server 2.11 to 2.14 left at their defaults, such as false.
+      # Servers since v2.12.0, and v2.11 ones in strict mode, refuse the
+      # settings that they do not know.
+      #
       # @!attribute type
       #   @return [String]
       # @!attribute config
@@ -165,12 +278,75 @@ module NATS
       #   @return [Integer]
       # @!attribute discard
       #   @return [String]
+      # @!attribute discard_new_per_subject
+      #   Whether a subject that holds max_msgs_per_subject messages refuses
+      #   new ones, instead of discarding its oldest. Needs discard "new" and
+      #   max_msgs_per_subject; the server reports false as nil.
+      #   @return [Boolean, nil]
       # @!attribute storage
       #   @return [String]
       # @!attribute num_replicas
       #   @return [Integer]
       # @!attribute duplicate_window
+      #   Nanoseconds within which the stream stores a message only once for
+      #   each Header::MSG_ID. Unless set, it is 2 minutes, except that
+      #   mirrors, and since nats-server v2.14.0 streams with sources, get
+      #   none: the messages published to them are not deduplicated.
+      #   @return [Integer]
+      # @!attribute compression
+      #   Storage compression of a file based stream, "s2" or "none"
+      #   (requires nats-server v2.10.0).
+      #   @return [String]
+      # @!attribute first_seq
+      #   The sequence of the first message stored in a new stream
+      #   (requires nats-server v2.10.0).
       #   @return [Integer]
+      # @!attribute subject_transform
+      #   Transform applied to the subject of every message stored, as
+      #   `{src:, dest:}` (requires nats-server v2.10.0).
+      #   @return [Hash]
+      # @!attribute consumer_limits
+      #   Defaults and upper limits for the stream's consumers, as
+      #   `{inactive_threshold:, max_ack_pending:}`. Like the other durations
+      #   of a stream, inactive_threshold is in nanoseconds
+      #   (requires nats-server v2.10.0).
+      #   @return [Hash]
+      # @!attribute allow_msg_ttl
+      #   Whether messages can be published with a TTL of their own
+      #   (requires nats-server v2.11.0). Once enabled, it cannot be
+      #   disabled, and before v2.11.2 it cannot be enabled by an update.
+      #   @return [Boolean]
+      # @!attribute subject_delete_marker_ttl
+      #   Nanoseconds to keep the marker that the server leaves when the last
+      #   message of a subject expires, at least a second (requires
+      #   nats-server v2.11.0). Before v2.11.2 it needs allow_msg_ttl. From
+      #   v2.11.2 on, setting it enables allow_msg_ttl and allow_rollup_hdrs,
+      #   and allows purges, so an update cannot set it on a stream that
+      #   denies them.
+      #   @return [Integer]
+      # @!attribute allow_msg_counter
+      #   Whether the stream holds counters, which cannot change later
+      #   (requires nats-server v2.12.0).
+      #   @return [Boolean]
+      # @!attribute allow_atomic
+      #   Whether messages can be published in atomic batches
+      #   (requires nats-server v2.12.0).
+      #   @return [Boolean]
+      # @!attribute allow_msg_schedules
+      #   Whether messages can schedule messages (requires nats-server
+      #   v2.12.0). Once enabled, it cannot be disabled. Setting it enables
+      #   allow_rollup_hdrs and allows purges, so an update cannot set it on
+      #   a stream that denies them.
+      #   @return [Boolean]
+      # @!attribute persist_mode
+      #   "async" to acknowledge messages before they are flushed to disk,
+      #   or "default"; the server reports the default as nil. It cannot
+      #   change later (requires nats-server v2.12.0).
+      #   @return [String, nil]
+      # @!attribute allow_batched
+      #   Whether messages can be published in fast batches
+      #   (requires nats-server v2.14.0).
+      #   @return [Boolean]
       StreamConfig = Struct.new(
         :name,
         :description,
@@ -198,6 +374,18 @@ module NATS
         :allow_direct,
         :mirror_direct,
         :metadata,
+        :compression,
+        :first_seq,
+        :subject_transform,
+        :consumer_limits,
+        :allow_msg_ttl,
+        :subject_delete_marker_ttl,
+        :allow_msg_counter,
+        :allow_atomic,
+        :allow_msg_schedules,
+        :persist_mode,
+        :allow_batched,
+        :discard_new_per_subject,
         keyword_init: true
       ) do
         def initialize(opts = {})
@@ -220,12 +408,32 @@ module NATS
       #   @return [Hash]
       # @!attribute domain
       #   @return [String]
+      # @!attribute mirror
+      #   State of the stream's mirror, such as its lag and subject
+      #   transforms, as a Hash.
+      #   @return [Hash]
+      # @!attribute sources
+      #   State of each of the stream's sources, such as its lag and subject
+      #   transforms, as Hashes.
+      #   @return [Array<Hash>]
+      # @!attribute cluster
+      #   The cluster of the stream, such as its leader, its replicas and,
+      #   as leader_since, when the leader was elected (requires nats-server
+      #   v2.12.0). A standalone server reports only itself, as the leader.
+      #   The values are the server's: leader_since is a String, and the
+      #   active of the replicas is in nanoseconds.
+      #   @return [Hash]
+      # @!attribute ts
+      #   When the server reported this info (requires nats-server v2.10.0).
+      #   @return [Time]
       StreamInfo = Struct.new(:type, :config, :created, :state, :domain,
+        :mirror, :sources, :cluster, :ts,
         keyword_init: true) do
         def initialize(opts = {})
           opts[:config] = StreamConfig.new(opts[:config])
           opts[:state] = StreamState.new(opts[:state])
           opts[:created] = ::Time.parse(opts[:created])
+          opts[:ts] = ::Time.parse(opts[:ts]) if opts[:ts]
 
           # Filter fields and freeze.
           rem = opts.keys - members

data/lib/nats/io/jetstream/errors.rb

@@ -115,6 +115,31 @@ module NATS
           @code ||= 400
         end
       end
+
+      # When create_consumer finds the consumer already exists with a
+      # different configuration.
+      class ConsumerAlreadyExists < BadRequest; end
+
+      # When update_consumer finds no consumer to update. The server reports
+      # it as a bad request, so unlike ConsumerNotFound it is not NotFound.
+      class ConsumerDoesNotExist < BadRequest; end
+
+      # When reset_consumer is given a sequence that the consumer cannot be
+      # reset to: one before its start, or any for a consumer that does
+      # not deliver all messages or from a start sequence or time.
+      class ConsumerInvalidReset < BadRequest; end
+
+      # When a fetch from a consumer with the pinned_client priority policy
+      # finds the subscription no longer pinned, as its pin expired or it
+      # was unpinned. The subscription forgets its pin, so that its next
+      # fetch can be pinned again.
+      # This condition is represented with a message that has 423 status code header.
+      class PinIdMismatch < APIError
+        def initialize(params = {})
+          super
+          @code ||= 423
+        end
+      end
     end
   end
 end

data/lib/nats/io/jetstream/header.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+# Copyright 2026 The NATS Authors
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+module NATS
+  class JetStream
+    # Header names headers that publishers set for JetStream, and that
+    # JetStream sets on the messages that it stores, republishes or returns
+    # from direct gets.
+    #
+    # @example Publish unless the subject got another message since sequence 10
+    #   js.publish("orders.1", data, header: {
+    #     NATS::JetStream::Header::EXPECTED_LAST_SUBJECT_SEQUENCE => "10"
+    #   })
+    module Header
+      # Id of the message; the stream stores a message only once for each
+      # id within its duplicate_window.
+      MSG_ID = "Nats-Msg-Id"
+      # Name of the stream that has to store the message.
+      EXPECTED_STREAM = "Nats-Expected-Stream"
+      # Sequence of the last message that the stream has to have.
+      EXPECTED_LAST_SEQUENCE = "Nats-Expected-Last-Sequence"
+      # Sequence of the last message that the subject has to have.
+      EXPECTED_LAST_SUBJECT_SEQUENCE = "Nats-Expected-Last-Subject-Sequence"
+      # Subject for EXPECTED_LAST_SUBJECT_SEQUENCE to check instead of the
+      # subject of the message (requires nats-server v2.11.0).
+      EXPECTED_LAST_SUBJECT_SEQUENCE_SUBJECT = "Nats-Expected-Last-Subject-Sequence-Subject"
+      # Id of the last message that the stream has to have.
+      EXPECTED_LAST_MSG_ID = "Nats-Expected-Last-Msg-Id"
+      # "sub" to remove the earlier messages of the subject, or "all" those
+      # of the stream, as the message is stored.
+      ROLLUP = "Nats-Rollup"
+
+      # TTL of the message: seconds, a Go duration such as "1h", or "never"
+      # (requires nats-server v2.11.0).
+      MSG_TTL = "Nats-TTL"
+      # Set by the server on the marker it leaves when the last message of a
+      # subject expires, to "MaxAge" (requires nats-server v2.11.0).
+      MARKER_REASON = "Nats-Marker-Reason"
+
+      # Set by the server on the messages that it republishes or returns
+      # from direct gets, to the stream of the message.
+      STREAM = "Nats-Stream"
+      # Set with STREAM, to the subject of the message.
+      SUBJECT = "Nats-Subject"
+      # Set with STREAM, to the sequence of the message in the stream.
+      SEQUENCE = "Nats-Sequence"
+      # Set with STREAM, to when the stream stored the message.
+      TIME_STAMP = "Nats-Time-Stamp"
+      # Set by the server on the messages that it republishes, to the
+      # sequence of the message before on the same subject, or "0".
+      LAST_SEQUENCE = "Nats-Last-Sequence"
+      # Set by the server on the messages that a stream sources, starting
+      # with the name of the stream they come from and their sequence there.
+      STREAM_SOURCE = "Nats-Stream-Source"
+
+      # Id of an atomic batch, of up to 64 characters
+      # (requires nats-server v2.12.0).
+      BATCH_ID = "Nats-Batch-Id"
+      # Sequence of the message in its atomic batch, from 1.
+      BATCH_SEQUENCE = "Nats-Batch-Sequence"
+      # "1" to commit an atomic batch with the message, or, since nats-server
+      # v2.14.0, "eob" to commit it without storing the message.
+      BATCH_COMMIT = "Nats-Batch-Commit"
+
+      # Makes the message a schedule: "@at" and an RFC 3339 time (requires
+      # nats-server v2.12.0), or "@every" and a Go duration, a cron
+      # expression with seconds, or "@hourly", "@daily" (or "@midnight"),
+      # "@weekly", "@monthly" or "@yearly" (or "@annually")
+      # (requires nats-server v2.14.0).
+      SCHEDULE = "Nats-Schedule"
+      # Subject that the schedule publishes its messages to.
+      SCHEDULE_TARGET = "Nats-Schedule-Target"
+      # Subject whose last message the schedule publishes, instead of its
+      # own (requires nats-server v2.14.0).
+      SCHEDULE_SOURCE = "Nats-Schedule-Source"
+      # MSG_TTL of the messages that the schedule publishes.
+      SCHEDULE_TTL = "Nats-Schedule-TTL"
+      # Time zone of a cron schedule, such as "Europe/Warsaw"
+      # (requires nats-server v2.14.0).
+      SCHEDULE_TIME_ZONE = "Nats-Schedule-Time-Zone"
+      # "sub" to roll up the target with each message that the schedule
+      # publishes (requires nats-server v2.14.0).
+      SCHEDULE_ROLLUP = "Nats-Schedule-Rollup"
+      # Set by the server on the messages that a schedule publishes, to the
+      # subject of the schedule. With SCHEDULE_NEXT "purge", names the
+      # schedule to cancel.
+      SCHEDULER = "Nats-Scheduler"
+      # Set by the server on the messages that a schedule publishes, to when
+      # the schedule fires next, or to "purge" when it does not. Published
+      # as "purge", cancels the SCHEDULER schedule.
+      SCHEDULE_NEXT = "Nats-Schedule-Next"
+
+      # The API level that the server has to have for a JetStream API
+      # request, a pull, a direct get, or a message of an atomic batch
+      # (since nats-server v2.12.1) or a fast batch, which it otherwise
+      # refuses with status 412, and err_code 10185 for API requests and
+      # batches (requires nats-server v2.12.0). The server stores batch
+      # messages without it, and plain publishes with it, as sent.
+      REQUIRED_API_LEVEL = "Nats-Required-Api-Level"
+    end
+  end
+end

data/lib/nats/io/jetstream/js/header.rb

@@ -29,6 +29,7 @@ module NATS
         ExpectedLastMsgID = "Nats-Expected-Last-Msg-Id"
         LastConsumerSeq = "Nats-Last-Consumer"
         LastStreamSeq = "Nats-Last-Stream"
+        PinId = "Nats-Pin-Id"
 
         # rubocop:enable Naming/ConstantName
       end

data/lib/nats/io/jetstream/js/status.rb

@@ -24,6 +24,7 @@ module NATS
         NoMsgs = "404"
         NotFound = "404"
         RequestTimeout = "408"
+        PinIdMismatch = "423"
         ServiceUnavailable = "503"
 
         # rubocop:enable Naming/ConstantName

data/lib/nats/io/jetstream/js.rb

@@ -32,11 +32,28 @@ module NATS
           req[:batch] = next_req[:batch]
           req[:expires] = next_req[:expires].to_i if next_req[:expires]
           req[:no_wait] = next_req[:no_wait] if next_req[:no_wait]
+          # Priority groups (requires nats-server v2.11.0).
+          req.merge!(next_req.slice(:group, :min_pending, :min_ack_pending, :priority, :id).compact)
           req.to_json
         end
 
+        # parse_time parses a time from the server, which sends Go's zero
+        # time for a time that is not set.
+        def parse_time(time)
+          return if time.nil?
+
+          time = ::Time.parse(time)
+          time unless time.year == 1
+        end
+
+        # is_status_msg tells whether the server sent a message as a status:
+        # one with a Status header and no reply. A message of a stream can
+        # have a Status header too, but a consumer delivers it with a reply
+        # to ack it.
         def is_status_msg(msg)
-          (!msg.nil? and (!msg.header.nil? and msg.header[Header::Status]))
+          return false if msg.nil? || msg.header.nil?
+
+          !msg.header[Header::Status].nil? && msg.reply.to_s.empty?
         end
 
         # check_503_error raises exception when a NATS::Msg has a 503 status header.
@@ -61,6 +78,8 @@ module NATS
           check_503_error(msg)
           code = msg.header[JS::Header::Status]
           desc = msg.header[JS::Header::Desc]
+          return ::NATS::JetStream::Error::PinIdMismatch.new({description: desc}) if code == Status::PinIdMismatch
+
           ::NATS::JetStream::API::Error.new({code: code, description: desc})
         end
 
@@ -83,7 +102,16 @@ module NATS
               ::NATS::JetStream::Error::NotFound.new(err)
             end
           when 400
-            ::NATS::JetStream::Error::BadRequest.new(err)
+            case err[:err_code]
+            when 10148
+              ::NATS::JetStream::Error::ConsumerAlreadyExists.new(err)
+            when 10149
+              ::NATS::JetStream::Error::ConsumerDoesNotExist.new(err)
+            when 10204
+              ::NATS::JetStream::Error::ConsumerInvalidReset.new(err)
+            else
+              ::NATS::JetStream::Error::BadRequest.new(err)
+            end
           else
             ::NATS::JetStream::API::Error.new(err)
           end