x-resources 1.0.0

data/lib/x/resources/pages.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+require "monitor"
+require "x/core"
+require_relative "batch"
+require_relative "batch_finders"
+require_relative "errors"
+require_relative "page"
+require_relative "utils"
+
+module X
+  module Resources
+    # The pages of a cursor, fetched when they are asked for and kept
+    # @api private
+    class Pages
+      # The message of the error raised for a page whose next token fetched an earlier page
+      REPEATED_TOKEN = "Page %<index>d of %<path>s names the next_token %<token>p, which fetched an earlier page"
+      private_constant :REPEATED_TOKEN
+
+      # Initialize the pages of a cursor
+      #
+      # @api private
+      # @param cursor [Cursor] the cursor whose pages these are
+      # @return [Pages] the pages
+      def initialize(cursor)
+        @cursor = cursor
+        @monitor = Monitor.new
+        @pages, @prefetching, @failures = [], Set.new, {}
+        freeze
+      end
+
+      # The page at an index, fetching the next in the background when prefetching
+      #
+      # @api private
+      # @param index [Integer] the zero-based page index
+      # @return [Page, nil] the page or nil if the collection has fewer pages
+      # @raise [TypeError] if the index is not an Integer
+      # @raise [ArgumentError] if the index is negative, since pages are read forward from the first
+      def at(index)
+        raise TypeError, "#{index.inspect} is not a page index: pages are numbered by Integers" unless index.instance_of?(Integer)
+        raise ArgumentError, "#{index} is not a page index: pages are numbered from zero" if index.negative?
+
+        current = cached(index)
+        prefetch(index + 1) if @cursor.prefetch? && current&.next_token
+        current
+      end
+
+      # The first resources, reading pages no larger than needed and keeping them
+      #
+      # The pages already fetched are read first, so a cursor that holds what is asked for pays for no request, and
+      # each page fetched asks for no more than what is asked for that the pages before it left, raised to the
+      # smallest page the endpoint accepts. The pages it fetches are kept, as every page is, so an iteration after
+      # it requests only what it left.
+      #
+      # @api private
+      # @param count [Integer] the number of resources wanted
+      # @return [Array<Resource>] the first resources, fewer if the collection holds fewer
+      # @raise [ArgumentError] if the count is negative, which Array#first raises for
+      def read(count)
+        @monitor.synchronize do
+          resources = fetched.flat_map(&:to_a)
+          while resources.size < count && (page = next_page(count - resources.size))
+            resources.concat(page.to_a)
+          end
+          resources.first(count).freeze
+        end
+      end
+
+      private
+
+      # The pages fetched so far
+      #
+      # A nil marks the end of the collection, and only ever follows every page, so what is not nil is every page.
+      #
+      # @api private
+      # @return [Array<Page>] the pages
+      def fetched = @pages.compact
+
+      # Fetch and keep the page after the pages fetched so far, sized for what is wanted
+      # @api private
+      # @param wanted [Integer] the number of resources wanted from the page
+      # @return [Page, nil] the page, or nil if the collection has no more
+      def next_page(wanted)
+        index = fetched.size
+        @pages[index] ||= fetch(index, wanted)
+      end
+
+      # Fetch the pages up to an index, in order, storing each in the cache
+      #
+      # The token of one page asks for the next, so the pages before an index are read first, one after another
+      # rather than one within another, since a collection of many pages would otherwise nest as deep as it is long.
+      #
+      # @api private
+      # @param index [Integer] the zero-based page index
+      # @return [Page, nil] the page or nil if the collection has fewer pages
+      def cached(index)
+        @monitor.synchronize do
+          page = nil #: Page?
+          (0..index).each do |current|
+            page = @pages[current] ||= fetch(current)
+            break if page.nil?
+          end
+          page
+        end
+      end
+
+      # Fetch a page from the API, unless a background thread failed to fetch it
+      #
+      # The error the thread failed with is raised in place of a request, once, so a page whose request failed is not
+      # requested again as soon as it is asked for, and one asked for after that error is requested again. A page
+      # fetched here, or whose error is raised here, is let go by a background thread that claimed it and has yet to
+      # fetch it, so that thread does not request it again, nor keep an error of its own for it.
+      #
+      # @api private
+      # @param index [Integer] the zero-based page index
+      # @param wanted [Integer, nil] the number of resources wanted from the page, or nil for the page size
+      # @return [Page, nil] the page or nil if the previous page was the last
+      # @raise [StandardError] the error a background thread failed to fetch the page with
+      # @raise [UnreadableResponse] if the previous page names the token of a page before it as the next
+      # @raise [InvalidAttribute] if the response holds a meta that is not an object
+      def fetch(index, wanted = nil)
+        @prefetching.delete(index)
+        @failures.delete(index)&.then { |failure| raise failure }
+
+        params = params_for(index)
+        return if params.nil?
+
+        params = sized(params, wanted) unless wanted.nil?
+        body = requester.get(Utils.path(@cursor.__send__(:path), params), **Utils::JSON_CLASSES)
+        Page.new(resources_from(body), meta: Page.__send__(:meta_of, body), problems: Problem.all_from(body))
+      end
+
+      # The client that fetches the pages, as the app for a space endpoint
+      # @api private
+      # @return [Object] the client
+      def requester = @cursor.__send__(:app_only?) ? Utils.app_client(@cursor.client) : @cursor.client
+
+      # Build the resources of a page, as stubs for a cursor of identifiers
+      # @api private
+      # @param body [Hash, nil] the response body
+      # @return [Array<Resource>] the resources
+      def resources_from(body)
+        klass = @cursor.resource_class
+        params = @cursor.__send__(:params)
+        resources = klass.__send__(:collection_built_from, body, client: @cursor.client, hydrated: klass.__send__(:fully_requested_by?, params), query: params)
+        id_only? ? stubs_from(resources) : resources
+      end
+
+      # The stubs of a page, which hydrate together, a lookup's worth at a time
+      #
+      # Hydrating one stub looks up the stubs of its batch in one request, rather than every stub of a page of up
+      # to a thousand, since the API bills each resource a lookup returns. A resource without a batch lookup, such
+      # as a list, whose class BatchFinders does not extend, hydrates each stub on its own.
+      #
+      # @api private
+      # @param resources [Array<Resource>] the resources of the page
+      # @return [Array<Resource>] the stubs
+      def stubs_from(resources)
+        klass = @cursor.resource_class
+        client = @cursor.client
+        resources.each_slice(BatchFinders::MAX_BATCH_SIZE).flat_map do |slice|
+          batch = (Batch.new(klass, slice, client:) if klass.is_a?(BatchFinders))
+          slice.map { |resource| klass.__send__(:from_id_in_batch, resource, client:, batch:) }
+        end
+      end
+
+      # Check whether the cursor requests nothing but identifiers
+      # @api private
+      # @return [Boolean] true if the fields parameter selects only the identifier, or the endpoint gives nothing else
+      def id_only? = @cursor.__send__(:ids_only?) || @cursor.__send__(:params)[@cursor.resource_class.__send__(:fields_key)].eql?(@cursor.resource_class.__send__(:id_key))
+
+      # Build the query parameters for a page, including the previous page token
+      #
+      # The page before this one is already fetched, since the pages are read in order.
+      #
+      # @api private
+      # @param index [Integer] the zero-based page index
+      # @return [Hash{String => Object}, nil] the parameters or nil if the previous page was the last
+      # @raise [UnreadableResponse] if the previous page names the token of a page before it as the next
+      def params_for(index)
+        return @cursor.__send__(:params) if index.zero?
+
+        token = next_token(index - 1) or return
+        @cursor.__send__(:params).merge(@cursor.__send__(:token_param) => token)
+      end
+
+      # The token of the page after a page, which fetched no page before it
+      #
+      # A page that names the token of a page before it as the next would have the pages fetched again for good, and
+      # the API bill each of them, so it raises instead. The token the cursor was given, which fetched its first page,
+      # is the token of a page before each of them too.
+      #
+      # @api private
+      # @param index [Integer] the zero-based index of the page, which is fetched
+      # @return [String, nil] the token, or nil if the page is the last
+      # @raise [UnreadableResponse] if the page names the token of a page before it as the next
+      def next_token(index)
+        pages = fetched
+        token = pages.fetch(index).next_token
+        raise UnreadableResponse, format(REPEATED_TOKEN, index:, path: @cursor.__send__(:path), token:) if earlier_tokens(pages, index).include?(token)
+
+        token
+      end
+
+      # The tokens that fetched the pages up to a page
+      #
+      # They are the token the cursor was given, if any, then the next token of each page before it.
+      #
+      # @api private
+      # @param pages [Array<Page>] the pages fetched
+      # @param index [Integer] the zero-based index of the page
+      # @return [Array<String>] the tokens
+      def earlier_tokens(pages, index)
+        [@cursor.__send__(:params)[@cursor.__send__(:token_param)], *pages.take(index).map(&:next_token)].compact
+      end
+
+      # The query parameters of a page, asking for no more than the resources wanted
+      #
+      # A cursor over an endpoint without a page size asks for the page as it is. The page size is raised to the
+      # smallest the endpoint accepts, but never past the max_results the cursor was given, so a max_results below
+      # that smallest page is sent as it was given, for the API to refuse, as an iteration sends it.
+      #
+      # @api private
+      # @param params [Hash{String => Object}] the query parameters of the page
+      # @param wanted [Integer] the number of resources wanted
+      # @return [Hash{String => Object}] the parameters, with the page size wanted, within the endpoint's limits
+      def sized(params, wanted)
+        maximum = params["max_results"]
+        return params if maximum.nil?
+
+        params.merge("max_results" => [wanted, @cursor.__send__(:min_results)].max.clamp(..Integer(maximum)))
+      end
+
+      # Fetch a page in a background thread; errors resurface when the page is requested
+      #
+      # A page already fetched, or being fetched by another thread, starts no thread, so reading the pages a cursor
+      # holds, or reading one page again, starts none. An error the thread fails with is kept, holding the lock of the
+      # pages, so no caller requests the page between the failure and its keeping, and raised to the caller that asks
+      # for the page, in place of a request for it; until then, a thread started for the page keeps it again rather
+      # than request the page. A thread whose page a caller fetched before the thread took the lock requests nothing.
+      # The pages before the page are fetched by the time it is claimed, so the thread reaches fetch for it, which
+      # lets the page go, unless a caller let it go first.
+      #
+      # @api private
+      # @param index [Integer] the zero-based page index
+      # @return [Thread, nil] the background thread, or nil if the page needs none
+      def prefetch(index)
+        return unless claim(index)
+
+        Thread.new do
+          @monitor.synchronize do
+            cached(index) if @prefetching.include?(index)
+          rescue => e
+            @failures[index] = e
+          end
+        end
+      end
+
+      # Claim a page for a background thread to fetch
+      # @api private
+      # @param index [Integer] the zero-based page index
+      # @return [Boolean] true if the page was claimed, which no other thread fetches until the thread that claimed it
+      #   is done
+      def claim(index)
+        @monitor.synchronize { !@pages.at(index) && !@prefetching.add?(index).nil? }
+      end
+    end
+    private_constant :Pages
+  end
+end

