x-streams 1.0.0

data/lib/x/streams/stream_rule.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "x/core"
+require_relative "validator"
+
+module X
+  module Streams
+    # A rule of the filtered stream: the value it matches posts against, the tag it is labelled with, and the
+    # identifier the API gave it
+    #
+    # {StreamingClient#rules} and {StreamingClient#add_rules} return the rules the API holds, and
+    # {StreamingClient#delete_rules} deletes one by its identifier, so a rule that was read deletes itself. A rule
+    # built to be added has no identifier until the API gives it one, and is deleted by the value it matches.
+    #
+    # It is frozen, compares equal to a rule of the same identifier, value, and tag, and matches a pattern of them, as
+    # in `rule in {value: /ruby/, tag: nil}`.
+    #
+    # @api public
+    class ::X::StreamRule
+      # The message of the error raised for a value or a tag that is not a String
+      NOT_A_STRING = "%s must be a String, not %s"
+      private_constant :NOT_A_STRING
+
+      # The number of the format of the state Marshal writes, which every release of 1.x writes
+      #
+      # A later release of 1.x adds to the state only what an earlier one ignores, parts after those it reads and keys of
+      # a Hash it does not read, so that the state one release of 1.x writes is read by every other, earlier or later.
+      MARSHAL_FORMAT = 1
+      private_constant :MARSHAL_FORMAT
+
+      # The identifier the API gave the rule
+      #
+      # The API sends it as a String, and it is read as an Integer, as the identifier of a resource of the object layer
+      # is, and as strictly: a String of digits alone, with no sign, underscore, or whitespace.
+      #
+      # @api public
+      # @return [Integer, nil] the identifier, or nil for a rule the API has not given one
+      # @example Get the identifier
+      #   rule.id # => 1165037377523306498
+      attr_reader :id
+
+      # The value the rule matches posts against
+      # @api public
+      # @return [String] the value, in the syntax of the filtered stream
+      # @example Get the value
+      #   rule.value # => "ruby -is:retweet"
+      attr_reader :value
+
+      # The tag the rule is labelled with, which each post it matches names
+      # @api public
+      # @return [String, nil] the tag, or nil for a rule without one
+      # @example Get the tag
+      #   rule.tag # => "ruby"
+      attr_reader :tag
+
+      # Initialize a rule
+      #
+      # @api public
+      # @param value [String] the value the rule matches posts against
+      # @param tag [String, nil] the tag the rule is labelled with, or nil for none
+      # @param id [Integer, String, nil] the identifier the API gave the rule, as an Integer that is not negative or as
+      #   the String of digits the API sends, or nil for a rule it has not given one
+      # @return [StreamRule] the frozen rule
+      # @raise [ArgumentError] if the value is not a String, the tag is neither a String nor nil, or the identifier is
+      #   neither an Integer that is not negative, a String of digits alone, nor nil
+      # @example Build a rule to add
+      #   X::StreamRule.new(value: "ruby -is:retweet", tag: "ruby")
+      def initialize(value:, tag: nil, id: nil)
+        @id = Validator.identifier!(id) unless id.nil?
+        @value = string!(:value, value)
+        @tag = string!(:tag, tag) unless tag.nil?
+        freeze
+      end
+
+      # The rule as a Hash
+      #
+      # @api public
+      # @return [Hash{Symbol => Integer, String, nil}] the identifier, value, and tag
+      # @example Store a rule
+      #   store.save(**rule.to_h)
+      def to_h = {id:, value:, tag:}
+
+      # The identifier, value, and tag of the rule, which a pattern matches against
+      #
+      # @api public
+      # @param _keys [Array<Symbol>, nil] the keys the pattern names
+      # @return [Hash{Symbol => Integer, String, nil}] the identifier, value, and tag
+      # @example Match the rules without a tag
+      #   streaming_client.rules.select { |rule| rule in {tag: nil} }
+      def deconstruct_keys(_keys) = to_h
+
+      # Check whether another rule is the same rule
+      #
+      # @api public
+      # @param other [Object] the other rule
+      # @return [Boolean] true if the other rule is a StreamRule of the same identifier, value, and tag
+      # @example Check whether a rule was read before
+      #   streaming_client.rules.include?(rule)
+      def ==(other) = other.instance_of?(self.class) && to_h.eql?(other.to_h)
+      alias_method :eql?, :==
+
+      # The hash of the rule, which equal rules share
+      #
+      # @api public
+      # @return [Integer] the hash
+      # @example Count the distinct rules
+      #   rules.uniq.size
+      def hash = [self.class, to_h].hash
+
+      # Summarize the rule for the console
+      #
+      # @api public
+      # @return [String] the class name, identifier, value, and tag
+      # @example Inspect a rule
+      #   rule.inspect # => #<X::StreamRule id=1165037377523306498 value="ruby -is:retweet" tag="ruby">
+      def inspect = "#<#{self.class} id=#{id.inspect} value=#{value.inspect} tag=#{tag.inspect}>"
+
+      # The state Marshal writes
+      #
+      # What is written is plain data, led by the number of its format, so that a rule written by one release of 1.x is
+      # read by a later one: its identifier, value, and tag, as to_h gives them.
+      #
+      # @api public
+      # @return [Array(Integer, Hash{Symbol => Integer, String, nil})] the number of the format, then the rule as a Hash
+      # @example Cache the rules of the filtered stream
+      #   Rails.cache.write("rules", streaming_client.rules)
+      def marshal_dump = [MARSHAL_FORMAT, to_h]
+
+      # Restore a rule Marshal read, built as the constructor builds it, frozen
+      #
+      # @api public
+      # @param state [Array] the state Marshal wrote
+      # @return [void]
+      # @raise [UnsupportedFormat] if the state is of a format this release does not read
+      # @example Read cached rules
+      #   Marshal.load(Marshal.dump(rule)).value
+      def marshal_load(state)
+        format, rule = state #: [Integer, {id: Integer?, value: String, tag: String?}]
+        raise UnsupportedFormat, "#{self.class} reads format #{MARSHAL_FORMAT} of Marshal, not #{format.inspect}" unless MARSHAL_FORMAT.eql?(format)
+
+        initialize(**rule.slice(:id, :value, :tag)) # steep:ignore InsufficientKeywordArguments
+      end
+
+      # Write the state Marshal writes as YAML
+      #
+      # YAML would write the instance variables of the rule, and read them back into a rule that is not frozen, so
+      # it says how it is written: the number of its format, then each of its parts, under the name to_h gives it.
+      #
+      # @api public
+      # @param coder [Psych::Coder] the coder YAML writes the rule with
+      # @return [void]
+      # @example Write a rule as YAML
+      #   YAML.dump(rule)
+      def encode_with(coder)
+        coder["format"] = MARSHAL_FORMAT
+        to_h.each { |key, value| coder[key.to_s] = value }
+      end
+
+      # Restore a rule YAML read, frozen, as Marshal restores one
+      #
+      # @api public
+      # @param coder [Psych::Coder] the coder YAML read the rule with
+      # @return [void]
+      # @raise [UnsupportedFormat] if the state is of a format this release does not read
+      # @example Read a rule written as YAML
+      #   YAML.unsafe_load(YAML.dump(rule)).value
+      def init_with(coder) = marshal_load([coder["format"], coder.map.transform_keys(&:to_sym)])
+
+      private
+
+      # A frozen copy of a String a rule holds
+      # @api private
+      # @param name [Symbol] the name of the attribute, which the error names
+      # @param string [Object] the value of the attribute
+      # @return [String] the frozen copy
+      # @raise [ArgumentError] if the value is not a String
+      def string!(name, string)
+        (String.try_convert(string) || raise(ArgumentError, format(NOT_A_STRING, name, string.inspect))).dup.freeze
+      end
+    end
+  end
+end

