x-resources 1.0.0

data/lib/x/resources/finders.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "x/core"
+require_relative "errors"
+require_relative "utils"
+
+module X
+  module Resources
+    # Class methods that look resources up one at a time, extended into each resource class the API can look up
+    #
+    # A resource the API offers no lookup of, such as a poll or a place, does not extend it, and so answers none of
+    # its methods, rather than answer them only to raise. BatchFinders includes it for a resource the API can also
+    # look up many at a time.
+    #
+    # Internal to x-resources: the methods it gives a resource class, such as X::Post.find, are public API, but the module
+    # is only how they are shared, and which classes extend or include it can change within 1.x.
+    #
+    # @api semipublic
+    module Finders
+      # Look up a resource by identifier
+      #
+      # @api public
+      # @param id [String, Integer, Resource] the identifier, or a resource of this class
+      # @param client [Object] the client used to make the request
+      # @param params [Hash] query parameters merged over the default parameters; one that overrides a default field
+      #   or expansion parameter to leave some out builds resources that are not hydrated, so hydrate fetches the rest
+      # @return [Resource, nil] the resource or nil if it was not found, whether the API answers 200 with no data or a
+      #   404 that reports the resource as not found
+      # @raise [ArgumentError] if the identifier is not one, or is a resource of another class, before a request
+      # @raise [X::NotFound] if the API answers any other 404, such as one from a client pointed at the wrong host or
+      #   API version
+      # @yieldparam problem [Problem] each problem the API reported, such as a resource that was not found
+      # @example Look up a post by identifier
+      #   X::Post.find(1234567890, client: client)
+      def find(id, client:, **params, &) = locate("#{endpoint!}/#{Utils.id_of(id, self)}", client:, **params, &)
+
+      # Look up a resource by identifier, which must exist
+      #
+      # The error it raises names the identifier looked up, whether the identifier or a resource was given. Its cause
+      # is the X::NotFound of a lookup the API answered with a 404 that reports the resource as not found.
+      #
+      # @api public
+      # @param id [String, Integer, Resource] the identifier, or a resource of this class
+      # @param client [Object] the client used to make the request
+      # @param params [Hash] query parameters merged over the default parameters; one that overrides a default field
+      #   or expansion parameter to leave some out builds resources that are not hydrated, so hydrate fetches the rest
+      # @return [Resource] the resource
+      # @raise [ArgumentError] if the identifier is not one, or is a resource of another class, before a request
+      # @raise [MissingResource] if the resource was not found, whether the API answers 200 with no data or a 404 that
+      #   reports the resource as not found
+      # @raise [X::NotFound] if the API answers any other 404, such as one from a client pointed at the wrong host or
+      #   API version
+      # @example Look up a post by identifier
+      #   X::Post.find!(1234567890, client: client)
+      def find!(id, client:, **params)
+        locate!("#{endpoint!}/#{Utils.id_of(id, self)}", Utils.id_from(id, self), client:, **params)
+      end
+
+      # Fetch a single resource from an endpoint
+      #
+      # Internal to x-resources: locate and the lookup of the authenticated user call it with the path of an endpoint,
+      # which names the API's own resources and can change within 1.x as the API does. It raises the NotFound of a
+      # 404, which only locate, whose path names one resource, reads as a resource that is missing, and only when the
+      # 404 reports it so.
+      #
+      # Data that holds no identifier is no resource: X answers the lookup of a user that does not exist, when it asks
+      # for a field the client may not read, such as parody for a client that authenticates as the app, with data that
+      # holds only the defaults of the fields it may, and the errors of those it may not, but no identifier.
+      #
+      # @api private
+      # @param path [String] the endpoint path
+      # @param client [Object] the client used to make the request
+      # @param params [Hash] query parameters merged over the default parameters; one that overrides a default field
+      #   or expansion parameter to leave some out builds resources that are not hydrated, so hydrate fetches the rest
+      # @return [Resource, nil] the resource or nil if the response has no data, or data that holds no identifier
+      # @yieldparam problem [Problem] each problem the API reported
+      # @example Fetch the authenticated user
+      #   X::User.__send__(:lookup, "users/me", client: client)
+      def lookup(path, client:, **params, &)
+        query = Utils.merge_params(default_params, params)
+        body = reporting(get(path, client:, query:), &)
+        resource_built_from(body, client:, hydrated: fully_requested_by?(query), query:) unless resourceless?(body)
+      end
+
+      # Fetch the resource a path names, which may be missing
+      #
+      # Internal to x-resources: the finders and hydrate call it with a path that ends in the identifier or the username
+      # of the resource, which they checked before building it. X documents both a 200 with no data and a 404 that
+      # reports the resource as not found as its answer to the lookup of a resource that is deleted, suspended, or was
+      # never there, so this reads the NotFound of the one as lookup reads the other: it finds nothing, and the block
+      # is given the problems the body of the 404 named.
+      #
+      # Any other 404 raises as it is, as every other failure does, since it says nothing of the resource: one that
+      # answers another request the client made for the lookup, such as the request for a token, or one whose body
+      # reports no resource as not found, such as that of a client pointed at the wrong host or API version.
+      #
+      # @api private
+      # @param path [String] the endpoint path, which ends in the identifier or the username of the resource
+      # @param client [Object] the client used to make the request
+      # @param params [Hash] query parameters merged over the default parameters; one that overrides a default field
+      #   or expansion parameter to leave some out builds resources that are not hydrated, so hydrate fetches the rest
+      # @return [Resource, nil] the resource or nil if the API answers a 404 that reports the resource as not found,
+      #   or a response that holds no resource
+      # @raise [X::NotFound] if the API answers any other 404
+      # @yieldparam problem [Problem] each problem the API reported
+      # @example Fetch a user that may not exist
+      #   X::User.__send__(:locate, "users/7505382", client: client)
+      def locate(path, client:, **params, &)
+        lookup(path, client:, **params, &)
+      rescue X::NotFound => e
+        raise unless reports_missing?(e, path)
+
+        e.problems.each { |problem| yield problem } if block_given?
+        nil
+      end
+
+      # Fetch the resource a path names, which must exist
+      #
+      # Internal to x-resources: the finders that end in a bang call it with the path locate takes, and what the message
+      # of the error names the resource by. The error holds the problems of the response, and, when the API answers
+      # a 404 that reports the resource as not found, its cause is the NotFound that holds the response itself.
+      #
+      # @api private
+      # @param path [String] the endpoint path, which ends in the identifier or the username of the resource
+      # @param name [String] the identifier, or the username after an at sign, the message names the resource by
+      # @param client [Object] the client used to make the request
+      # @param params [Hash] query parameters merged over the default parameters; one that overrides a default field
+      #   or expansion parameter to leave some out builds resources that are not hydrated, so hydrate fetches the rest
+      # @return [Resource] the resource
+      # @raise [MissingResource] if the API answers a 404 that reports the resource as not found, or a response that
+      #   holds no resource
+      # @raise [X::NotFound] if the API answers any other 404
+      # @example Fetch a user that must exist
+      #   X::User.__send__(:locate!, "users/7505382", "7505382", client: client)
+      def locate!(path, name, client:, **params)
+        problems = [] #: Array[Problem]
+        lookup(path, client:, **params) { |problem| problems << problem } || raise(missing(name, problems))
+      rescue X::NotFound => e
+        raise unless reports_missing?(e, path)
+
+        raise missing(name, e.problems)
+      end
+
+      # Fetch a list of resources from an endpoint without paginating
+      #
+      # Internal to x-resources: the batch lookups call it with the path of an endpoint, which names the API's own
+      # resources and can change within 1.x as the API does.
+      #
+      # @api private
+      # @param path [String] the endpoint path
+      # @param client [Object] the client used to make the request
+      # @param params [Hash] query parameters merged over the default parameters; one that overrides a default field
+      #   or expansion parameter to leave some out builds resources that are not hydrated, so hydrate fetches the rest
+      # @return [Array<Resource>] the resources
+      # @yieldparam problem [Problem] each problem the API reported
+      # @example Fetch users by username
+      #   X::User.__send__(:lookup_all, "users/by", client: client, usernames: ["sferik", "gem"])
+      def lookup_all(path, client:, **params, &)
+        query = Utils.merge_params(default_params, params)
+        collection_built_from(reporting(get(path, client:, query:), &), client:, hydrated: fully_requested_by?(query), query:)
+      end
+
+      # The client a lookup of this resource makes its requests with
+      #
+      # Most endpoints take the client as it is, and one that refuses the credentials a client signs with, such as the
+      # space endpoints, which refuse OAuth 1.0a, replaces it with a client that authenticates as the app.
+      #
+      # @api private
+      # @param client [Object] the client the lookup was given
+      # @return [Object] the client the request is made with
+      # @example Get the client a user lookup requests with
+      #   X::User.__send__(:client_for, client) # => client
+      def client_for(client) = client
+
+      private :lookup, :locate, :locate!, :lookup_all, :client_for
+
+      private
+
+      # Request an endpoint
+      # @api private
+      # @param path [String] the endpoint path
+      # @param client [Object] the client used to make the request
+      # @param query [Hash] the query parameters, merged over the default parameters
+      # @return [Hash, nil] the parsed response body
+      def get(path, client:, query:)
+        client_for(client).get(Utils.path(path, query), **Utils::JSON_CLASSES)
+      end
+
+      # Build the resource a request that creates one returned, which must hold it
+      #
+      # The API answers a request that creates a resource with the resource, so a successful response without one
+      # created nothing the caller can read, and raises, holding the problems the response reported, as current!
+      # raises for a users/me that returns no user, rather than return nil, which the caller would read as the
+      # resource. A response whose data holds no identifier holds no resource, as find reads it, so it raises too.
+      #
+      # @api private
+      # @param body [Hash, nil] the parsed response body
+      # @param request [String] the method and path of the request, which the message names
+      # @param client [Object] the client used to make the request
+      # @return [Resource] the resource
+      # @raise [MissingResource] if the response holds no resource, or data without an identifier
+      # @raise [InvalidAttribute] if the response holds a resource with an identifier that is not one
+      # @example Build the post a request created
+      #   X::Post.__send__(:created_from_response, {"data" => {"id" => "1"}}, "POST tweets", client: client)
+      def created_from_response(body, request, client:)
+        raise MissingResource.new("#{request} returned no #{self}", problems: Problem.all_from(body)) if resourceless?(body)
+
+        resource_built_from(body, client:, hydrated: false, query: nil) #: Resource
+      end
+
+      # The error of a resource a lookup did not find
+      # @api private
+      # @param name [String] the identifier, or the username after an at sign, the message names the resource by
+      # @param problems [Array<Problem>] the problems the API reported
+      # @return [MissingResource] the error, which names the class and the resource
+      def missing(name, problems) = MissingResource.new("Could not find #{self} #{name}", problems:)
+
+      # Whether a 404 reports the resource a lookup named as not found
+      #
+      # It does when it answers the lookup itself, a GET of a URI whose path ends in the path of the lookup, behind
+      # whatever path the base URL of the client holds, and its body describes, or names among its errors, a problem
+      # of the resource-not-found type. A NotFound that names no request, as one built without a URI does, is not
+      # known to answer the lookup, so it reports nothing.
+      #
+      # @api private
+      # @param error [X::NotFound] the error of the 404
+      # @param path [String] the endpoint path of the lookup
+      # @return [Boolean] true if the 404 answers the lookup and reports a resource as not found
+      def reports_missing?(error, path)
+        error.http_method.eql?(:get) && error.uri&.path.to_s.end_with?("/#{path}") &&
+          [*error.problems, error.problem].compact.any?(&:not_found?)
+      end
+
+      # Whether a response body holds no resource
+      #
+      # It holds none when it holds no data, data that is no object, or an object with no identifier.
+      #
+      # @api private
+      # @param body [Hash, nil] the parsed response body
+      # @return [Boolean] true if the body holds no object with an identifier as its data
+      def resourceless?(body) = Hash.try_convert(body.to_h["data"]).to_h[id_key].nil?
+
+      # Pass the problems a response body reports to a block, if there is one
+      # @api private
+      # @param body [Hash, nil] the parsed response body
+      # @return [Hash, nil] the body
+      # @yieldparam problem [Problem] each problem the body reports
+      def reporting(body)
+        Problem.all_from(body).each { |problem| yield problem } if block_given?
+        body
+      end
+    end
+    private_constant :Finders
+  end
+end