data/lib/x/resources/parallel.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module X
+  module Resources
+    # Runs blocks across a bounded pool of threads
+    # @api private
+    module Parallel
+      extend self
+
+      # Map over items concurrently while preserving order
+      #
+      # Every item is given its place in the results before any thread starts, so that a worker never resizes the
+      # array it writes into, which keeps the writes of the workers safe on a Ruby that runs them in parallel.
+      #
+      # A block that raises stops the items not yet begun, since each is a request the API bills, and once the
+      # items already begun have finished, the first error raised is raised again. An interruption of the wait,
+      # such as a timeout, a shutdown, or a signal, stops them the same way, rather than leave the threads to
+      # spend what the caller is no longer waiting for.
+      #
+      # @api private
+      # @param items [Enumerable] the items to map
+      # @param concurrency [Integer] the maximum number of concurrent threads, which callers check is at least one
+      # @yield [Object] each item
+      # @return [Array] the results in the same order as the items
+      # @raise [StandardError] the first error raised by any block
+      def map(items, concurrency:, &block)
+        items = items.to_a
+        results = Array.new(items.size) #: Array[untyped]
+        queue = Queue.new
+        items.each_index { |index| queue << index }
+        queue.close
+        errors = Queue.new
+        drain(queue, [concurrency, items.size].min) { worker(queue, errors, items, results, &block) }
+        raise errors.deq unless errors.empty?
+
+        results
+      end
+
+      private
+
+      # Start the workers and wait for them, emptying the queue however the wait ends
+      #
+      # The workers are started inside it, so that an exception raised in the caller as one is started, such as an
+      # interrupt, empties the queue too, rather than leave the workers started to work through it once the caller
+      # has gone.
+      #
+      # @api private
+      # @param queue [Queue] the queue of item indexes
+      # @param count [Integer] the number of workers to start
+      # @yieldreturn [Thread] a worker it started
+      # @return [void]
+      def drain(queue, count)
+        threads = [] #: Array[Thread]
+        count.times { threads << yield }
+        threads.each(&:join)
+      ensure
+        queue.clear
+      end
+
+      # Start a worker thread that drains the queue, emptying it if the block raises
+      #
+      # @api private
+      # @param queue [Queue] the queue of item indexes
+      # @param errors [Queue] the errors the block raised, in the order it raised them
+      # @param items [Array] the items to map
+      # @param results [Array] the results to fill
+      # @yield [Object] each item
+      # @return [Thread] the worker thread
+      def worker(queue, errors, items, results, &block)
+        Thread.new do
+          while (index = queue.deq)
+            results[index] = block.call(items.fetch(index))
+          end
+        rescue => e
+          errors << e
+          queue.clear
+        end
+      end
+    end
+    private_constant :Parallel
+  end
+end

