x-streams 1.0.0

data/lib/x/streams/validator.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module X
+  module Streams
+    # Checks the settings of a streaming client and the parsing classes of a stream before a stream is opened, and the
+    # identifiers of rules
+    #
+    # Internal to x-streams: StreamingClient and ReconnectHandler check what they are given with it, with the
+    # messages X::Client checks its own settings with, and StreamRule and StreamRules read identifiers with it, as
+    # x-resources reads them.
+    #
+    # @api private
+    module Validator
+      extend self
+
+      # The message of the error raised for a count that is neither an Integer of at least 0 nor Float::INFINITY
+      INVALID_COUNT_OR_INFINITY = "%s must be an Integer of at least 0, or Float::INFINITY for no limit, not %s"
+      # The fewest seconds a stream may wait for a read: the interval of the keep-alive X sends a quiet stream, and five
+      # seconds more, so that a keep-alive that arrives a little late does not time the read out
+      MINIMUM_READ_TIMEOUT = 25 # seconds
+      # The message of the error raised for a read timeout that is neither a finite number of seconds of at least
+      # MINIMUM_READ_TIMEOUT nor nil
+      INVALID_READ_TIMEOUT = "%s must be a finite number of seconds of at least #{MINIMUM_READ_TIMEOUT}, five more than the " \
+        "20-second interval of the keep-alive X sends a quiet stream, or nil for no timeout, not %s"
+      # The message of the error raised for an array_class that is not a Class
+      INVALID_ARRAY_CLASS = "%s must be a Class that JSON.parse builds each array into, such as Array, not %s"
+      # The message of the error raised for an object_class that is neither a Class nor responds to from_response
+      INVALID_OBJECT_CLASS = "%s must be a Class that JSON.parse builds each object into, such as Hash, or respond to " \
+        "from_response, as the resource classes of x-resources do, not %s"
+      # The message of the error raised for a callback that neither responds to call nor is nil
+      INVALID_CALLABLE = "%s must respond to call, as a Proc or a lambda does, or be nil, not %s %s"
+      # The pattern of the name of a class that an takes the place of a before, as that of an Integer
+      VOWEL = /\A[AEIOU]/
+      # The pattern of an identifier given as a String: digits alone, with no sign, underscore, or whitespace
+      IDENTIFIER = /\A\d+\z/
+      # The message of the error raised for an identifier that is neither an Integer that is not negative nor a String
+      # of digits, as Integer() words it
+      INVALID_IDENTIFIER = "invalid value for Integer(): %s"
+      private_constant :MINIMUM_READ_TIMEOUT, :INVALID_COUNT_OR_INFINITY, :INVALID_READ_TIMEOUT, :INVALID_ARRAY_CLASS, :INVALID_OBJECT_CLASS,
+        :INVALID_CALLABLE, :VOWEL, :IDENTIFIER, :INVALID_IDENTIFIER
+
+      # Check that a count is an Integer of at least 0, or Float::INFINITY for no limit
+      #
+      # @api private
+      # @param name [Symbol] the name of the setting, which the error names
+      # @param value [Object] the value of the setting
+      # @return [Integer, Float] the value
+      # @raise [ArgumentError] if the value is neither an Integer of at least 0 nor Float::INFINITY
+      def count_or_infinity!(name, value)
+        return value if (value.instance_of?(Integer) && !value.negative?) || Float::INFINITY.eql?(value)
+
+        raise ArgumentError, format(INVALID_COUNT_OR_INFINITY, name, value.inspect)
+      end
+
+      # Check that a read timeout is a finite number of seconds of at least 25, or nil
+      #
+      # X sends a quiet stream a keep-alive every 20 seconds, so a read timeout no longer than that drops a stream that
+      # is quiet but connected whenever a keep-alive arrives a little late, and one shorter drops it every time, and
+      # reconnects it without end, delivering nothing, where the read timeout of a request may be as short as 0.
+      #
+      # @api private
+      # @param name [Symbol] the name of the setting, which the error names
+      # @param value [Object] the value of the setting
+      # @return [Integer, Float, nil] the value
+      # @raise [ArgumentError] if the value is neither a finite real number of at least MINIMUM_READ_TIMEOUT nor nil
+      def read_timeout!(name, value)
+        return value if value.nil? || (value.is_a?(Numeric) && value.real? && value.finite? && value >= MINIMUM_READ_TIMEOUT)
+
+        raise ArgumentError, format(INVALID_READ_TIMEOUT, name, value.inspect)
+      end
+
+      # Check that a callback responds to call, or is nil
+      #
+      # @api private
+      # @param name [Symbol] the name of the setting, which the error names
+      # @param value [Object] the value of the setting
+      # @return [#call, nil] the value
+      # @raise [ArgumentError] if the value neither responds to call nor is nil
+      def callable!(name, value)
+        return value if value.nil? || value.respond_to?(:call)
+
+        raise ArgumentError, format(INVALID_CALLABLE, name, value.class.to_s.match?(VOWEL) ? "an" : "a", value.class)
+      end
+
+      # Read the identifier of a rule as an Integer
+      #
+      # It is read as strictly as x-resources reads an identifier: an Integer that is not negative, or a String of digits
+      # alone, as the API sends one, with no sign, underscore, or whitespace, which Integer() would take, so that
+      # " 1_0 " is not read as 10, nor "-1" as -1.
+      #
+      # @api private
+      # @param value [Object] the identifier
+      # @return [Integer] the identifier
+      # @raise [ArgumentError] if the identifier is neither an Integer that is not negative nor a String of digits
+      def identifier!(value)
+        return value if value.instance_of?(Integer) && !value.negative?
+        raise ArgumentError, format(INVALID_IDENTIFIER, value.to_s.inspect) unless value.instance_of?(String) && IDENTIFIER.match?(value)
+
+        Integer(value, 10)
+      end
+
+      # Check the classes a stream parses its objects into
+      #
+      # @api private
+      # @param array_class [Object] the class for parsing JSON arrays
+      # @param object_class [Object] the class for parsing JSON objects, or one that responds to from_response
+      # @return [void]
+      # @raise [ArgumentError] if array_class is not a Class, or object_class is neither a Class nor responds to
+      #   from_response
+      def parsing_classes!(array_class:, object_class:)
+        raise ArgumentError, format(INVALID_ARRAY_CLASS, :array_class, array_class.inspect) unless array_class.instance_of?(Class)
+        return if object_class.instance_of?(Class) || object_class.respond_to?(:from_response)
+
+        raise ArgumentError, format(INVALID_OBJECT_CLASS, :object_class, object_class.inspect)
+      end
+    end
+    private_constant :Validator
+  end
+end

