nats-pure 2.6.0 → 2.7.0

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

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

@@ -28,6 +28,23 @@ module NATS
     #
     #
     module Manager
+      # The defaults of the stream settings of nats-server 2.11 to 2.14,
+      # which are not sent, as nats.go does not send them either, so that
+      # servers that do not know the settings take configs that leave them
+      # at their defaults. Nor is discard_new_per_subject at its default,
+      # which the client did not send before it knew the setting.
+      UNSENT_STREAM_DEFAULTS = {
+        discard_new_per_subject: [false],
+        allow_msg_ttl: [false],
+        subject_delete_marker_ttl: [0],
+        allow_msg_counter: [false],
+        allow_atomic: [false],
+        allow_msg_schedules: [false],
+        persist_mode: ["", "default"],
+        allow_batched: [false]
+      }.freeze
+      private_constant :UNSENT_STREAM_DEFAULTS
+
       # add_stream creates a stream with a given config.
       # @param config [JetStream::API::StreamConfig] Configuration of the stream to create.
       # @param params [Hash] Options to customize API request.
@@ -44,8 +61,7 @@ module NATS
         raise ArgumentError.new("Spaces, tabs, period (.), greater than (>) or asterisk (*) are prohibited in stream names") if stream =~ /(\s|\.|>|\*)/
         req_subject = "#{@prefix}.STREAM.CREATE.#{stream}"
 
-        cfg = config.to_h.compact
-        result = api_request(req_subject, cfg.to_json, params)
+        result = api_request(req_subject, stream_config_json(config), params)
         JetStream::API::StreamCreateResponse.new(result)
       end
 
@@ -62,7 +78,11 @@ module NATS
         JetStream::API::StreamInfo.new(result)
       end
 
-      # update_stream edits an existed stream with a given config.
+      # update_stream edits an existed stream with a given config. The config
+      # replaces the stream's, so pass all of it, as from stream_info.
+      # Updating a mirror without its mirror setting makes it a stream of its
+      # own for good, no longer a mirror (nats-server v2.12.0; older servers
+      # refuse the update).
       # @param config [JetStream::API::StreamConfig] Configuration of the stream to create.
       # @param params [Hash] Options to customize API request.
       # @option params [Float] :timeout Time to wait for response.
@@ -77,8 +97,7 @@ module NATS
         raise ArgumentError.new(":name is required to create streams") unless stream
         raise ArgumentError.new("Spaces, tabs, period (.), greater than (>) or asterisk (*) are prohibited in stream names") if stream =~ /(\s|\.|>|\*)/
         req_subject = "#{@prefix}.STREAM.UPDATE.#{stream}"
-        cfg = config.to_h.compact
-        result = api_request(req_subject, cfg.to_json, params)
+        result = api_request(req_subject, stream_config_json(config), params)
         JetStream::API::StreamCreateResponse.new(result)
       end
 
@@ -95,75 +114,45 @@ module NATS
         result[:success]
       end
 
-      # add_consumer creates a consumer with a given config.
+      # add_consumer creates a consumer with a given config, or updates the
+      # consumer if one with the same name already exists.
       # @param stream [String] Name of the stream.
       # @param config [JetStream::API::ConsumerConfig] Configuration of the consumer to create.
       # @param params [Hash] Options to customize API request.
       # @option params [Float] :timeout Time to wait for response.
       # @return [JetStream::API::ConsumerInfo] The result of creating a Consumer.
       def add_consumer(stream, config, params = {})