data/lib/x/resources/identity.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module X
+  module Resources
+    # Equality and hashing by class and identifier, so the same resource fetched twice compares equal
+    #
+    # Internal to x-resources: the methods it gives a resource, such as ==, are public API, but the module is only how
+    # they are shared, and which classes extend or include it can change within 1.x.
+    #
+    # @api semipublic
+    module Identity
+      # Compare resources by class and identifier
+      #
+      # @api public
+      # @param other [Object] the object to compare with
+      # @return [Boolean] true if the other object is the same kind of resource with the same identifier
+      # @example Compare users fetched in different requests
+      #   post.author == client.find_user("sferik")
+      def ==(other)
+        self.class.equal?(other.class) && id.eql?(other.id)
+      end
+
+      # @!method eql?(other)
+      #   Alias for ==, compares resources by class and identifier
+      #   @api public
+      #   @param other [Object] the object to compare with
+      #   @return [Boolean] true if the other object is the same kind of resource with the same identifier
+      #   @example Deduplicate resources
+      #     [user, client.find_user("sferik")].uniq
+      alias_method :eql?, :==
+
+      # Hash resources by class and identifier
+      #
+      # @api public
+      # @return [Integer] the hash code
+      # @example Use resources as hash keys
+      #   {user => 1}[client.find_user("sferik")]
+      def hash
+        [self.class, id].hash
+      end
+
+      # Deconstruct the resource into its attributes, so it matches a hash pattern
+      #
+      # Every attribute the resource declares is read as its own method reads it, so a pattern sees the
+      # identifier as a number, a timestamp as a Time, and a metric by the name it is read by. A pattern can ask
+      # for an attribute by another name it is read by, such as retweet_count for repost_count, and a pattern
+      # that asks for every attribute, with a double splat, gets each once, by the name the resource declares.
+      #
+      # @api public
+      # @param keys [Array<Symbol>, nil] the keys the pattern asks for, or nil for every attribute
+      # @return [Hash{Symbol => Object}] the attributes
+      # @example Match a post by its author
+      #   puts "by sferik" if post in {author_id: 7505382}
+      # @example Match a post by a name from before posts were posts
+      #   puts "widely reposted" if post in {retweet_count: 100..}
+      def deconstruct_keys(keys)
+        klass = self.class
+        names = klass.__send__(:attribute_names)
+        names = (names + klass.__send__(:attribute_aliases)) & keys unless keys.nil?
+        names.to_h { |name| [name, public_send(name)] }
+      end
+    end
+    private_constant :Identity
+  end
+end