data/lib/x/resources/personalized_trend.rb

@@ -0,0 +1,124 @@
+# 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 topic trending for the authenticated user, as the trends X picks for them report it
+    #
+    # A personalized trend has no identifier, and the API offers no lookup of one, so the trends are read all at once,
+    # for the user the client authenticates as. They are described as they are shown: the number of posts, and how long
+    # the topic has trended, are text such as "12.3K posts", rather than numbers.
+    #
+    # @api public
+    class ::X::PersonalizedTrend
+      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 endpoint that reports the trends of the authenticated user
+      # @api private
+      ENDPOINT = "users/personalized_trends"
+      private_constant :ENDPOINT
+      # Every personalized trend field
+      #
+      # A minor release may add to it the fields the API adds, so that the trends ask for them too.
+      FIELDS = %w[category post_count trend_name trending_since].freeze
+
+      # The raw attributes of the trend
+      # @api public
+      # @return [Hash{String => Object}] the attributes
+      # @example Get the raw attributes
+      #   trend.attrs # => {"trend_name" => "#ruby", "category" => "Technology", ...}
+      attr_reader :attrs
+
+      # The topics trending for the authenticated user
+      #
+      # The endpoint names no user, so these are always the trends of the user the client authenticates as, and it
+      # takes a user's authentication alone, so a client that authenticates as the app is refused.
+      #
+      # @api public
+      # @param client [Object] the client used to make the request
+      # @param params [Hash] query parameters merged over the default parameters
+      # @return [Array<PersonalizedTrend>] the trends, frozen
+      # @raise [InvalidAttribute] if the response holds the trends as something other than a list of objects
+      # @example Print the topics trending for the authenticated user
+      #   X::PersonalizedTrend.all(client: client).each { |trend| puts "#{trend.name}: #{trend.post_count_text}" }
+      def self.all(client:, **params)
+        body = client.get(Utils.path(ENDPOINT, {"personalized_trend.fields" => FIELDS}.merge(params)), **Utils::JSON_CLASSES)
+        Shape.objects("#{self}.all", body.to_h["data"]).map { |attrs| new(attrs) }.freeze
+      end
+
+      # Initialize a trend from the attributes the API reported
+      #
+      # @api public
+      # @param attrs [Hash{String, Symbol => Object}] the attributes
+      # @return [PersonalizedTrend] a new trend
+      # @raise [ArgumentError] if the attributes are not a Hash
+      # @example Build a trend
+      #   X::PersonalizedTrend.new({"trend_name" => "#ruby", "post_count" => "12.3K posts"})
+      def initialize(attrs)
+        @attrs = Utils.deep_freeze(Utils.attributes!(attrs))
+        freeze
+      end
+
+      # The name of the trend, such as a hashtag or a phrase
+      #
+      # @api public
+      # @return [String, nil] the name
+      # @example Get the name
+      #   trend.name # => "#ruby"
+      def name = attrs["trend_name"]
+
+      # The category of the trend
+      #
+      # @api public
+      # @return [String, nil] the category
+      # @example Get the category
+      #   trend.category # => "Technology"
+      def category = attrs["category"]
+
+      # The number of posts about the trend, as the text X shows it
+      #
+      # It is named for the text it is, apart from the post_count of X::Trend, which is an Integer, so that code that
+      # reads both trends never takes one for the other.
+      #
+      # @api public
+      # @return [String, nil] the number of posts, as text
+      # @example Get the number of posts
+      #   trend.post_count_text # => "12.3K posts"
+      def post_count_text = attrs["post_count"]
+
+      # How long the topic has trended, as the text X shows it
+      #
+      # It is named for the text it is, as post_count_text is, so that it is not taken for a Time, which every other
+      # reader of when something happened answers.
+      #
+      # @api public
+      # @return [String, nil] how long the topic has trended, as text
+      # @example Get how long the topic has trended
+      #   trend.trending_since_text # => "Trending now"
+      def trending_since_text = attrs["trending_since"]
+
+      # Deconstruct the trend into what its readers read, so it matches a hash pattern
+      #
+      # @api public
+      # @param keys [Array<Symbol>, nil] the keys the pattern asks for, or nil for every reader
+      # @return [Hash{Symbol => String, nil}] what the readers read
+      # @example Keep the topics of the technology category
+      #   X::PersonalizedTrend.all(client: client).select { |trend| trend in {category: "Technology"} }
+      def deconstruct_keys(keys) = Utils.deconstruct(self, keys, %i[name category post_count_text trending_since_text])
+    end
+  end
+end