-        raise JetStream::Error::InvalidStreamName.new("nats: invalid stream name") if stream.nil? || stream.empty?
-        config = if !config.is_a?(JetStream::API::ConsumerConfig)
-          JetStream::API::ConsumerConfig.new(config)
-        else
-          config
-        end
-        config[:name] ||= config[:durable_name]
-        req_subject = if config[:name]
-          ###############################################################################
-          #                                                                             #
-          #  Using names is the supported way of creating consumers (NATS +v2.9.0.      #
-          #                                                                             #
-          ###############################################################################
-          if config[:filter_subject] && config[:filter_subject] != ">"
-            "#{@prefix}.CONSUMER.CREATE.#{stream}.#{config[:name]}.#{config[:filter_subject]}"
-          else
-            ##############################################################################
-            #                                                                            #
-            # Endpoint to support creating ANY consumer with multi-filters (NATS +v2.10) #
-            #                                                                            #
-            ##############################################################################
-            "#{@prefix}.CONSUMER.CREATE.#{stream}.#{config[:name]}"
-          end
-        elsif config[:durable_name]
-          ###############################################################################
-          #                                                                             #
-          # Endpoint to support creating DURABLES before NATS v2.9.0.                   #
-          #                                                                             #
-          ###############################################################################
-          "#{@prefix}.CONSUMER.DURABLE.CREATE.#{stream}.#{config[:durable_name]}"
-        else
-          ###############################################################################
-          #                                                                             #
-          # Endpoint to support creating EPHEMERALS before NATS v2.9.0.                 #
-          #                                                                             #
-          ###############################################################################
-          "#{@prefix}.CONSUMER.CREATE.#{stream}"
-        end
-
-        config[:ack_policy] ||= JS::Config::AckExplicit
-        # Check if have to normalize ack wait so that it is in nanoseconds for Go compat.
-        if config[:ack_wait]
-          raise ArgumentError.new("nats: invalid ack wait") unless config[:ack_wait].is_a?(Integer)
-          config[:ack_wait] = config[:ack_wait] * ::NATS::NANOSECONDS
-        end
-        if config[:inactive_threshold]
-          raise ArgumentError.new("nats: invalid inactive threshold") unless config[:inactive_threshold].is_a?(Integer)
-          config[:inactive_threshold] = config[:inactive_threshold] * ::NATS::NANOSECONDS
-        end
-        if config[:idle_heartbeat]
-          raise ArgumentError.new("nats: invalid idle heartbeat") unless config[:idle_heartbeat].is_a?(Integer)
-          config[:idle_heartbeat] = config[:idle_heartbeat] * ::NATS::NANOSECONDS
-        end
+        upsert_consumer(stream, config, nil, params)
+      end
 
-        cfg = config.to_h.compact
-        req = {
-          stream_name: stream,
-          config: cfg
-        }
+      # create_consumer creates a consumer with a given config. Creating a
+      # consumer that already exists with the same config succeeds; one that
+      # exists with a different config raises ConsumerAlreadyExists.
+      # Requires nats-server v2.10.0.
+      # @param stream [String] Name of the stream.
+      # @param config [JetStream::API::ConsumerConfig] Configuration of the consumer to create.
+      # @param params [Hash] Options to customize API request.
+      # @option params [Float] :timeout Time to wait for response.
+      # @return [JetStream::API::ConsumerInfo] The result of creating a Consumer.
+      def create_consumer(stream, config, params = {})
+        upsert_consumer(stream, config, "create", params)
+      end
 
-        result = api_request(req_subject, req.to_json, params)
-        JetStream::API::ConsumerInfo.new(result).freeze
+      # update_consumer replaces the config of an existing consumer, named by
+      # the config's name or durable_name, so fields left out take their
+      # defaults: pass the whole config, with the changes. The config from
+      # consumer_info lacks the settings this client does not know, and has
+      # its durations rounded down to whole seconds. A consumer that does
+      # not exist raises ConsumerDoesNotExist; the server decides which
+      # fields may change, and keeps the pause of the consumer, which
+      # pause_consumer and resume_consumer change. Requires nats-server v2.10.0.
+      # @param stream [String] Name of the stream.
+      # @param config [JetStream::API::ConsumerConfig] New configuration of the consumer.
+      # @param params [Hash] Options to customize API request.
+      # @option params [Float] :timeout Time to wait for response.
+      # @return [JetStream::API::ConsumerInfo] The updated Consumer.
+      def update_consumer(stream, config, params = {})
+        upsert_consumer(stream, config, "update", params)
       end
 
       # consumer_info retrieves the current status of a consumer.
