nats-pure 2.2.0 → 2.3.0

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

@@ -0,0 +1,305 @@
+# Copyright 2021 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.
+#
+
+require_relative 'errors'
+require 'base64'
+require 'time'
+
+module NATS
+  class JetStream
+    # JetStream::API are the types used to interact with the JetStream API.
+    module API
+      # When the server responds with an error from the JetStream API.
+      Error = ::NATS::JetStream::Error::APIError
+
+      # SequenceInfo is a pair of consumer and stream sequence and last activity.
+      # @!attribute consumer_seq
+      #   @return [Integer] The consumer sequence.
+      # @!attribute stream_seq
+      #   @return [Integer] The stream sequence.
+      SequenceInfo = Struct.new(:consumer_seq, :stream_seq, :last_active,
+                                keyword_init: true) do
+        def initialize(opts={})
+          # Filter unrecognized fields and freeze.
+          rem = opts.keys - members
+          opts.delete_if { |k| rem.include?(k) }
+          super(opts)
+          freeze
+        end
+      end
+
+      # ConsumerInfo is the current status of a JetStream consumer.
+      #
+      # @!attribute stream_name
+      #   @return [String] name of the stream to which the consumer belongs.
+      # @!attribute name
+      #   @return [String] name of the consumer.
+      # @!attribute created
+      #   @return [String] time when the consumer was created.
+      # @!attribute config
+      #   @return [ConsumerConfig] consumer configuration.
+      # @!attribute delivered
+      #   @return [SequenceInfo]
+      # @!attribute ack_floor
+      #   @return [SequenceInfo]
+      # @!attribute num_ack_pending
+      #   @return [Integer]
+      # @!attribute num_redelivered
+      #   @return [Integer]
+      # @!attribute num_waiting
+      #   @return [Integer]
+      # @!attribute num_pending
+      #   @return [Integer]
+      # @!attribute cluster
+      #   @return [Hash]
+      ConsumerInfo = Struct.new(:type, :stream_name, :name, :created,
+                                :config, :delivered, :ack_floor,
+                                :num_ack_pending, :num_redelivered, :num_waiting,
+                                :num_pending, :cluster, :push_bound,
+                                keyword_init: true) do
+        def initialize(opts={})
+          opts[:created] = Time.parse(opts[:created])
+          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] = ConsumerConfig.new(opts[:config])
+          opts.delete(:cluster)
+          # Filter unrecognized fields just in case.
+          rem = opts.keys - members
+          opts.delete_if { |k| rem.include?(k) }
+          super(opts)
+          freeze
+        end
+      end
+
+      # ConsumerConfig is the consumer configuration.
+      #
+      # @!attribute durable_name
+      #   @return [String]
+      # @!attribute deliver_policy
+      #   @return [String]
+      # @!attribute ack_policy
+      #   @return [String]
+      # @!attribute ack_wait
+      #   @return [Integer]
+      # @!attribute max_deliver
+      #   @return [Integer]
+      # @!attribute replay_policy
+      #   @return [String]
+      # @!attribute max_waiting
+      #   @return [Integer]
+      # @!attribute max_ack_pending
+      #   @return [Integer]
+      ConsumerConfig = Struct.new(:name, :durable_name, :description,
+                                  :deliver_policy, :opt_start_seq, :opt_start_time,
+                                  :ack_policy, :ack_wait, :max_deliver, :backoff,
+                                  :filter_subject, :replay_policy, :rate_limit_bps,
+                                  :sample_freq, :max_waiting, :max_ack_pending,
+                                  :flow_control, :idle_heartbeat, :headers_only,
+
+                                  # Pull based options
+                                  :max_batch, :max_expires,
+                                  # Push based consumers
+                                  :deliver_subject, :deliver_group,
+                                  # Ephemeral inactivity threshold
+                                  :inactive_threshold,
+                                  # Generally inherited by parent stream and other markers,
+                                  # now can be configured directly.
+                                  :num_replicas,
+                                  # Force memory storage
+                                  :mem_storage,
+                                  keyword_init: true) do
+        def initialize(opts={})
+          # Filter unrecognized fields just in case.
+          rem = opts.keys - members
+          opts.delete_if { |k| rem.include?(k) }
+          super(opts)
+        end
+      end
+
+      # StreamConfig represents the configuration of a stream from JetStream.
+      #
+      # @!attribute type
+      #   @return [String]
+      # @!attribute config
+      #   @return [Hash]
+      # @!attribute created
+      #   @return [String]
+      # @!attribute state
+      #   @return [StreamState]
+      # @!attribute did_create
+      #   @return [Boolean]
+      # @!attribute name
+      #   @return [String]
+      # @!attribute subjects
+      #   @return [Array]
+      # @!attribute retention
+      #   @return [String]
+      # @!attribute max_consumers
+      #   @return [Integer]
+      # @!attribute max_msgs
+      #   @return [Integer]
+      # @!attribute max_bytes
+      #   @return [Integer]
+      # @!attribute max_age
+      #   @return [Integer]
+      # @!attribute max_msgs_per_subject
+      #   @return [Integer]
+      # @!attribute max_msg_size
+      #   @return [Integer]
+      # @!attribute discard
+      #   @return [String]
+      # @!attribute storage
+      #   @return [String]
+      # @!attribute num_replicas
+      #   @return [Integer]
+      # @!attribute duplicate_window
+      #   @return [Integer]
+      StreamConfig = Struct.new(
+        :name,
+        :description,
+        :subjects,
+        :retention,
+        :max_consumers,
+        :max_msgs,
+        :max_bytes,
+        :discard,
+        :max_age,
+        :max_msgs_per_subject,
+        :max_msg_size,
+        :storage,
+        :num_replicas,
+        :no_ack,
+        :duplicate_window,
+        :placement,
+        :mirror,
+        :sources,
+        :sealed,
+        :deny_delete,
+        :deny_purge,
+        :allow_rollup_hdrs,
+        :republish,
+        :allow_direct,
+        :mirror_direct,
+        keyword_init: true) do
+        def initialize(opts={})
+          # Filter unrecognized fields just in case.
+          rem = opts.keys - members
+          opts.delete_if { |k| rem.include?(k) }
+          super(opts)
+        end
+      end
+
+      # StreamInfo is the info about a stream from JetStream.
+      #
+      # @!attribute type
+      #   @return [String]
+      # @!attribute config
+      #   @return [Hash]
+      # @!attribute created
+      #   @return [String]
+      # @!attribute state
+      #   @return [Hash]
+      # @!attribute domain
+      #   @return [String]
+      StreamInfo = Struct.new(:type, :config, :created, :state, :domain,
+                              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])
+
+          # Filter fields and freeze.
+          rem = opts.keys - members
+          opts.delete_if { |k| rem.include?(k) }
+          super(opts)
+          freeze
+        end
+      end
+
+      # StreamState is the state of a stream.
+      #
+      # @!attribute messages
+      #   @return [Integer]
+      # @!attribute bytes
+      #   @return [Integer]
+      # @!attribute first_seq
+      #   @return [Integer]
+      # @!attribute last_seq
+      #   @return [Integer]
+      # @!attribute consumer_count
+      #   @return [Integer]
+      StreamState = Struct.new(:messages, :bytes, :first_seq, :first_ts,
+                               :last_seq, :last_ts, :consumer_count,
+                               keyword_init: true) do
+        def initialize(opts={})
+          rem = opts.keys - members
+          opts.delete_if { |k| rem.include?(k) }
+          super(opts)
+        end
+      end
+
+      # StreamCreateResponse is the response from the JetStream $JS.API.STREAM.CREATE API.
+      #
+      # @!attribute type
+      #   @return [String]
+      # @!attribute config
+      #   @return [StreamConfig]
+      # @!attribute created
+      #   @return [String]
+      # @!attribute state
+      #   @return [StreamState]
+      # @!attribute did_create
+      #   @return [Boolean]
+      StreamCreateResponse = Struct.new(:type, :config, :created, :state, :did_create,
+                                        keyword_init: true) do
+        def initialize(opts={})
+          rem = opts.keys - members
+          opts.delete_if { |k| rem.include?(k) }
+          opts[:config] = StreamConfig.new(opts[:config])
+          opts[:state] = StreamState.new(opts[:state])
+          super(opts)
+          freeze
+        end
+      end
+
+      RawStreamMsg = Struct.new(:subject, :seq, :data, :headers, keyword_init: true) do
+        def initialize(opts)
+          opts[:data] = Base64.decode64(opts[:data]) if opts[:data]
+          if opts[:hdrs]
+            header = Base64.decode64(opts[:hdrs])
+            hdr = {}
+            lines = header.lines
+            lines.slice(1, header.size).each do |line|
+              line.rstrip!
+              next if line.empty?
+              key, value = line.strip.split(/\s*:\s*/, 2)
+              hdr[key] = value
+            end
+            opts[:headers] = hdr
+          end
+
+          # Filter out members not present.
+          rem = opts.keys - members
+          opts.delete_if { |k| rem.include?(k) }
+          super(opts)
+        end
+
+        def sequence
+          self.seq
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# Copyright 2021 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
+    # Error is any error that may arise when interacting with JetStream.
+    class Error < NATS::IO::Error
+
+      # When there is a NATS::IO::NoResponders error after making a publish request.
+      class NoStreamResponse < Error; end
+
+      # When an invalid durable or consumer name was attempted to be used.
+      class InvalidDurableName < Error; end
+
+      # When an ack not longer valid.
+      class InvalidJSAck < Error; end
+
+      # When an ack has already been acked.
+      class MsgAlreadyAckd < Error; end
+
+      # When the delivered message does not behave as a message delivered by JetStream,
+      # for example when the ack reply has unrecognizable fields.
+      class NotJSMessage < Error; end
+
+      # When the stream name is invalid.
+      class InvalidStreamName < Error; end
+
+      # When the consumer name is invalid.
+      class InvalidConsumerName < Error; end
+
+      # When the server responds with an error from the JetStream API.
+      class APIError < Error
+        attr_reader :code, :err_code, :description, :stream, :seq
+
+        def initialize(params={})
+          @code = params[:code]
+          @err_code = params[:err_code]
+          @description = params[:description]
+          @stream = params[:stream]
+          @seq = params[:seq]
+        end
+
+        def to_s
+          "#{@description} (status_code=#{@code}, err_code=#{@err_code})"
+        end
+      end
+
+      # When JetStream is not currently available, this could be due to JetStream
+      # not being enabled or temporarily unavailable due to a leader election when
+      # running in cluster mode.
+      # This condition is represented with a message that has 503 status code header.
+      class ServiceUnavailable < APIError
+        def initialize(params={})
+          super(params)
+          @code ||= 503
+        end
+      end
+
+      # When there is a hard failure in the JetStream.
+      # This condition is represented with a message that has 500 status code header.
+      class ServerError < APIError
+        def initialize(params={})
+          super(params)
+          @code ||= 500
+        end
+      end
+
+      # When a JetStream object was not found.
+      # This condition is represented with a message that has 404 status code header.
+      class NotFound < APIError
+        def initialize(params={})
+          super(params)
+          @code ||= 404
+        end
+      end
+
+      # When the stream is not found.
+      class StreamNotFound < NotFound; end
+
+      # When the consumer or durable is not found by name.
+      class ConsumerNotFound < NotFound; end
+
+      # When the JetStream client makes an invalid request.
+      # This condition is represented with a message that has 400 status code header.
+      class BadRequest < APIError
+        def initialize(params={})
+          super(params)
+          @code ||= 400
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# Copyright 2021 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
+    module JS
+      module Config
+        # AckPolicy
+        AckExplicit = ("explicit".freeze)
+        AckAll      = ("all".freeze)
+        AckNone     = ("none".freeze)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# Copyright 2021 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
+    module JS
+      module Header
+        Status              = ("Status".freeze)
+        Desc                = ("Description".freeze)
+        MsgID               = ("Nats-Msg-Id".freeze)
+        ExpectedStream      = ("Nats-Expected-Stream".freeze)
+        ExpectedLastSeq     = ("Nats-Expected-Last-Sequence".freeze)
+        ExpectedLastSubjSeq = ("Nats-Expected-Last-Subject-Sequence".freeze)
+        ExpectedLastMsgID   = ("Nats-Expected-Last-Msg-Id".freeze)
+        LastConsumerSeq     = ("Nats-Last-Consumer".freeze)
+        LastStreamSeq       = ("Nats-Last-Stream".freeze)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# Copyright 2021 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
+    module JS
+      module Status
+        CtrlMsg        = ("100".freeze)
+        NoMsgs         = ("404".freeze)
+        NotFound       = ("404".freeze)
+        RequestTimeout = ("408".freeze)
+        ServiceUnavailable = ("503".freeze)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# Copyright 2021 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
+    module JS
+      class Sub
+        attr_reader :js, :stream, :consumer, :nms
+
+        def initialize(opts={})
+          @js = opts[:js]
+          @stream = opts[:stream]
+          @consumer = opts[:consumer]
+          @nms = opts[:nms]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+# Copyright 2021 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.
+#
+
+require_relative 'js/config'
+require_relative 'js/header'
+require_relative 'js/status'
+require_relative 'js/sub'
+
+module NATS
+  class JetStream
+    # Misc internal functions to support JS API.
+    # @private
+    module JS
+      DefaultAPIPrefix = ("$JS.API".freeze)
+
+      class << self
+        def next_req_to_json(next_req)
+          req = {}
+          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]
+          req.to_json
+        end
+
+        def is_status_msg(msg)
+          return (!msg.nil? and (!msg.header.nil? and msg.header[Header::Status]))
+        end
+
+        # check_503_error raises exception when a NATS::Msg has a 503 status header.
+        # @param msg [NATS::Msg] The message with status headers.
+        # @raise [NATS::JetStream::Error::ServiceUnavailable]
+        def check_503_error(msg)
+          return if msg.nil? or msg.header.nil?
+          if msg.header[Header::Status] == Status::ServiceUnavailable
+            raise ::NATS::JetStream::Error::ServiceUnavailable
+          end
+        end
+
+        # from_msg takes a plain NATS::Msg and checks its headers to confirm
+        # if it was an error:
+        #
+        # msg.header={"Status"=>"503"})
+        # msg.header={"Status"=>"408", "Description"=>"Request Timeout"})
+        #
+        # @param msg [NATS::Msg] The message with status headers.
+        # @return [NATS::JetStream::API::Error]
+        def from_msg(msg)
+          check_503_error(msg)
+          code = msg.header[JS::Header::Status]
+          desc = msg.header[JS::Header::Desc]
+          return ::NATS::JetStream::API::Error.new({code: code, description: desc})
+        end
+
+        # from_error takes an API response that errored and maps the error
+        # into a JetStream error type based on the status and error code.
+        def from_error(err)
+          return unless err
+          case err[:code]
+          when 503
+            ::NATS::JetStream::Error::ServiceUnavailable.new(err)
+          when 500
+            ::NATS::JetStream::Error::ServerError.new(err)
+          when 404
+            case err[:err_code]
+            when 10059
+              ::NATS::JetStream::Error::StreamNotFound.new(err)
+            when 10014
+              ::NATS::JetStream::Error::ConsumerNotFound.new(err)
+            else
+              ::NATS::JetStream::Error::NotFound.new(err)
+            end
+          when 400
+            ::NATS::JetStream::Error::BadRequest.new(err)
+          else
+            ::NATS::JetStream::API::Error.new(err)
+          end
+        end
+      end
+    end
+    private_constant :JS
+  end
+end