data/lib/x/streams/version.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "rubygems/version"
+
+module X
+  # Streams from the X API, and the rules of its filtered stream
+  # @api public
+  module Streams
+    # The current version of the x-streams gem
+    VERSION = "1.0.0"
+
+    # The version as a Gem::Version, which compares one release with another
+    #
+    # VERSION is a String, as a version constant is throughout Ruby, so that what reads it can split it, match it,
+    # or send it wherever a String belongs. This builds the Gem::Version that compares it with another version,
+    # which a String compares by character rather than by segment.
+    #
+    # @api public
+    # @return [Gem::Version] the version
+    # @example Take a path that a later release opened
+    #   X::Streams.gem_version >= Gem::Version.new("1.1")
+    def self.gem_version = Gem::Version.new(VERSION)
+  end
+end

data/lib/x/streams.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "streams/version"
+require_relative "streams/api"
+require_relative "streams/error"
+require_relative "streams/rules_rejected"
+require_relative "streams/stream_error"
+require_relative "streams/stream_rule"
+require_relative "streams/streaming_client"

data/sig/manifest.yaml

@@ -0,0 +1,6 @@
+# The standard libraries the signatures of x-streams refer to, which rbs collection loads for code that depends on it
+#
+# rbs collection reads every library named here as a standard library, so the gems x-streams depends on are left to
+# its gemspec, from which it installs their signatures.
+dependencies:
+  - name: uri

data/sig/x-streams.rbs