@@ -196,6 +185,96 @@ module NATS
         result[:success]
       end
 
+      # pause_consumer pauses a consumer, so that it delivers no messages
+      # until the given time. Requires nats-server v2.11.0: older servers
+      # let the request time out.
+      # @param stream [String] Name of the stream.
+      # @param consumer [String] Name of the consumer.
+      # @param pause_until [Time, String] When to resume, as a Time or as an RFC 3339 String.
+      # @param params [Hash] Options to customize API request.
+      # @option params [Float] :timeout Time to wait for response.
+      # @return [JetStream::API::ConsumerPauseResponse]
+      # @raise [ArgumentError] When pause_until is nil: resume_consumer resumes.
+      # @raise [JetStream::Error::StreamNotFound] When the stream does not exist.
+      # @raise [JetStream::Error::ConsumerNotFound] When the consumer does not exist.
+      # @raise [NATS::Timeout] With a server before v2.11.0.
+      def pause_consumer(stream, consumer, pause_until, params = {})
+        raise ArgumentError.new("nats: a time to pause until is required, resume_consumer resumes") if pause_until.nil?
+
+        request_pause(stream, consumer, {pause_until: rfc3339(pause_until)}, params)
+      end
+
+      # resume_consumer resumes a paused consumer. Requires nats-server
+      # v2.11.0: older servers let the request time out.
+      # @param stream [String] Name of the stream.
+      # @param consumer [String] Name of the consumer.
+      # @param params [Hash] Options to customize API request.
+      # @option params [Float] :timeout Time to wait for response.
+      # @return [JetStream::API::ConsumerPauseResponse]
+      # @raise [JetStream::Error::StreamNotFound] When the stream does not exist.
+      # @raise [JetStream::Error::ConsumerNotFound] When the consumer does not exist.
+      # @raise [NATS::Timeout] With a server before v2.11.0.
+      def resume_consumer(stream, consumer, params = {})
+        request_pause(stream, consumer, {}, params)
+      end
+
+      # unpin_consumer unpins a priority group of a consumer with the
+      # pinned_client priority policy from its subscription, so that the
+      # next subscription to pull is pinned instead. The server tells the
+      # subscription that was pinned once it has a message for its pull, and
+      # its fetch then raises PinIdMismatch; without messages, the fetch
+      # times out. Requires nats-server v2.11.0.
+      # @param stream [String] Name of the stream.
+      # @param consumer [String] Name of the consumer.
+      # @param group [String] Name of the priority group.
+      # @param params [Hash] Options to customize API request.
+      # @option params [Float] :timeout Time to wait for response.
+      # @return [Boolean]
+      # @raise [JetStream::Error::StreamNotFound] When the stream does not exist.
+      # @raise [JetStream::Error::ConsumerNotFound] When the consumer does not exist.
+      # @raise [JetStream::Error::BadRequest] When the consumer has no such group.
+      # @raise [NATS::Timeout] With a server before v2.11.0.
+      def unpin_consumer(stream, consumer, group, params = {})
+        raise JetStream::Error::InvalidStreamName.new("nats: invalid stream name") if stream.nil? || stream.empty?
+        raise JetStream::Error::InvalidConsumerName.new("nats: invalid consumer name") if consumer.nil? || consumer.empty?
+
+        req_subject = "#{@prefix}.CONSUMER.UNPIN.#{stream}.#{consumer}"
+        api_request(req_subject, {group: group}.to_json, params)
+        true
+      end
+
+      # reset_consumer resets the delivery state of a consumer, as if it had
+      # been created again to start from a stream sequence: by default the
+      # one after its ack floor, so that it redelivers the messages that
+      # await acks. Only a consumer that delivers all messages, or from a
+      # start sequence or time, can be given a sequence, and not one before
+      # its start. Requires nats-server v2.14.0: an older server, like a
+      # stream or consumer that does not exist, lets the request time out.
+      # @param stream [String] Name of the stream.
+      # @param consumer [String] Name of the consumer.
+      # @param params [Hash] Options to customize API request.
+      # @option params [Integer] :seq Stream sequence to deliver from; 0, like
+      #   none, for the one after the ack floor.
+      # @option params [Float] :timeout Time to wait for response.
+      # @return [JetStream::API::ConsumerResetResponse]
+      # @raise [ArgumentError] When seq is not an integer of 0 or more.
+      # @raise [JetStream::Error::ConsumerInvalidReset] When the consumer cannot be reset to seq.
+      # @raise [NATS::Timeout] When the stream or consumer does not exist, or the server
+      #   cannot reset consumers.
+      def reset_consumer(stream, consumer, params = {})
+        raise JetStream::Error::InvalidStreamName.new("nats: invalid stream name") if stream.nil? || stream.empty?
+        raise JetStream::Error::InvalidConsumerName.new("nats: invalid consumer name") if consumer.nil? || consumer.empty?
+        seq = params[:seq]
+        if !seq.nil? && !(seq.is_a?(Integer) && seq >= 0)
+          raise ArgumentError.new("nats: seq should be an integer of 0 or more")
+        end
+
+        req_subject = "#{@prefix}.CONSUMER.RESET.#{stream}.#{consumer}"
+        req = {seq: seq}.compact
+        result = api_request(req_subject, req.to_json, params.except(:seq))
+        JetStream::API::ConsumerResetResponse.new(result)
+      end
+
       # find_stream_name_by_subject does a lookup for the stream to which
       # the subject belongs.
       # @param subject [String] The subject that belongs to a stream.
