x-resources 1.0.0

data/lib/x/resources/matching_rule.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "serialization"
+require_relative "shape"
+require_relative "utils"
+require_relative "value_equality"
+require_relative "value_marshalling"
+
+module X
+  module Resources
+    # A rule of the filtered stream that a post the stream delivered matched: the identifier the API gave the rule, and
+    # the tag it is labelled with
+    #
+    # The stream names a rule a post matched by its identifier and its tag alone, not by the value it matches, so this is
+    # not an X::StreamRule of x-streams, which holds that value. It names the rule to X::StreamingClient#delete_rules
+    # by its identifier, as rule.id, or as rule.to_h, and it is found among the rules X::StreamingClient#rules reads by
+    # the identifier they share. x-resources depends on x-streams for none of this: a stream builds each post with
+    # X::Post.from_response, as a request does.
+    #
+    # It is frozen, compares equal to a rule of the same attributes, and matches a pattern of its identifier and tag,
+    # as in `rule in {tag: "ruby"}`. Its attributes are what the stream sent of the rule, as those of a resource are, so
+    # to_h, as_json, and to_json give them as the stream did, whatever the stream comes to send of a rule beside its
+    # identifier and tag.
+    #
+    # @api public
+    class ::X::MatchingRule
+      include Serialization
+      include ValueEquality
+      include ValueMarshalling
+
+      # The mixins of the class by their full names, which YARD needs to resolve them in a class opened under X
+      #
+      # @!parse
+      #   include X::Resources::Serialization
+      #   include X::Resources::ValueEquality
+      #   include X::Resources::ValueMarshalling
+
+      # The attributes of the rule, as the stream sends them
+      #
+      # The identifier is a String, as the stream sends it, and a rule without a tag holds none.
+      #
+      # @api public
+      # @return [Hash{String => Object}] the attributes, frozen
+      # @example Get the attributes
+      #   rule.attrs # => {"id" => "1165037377523306498", "tag" => "ruby"}
+      attr_reader :attrs
+
+      # Initialize a rule a post matched from the attributes the stream sent of it
+      #
+      # The identifier and tag are read as it is built, so that a rule that holds either as something else raises
+      # here, rather than from its readers.
+      #
+      # @api public
+      # @param attrs [Hash{String, Symbol => Object}] the attributes, which name the identifier as id, as an Integer or
+      #   as the String the stream sends, and the tag as tag, unless the rule has none
+      # @return [MatchingRule] the frozen rule
+      # @raise [ArgumentError] if the attributes are not a Hash, the identifier is not one, or the tag is neither a
+      #   String nor nil
+      # @example Build a rule a post matched
+      #   X::MatchingRule.new({"id" => "1165037377523306498", "tag" => "ruby"})
+      def initialize(attrs)
+        @attrs = Utils.deep_freeze(Utils.attributes!(attrs))
+        id
+        raise ArgumentError, "tag must be a String, not #{tag.inspect}" unless tag.nil? || tag.is_a?(String)
+
+        freeze
+      end
+
+      # 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 stream rule is, and as
+      # strictly as any identifier is read: a String of digits alone, with no sign, underscore, or whitespace.
+      #
+      # @api public
+      # @return [Integer] the identifier
+      # @raise [ArgumentError] if the attributes hold no identifier, or one that is neither an Integer that is not
+      #   negative nor a String of digits
+      # @example Get the identifier
+      #   rule.id # => 1165037377523306498
+      def id = Shape.integer(attrs["id"]) || raise(ArgumentError, "a matching rule needs an id")
+
+      # The tag the rule is labelled with
+      # @api public
+      # @return [String, nil] the tag, or nil for a rule without one
+      # @example Get the tag
+      #   rule.tag # => "ruby"
+      def tag = attrs["tag"]
+
+      # The identifier and tag of the rule, which a pattern matches against
+      #
+      # @api public
+      # @param keys [Array<Symbol>, nil] the keys the pattern asks for, or nil for both
+      # @return [Hash{Symbol => Integer, String, nil}] the identifier and tag the pattern asks for
+      # @example Keep the posts that matched the rule tagged ruby
+      #   post.matching_rules.any? { |rule| rule in {tag: "ruby"} }
+      def deconstruct_keys(keys) = Utils.deconstruct(self, keys, %i[id tag])
+
+      # Summarize the rule for the console
+      #
+      # @api public
+      # @return [String] the class name, identifier, and tag
+      # @example Inspect a rule
+      #   rule.inspect # => #<X::MatchingRule id=1165037377523306498 tag="ruby">
+      def inspect = "#<#{self.class} id=#{id} tag=#{tag.inspect}>"
+    end
+  end
+end