@@ -0,0 +1,87 @@
+# Signatures of the public API of x-streams, which the gem ships; sig/internal declares its internals for Steep alone
+module X
+  module Streams
+    VERSION: String
+
+    def self.gem_version: () -> Gem::Version
+
+    class Error < X::Error
+    end
+
+    # The streaming method mixed into a client
+    module API
+      def streaming: (?read_timeout: Numeric?, ?max_reconnects: Float | Integer, ?on_reconnect: StreamingClient::_ReconnectHook?) -> StreamingClient
+    end
+  end
+
+  class RulesRejected < Streams::Error
+    attr_reader problems: Array[Problem]
+    attr_reader added: Array[StreamRule]?
+    attr_reader deleted_count: Integer?
+
+    def initialize: (?String? message, ?problems: Array[Problem], ?added: Array[StreamRule]?, ?deleted_count: Integer?) -> void
+  end
+
+  class StreamError < Streams::Error
+    attr_reader problems: Array[Problem]
+    attr_reader http_method: Symbol?
+    attr_reader uri: URI::Generic?
+
+    def initialize: (?String? message, ?problems: Array[Problem], ?http_method: (Symbol | String)?, ?uri: URI::Generic?) -> void
+  end
+
+  class StreamRule
+    attr_reader id: Integer?
+    attr_reader value: String
+    attr_reader tag: String?
+    def initialize: (value: String, ?tag: String?, ?id: (Integer | String)?) -> void
+    def to_h: () -> {id: Integer?, value: String, tag: String?}
+    def deconstruct_keys: (Array[Symbol]? _keys) -> {id: Integer?, value: String, tag: String?}
+    def ==: (untyped other) -> bool
+    def eql?: (untyped other) -> bool
+    def hash: () -> Integer
+    def inspect: () -> String
+    def marshal_dump: () -> untyped
+    def marshal_load: (untyped state) -> void
+    def encode_with: (untyped coder) -> void
+    def init_with: (untyped coder) -> void
+  end
+
+  class StreamingClient
+    DEFAULT_READ_TIMEOUT: Float | Integer
+    DEFAULT_MAX_RECONNECTS: Float | Integer
+
+    type addable_rule = StreamRule | Hash[untyped, untyped] | String
+    type rule = addable_rule | Integer | _MatchingRule
+
+    # The X::MatchingRule of x-resources, which x-streams does not depend on, and which names a rule by its identifier;
+    # anything else with an id raises ArgumentError
+    interface _MatchingRule
+      def id: () -> Integer
+      def tag: () -> String?
+    end
+
+    # The callable passed the error that dropped a stream and its wait to reconnect, before each wait; every release
+    # of 1.x passes these two arguments and no others
+    interface _ReconnectHook
+      def call: (StandardError error, Integer | Float wait) -> untyped
+    end
+
+    attr_reader client: Client
+    attr_reader on_reconnect: _ReconnectHook?
+    def initialize: (Client client, ?read_timeout: Numeric?, ?max_reconnects: Integer | Float, ?on_reconnect: _ReconnectHook?) -> void
+    def inspect: () -> String
+    def stream: (String endpoint, ?params: params?, ?headers: headers, ?array_class: Class, ?object_class: object_class) { (untyped) -> void } -> untyped
+    def stop: () -> nil
+    def stopped?: () -> bool
+    def read_timeout: () -> Numeric?
+    def max_reconnects: () -> (Integer | Float)
+    def rules: (?params: params?) -> Array[StreamRule]
+    def add_rules: (Array[addable_rule] | addable_rule rules, ?dry_run: bool) ?{ (Problem problem) -> void } -> Array[StreamRule]
+    def delete_rules: (Array[rule] | rule rules, ?dry_run: bool) ?{ (Problem problem) -> void } -> Integer
+    def marshal_dump: () -> bot
+    def encode_with: (untyped coder) -> bot
+    def as_json: (*untyped) -> bot
+    def to_json: (?JSON::State? state) -> bot
+  end
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: x-streams
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Erik Berlin
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: x-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+email:
+- sferik@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/x/streams.rb
+- lib/x/streams/api.rb
+- lib/x/streams/callback_error.rb
+- lib/x/streams/error.rb
+- lib/x/streams/reconnect_handler.rb
+- lib/x/streams/rules_rejected.rb
+- lib/x/streams/stopper.rb
+- lib/x/streams/stream_error.rb
+- lib/x/streams/stream_parser.rb
+- lib/x/streams/stream_rule.rb
+- lib/x/streams/stream_rules.rb
+- lib/x/streams/streaming_client.rb
+- lib/x/streams/validator.rb
+- lib/x/streams/version.rb
+- sig/manifest.yaml
+- sig/x-streams.rbs
+homepage: https://sferik.github.io/x-ruby
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  bug_tracker_uri: https://github.com/sferik/x-ruby/issues
+  changelog_uri: https://github.com/sferik/x-ruby/blob/main/x-streams/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/x-streams/
+  funding_uri: https://github.com/sponsors/sferik/
+  homepage_uri: https://sferik.github.io/x-ruby
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/sferik/x-ruby/tree/main/x-streams
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.21
+specification_version: 4
+summary: 'Streaming for the X gem: the sample and filtered streams, reconnected as
+  X recommends, and the rules of the filtered stream.'
+test_files: []