data/lib/x/resources/place.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module X
+  # A place tagged in a post
+  #
+  # The API offers no lookup of places, so a place is read from the response of the post that expanded it, and the class
+  # answers no finder. from_id builds one from its identifier, which a place the response did not expand is built as
+  # too, and which compares equal to the place it identifies, but hydrate and refresh raise UnsupportedOperation for one
+  # that is not hydrated, since there is nothing to look it up with.
+  #
+  # @api public
+  class Place < Resource
+    # Every public place 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[contained_within country country_code full_name geo id name place_type].freeze
+
+    # The type of the identifier, which is not a number
+    #
+    # @api private
+    # @return [Symbol] raw
+    # @example Get the identifier type
+    #   X::Place.__send__(:id_type) # => :raw
+    def self.id_type = :raw
+
+    # The default query parameters, which request every field
+    #
+    # The API offers no lookup of places, so they are requested by the posts that expand them, which ask for these
+    # fields, and a place a response included with all of them is hydrated.
+    #
+    # @api public
+    # @return [Hash{String => Array<String>}] the default query parameters
+    # @example Get the default parameters
+    #   X::Place.default_params # => {"place.fields" => [...]}
+    def self.default_params = {"place.fields" => FIELDS}
+
+    # The key under which places appear in the includes of a response
+    #
+    # @api private
+    # @return [String] the includes key
+    # @example Get the includes key
+    #   X::Place.__send__(:includes_key) # => "places"
+    def self.includes_key
+      "places"
+    end
+    private_class_method :id_type, :includes_key
+
+    # @!attribute [r] name
+    #   The short name
+    #   @api public
+    #   @return [String, nil] the short name
+    #   @example Get the name
+    #     place.name
+    attribute :name
+
+    # @!attribute [r] full_name
+    #   The full name
+    #   @api public
+    #   @return [String, nil] the full name
+    #   @example Get the full name
+    #     place.full_name
+    attribute :full_name
+
+    # @!attribute [r] country
+    #   The country name
+    #   @api public
+    #   @return [String, nil] the country name
+    #   @example Get the country
+    #     place.country
+    attribute :country
+
+    # @!attribute [r] country_code
+    #   The ISO 3166-1 alpha-2 country code
+    #   @api public
+    #   @return [String, nil] the country code
+    #   @example Get the country code
+    #     place.country_code
+    attribute :country_code
+
+    # @!attribute [r] place_type
+    #   The place type, such as city or poi
+    #   @api public
+    #   @return [String, nil] the place type
+    #   @example Get the place type
+    #     place.place_type
+    attribute :place_type
+
+    # @!attribute [r] contained_within
+    #   The identifiers of the places containing this place
+    #   @api public
+    #   @return [Array<String>] the containing place identifiers, empty if there are none
+    #   @example Get the containing places
+    #     place.contained_within
+    attribute :contained_within, :list
+
+    # @!attribute [r] geo
+    #   The GeoJSON bounding box
+    #   @api public
+    #   @return [Hash, nil] the GeoJSON
+    #   @example Get the GeoJSON
+    #     place.geo
+    attribute :geo, :object
+  end
+end