@@ -260,6 +339,102 @@ module NATS
 
       private
 
+      # upsert_consumer sends a consumer create request. The action is
+      # "create", "update", or nil to create or update.
+      def upsert_consumer(stream, config, action, params)
+        raise JetStream::Error::InvalidStreamName.new("nats: invalid stream name") if stream.nil? || stream.empty?
+        # Work on a copy: the durations are converted to nanoseconds below,
+        # and the caller may send the same config again.
+        config = if !config.is_a?(JetStream::API::ConsumerConfig)
+          JetStream::API::ConsumerConfig.new(config)
+        else
+          config.dup
+        end
+        config[:name] ||= config[:durable_name]
+        if action == "update" && (config[:name].nil? || config[:name].empty?)
+          raise ArgumentError.new("nats: the consumer to update needs a name or durable name")
+        end
+        req_subject = if config[:name]
+          ###############################################################################
+          #                                                                             #
+          #  Using names is the supported way of creating consumers (NATS +v2.9.0.      #
+          #                                                                             #
+          ###############################################################################
+          if config[:filter_subject] && config[:filter_subject] != ">"
+            "#{@prefix}.CONSUMER.CREATE.#{stream}.#{config[:name]}.#{config[:filter_subject]}"
+          else
+            ##############################################################################
+            #                                                                            #
+            # Endpoint to support creating ANY consumer with multi-filters (NATS +v2.10) #
+            #                                                                            #
+            ##############################################################################
+            "#{@prefix}.CONSUMER.CREATE.#{stream}.#{config[:name]}"
+          end
+        elsif config[:durable_name]
+          ###############################################################################
+          #                                                                             #
+          # Endpoint to support creating DURABLES before NATS v2.9.0.                   #
+          #                                                                             #
+          ###############################################################################
+          "#{@prefix}.CONSUMER.DURABLE.CREATE.#{stream}.#{config[:durable_name]}"
+        else
+          ###############################################################################
+          #                                                                             #
+          # Endpoint to support creating EPHEMERALS before NATS v2.9.0.                 #
+          #                                                                             #
+          ###############################################################################
+          "#{@prefix}.CONSUMER.CREATE.#{stream}"
+        end
+
+        config[:ack_policy] ||= JS::Config::AckExplicit
+        # Check if have to normalize ack wait so that it is in nanoseconds for Go compat.
+        if config[:ack_wait]
+          raise ArgumentError.new("nats: invalid ack wait") unless config[:ack_wait].is_a?(Integer)
+          config[:ack_wait] = config[:ack_wait] * ::NATS::NANOSECONDS
+        end
+        if config[:inactive_threshold]
+          raise ArgumentError.new("nats: invalid inactive threshold") unless config[:inactive_threshold].is_a?(Integer)
+          config[:inactive_threshold] = config[:inactive_threshold] * ::NATS::NANOSECONDS
+        end
+        if config[:idle_heartbeat]
+          raise ArgumentError.new("nats: invalid idle heartbeat") unless config[:idle_heartbeat].is_a?(Integer)
+          config[:idle_heartbeat] = config[:idle_heartbeat] * ::NATS::NANOSECONDS
+        end
+        if config[:priority_timeout]
+          raise ArgumentError.new("nats: invalid priority timeout") unless config[:priority_timeout].is_a?(Integer)
+          config[:priority_timeout] = config[:priority_timeout] * ::NATS::NANOSECONDS
+        end
+        config[:pause_until] = rfc3339(config[:pause_until])
+
+        cfg = config.to_h.compact
+        req = {
+          stream_name: stream,
+          config: cfg
+        }
+        # Without an action the server creates or updates.
+        req[:action] = action if action
+
+        result = api_request(req_subject, req.to_json, params)
+        JetStream::API::ConsumerInfo.new(result).freeze
+      end
+
+      # request_pause sends a consumer pause request, which resumes the
+      # consumer when it has no pause time.
+      def request_pause(stream, consumer, req, params)
+        raise JetStream::Error::InvalidStreamName.new("nats: invalid stream name") if stream.nil? || stream.empty?
+        raise JetStream::Error::InvalidConsumerName.new("nats: invalid consumer name") if consumer.nil? || consumer.empty?
+
+        req_subject = "#{@prefix}.CONSUMER.PAUSE.#{stream}.#{consumer}"
+        result = api_request(req_subject, req.to_json, params)
+        JetStream::API::ConsumerPauseResponse.new(result)
+      end
+
+      # rfc3339 formats a Time as the server expects it; a String is
+      # sent as is.
+      def rfc3339(time)
+        time.is_a?(Time) ? time.getutc.iso8601(9) : time
+      end
+
       def api_request(req_subject, req = "", params = {})
         params[:timeout] ||= @opts[:timeout]
         msg = begin
@@ -300,6 +475,11 @@ module NATS
 
         raw_msg
       end
+
+      # stream_config_json makes the request to create or update a stream.
+      def stream_config_json(config)
+        config.to_h.compact.reject { |key, value| UNSENT_STREAM_DEFAULTS[key]&.include?(value) }.to_json
+      end
     end
   end
 end

data/lib/nats/io/jetstream/msg/ack_methods.rb

@@ -58,13 +58,19 @@ module NATS
           resp
         end
 
+        # term tells the server not to redeliver the message. A :reason is
+        # passed on in the server's terminated advisory. Servers before
+        # v2.10.4 do not terminate a message given a reason, so it will
+        # be redelivered.
         def term(**params)
           ensure_is_acked_once!
 
+          reason = params.delete(:reason)
+          payload = reason.to_s.strip.empty? ? Ack::Term : "#{Ack::Term} #{reason}"
           resp = if params[:timeout]
-            @nc.request(@reply, Ack::Term, **params)
+            @nc.request(@reply, payload, **params)
           else
-            @nc.publish(@reply, Ack::Term)
+            @nc.publish(@reply, payload)
           end
           @sub.synchronize { @ackd = true }