data/lib/x/resources/includes.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "monitor"
+require_relative "utils"
+
+module X
+  module Resources
+    # The context of one API response: its identity map of expanded objects and stubs, and the problems it reported
+    # @api private
+    class Includes
+      # The keys the API gave the includes of a class before it named tweets posts, which it still gives them where it
+      # has not renamed them, such as in a stream
+      TWEET_KEYS = {"posts" => "tweets"}.freeze
+      private_constant :TWEET_KEYS
+
+      # Initialize a new identity map
+      #
+      # @api private
+      # @param data [Hash, nil] the includes hash from an API response
+      # @param problems [Array<Problem>] the problems the response reported
+      # @param query [Hash{String => Object}, nil] the query parameters of the request, merged over the defaults, or
+      #   nil if they are not known
+      # @return [Includes] a new identity map
+      def initialize(data = nil, problems: [], query: nil)
+        @data = Utils.deep_freeze(data.to_h)
+        @problems = problems.freeze
+        @query = Utils.deep_freeze(query)
+        @monitor = Monitor.new
+        @index = {}
+        @resources = {}
+        freeze
+      end
+
+      # The problems the response reported, such as missing expanded resources
+      # @api private
+      # @return [Array<Problem>] the problems
+      attr_reader :problems
+
+      # What some resources built over the identity map refer to of it, as plain data
+      #
+      # A resource that Marshal writes holds it, and a page holds it once for the resources that share it. It is the
+      # included objects the resources refer to, and the ones those refer to in turn, so that every reference that
+      # resolves to an included object still does, with none of the rest of the response; the problems about any of
+      # them, or about none; and the query, which tells whether an included object is hydrated. The problems are
+      # written as themselves, which Marshal writes as their attributes.
+      #
+      # @api private
+      # @param resources [Array<Resource>] the resources, each built over this identity map
+      # @return [Array(Hash, Array<Problem>, Hash, nil)] the included objects, the problems, and the query
+      def state_of(resources)
+        kept = {} #: Hash[String, Array[attrs]]
+        ids = resources.map(&:id)
+        pending = resources.map { |resource| [resource.class, resource.attrs] } #: Array[[singleton(Resource), attrs]]
+        # Each object kept joins the objects whose references are read, which each reaches once it comes to them
+        pending.each do |klass, attrs|
+          referenced = referenced_by(klass, attrs)
+          ids.concat(referenced)
+          pending.concat(keep(kept, referenced))
+        end
+        [kept, problems_about(ids), @query]
+      end
+
+      # Check whether a resource of the response is hydrated as it is read back
+      #
+      # A resource written with the query of its request is hydrated only if that query asks for every field and
+      # expansion this release requests of its class, since a minor release may add to them, so that a resource an
+      # earlier release wrote as hydrated is not, once it lacks what was added, and hydrate fetches it. One written
+      # without a query, as one a caller built from a response is, is hydrated as it was written.
+      #
+      # @api private
+      # @param klass [Class] the resource class
+      # @param hydrated [Boolean] whether the resource was hydrated as it was written
+      # @return [Boolean] true if the resource holds every field this release requests
+      def hydrated_as_read?(klass, hydrated)
+        query = @query
+        hydrated && (query.nil? || klass.__send__(:fully_requested_by?, query))
+      end
+
+      # The problems the response reported about any of some identifiers
+      #
+      # A problem that names no resource is about any of them, too. A problem names the resource it is about by its resource_id, or by its value, and one that names neither
+      # could be about any resource of the response.
+      #
+      # @api private
+      # @param ids [Array<Object>] the identifiers of a resource and of the resources it refers to
+      # @return [Array<Problem>] the problems, frozen
+      def problems_about(ids)
+        ids = ids.map(&:to_s)
+        problems.select { |problem| about?(problem, ids) }.freeze
+      end
+
+      # Resolve a reference to the included resource or a stub holding its identifier
+      #
+      # Every reference to the same resource within one response resolves to the same object,
+      # so hydrating it once hydrates it everywhere it is referenced.
+      #
+      # An included resource is hydrated when the request asked for every field of its class, and its class expands
+      # nothing of its own, as a poll, a place, and media expand nothing, since the API applies the expansions of a
+      # request to its data alone: a post or a user included in a response lacks the resources it would expand, which
+      # hydrate looks up. A stub, of a resource the response did not include, is never hydrated.
+      #
+      # @api private
+      # @param klass [Class] the resource class
+      # @param id [String] the identifier
+      # @param client [Object, nil] the client used to fetch the response
+      # @return [Resource] the resource
+      def resolve(klass, id, client:)
+        @monitor.synchronize do
+          @resources[[klass, id]] ||= build(klass, id, client)
+        end
+      end
+
+      private
+
+      # Build the included resource an identifier names, or a stub of it
+      # @api private
+      # @param klass [Class] the resource class
+      # @param id [String] the identifier
+      # @param client [Object, nil] the client used to fetch the response
+      # @return [Resource] the resource
+      def build(klass, id, client)
+        attrs = index(klass)[id]
+        return klass.__send__(:build, {klass.__send__(:id_key) => id}, client:, includes: self) if attrs.nil?
+
+        klass.__send__(:build, attrs, client:, includes: self, hydrated: fully_requested?(klass))
+      end
+
+      # Check whether a problem names one of some identifiers, or names none
+      # @api private
+      # @param problem [Problem] the problem
+      # @param ids [Array<String>] the identifiers
+      # @return [Boolean] true if the problem names one of the identifiers, or names no resource
+      def about?(problem, ids)
+        named = [problem.resource_id, problem.value].compact
+        named.empty? || named.any? { |value| ids.include?(value.to_s) }
+      end
+
+      # Check whether the request asked for every field of a class that expands nothing
+      # @api private
+      # @param klass [Class] the resource class
+      # @return [Boolean] true if a resource of the class that the response included holds every field
+      def fully_requested?(klass)
+        query = @query
+        return false if query.nil? || klass.default_params.key?("expansions")
+
+        klass.__send__(:fully_requested_by?, query)
+      end
+
+      # Keep the included objects some identifiers name that are not kept yet
+      #
+      # An object is kept under the key the response included it by, in the order the response included it, so that
+      # what is kept resolves as the response did.
+      #
+      # @api private
+      # @param kept [Hash{String => Array<Hash>}] the included objects kept so far, which this adds to
+      # @param ids [Array<Object>] the identifiers, as the objects that refer to them hold them
+      # @return [Array(Class, Hash)] the class and attributes of each object this kept, whose references are kept next
+      def keep(kept, ids)
+        collections.flat_map do |klass, key|
+          found = named(klass, key, ids) - kept[key].to_a
+          kept[key] = @data.fetch(key) & (kept[key].to_a + found) unless found.empty?
+          found.map { |attrs| [klass, attrs] }
+        end
+      end
+
+      # The included objects of a resource class that some identifiers name
+      # @api private
+      # @param klass [Class] the resource class
+      # @param key [String] the key the response included the objects of the class under
+      # @param ids [Array<Object>] the identifiers
+      # @return [Array<Hash>] the objects, in the order the response included them
+      def named(klass, key, ids) = @data.fetch(key).select { |attrs| ids.include?(attrs[klass.__send__(:id_key)]) }
+
+      # The identifiers of what an object refers to, as the object holds them
+      #
+      # A reference resolves an identifier as the object holds it, so it is kept as that too.
+      #
+      # @api private
+      # @param klass [Class] the resource class of the object
+      # @param attrs [Hash{String => Object}] the attributes of the object
+      # @return [Array<Object>] the identifiers
+      def referenced_by(klass, attrs) = klass.__send__(:referenced_ids, attrs).compact
+
+      # The key the response included each resource class under, of those it included
+      # @api private
+      # @return [Array<Array(Class, String)>] each class, and the key the response included it under
+      def collections
+        classes = Resource.subclasses #: Array[singleton(Resource)]
+        classes.filter_map do |klass|
+          name = klass.__send__(:includes_key)
+          key = [name, TWEET_KEYS[name]].find { |candidate| @data.key?(candidate) } #: String?
+          [klass, key] unless key.nil?
+        end
+      end
+
+      # The included objects of one resource class, under the key the API gave them
+      # @api private
+      # @param klass [Class] the resource class
+      # @return [Array<Hash>] the included objects, empty if the response included none
+      def entries_of(klass)
+        key = klass.__send__(:includes_key)
+        @data.fetch(key) { @data.fetch(TWEET_KEYS[key], []) }
+      end
+
+      # Build or fetch the identifier index for one type of expanded object
+      #
+      # @api private
+      # @param klass [Class] the resource class
+      # @return [Hash{String => Hash}] the expanded objects keyed by identifier
+      def index(klass)
+        @index[klass.__send__(:includes_key)] ||= entries_of(klass).group_by { |attrs| attrs[klass.__send__(:id_key)] }.transform_values(&:first)
+      end
+    end
+    private_constant :Includes
+  end
+end