nats-pure 2.6.0 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d5c22758be6db2c05382a55c718c2c4f836a2c723f77820d4728bbf1538f30b
-  data.tar.gz: 1745fb8cfa406b598099779a027a3cc3dcc4cee28c22fd7c08e1b156b6ce4a5b
+  metadata.gz: 18d1e6a53bcd6c3dc5c3fe1aa9f03c5b1d17a68fdf6381bae8f7ef3c6a6995b3
+  data.tar.gz: ce0f4719c5902ad9b7bec424f341cab7f39a980de31452fe445fbe6733a401d0
 SHA512:
-  metadata.gz: 84b049092f60f34c3ca6b5a8ac2b4334a1a32dbaefd2659424f91db3472df105604bbddd4989793a56757a9cdee1c710db6b52fc02e40b95f64bc0b0eae21dd6
-  data.tar.gz: 38585616a5820faefe491c8c16d815bc52759e0cd2b7f77ab5b3a0227d3728720c4f1ac56d6d2af6354c2c53e54245ab48ce71c2a063efe3fe737e60e21c6af7
+  metadata.gz: 48591880c765700baac0ab6762fc437ef1da21cd728c43f64886547da8607208f8b68599cb75802ca3bc82d1e10e6c3875c9eac9c86e9ec955f035049d4e25db
+  data.tar.gz: 6de527742e1cb8a380f2806dae0f365612f7a6dbc622ebda50bc9cb46d3a4221dc296308c4c82b9c72c108dc0ff5462138f31aaf8898429d1028e1b7b2c50573

data/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 ## main
 