data/lib/x/resources/media.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require_relative "batch_finders"
+require_relative "media_ids"
+require_relative "resource"
+
+module X
+  module Resources
+    # A photo, video, or animated GIF attached to a post, which its media key identifies
+    # @api public
+    class ::X::Media < Resource
+      extend BatchFinders
+
+      # The mixins of the class by their full names, which YARD needs to resolve them in a class opened under X
+      #
+      # @!parse
+      #   extend X::Resources::BatchFinders
+
+      # Every public media field
+      #
+      # A minor release may add to it the fields the API adds, so that a lookup asks for them too; see
+      # {Resource#hydrated?} for what that means for a resource looked up with a list of fields of its own.
+      FIELDS = %w[alt_text duration_ms height media_key preview_image_url public_metrics type url variants width].freeze
+
+      # The attribute holding the identifier
+      #
+      # @api private
+      # @return [String] the identifier key
+      # @example Get the identifier key
+      #   X::Media.__send__(:id_key) # => "media_key"
+      def self.id_key
+        "media_key"
+      end
+
+      # The lookup endpoint
+      #
+      # @api private
+      # @return [String] the endpoint
+      # @example Get the lookup endpoint
+      #   X::Media.__send__(:endpoint) # => "media"
+      def self.endpoint
+        "media"
+      end
+
+      # The query parameter a batch lookup takes the media keys in
+      #
+      # @api private
+      # @return [Symbol] the parameter name
+      # @example Get the parameter of a batch lookup
+      #   X::Media.__send__(:batch_key) # => :media_keys
+      def self.batch_key = :media_keys
+
+      # The name of the fields parameter
+      #
+      # @api private
+      # @return [String] the fields parameter
+      # @example Get the fields parameter
+      #   X::Media.__send__(:fields_key) # => "media.fields"
+      def self.fields_key = "media.fields"
+
+      # The default query parameters requesting every public field
+      #
+      # @api public
+      # @return [Hash{String => Array<String>}] the default query parameters
+      # @example Get the default fields
+      #   X::Media.default_params["media.fields"]
+      def self.default_params
+        {"media.fields" => FIELDS}
+      end
+
+      # The type of the identifier, a media key
+      #
+      # Media is looked up by its media key, such as "3_1880028106020515840", and not by the numeric identifier an
+      # upload returns beside it, which the lookup endpoint does not find, so a number raises rather than look up
+      # nothing.
+      #
+      # @api private
+      # @return [Symbol] media_key
+      # @example Get the identifier type
+      #   X::Media.__send__(:id_type) # => :media_key
+      def self.id_type = :media_key
+
+      # The media key of what an upload returned, or of a value that is one already
+      #
+      # What an upload returns holds both a media key and a numeric identifier, and the lookup endpoint takes the
+      # media key, so this reads that rather than the identifier a resource is usually found by.
+      #
+      # @api private
+      # @param media [#media_key, String] the media, or its media key
+      # @return [Object] the media key
+      # @example Get the media key of an upload
+      #   X::Media.__send__(:key_of, uploaded) # => "3_1880028106020515840"
+      def self.key_of(media) = media.respond_to?(:media_key) ? media.media_key : media
+
+      # Look up media by media key
+      #
+      # @api public
+      # @param media [#media_key, String, Media] the media key, what an upload returned, or media
+      # @param client [Object] the client used to make the request
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Media, nil] the media, or nil if it was not found
+      # @yieldparam problem [Problem] each problem the API reported
+      # @example Look up what an upload returned
+      #   X::Media.find(uploaded, client: client)
+      def self.find(media, client:, **params) = super(key_of(media), client:, **params) #: Media?
+
+      # Look up media by media key, which must exist
+      #
+      # The error it raises names the media key looked up, whether a media key, what an upload returned, or media was
+      # given.
+      #
+      # @api public
+      # @param media [#media_key, String, Media] the media key, what an upload returned, or media
+      # @param client [Object] the client used to make the request
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Media] the media
+      # @raise [MissingResource] if the media was not found
+      # @example Look up what an upload returned
+      #   X::Media.find!(uploaded, client: client)
+      def self.find!(media, client:, **params) = super(key_of(media), client:, **params) #: Media
+
+      # Refer to media by media key without a request
+      #
+      # @api public
+      # @param media [#media_key, String, Media] the media key, what an upload returned, or media
+      # @param client [Object, nil] the client used to fetch the media
+      # @return [Media] a stub that hydrates to the full media
+      # @example Refer to what an upload returned
+      #   X::Media.from_id(uploaded, client: client).hydrate.url
+      def self.from_id(media, client: nil) = super #: Media
+
+      # Build a stub of media that hydrates with the stubs of a batch
+      #
+      # @api private
+      # @param media [#media_key, String, Media] the media key, what an upload returned, or media
+      # @param client [Object, nil] the client used to fetch the media
+      # @param batch [Resources::Batch, nil] the batch the stub hydrates with
+      # @return [Media] a stub that hydrates to the full media
+      # @example Build the stub of a page of media
+      #   X::Media.__send__(:from_id_in_batch, "3_1", client: client, batch: batch)
+      def self.from_id_in_batch(media, client:, batch: nil) = super(key_of(media), client:, batch:)
+
+      # Look up many media by media key, in parallel batches
+      #
+      # @api public
+      # @param media [Array<#media_key, String, Media>] the media keys, what the uploads returned, or media
+      # @param client [Object] the client used to make the requests
+      # @param params [Hash] query parameters merged over the default parameters, and the concurrency of the batches
+      # @return [Array<Media>] the media that was found
+      # @yieldparam problem [Problem] each problem the API reported
+      # @example Look up what the uploads returned
+      #   X::Media.find_all(uploads, client: client)
+      def self.find_all(media, client:, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) = super(media.map { |value| key_of(value) }, client:, concurrency:, **params) #: Array[Media]
+
+      # The key under which media appear in the includes of a response
+      #
+      # @api private
+      # @return [String] the includes key
+      # @example Get the includes key
+      #   X::Media.__send__(:includes_key) # => "media"
+      def self.includes_key
+        "media"
+      end
+      private_class_method :id_key, :endpoint, :batch_key, :fields_key, :id_type, :key_of, :from_id_in_batch, :includes_key
+
+      # @!method id
+      #   The identifier of the media, which is its media key
+      #
+      #   Media is looked up by its media key, so that is what identifies it here, where the identifier of uploaded
+      #   media, and the one a post or a direct message attaches media by, is the number media_id reads. Both X::Media
+      #   and the uploaded media of x-uploads answer media_key and media_id alike.
+      #
+      #   @api public
+      #   @return [String] the media key
+      #   @example Get the media key
+      #     media.id # => "3_1880028106020515840"
+
+      # @!attribute [r] media_key
+      #   The media key
+      #   @api public
+      #   @return [String] the media key
+      #   @example Get the media key
+      #     media.media_key
+      attribute :media_key
+
+      # The numeric identifier of the media, which its media key names
+      #
+      # A media key names the identifier after the number of the type of the media and an underscore. It is the
+      # identifier an upload returns, and the one a post or a direct message attaches media by.
+      #
+      # @api public
+      # @return [Integer] the media identifier
+      # @example Get the identifier the media key names
+      #   X::Media.from_id("3_1880028106020515840").media_id # => 1880028106020515840
+      def media_id = Integer(MediaIds.media_key_id(self), 10)
+
+      # @!attribute [r] type
+      #   The media type: photo, video, or animated_gif
+      #   @api public
+      #   @return [String, nil] the media type
+      #   @example Get the type
+      #     media.type
+      attribute :type
+
+      # @!attribute [r] url
+      #   The URL of a photo
+      #   @api public
+      #   @return [String, nil] the URL
+      #   @example Get the URL
+      #     media.url
+      attribute :url
+
+      # @!attribute [r] preview_image_url
+      #   The URL of a video or GIF preview image
+      #   @api public
+      #   @return [String, nil] the preview image URL
+      #   @example Get the preview image URL
+      #     media.preview_image_url
+      attribute :preview_image_url
+
+      # @!attribute [r] alt_text
+      #   The alternative text
+      #   @api public
+      #   @return [String, nil] the alternative text
+      #   @example Get the alternative text
+      #     media.alt_text
+      attribute :alt_text
+
+      # @!attribute [r] duration_ms
+      #   The duration of a video in milliseconds
+      #   @api public
+      #   @return [Integer, nil] the duration in milliseconds
+      #   @example Get the duration
+      #     media.duration_ms
+      attribute :duration_ms, :integer
+
+      # @!attribute [r] height
+      #   The height in pixels
+      #   @api public
+      #   @return [Integer, nil] the height in pixels
+      #   @example Get the height
+      #     media.height
+      attribute :height, :integer
+
+      # @!attribute [r] width
+      #   The width in pixels
+      #   @api public
+      #   @return [Integer, nil] the width in pixels
+      #   @example Get the width
+      #     media.width
+      attribute :width, :integer
+
+      # @!attribute [r] variants
+      #   The video variants with their bit rates, content types, and URLs
+      #   @api public
+      #   @return [Array<Hash>] the variants, empty if there are none
+      #   @example Get the variants
+      #     media.variants
+      attribute :variants, :objects
+
+      # @!attribute [r] public_metrics
+      #   The public metrics
+      #   @api public
+      #   @return [Hash, nil] the public metrics
+      #   @example Get the public metrics
+      #     media.public_metrics
+      attribute :public_metrics, :object
+
+      # @!attribute [r] view_count
+      #   The number of views
+      #   @api public
+      #   @return [Integer, nil] the view count
+      #   @example Get the view count
+      #     media.view_count
+      attribute :view_count, :integer, key: %w[public_metrics view_count]
+    end
+  end
+end