data/lib/x/resources/poll.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module X
+  # A poll attached to a post
+  #
+  # The API offers no lookup of polls, so a poll is read from the response of the post that expanded it, and the class
+  # answers no finder. from_id builds one from its identifier, which a poll the response did not expand is built as too,
+  # and which compares equal to the poll it identifies, but hydrate and refresh raise UnsupportedOperation for one that
+  # is not hydrated, since there is nothing to look it up with.
+  #
+  # @api public
+  class Poll < Resource
+    # Every public poll 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[duration_minutes end_datetime id options voting_status].freeze
+
+    # The default query parameters, which request every field
+    #
+    # The API offers no lookup of polls, so they are requested by the posts that expand them, which ask for these
+    # fields, and a poll a response included with all of them is hydrated.
+    #
+    # @api public
+    # @return [Hash{String => Array<String>}] the default query parameters
+    # @example Get the default parameters
+    #   X::Poll.default_params # => {"poll.fields" => [...]}
+    def self.default_params = {"poll.fields" => FIELDS}
+
+    # The key under which polls appear in the includes of a response
+    #
+    # @api private
+    # @return [String] the includes key
+    # @example Get the includes key
+    #   X::Poll.__send__(:includes_key) # => "polls"
+    def self.includes_key
+      "polls"
+    end
+    private_class_method :includes_key
+
+    # @!attribute [r] options
+    #   The poll options with their positions, labels, and vote counts
+    #   @api public
+    #   @return [Array<Hash>] the options, empty if there are none
+    #   @example Get the options
+    #     poll.options
+    attribute :options, :objects
+
+    # @!attribute [r] duration_minutes
+    #   The duration of the poll in minutes
+    #   @api public
+    #   @return [Integer, nil] the duration in minutes
+    #   @example Get the duration
+    #     poll.duration_minutes
+    attribute :duration_minutes, :integer
+
+    # @!attribute [r] end_datetime
+    #   The time when the poll ends
+    #   @api public
+    #   @return [Time, nil] the end time
+    #   @example Get the end time
+    #     poll.end_datetime
+    attribute :end_datetime, :time
+
+    # @!attribute [r] voting_status
+    #   The voting status: open or closed
+    #   @api public
+    #   @return [String, nil] the voting status
+    #   @example Get the voting status
+    #     poll.voting_status
+    attribute :voting_status
+  end
+end