+## v2.7.0
+
+This release adds the JetStream features of nats-server 2.10 to 2.14 that the
+client lacked, such as per-message TTLs, message schedules, and consumers that
+can be paused, reset and serve priority groups. `fetch` now pulls once and
+waits, like `Fetch` of the nats.go `jetstream` package, and a subscription read
+with `next_msg` no longer drops every message after its first 64 MiB. Code that
+passed stream or KV settings the client used to drop now sends them; see Changed.
+
+### Added
+
+- JetStream: `fetch(batch, no_wait: true)` takes what the server delivers at once, without waiting for more messages, like `FetchNoWait` of nats.go and `fetch` of nats.rs: an empty Array when none are pending, or when other pulls wait for more than are pending. While the consumer may not deliver more until some are acked (`max_ack_pending`), the server holds the pull back, and the fetch returns what it got once its timeout is up, 1 second by default. (#195)
+- JetStream: `fetch` takes a block, to which it passes each delivery as it comes, in the calling thread, so that the message can be acked before the `ack_wait` of the consumer is up: `psub.fetch(100, timeout: 60) { |msg| msg.ack }`. It still returns the messages. (#195)
+- JetStream: stream configs take the settings added in nats-server 2.10: `compression`, `first_seq`, `subject_transform` and `consumer_limits` (whose `inactive_threshold` is in nanoseconds, like the other stream durations). They used to be dropped, so a stream could not be created with them, and sending a fetched config back as an update left them out. (#191)
+- JetStream: stream configs take the settings added in nats-server 2.11 to 2.14: `allow_msg_ttl` and `subject_delete_marker_ttl` (2.11; the latter in nanoseconds, like the other stream durations), `allow_msg_counter`, `allow_atomic`, `allow_msg_schedules` and `persist_mode` (2.12), and `allow_batched` (2.14). Like nats.go, the client does not send them at their defaults, such as `false`, as servers since 2.12, and 2.11 ones in strict mode, refuse settings they do not know. (#194)
+- JetStream: `NATS::JetStream::Header` names the JetStream headers: those for deduplication and optimistic concurrency, such as `MSG_ID` and `EXPECTED_LAST_SUBJECT_SEQUENCE`, and those of nats-server 2.11 to 2.14: `EXPECTED_LAST_SUBJECT_SEQUENCE_SUBJECT`, `MSG_TTL` and `MARKER_REASON` (2.11), the atomic batch headers (2.12; `BATCH_COMMIT` `"eob"` needs 2.14), the message schedule headers (2.12 and 2.14), and `REQUIRED_API_LEVEL` (2.12), which JetStream API requests send as a `header:` option, as in `js.stream_info(name, header: {...})`. It also names the headers that the server sets on the messages it republishes, sources or returns from direct gets, such as `STREAM` and `SEQUENCE`. (#194)
+- JetStream: `js.publish` takes `ttl:`, the whole seconds after which the stream removes the message, or `:never` to keep it past the stream's `max_age`, for streams with `allow_msg_ttl` (nats-server 2.11). Other values raise `ArgumentError`. (#194)
+- JetStream: `js.publish` takes `schedule:`, which makes the message a schedule that publishes it to its `target:` subject: once, `at:` a Time (nats-server 2.12), `every:` so many seconds, or on a `cron:` expression with seconds, in UTC or a `time_zone:` (2.14). The schedule can give the messages it publishes a `ttl:` (2.12), and publish the last message of a `source:` subject instead and roll up the target (`rollup: true`) (2.14; 2.12 ignores both). The stream needs `allow_msg_schedules`. An invalid schedule raises `ArgumentError`, before anything is sent; `NATS::JetStream::Header::SCHEDULE_NEXT` and `SCHEDULER` cancel a schedule. (#194)
+- JetStream: `stream_info` reports the stream's `mirror` and `sources`, including their subject transforms, and both `stream_info` and `consumer_info` report when the server reported the info, as `ts`. (#191)
+- JetStream: `create_consumer` and `update_consumer` use the create and update actions of nats-server 2.10. Creating a consumer that exists with a different config raises `NATS::JetStream::Error::ConsumerAlreadyExists`, and updating one that does not exist raises `NATS::JetStream::Error::ConsumerDoesNotExist`; both are `BadRequest` errors. An update replaces the whole config, so fields left out take their defaults. `add_consumer` still creates or updates. (#191)
+- JetStream: `msg.term(reason: "...")` passes the reason on to the server's advisory for the terminated message. Servers before 2.10.4 do not terminate a message given a reason. (#191)
+- JetStream: consumers can be paused (nats-server 2.11): created paused with `pause_until` in their config, as a `Time` or an RFC 3339 String, or paused and resumed with `pause_consumer` and `resume_consumer`; updating a consumer keeps its pause. `consumer_info` reports whether a consumer is `paused`, and the seconds until it resumes, as `pause_remaining`. Servers before 2.11 create consumers unpaused, and let `pause_consumer` and `resume_consumer` time out. (#193)
+- JetStream: pull consumers can serve priority groups (nats-server 2.11). Consumer configs take `priority_policy`, `priority_groups` and `priority_timeout` (in seconds, like the other consumer durations), and `consumer_info` reports the state of the groups as `priority_groups`. `fetch` takes the `group` to pull from, `min_pending` and `min_ack_pending` for the `"overflow"` policy, and `priority` for the `"prioritized"` policy of nats-server 2.12. (#193)
+- JetStream: with the `"pinned_client"` priority policy, a pull subscription keeps the pin id that the server delivers with its messages, and sends it with its pulls. When the server says that the subscription is no longer pinned, as its pin expired or it was unpinned with the new `unpin_consumer`, a fetch that got no messages raises `NATS::JetStream::Error::PinIdMismatch`, and the next fetch can be pinned again. The server counts the consumer's `priority_timeout` from each pull, not while a pull waits, so keep the fetch timeout, plus the time between fetches, below it, or the subscription loses its pin. (#193, #195)
+- JetStream: `reset_consumer` makes a consumer deliver again from after its ack floor, or from the stream sequence given as `seq` (nats-server 2.14). A sequence that the deliver policy of the consumer does not let it be reset to raises `NATS::JetStream::Error::ConsumerInvalidReset`, a `BadRequest` error, and one that is not an integer of 0 or more raises `ArgumentError`. For a stream or consumer that does not exist, and with servers before 2.14, the request times out. (#193)
+- JetStream: `stream_info` and `consumer_info` report the `cluster` of the stream or consumer as a Hash, including when its leader was elected, as `leader_since` (nats-server 2.12). `consumer_info` used to drop it. (#193)
+- KV: buckets can be created with `compression: true` and with `metadata`, which `status.compressed?` and `status.metadata` report. (#191)
+- KV: `watch` takes an Array of keys, watched by a single consumer (nats-server 2.10). An empty Array watches all keys. (#191)
+
+### Changed
+
+- JetStream: `fetch` pulls once, for the whole batch, and waits: it returns as soon as it has the batch, and otherwise the messages that came when its timeout is up, like `Fetch` of the nats.go `jetstream` package and `batch` of nats.rs. A fetch of more than one message used to ask first, without waiting, for the messages that were pending. When it got some, it then waited out its timeout without pulling for more, so it neither took the messages that came meanwhile nor returned sooner. When other pulls of the consumer waited for more messages than were pending, the server turned that first pull away (408 Requests Pending), and `fetch` raised `NATS::IO::Timeout` at once. (#195)
+- JetStream: a pull subscription subscribes to `<inbox>.*`, which `subject` now returns, and each pull gets a reply subject of its own under it, as ADR-13 describes, so that a fetch tells the status that ended its own pull from those that ended the pulls of other fetches. A `fetch` with `no_wait: true` pulls with a subscription of its own, which it drops when done, so that its pull does not linger when the server holds it, as while the consumer may not deliver more messages until some are acked (`max_ack_pending`): the fetch then returns what it got once its timeout is up, and leaves what comes later to the next fetch. A server with leafnodes or gateways delivers to a pull until it is 2 seconds old even once the subscription is gone, so the subscription stays until then. (#195)
+- JetStream: `fetch` raises `ArgumentError` for a `timeout` that is not a finite positive number, such as 0, with which it used to raise `NATS::IO::Timeout` at once. It leaves the options it is given unchanged; it used to set their `:timeout`. (#195)
+- JetStream: as `fetch` always pulls with an expiry of its timeout, a consumer whose `max_expires` is shorter than the timeout turns every fetch away, with 409 "Exceeded MaxRequestExpires", raised as `NATS::JetStream::API::Error`. A fetch of more than one message used to get the messages that were pending first, with a pull that had no expiry. Pass a `timeout` no longer than the consumer's `max_expires`. (#195)
+- JetStream: `fetch` returns when the server ends its pull, so it takes its timeout plus the round trip to the server. When no end comes, it waits up to 1 second longer, like nats.go, before it returns what it got or raises `NATS::IO::Timeout`. (#195)
+- JetStream and KV: settings that used to be dropped are now sent. Code that already passed `compression`, `first_seq`, `subject_transform` or `consumer_limits` to `add_stream`, or `compression` or `metadata` to `create_key_value`, created its streams and buckets without them, so calling it again for an existing stream or bucket now fails with "stream name already in use with a different configuration" (err_code 10058). Apply the setting with `update_stream`, or stop passing it. (#191)
+- JetStream: the same goes for the settings of nats-server 2.11 to 2.14: code that passed them to `add_stream` created its streams without them, so calling it again for an existing stream now fails with err_code 10058. `update_stream` applies them, except `allow_msg_counter` and `persist_mode`, which a stream cannot change. (#194)
+- JetStream: consumer configs now send `pause_until`, `priority_policy`, `priority_groups` and `priority_timeout`, which used to be dropped. As `add_consumer` creates or updates, code that already passed the priority settings to it now gives an existing consumer priority groups, after which the server turns away pulls that name no group (400 "Priority Group missing"). (#193)
+- KV: `create_key_value` takes only `true` or `false` for `compression`; anything else, such as `"s2"`, which used to be ignored, raises `ArgumentError`. (#191)
+- JetStream: `add_consumer` leaves the `ConsumerConfig` it is given unchanged. It used to set its `name` and a default `ack_policy`, and convert its durations to nanoseconds, so passing the same config again sent durations a billion times too long. (#191)
+- JetStream: two `stream_info` or `consumer_info` results are no longer `==` unless they were reported at the same time, as they now carry `ts`, and the `cluster`, `mirror` and `sources`, whose lag and activity change all the time, even with servers that do not report `ts`. (#191, #193)
+- KV: `watch` no longer looks up the bucket's stream before creating its consumer. (#191)
+
+### Fixed
+
+- JetStream: `update_stream` with the config from `stream_info` failed with err_code 10052, such as "message TTL status can not be disabled", for streams with per-message TTLs, subject delete markers, counters, message schedules or async persistence, and turned off atomic and fast batches, as `StreamConfig` dropped the settings of nats-server 2.11 to 2.14. It now keeps them. (#194)
+- JetStream: `StreamConfig` dropped `discard_new_per_subject`, so `add_stream` created streams without it, and `update_stream` with the config from `stream_info` turned it off: a subject that held `max_msgs_per_subject` messages then discarded its oldest message instead of refusing the new one. It now keeps it. (#199)
+- JetStream: `js.publish` with `stream:` added `Nats-Expected-Stream` to the header Hash it was given, so a caller that reused the Hash sent it with its later publishes. (#194)
+- JetStream: `js.publish` raised `ArgumentError: unknown keywords` after the server had stored the message, when publishing to a stream with counters or committing an atomic batch, as the acks of nats-server 2.12 carry `val`, `batch` and `count`. `PubAck` now has these fields and ignores any it does not know, so fields added to acks later cannot break publish. (#192, #177, thanks @jnowakplacewise)
+- JetStream: `add_consumer`, `consumer_info`, `subscribe` and `pull_subscribe` raised `NoMethodError` for consumers that do not ack (`ack_policy: "none"`) created without an `ack_wait`, after the consumer had been created. The server omits `ack_wait` for them, and `config.ack_wait` is now `nil`. (#192)
+- JetStream: `fetch` took a status that an earlier pull had left in the subscription, such as the 408 of a fetch that timed out, for the reply to its own pull, and raised `NATS::IO::Timeout` at once, even with messages pending: a fetch of more than one message with any such status, a fetch of one message with a second one. `fetch` now first takes what earlier pulls left, and pulls for the rest only. And a fetch that got messages before an error status, such as 409 Consumer Deleted, raised the error and dropped them; like nats.go, it now returns them. (#193, #195)
+- JetStream: when threads fetched from the same subscription at once, a fetch could take the 408 that ended the pull of another for the end of its own, and raise `NATS::IO::Timeout` before its timeout. (#195)
+- JetStream: `fetch` pulled with an expiry a little short of its timeout only after a first pull, which did not wait, came back empty, so its pull outlived it by the time that first pull took: a message delivered meanwhile waited in the subscription for the next fetch, and, if none came, was delivered again once the `ack_wait` was up. A fetch now waits for the server to end its pull, which expires with its timeout. (#195)
+- JetStream: a `fetch` that waited longer than the `ack_wait` of the consumer returned a message twice when the server delivered it again meanwhile. It now returns each message once, as last delivered. (#195)
+- JetStream: `fetch` took a message of the stream with a `Status` header for a status of the server, and raised an error or ended without it. Statuses are now only the messages with a `Status` header that the server sends without a reply. (#195)
+- JetStream: a `fetch` of one message raised `TypeError: nil can't be coerced into Float` when threads fetched from the same subscription at once: woken up for a message that another thread took, it did not wait on. It now waits until its timeout. (#193, #181, thanks @route)
+- JetStream: a `fetch` of one message raised `NATS::IO::Timeout` ("nats: fetch request timeout") before its timeout when a status that ended an earlier pull, such as the 408 of a fetch that had just timed out, came while it waited, and left its own message for the next fetch. Like nats.go, it now waits on for its message until its timeout. (#193)
+- JetStream: `fetch` could miss the reply to its pull when it came before the fetch waited for it, as when its thread was preempted: a fetch of one message then waited out its timeout and raised `NATS::IO::Timeout`, leaving its message to be redelivered after the ack wait, and a fetch of more messages returned only the first one, after its timeout. `fetch` now takes what is there before it waits. (#193)
+- KV: after its consumer was recreated, as after a server restart, a watcher yielded the entries of every key in the bucket instead of the watched keys. The recreated consumer now keeps the keys filter. (#192)
+- KV: after its consumer was recreated, a watcher yielded its last entry again, and a watcher with no entries yet, such as one on an empty bucket, never got its consumer back (`err_code` 10094) and stayed silent. The recreated consumer now starts after the last entry. (#192, #175, thanks @Xayc73)
+- A subscription without a callback, read with `next_msg`, dropped every message and reported `NATS::IO::SlowConsumer` once it had received its `pending_bytes_limit` in all, 64 MiB by default, however fast it was read, as `next_msg` did not take the messages it returned off the pending bytes. (#196)
+
 ## v2.6.0
 
 This release prepares nats-pure for nats-server 2.16, whose new JetStream

data/README.md

@@ -102,6 +102,89 @@ loop do
 end
 ```
 
+`fetch` returns as soon as it has the batch, or once its timeout is up, the
+messages that came. With `no_wait: true`, it takes what the server delivers at
+once, without waiting for more. Given a block, it passes each message to it as it comes,
+so that the message can be acked before the `ack_wait` of the consumer is up:
+
+```ruby
+psub.fetch(100, timeout: 60) do |msg|
+  puts msg.data
+  msg.ack
+end
+```
+
+Messages can expire on their own, in streams that allow it (nats-server 2.11):
+
+```ruby
+js.add_stream(name: "sessions", subjects: ["sessions.>"], allow_msg_ttl: true)
+
+# Removed after an hour. With ttl: :never, kept past the max_age of the stream.
+js.publish("sessions.42", "token", ttl: 3600)
+```
+
+Messages can also be scheduled (nats-server 2.12; `every:` and `cron:` need 2.14):
+
+```ruby
+js.add_stream(name: "reminders", subjects: ["reminders.>", "due.>"], allow_msg_schedules: true)
+
+# Published to due.42 in an hour. Another schedule on reminders.42 replaces it.
+js.publish("reminders.42", "call back", schedule: {at: Time.now + 3600, target: "due.42"})
+
+# Published to due.standup at 9:00 on weekdays, Warsaw time.
+js.publish("reminders.standup", "stand-up",
+  schedule: {cron: "0 0 9 * * 1-5", time_zone: "Europe/Warsaw", target: "due.standup"})
+
+# Cancels the schedule on reminders.42.
+js.publish("reminders.cancelled", "", header: {
+  NATS::JetStream::Header::SCHEDULE_NEXT => "purge",
+  NATS::JetStream::Header::SCHEDULER => "reminders.42"
+})
+```
+
+Streams and consumers can also be managed directly:
+
+```ruby
+# Compressed, and no consumer may have more than 1000 unacknowledged messages.
+js.add_stream(name: "orders", subjects: ["orders.>"], compression: "s2",
+  consumer_limits: {max_ack_pending: 1000})
+
+config = {durable_name: "billing", filter_subject: "orders.paid", max_ack_pending: 100}
+
+# Fails with NATS::JetStream::Error::ConsumerAlreadyExists if "billing"
+# exists with a different config.
+js.create_consumer("orders", config)
+
+# An update replaces the whole config, so send all of it again.
+# Fails with NATS::JetStream::Error::ConsumerDoesNotExist if there is no "billing".
+js.update_consumer("orders", config.merge(max_ack_pending: 200))
+
+# Deliver nothing for an hour, or until resumed.
+js.pause_consumer("orders", "billing", Time.now + 3600)
+js.resume_consumer("orders", "billing")
+```
+
+Pull consumers can serve priority groups. With the `"pinned_client"` policy,
+the server delivers to one subscription at a time, and to another once it
+stops pulling for `priority_timeout` seconds. The server counts it from
+each pull, not while a pull waits: keep the fetch timeout, 5 seconds by
+default, plus the time between fetches, below `priority_timeout`, or the
+subscription can lose its pin:
+
+```ruby
+js.create_consumer("orders", durable_name: "shipping", filter_subject: "orders.paid",
+  priority_policy: "pinned_client", priority_groups: ["workers"], priority_timeout: 60)
+
+psub = js.pull_subscribe("orders.paid", "shipping", stream: "orders")
+begin
+  psub.fetch(5, group: "workers").each(&:ack)
+rescue NATS::JetStream::Error::PinIdMismatch
+  # This subscription is no longer pinned; the next fetch may be pinned again.
+rescue NATS::IO::Timeout
+  # Nothing to do, or another subscription is pinned.
+end
+```
+
 ## Service API
 
 The service API allows you to easily [build NATS services](docs/service_api.md).

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