data/lib/x/resources/media_ids.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module X
+  module Resources
+    # Reads the media identifiers a new post or direct message attaches
+    #
+    # What an upload returns, media such as the media of another post, and a media identifier each name media, and
+    # this reads the identifier the API takes from any of them.
+    #
+    # @api private
+    module MediaIds
+      # The pattern of a media key, which names the media identifier after the number of its type and an underscore
+      MEDIA_KEY = /\A\d+_(\d+)\z/
+
+      # The pattern of a media identifier the API takes: one to nineteen digits
+      MEDIA_ID = /\A\d{1,19}\z/
+
+      # The message of the error raised for something that is neither media nor the identifier of media
+      NOT_MEDIA = "media is what an upload returned, media such as X::Media, a media key, or a media identifier, not %s"
+      private_constant :MEDIA_KEY, :MEDIA_ID, :NOT_MEDIA
+
+      extend self
+
+      # Extract a media identifier from an upload, from media, or from a raw value
+      #
+      # What an upload returns is read with fetch, which a Hash answers and so does the uploaded media of
+      # x-uploads, which this gem does not depend on. Media, such as the media of a post, is read from its media
+      # key, which names the identifier, and so is a String that is a media key, such as the id of X::Media.
+      #
+      # @api private
+      # @param value [#fetch, #media_key, String, Integer] what an upload returned, holding an id, media, a media key,
+      #   or an identifier
+      # @return [String] the media identifier
+      # @raise [ArgumentError] if the value is none of them, such as a Hash without an "id", or names an identifier the
+      #   API would refuse
+      def media_id_of(value)
+        id = case value
+        when String then value[MEDIA_KEY, 1] || value
+        when Integer then value.to_s
+        else value.respond_to?(:fetch) ? value.fetch("id") { raise ArgumentError, "#{format(NOT_MEDIA, value.inspect)}, which holds no \"id\"" }.to_s : media_key_id(value)
+        end
+        id.match?(MEDIA_ID) ? id : raise(ArgumentError, format(NOT_MEDIA, value.inspect))
+      end
+
+      # The media identifier a media key names
+      # @api private
+      # @param media [#media_key, Object] the media
+      # @return [String] the media identifier
+      # @raise [ArgumentError] if the media has no media key that names an identifier
+      def media_key_id(media)
+        key = media.media_key if media.respond_to?(:media_key)
+        key.to_s[MEDIA_KEY, 1] || raise(ArgumentError, format(NOT_MEDIA, media.inspect))
+      end
+
+      # The media identifiers of one upload or of several
+      #
+      # One upload needs no array around it, so a single value is read as a list of one, and nil, like an empty
+      # list, as none.
+      #
+      # @api private
+      # @param media_ids [Array, #fetch, Media, String, Integer, nil] what the uploads returned, media, or identifiers,
+      #   one or many
+      # @return [Array<String>] the media identifiers, empty for nil
+      def media_ids_of(media_ids)
+        case media_ids
+        when nil then []
+        when Array then media_ids.map { |media| media_id_of(media) }
+        else [media_id_of(media_ids)]
+        end
+      end
+    end
+    private_constant :MediaIds
+  end
+end