data/lib/x/streams/stream_rules.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require_relative "stream_rule"
+require_relative "validator"
+
+module X
+  module Streams
+    # The rules of the filtered stream, read from what a caller gives and what the API returns
+    #
+    # A rule is given as a StreamRule, a Hash, a String, or, to delete it, an Integer or the X::MatchingRule of a post
+    # of x-resources, and each of the rules methods of a streaming client reads it here into what the API takes.
+    #
+    # Internal to x-streams: StreamingClient reads the rules it adds and deletes with it.
+    #
+    # @api private
+    module StreamRules
+      extend self
+
+      # The message of the error raised for something that is neither a rule nor the identifier of one
+      NOT_A_RULE = "a rule is a StreamRule, a Hash holding an id or a value, an X::MatchingRule, the value it matches, " \
+        "or its identifier, not %s"
+      # The message of the error raised for something that is neither a rule to add nor the value one matches
+      NOT_A_RULE_TO_ADD = "a rule to add is a StreamRule, a Hash holding a value, or the value it matches, not %s"
+      # What the type of the problem of a rule the app already has ends in
+      DUPLICATE_RULES = "/duplicate-rules"
+      private_constant :NOT_A_RULE, :NOT_A_RULE_TO_ADD, :DUPLICATE_RULES
+
+      # The rules to delete, named by identifier and by the value they match
+      #
+      # A list the API is given none of would delete every rule, so neither is sent unless it holds something. The API
+      # takes an identifier as a String, as it sends one, so an Integer is sent as one, and each is read as strictly
+      # as a StreamRule reads one, so that " 1_0 " is not sent for 10, nor -1 for a rule.
+      #
+      # @api private
+      # @param ids [Array] the rules that hold an identifier
+      # @param values [Array] the rules that hold a value and no identifier
+      # @return [Hash{Symbol => Array}] the identifiers and values of the rules to delete
+      # @raise [ArgumentError] if an identifier is neither an Integer that is not negative nor a String of digits
+      def deletion(ids, values)
+        {ids: ids.map { |rule| Validator.identifier!(identifier_of(rule)).to_s }, values: values.map { |rule| value_of(rule) }}.reject { |_, list| list.empty? }
+      end
+
+      # The rules given, which may be one rule rather than a list of them
+      #
+      # Only an Array is read as a list of rules, and anything else as one rule, since Array() would read a Hash as the
+      # list of its pairs, and a Struct as the list of its members, so that a Struct of a value and a tag would add its
+      # tag as a rule, and one of an identifier and a text delete the rule of that identifier. nil is no rules. A
+      # StreamRule is read as the Hash of what it holds, which the rest read as they read any other.
+      #
+      # @api private
+      # @param rules [Array, StreamRule, Hash, String, Integer, nil] the rules, or one rule
+      # @return [Array] the rules
+      def each_rule(rules)
+        listed = rules.nil? ? [] : Array.try_convert(rules) || [rules] #: Array[untyped]
+        listed.map { |rule| rule.is_a?(StreamRule) ? rule.to_h.compact : rule }
+      end
+
+      # The rules of a response, which holds none when it changed or matched none
+      # @api private
+      # @param body [Hash, nil] the parsed response body
+      # @return [Array<StreamRule>] the rules, frozen
+      def rules_of(body)
+        rules = Array(body.to_h["data"]) #: Array[Hash[String, untyped]]
+        rules.map { |rule| StreamRule.new(id: rule["id"], value: rule["value"], tag: rule["tag"]) }.freeze
+      end
+
+      # Check whether a problem is of a rule the app already has
+      #
+      # The API reports a rule it was asked to add that matches the value of a rule the app has as a DuplicateRule,
+      # whose type ends in duplicate-rules. It is not a rule the API rejected, so add_rules raises nothing for it.
+      #
+      # @api private
+      # @param problem [Problem] the problem the API reported
+      # @return [Boolean] true if the problem is a DuplicateRule
+      def duplicate?(problem) = problem.type.to_s.end_with?(DUPLICATE_RULES)
+
+      # The token of the page of rules after a response, or nil for the last page
+      #
+      # An empty token names no page, and a token that fetched a page already would have the pages requested again for
+      # good, and the API bills each request, so the page that names either is the last, as a page that names none is.
+      #
+      # @api private
+      # @param body [Hash, nil] the parsed response body
+      # @param spent [Array<String>] the tokens that fetched the pages before it
+      # @return [String, nil] the token, or nil if the page is the last
+      def next_token(body, spent)
+        token = body.to_h.dig("meta", "next_token")
+        token unless ["", *spent].include?(token)
+      end
+
+      # A rule to add, from the rule itself or the value it matches
+      #
+      # The API gives each rule it adds an identifier of its own, so one that a rule holds, as a rule that was read
+      # does, is not sent.
+      #
+      # @api private
+      # @param rule [Hash, String] the rule, or the value it matches
+      # @return [Hash] the rule
+      # @raise [ArgumentError] if the rule is neither a String nor a Hash that holds a value
+      def rule_to_add(rule)
+        value = String.try_convert(rule)
+        return {value:} if value
+
+        hash = Hash.try_convert(rule)
+        return hash.except("id", :id) if hash && (hash["value"] || hash[:value])
+
+        raise ArgumentError, format(NOT_A_RULE_TO_ADD, rule.inspect)
+      end
+
+      # The identifier of a rule, if it is one or holds one
+      #
+      # A String is the value a rule matches, as add_rules reads it, so an identifier is an Integer, held by a Hash,
+      # or read from the id of an X::MatchingRule, which each post of x-resources names in matching_rules, and which holds
+      # no value. Anything else with an id is not read for one, since a post, a user, or any other resource has an id
+      # too, which would delete whichever rule shared it.
+      #
+      # @api private
+      # @param rule [Hash, String, Integer, X::MatchingRule] the rule, the value it matches, or its identifier
+      # @return [Object, nil] the identifier, or nil for a rule that holds none
+      def identifier_of(rule)
+        hash = Hash.try_convert(rule)
+        return hash["id"] || hash[:id] if hash
+        return rule if rule.instance_of?(Integer)
+
+        rule.id if matching_rule?(rule)
+      end
+
+      # Check whether a rule is an X::MatchingRule
+      #
+      # x-streams does not depend on x-resources, which defines X::MatchingRule, so no rule is one until x-resources is
+      # loaded.
+      #
+      # @api private
+      # @param rule [Object] the rule
+      # @return [Boolean, nil] true if x-resources is loaded and the rule is an X::MatchingRule
+      def matching_rule?(rule) = defined?(X::MatchingRule) && rule.is_a?(X::MatchingRule) # steep:ignore UnknownConstant
+
+      # The value a rule matches, which deletes a rule holding no identifier
+      # @api private
+      # @param rule [Hash, String] the rule, or the value it matches
+      # @return [String] the value
+      # @raise [ArgumentError] if the rule is neither a String nor a Hash that holds an identifier or a value
+      def value_of(rule)
+        value = String.try_convert(rule)
+        return value if value
+
+        hash = Hash.try_convert(rule) || {} #: Hash[untyped, untyped]
+        hash["value"] || hash[:value] || raise(ArgumentError, format(NOT_A_RULE, rule.inspect))
+      end
+    end
+    private_constant :StreamRules
+  end
+end