data/lib/x/resources/memo.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module X
+  module Resources
+    # A thread-safe slot that holds one lazily computed value
+    # @api private
+    class Memo
+      # Marker for a slot that holds no value yet
+      UNSET = Object.new.freeze
+      private_constant :UNSET
+
+      # Initialize an empty memo
+      #
+      # @api private
+      # @return [Memo] a new memo
+      def initialize
+        @monitor = Monitor.new
+        @value = UNSET
+      end
+
+      # Fetch the value, computing and storing it on first access
+      #
+      # @api private
+      # @yield computes the value when none is stored
+      # @return [Object] the memoized value
+      def fetch
+        @monitor.synchronize do
+          @value = yield if @value.equal?(UNSET)
+          @value
+        end
+      end
+
+      # Check whether a value is stored, whether computed or stored
+      #
+      # It reads the slot without the lock, since a value, once stored, is only ever replaced by another.
+      #
+      # @api private
+      # @return [Boolean] true if the memo holds a value, which may be nil
+      def stored? = !@value.equal?(UNSET)
+
+      # Store a value, replacing any memoized value
+      #
+      # @api private
+      # @param value [Object] the value to store
+      # @return [Object] the stored value
+      def store(value)
+        @monitor.synchronize { @value = value }
+      end
+    end
+    private_constant :Memo
+  end
+end