shep 0.1.0.pre.alpha0

data/lib/shep/session.rb

@@ -0,0 +1,970 @@
+
+#
+# The session class.  This implements all of the API calls.
+#
+
+
+
+
+module Shep
+  using Assert
+
+  # Represents a connection to a Mastodon (or equivalent) server.
+  #
+  # @attr_reader [Logger] logger    The logger object
+  # @attr_reader [String] host      The Server's hostname
+  #
+  # ## Conventions
+  #
+  # `fetch_*` methods retrieve a single Mastodon object, an `Entity`
+  # subinstance.
+  #
+  # `each_*` methods retrieve multiple objects, also `Entity`
+  # subinstances.  If called with a block, the block is evaluated on
+  # each item in turn and the block's result is ignored.  Otherwise,
+  # it returns an `Enumerator` which can be used in the usual ways.
+  #
+  # `each_*` will automatically paginate through the available items;
+  # for example,
+  #
+  #         statuses = session.each_public_status.to_a
+  #
+  # will retrieve the server's entire public timeline and put it in an
+  # array. (Note: don't do this.)  The `limit:` keyword option will
+  # set an upper limit on the number of items retrieved (but note that
+  # the method may retrieve more from the API endpoint).
+  #
+  # The remaining Mastodon API methods will in some way modify the
+  # state of the server and return an Entity subinstance on success.
+  #
+  # All API calls throw an exception on failure.
+  class Session
+    attr_reader :logger, :host
+
+    # Initialize a new {Session}.
+    #
+    # @param host       [String]    Hostname of the server
+    # @param token      [String]    Bearer token; optional
+    # @param logger     [Logger]    The logger or mode; optional
+    # @param debug_http [Boolean]   Enable `Net::HTTP` debugging; insecure!
+    #
+    # Parameter `logger` may be a `Logger` object, `nil`, or a
+    # `Symbol` whose value is the name of one of the supported log
+    # levels.  In the latter case, a new Logger is created and set to
+    # that level.  If `nil` is given, a dummy `Logger` is created and
+    # used.
+    #
+    # If `debug_http` is true, compression is disabled and the
+    # transactions are sent to `STDERR` via
+    # `Net::HTTP.set_debug_output`.  **WARNING:** this opens a serious
+    # security hole and should not be used in production.
+    def initialize(host:,
+                   token: nil,
+                   logger: nil,
+                   debug_http: false)
+      @host = host
+      @token = token
+      @logger = init_logger(logger)
+      @rate_limit = Struct.new(:limit, :remaining, :reset).new
+      @debug_http = debug_http
+    end
+
+    private
+
+    def init_logger(logger_arg)
+      result = nil
+      if %i{debug error fatal info warn}.include? logger_arg
+        result = Logger.new(STDOUT)
+        result.send((logger_arg.to_s + '!').intern)
+      elsif logger_arg.is_a? Logger
+        result = logger_arg
+      else
+        result = Logger.new(nil)
+      end
+
+      return result
+    end
+
+
+    public
+
+    # Return the rate limit information as of the last operation.
+    #
+    # The result is a Struct with the following fields:
+    #
+    # * limit       Integer - Number of allowed requests per time period
+    # * remaining   Integer - Number of requests you have left
+    # * reset       Time -    Future time when the limit resets
+    #
+    # Note that different types of operations have different rate
+    # limits.  For example, most endpoints can be called up to 300
+    # times within 5 minutes but no more than 30 media uploads are
+    # allowed within a 30 minute time period.
+    #
+    # @see https://docs.joinmastodon.org/api/rate-limits/
+    #
+    # @return [Struct.new(:limit, :remaining, :reset)]
+    def rate_limit = @rate_limit.dup.freeze
+
+
+    # Return a human-readable summary of the rate limit.
+    #
+    # @return [String] `rate_limit()`'s result as nicely-formatted
+    # text
+    def rate_limit_desc
+      rem = (@rate_limit.remaining || '?').to_s
+      lim = (@rate_limit.limit || '?').to_s
+      reset = @rate_limit.reset ? (@rate_limit.reset - Time.now).round : '?'
+
+      return "#{rem}/#{lim}, #{reset}s"
+    end
+
+
+    #
+    # Account
+    #
+
+    # Return the Entity::Account object for the token we're using.
+    #
+    # Requires a token (obviously).
+    #
+    # @return [Entity::Account]
+    #
+    # @see https://docs.joinmastodon.org/methods/accounts/#verify_credentials
+    def verify_credentials
+      return rest_get('accounts/verify_credentials', Entity::Account, {})
+    end
+
+    # Fetch user details by ID
+    #
+    # @param id [String] the ID code of the account
+    #
+    # @return [Entity::Account]
+    #
+    # @see https://docs.joinmastodon.org/methods/accounts/#get
+    def fetch_account(id)
+      return rest_get("accounts/#{id}", Entity::Account, {})
+    end
+
+    # Fetch user details by username.
+    #
+    # The username must belong to a user on the current server.
+    #
+    # @param handle [String] the account's username **with** the
+    #                        leading '@' character (e.g. @benoitmandelbot)
+    #
+    # @return [Entity::Account]
+    #
+    # @see https://docs.joinmastodon.org/methods/accounts/#get
+    def fetch_account_by_username(handle)
+      return rest_get("accounts/lookup", Entity::Account, {acct: handle})
+    end
+
+    # Fetch an individual notification by ID.
+    #
+    # Requires a token with sufficient permissions.
+    #
+    # @param ntfn_id [String] the notification ID
+    #
+    # @return [Entity::Notification]
+    #
+    # @see https://docs.joinmastodon.org/methods/notifications/#get-one
+    def fetch_notification(ntfn_id) =
+      rest_get("notifications/#{ntfn_id}", Entity::Notification, {})
+
+    # Fetch a single status
+    #
+    # @return [Entity::Status]
+    #
+    # @see https://docs.joinmastodon.org/methods/statuses/#get
+    def fetch_status(id) = rest_get("statuses/#{id}", Entity::Status, {})
+
+    # Fetch the context (parent and child status) of status at 'id'
+    #
+    # @return [Entity::Context]
+    #
+    # @see https://docs.joinmastodon.org/methods/statuses/#context
+    def fetch_context(id) = rest_get("statuses/#{id}/context", Entity::Context, {})
+
+    # Fetch the editable source of status at id.
+    #
+    # Requires token.
+    #
+    # @return [Entity::StatusSource]
+    #
+    # @see https://docs.joinmastodon.org/methods/statuses/#source
+    def fetch_status_src(id) = rest_get("statuses/#{id}/source",
+                                        Entity::StatusSource, {})
+
+    # Fetch the given status and also any attached media.
+    #
+    # @param id         [String]    ID of the status to retrieve
+    #
+    # @param media_dir  [String]    Path to the download directory
+    #
+    # @param refetch    [Boolean]   Fetch the media even if it is already
+    #                               present
+    #
+    # Media is downloaded into the given directory unless a file with
+    # the expected name is already there (and `refetch` is not
+    # `true`).
+    #
+    # Filenames are chosen by the function; the second return value (a
+    # `Hash`) can be used to find them.  Value order also corresponds
+    # to the order of the returned `Status`'s `media_attachments`
+    # field.
+    #
+    # Note that intermediate files unique temporary names while
+    # downloading is in progress.  This means it is safe to set
+    # `refetch` to false even if a previous download attempt failed.
+    # However, it is would be necessary to delete the intermediate
+    # file, which has the suffic ".tmp".
+    #
+    # @return [Entity::Status, Hash] the Status and a Hash mapping the media
+    #                        URL to the corresponding local file.
+    #
+    # @see https://docs.joinmastodon.org/methods/statuses/#get
+    def fetch_status_with_media(id, media_dir = '.', refetch: true)
+      status = fetch_status(id)
+      media = {}
+
+      status.media_attachments.each { |ma|
+        outfile = File.join(media_dir, File.basename(ma.url.path))
+
+        if !refetch && File.exist?(outfile)
+          @logger.info "Found '#{outfile}'; skipping."
+          success = true
+        else
+          tmp = File.join(media_dir, SecureRandom.uuid + '.tmp')
+          success = basic_get_binary(ma.url, tmp)
+          if success
+            FileUtils.mv(tmp, outfile)
+          else
+            FileUtils.rm(tmp, force: true)
+          end
+        end
+
+        media[ma.url.to_s] = success ? outfile : nil
+      }
+
+      return [status, media]
+    end
+
+
+    # Retrieve the follower list of an account.
+    #
+    # As of Mastodon 4.0, no longer requires a token.
+    #
+    # @param account_id [String]    The account
+    # @param limit      [Integer]   Maximum number of items to retrieve
+    #
+    # @yield [item]                 Optional; applied to each item
+    # @yieldparam [Entity::Account]
+    #
+    # @return [Enumerator] if block is not given, otherwise self
+    #
+    #
+    # @see https://docs.joinmastodon.org/methods/accounts/#followers
+    def each_follower(account_id,
+                      limit: nil,
+                      &block)
+      query = magically_get_caller_kwargs(binding, method(__method__))
+      return rest_get_seq("accounts/#{account_id}/followers", Entity::Account,
+                          query, block)
+    end
+
+    # Retrieve the list of accounts this account follows
+    #
+    # @param account_id [String]    The account
+    # @param limit      [Integer]   Maximum number of items to retrieve
+    #
+    # @yield [item]                 Optional; applied to each item
+    # @yieldparam [Entity::Account]
+    #
+    # @return [Enumerator] if block is not given, otherwise self
+    #
+    #
+    # @see https://docs.joinmastodon.org/methods/accounts/#following
+    def each_following(account_id,
+                       limit: nil,
+                       &block)
+      query = magically_get_caller_kwargs(binding, method(__method__))
+      return rest_get_seq("accounts/#{account_id}/following", Entity::Account,
+                          query, block)
+    end
+
+    # Retrieve the account's statuses
+    #
+    # @param account_id         [String]    The ID of the account
+    #
+    # @param limit              [Integer]   Maximum number of accounts to
+    #                                       retrieve
+    #
+    # @param only_media         [Boolean]   If true, filter for statuses
+    #                                       with media
+    #
+    # @param exclude_replies    [Boolean]   If true, exclude replies
+    #
+    # @param exclude_reblogs    [Boolean]   If true, exclude boosts
+    #
+    # @param pinned             [Boolean]   If true, filter for pinned
+    #                                       statuses
+    #
+    # @param tagged             [String]    Filter for statuses containing the
+    #                                       given tag
+    #
+    # @yield [item]                         Optional; applied to each item
+    # @yieldparam [Entity::Status]
+    #
+    # @return [Enumerator] if block is not given, otherwise self
+    #
+    # @see https://docs.joinmastodon.org/methods/accounts/#statuses
+    def each_status(account_id,
+                    limit:              nil,
+                    only_media:         false,
+                    exclude_replies:    false,
+                    exclude_reblogs:    false,
+                    pinned:             false,
+                    tagged:             nil,
+                    &block)
+      query = magically_get_caller_kwargs(binding, method(__method__))
+      rest_get_seq("accounts/#{account_id}/statuses", Entity::Status, query, block)
+    end
+
+    # Retrieve the instance's public timeline(s)
+    #
+    # May require a token depending on the instance's settings.
+    #
+    # @param limit      [Integer]   Max. items to retrieve.
+    #
+    # @param local      [Boolean]   Retrieve only local statuses
+    #
+    # @param remote     [Boolean]   Retrieve only remote statuses
+    #
+    # @param only_media [Boolean]   Retrieve only statuses with media
+    #
+    #
+    # @yield [item]                 Optional; applied to each item
+    # @yieldparam [Entity::Status]
+    #
+    # @return [Enumerator] if block is not given, otherwise self
+    #
+    # @see https://docs.joinmastodon.org/methods/timelines/#public
+    def each_public_status(limit:              nil,
+                           local:              false,
+                           remote:             false,
+                           only_media:         false,
+                           &block)
+      query = magically_get_caller_kwargs(binding, method(__method__))
+      rest_get_seq("timelines/public", Entity::Status, query, block)
+    end
+
+    # Retrieve a tag's timeline.
+    #
+    # The tag may either be a String (containing one hashtag) or an
+    # Array containing one or more.  If more than one hashtag is
+    # given, all statuses containing **any** of the given hashtags are
+    # retrieved.  (This uses the `any[]` parameter in the API.)
+    #
+    # There is currently no check for contradictory tag lists.
+    #
+    # @param hashtag_s  [String, Array<String>]
+    #                             Hashtag(s) to retrieve.
+    #
+    # @param limit      [Integer] maximum number of items to retrieve
+    #
+    # @param local      [Boolean] retrieve only local statuses
+    #
+    # @param remote     [Boolean] retrieve only remote statuses
+    #
+    # @param only_media [Boolean] retrieve only media status
+    #
+    # @param all        [Array<String>] list of other tags that
+    #                                   must also be present.
+    #
+    # @param none       [Array<String>] list of tags that are excluded.
+    #
+    # @yield [item]               block to apply to each Status; optional
+    # @yieldparam [Entity::Status]
+    #
+    # @return [Enumerator] if block is not given, otherwise self
+    #
+    # @see https://docs.joinmastodon.org/methods/timelines/#tag
+    def each_tag_status(hashtag_s,
+                        limit:              nil,
+                        local:              false,
+                        remote:             false,
+                        only_media:         false,
+                        all:                [],
+                        none:               [],
+                        &block)
+
+      query = magically_get_caller_kwargs(binding, method(__method__))
+
+      any = []
+      if hashtag_s.is_a?(Array)
+        hashtag_s = hashtag_s.dup
+        hashtag = hashtag_s.shift
+        any = hashtag_s
+      else
+        hashtag = hashtag_s
+      end
+
+      assert("Empty hashtag!") { hashtag && !hashtag.empty? }
+
+      query[:any] = any unless any.empty?
+
+      rest_get_seq("timelines/tag/#{hashtag}", Entity::Status, query, block)
+    end
+
+
+    # Retrieve each Entity::Status in the home timeline.
+    #
+    # Requires token.
+    #
+    # @param limit [Integer] ,
+    # @param local [Boolean] ,
+    # @param remote [Boolean] ,
+    # @param only_media [Boolean] ,
+    #
+    # @yield [item]
+    #
+    # @yieldparam [Entity::Status]
+    #
+    # @return [Enumerator] if block is not given, otherwise self
+    #
+    #
+    # @see https://docs.joinmastodon.org/methods/timelines/#home
+    def each_home_status(limit:              nil,
+                         local:              false,
+                         remote:             false,
+                         only_media:         false,
+                         &block)
+      query = magically_get_caller_kwargs(binding, method(__method__))
+      rest_get_seq("timelines/home", Entity::Status, query, block)
+    end
+
+
+    # Retrieve each Entity::Account that boosted the given status.
+    #
+    # @param limit [Integer] Maximum number of items to retrieve
+    #
+    # @yield [item]
+    #
+    # @yieldparam [Entity::Account]
+    #
+    # @return [Enumerator] if block is not given, otherwise self
+    #
+    #
+    # @see https://docs.joinmastodon.org/methods/statuses/#reblogged_by
+    def each_boost_acct(status_id,
+                        limit: nil,
+                        &block)
+      query = magically_get_caller_kwargs(binding, method(__method__))
+      rest_get_seq("statuses/#{status_id}/reblogged_by",
+                   Entity::Account, query, block)
+    end
+
+    # Retrieve each account that favourited the given status.
+    #
+    # @param limit [Integer] Maximum number of items to retrieve
+    #
+    # @yield [item]
+    #
+    # @yieldparam [Entity::Account]
+    #
+    # @return [Enumerator] if block is not given, otherwise self
+    #
+    #
+    # @see https://docs.joinmastodon.org/methods/statuses/#favourited_by
+    def each_fave_acct(status_id,
+                       limit: nil,
+                       &block)
+      query = magically_get_caller_kwargs(binding, method(__method__))
+      rest_get_seq("statuses/#{status_id}/favourited_by",
+                   Entity::Account, query, block)
+    end
+
+
+    # Retrieve each notification.
+    #
+    # @param types          [Array<String>] list of notifications types to
+    #                                       enumerate; others are ignoredn
+    #
+    # @param exclude_types  [Array<String>] types of notifications to exclude
+    #
+    # @param limit          [Integer]       Maximum number of items to retrieve
+    #
+    # @param account_id     [String]        Only retrieve notifications from
+    #                                       the account with this ID.
+    #
+    # @yield [item]                         Applied to each Notification
+    #
+    # @yieldparam [Entity::Notification]
+    #
+    # @return [Enumerator] if block is not given, otherwise self
+    #
+    # @see https://docs.joinmastodon.org/methods/notifications/#get
+    def each_notification(types:            [],
+                          exclude_types:    [],
+                          limit:            nil,
+                          account_id:       nil,
+                          &block)
+      allowed_notifications = %i{mention status reblog follow follow_request
+                                 favourite poll update admin.sign_up
+                                 admin.report}
+
+      # Ensure valid filter values
+      types.uniq!
+      exclude_types.uniq!
+      (types + exclude_types).each{|filter|
+        assert("Unknown notification type: #{filter}") {
+          allowed_notifications.include?(filter.intern)
+        }
+      }
+
+      query = magically_get_caller_kwargs(binding, method(__method__))
+      rest_get_seq("notifications", Entity::Notification, query, block)
+    end
+
+
+
+
+
+    # Post a status containing the given text at the specified
+    # visibility with zero or more media attachments.
+    #
+    # visibility can be one of 'public', 'private', 'unlisted' or
+    # 'direct'; these can be strings of symbols)
+    #
+    # media_ids is an array containing the ID strings of any media
+    # that may need to be attached.
+    #
+    # @param visibility [Symbol]        Status visibility; one of :public,
+    #                                   :public, :unlisted or :direct
+    #
+    # @param media_ids [Array<String>]  List of IDs of attached media items.
+    #
+    # @param spoiler_text [String]      Content warning if non-empty string.
+    #                                   Also sets `sensitive` to true.
+    #
+    # @param language [String]          ISO language code
+    #
+    # @see https://docs.joinmastodon.org/methods/statuses/#create
+    def post_status(text,
+                    visibility:       :private,
+                    media_ids:        [],
+                    spoiler_text:     "",
+                    language:         "")
+      raise Error::Caller.new("Invalid visibility: #{visibility}") unless
+        %i{public unlisted private direct}.include? visibility.intern
+
+      query = magically_get_caller_kwargs(binding, method(__method__))
+      query[:status] = text
+      query[:sensitive] = true if
+        spoiler_text && !spoiler_text.empty?
+
+      # We need to convert to an array of keys and values rather than
+      # a hash because passing an array argument requires duplicate
+      # keys.  This causes Net::HTTP to submit it as a multipart form,
+      # but we can cope.
+      formdata = formhash2array(query)
+
+      return rest_post("statuses", Entity::Status, formdata)
+    end
+
+    # Update the status with the given Id.
+    #
+    # Requires token with sufficient permission for the account that
+    # owns the status.
+    #
+    # Notionally, this method will change *all* of the affected status
+    # parts each time it's invoked, passing the default parameter if
+    # none is given.  This is because it is unclear how the API
+    # handles omitted fields so we just don't do that.  (You can force
+    # it to omit an argument by setting it to nil; this may or may not
+    # work for you.)
+    #
+    # @param id             [String]        id of the status to edit
+    #
+    # @param status         [String]        new status text
+    #
+    # @param media_ids      [Array<String>] array of media object IDs
+    #                                       to attach to this status.
+    #
+    # @param spoiler_text   [String]        Sets or clears the content
+    #                                       warning. Non-empty value also
+    #                                       sets the `sensitive` field.
+    #
+    # @param language       [String]        The language of the status;
+    #                                       defaults to "en". (Apologies for
+    #                                       the anglocentrism; this should be
+    #                                       consistent.)
+    #
+    # @return [Entity::Status] the updated status
+    #
+    # @see https://docs.joinmastodon.org/methods/statuses/#edit
+    def edit_status(id, status,
+                    media_ids:          [],
+                    spoiler_text:       "",
+                    language:           "en")
+      formhash = magically_get_caller_kwargs(binding, method(__method__),
+                                             strip_ignorables: false)
+      formhash[:status] = status
+      formhash[:sensitive] = !!spoiler_text && !spoiler_text.empty?
+
+      formdata = formhash2array(formhash)
+      return rest_put("statuses/#{id}", Entity::Status, formdata)
+    end
+
+
+    # Upload the media contained in the file at 'path'.
+    #
+    # @see https://docs.joinmastodon.org/methods/media/#v2
+    def upload_media(path,
+                     content_type: nil,
+                     description: nil,
+                     focus_x: nil,
+                     focus_y: nil)
+      formdata = [
+        ['filename', File.basename(path)],
+        ['file', File.open(path, "rb"), {content_type: content_type}],
+      ]
+
+      formdata.push ['description', description] if description
+
+      # Focus args are more exacting so we do some checks here.
+      !!focus_x == !!focus_y or
+        raise Error::Caller.new("Args 'focus_x/y' must *both* be set or unset.")
+
+      if focus_x
+        raise Error::Caller.new("focus_x/y not a float between -1 and 1") unless
+          (focus_x.is_a?(Float) && focus_y.is_a?(Float) &&
+           focus_x >= -1.0 && focus_x <= 1.0 &&
+           focus_y >= -1.0 && focus_y <= 1.0)
+
+        formdata.push ['focus', "#{focus_x},#{focus_y}"]
+      end
+
+      return rest_post("media", Entity::MediaAttachment, formdata, v2: true)
+    end
+
+    # Delete the status at ID.
+    #
+    # @return [Entity::Status] the deleted status
+    #
+    # @see https://docs.joinmastodon.org/methods/statuses/#delete
+    def delete_status(id) = rest_delete("statuses/#{id}", Entity::Status)
+
+    # Dismiss the notification with the given ID.
+    #
+    # Warning: due to the complexity involved in repeatably sending a
+    # notification to an account, there is limited test coverage for
+    # this method.
+    #
+    # @see https://docs.joinmastodon.org/methods/notifications/#dismiss
+    def dismiss_notification(id)
+      url = rest_uri("notifications/#{id}/dismiss", {})
+      basic_rest_post_or_put(url, {})
+      return nil
+    end
+
+    private
+
+    #
+    # High-level REST support
+    #
+
+    # Extract all of the keyword arguments and their values from the
+    # caller's context.  (The context is 'cbinding', which must be a
+    # call to method 'cmethod'.)
+    #
+    # The results are returned as a hash mapping keyword to value.
+    #
+    # If 'strip_ignorables' is true, all key/value pairs whose value is
+    # deemed to be equivalent to omitting the pair entirely are
+    # removed.  (We mostly do this so that caller's definition can
+    # signal the expected type of the value, but it's sometimes the
+    # wrong thing.)
+    def magically_get_caller_kwargs(cbinding, cmethod, strip_ignorables: true)
+      ignorables = Set.new([0, false, "", nil, []])
+
+      kwargs = {}
+      for type, name in cmethod.parameters
+        if type == :key || type == :keyreq
+
+          arg = cbinding.local_variable_get(name)
+          next if strip_ignorables && ignorables.include?(arg)
+
+          kwargs[name] = arg
+        end
+      end
+
+      return kwargs
+    end
+
+    def rest_get(path, result_klass, query_args)
+      uri = rest_uri(path, query_args)
+      result_obj, _ = basic_rest_get_or_delete(uri)
+      return result_klass.from(result_obj)
+    end
+
+    def rest_delete(path, result_klass)
+      uri = rest_uri(path, {})
+      result_obj, _ = basic_rest_get_or_delete(uri, also_delete: true)
+      return result_klass.from(result_obj)
+    end
+
+    # We do the block+enumerator thing here as a placeholder for
+    # pagination.
+    def rest_get_seq(path, result_klass, query_args, block)
+      return Enumerator.new{ |y|
+        rest_get_seq(path, result_klass, query_args, proc{|item| y << item})
+      } unless block
+
+      uri = rest_uri(path, query_args)
+      limit = query_args[:limit]
+      while true
+        result_obj, link = basic_rest_get_or_delete(uri)
+        assert{result_obj.is_a? Array}
+        link_next = link["next"]
+
+        if limit
+          limit -= result_obj.size
+
+          link_next = nil if limit <= 0 # set break condition if we're done
+
+          # Discard extras
+          while limit < 0
+            result_obj.pop
+            limit += 1
+          end
+        end
+
+        result_obj
+          .map{|obj| result_klass.from(obj)}
+          .each(&block)
+
+        break unless link_next
+        uri = URI(link_next)
+      end
+
+      return self
+    end
+
+    def rest_post(path, result_klass, formdata, v2: false)
+      url = rest_uri(path, {}, v2: v2)
+      result = basic_rest_post_or_put(url, formdata)
+      return result_klass.from(result)
+    end
+
+    def rest_put(path, result_klass, formdata, v2: false)
+      url = rest_uri(path, {}, v2: v2)
+      result = basic_rest_post_or_put(url, formdata, is_put: true)
+      return result_klass.from(result)
+    end
+
+
+    #
+    # Low-level REST support
+    #
+
+    # Given a hash of query arguments, return an array of key-value
+    # pairs.
+    #
+    # This is slightly more complex than using 'to_a' because if the
+    # value is an array, each array element becomes the value of a
+    # key-value pair where the key is the array name with '[]'
+    # appended.
+    #
+    #   E.g. `foo : [1,2]` -> `["foo[]", "1"], ["foo[]", "2"]`
+    #
+    def formhash2array(query_arg_hash)
+      result = query_arg_hash.to_a.reject{|key, value| value.is_a?(Array)}
+
+      query_arg_hash
+        .select{|key, value| value.is_a?(Array)}
+        .each{|key, value| value.each{|v| result.push ["#{key}[]", v.to_s] } }
+
+      # And ensure the keys and values are all strings
+      result.map!{|k,v| [k.to_s, v.to_s]}
+
+      return result
+    end
+
+    def rest_uri(path, query_args, v2: false)
+      args = formhash2array(query_args)
+        .map{|pair| pair.join("=")}
+        .join('&')
+      args = "?#{args}" unless args.empty?
+
+      # Most of the API is v1 but a few calls have the v2 prefix.
+      version = v2 ? "v2" : "v1"
+
+      return URI("https://#{@host}/api/#{version}/#{path}#{args}")
+    end
+
+    def basic_rest_get_or_delete(uri, also_delete: false)
+      headers = headers_for(:get)
+
+      # Do the thing.
+      response = http_get_or_delete(uri, headers, also_delete)
+      update_rate_limit(response)
+
+      result = response.body() if response.class.body_permitted?
+      raise Error::Http.new(response) if response.is_a? Net::HTTPClientError
+
+      result_obj = JSON.parse(result)
+
+      if result.is_a?(Hash) && result_obj.has_key?("error")
+        raise Error::Server.new(result_obj["error"])
+      end
+
+      link = parse_link_header(response["link"])
+
+      return [result_obj, link]
+    rescue JSON::JSONError => e
+      raise Error::Remote.new("Error parsing result JSON: #{e}")
+    end
+
+    def http_get_or_delete(uri, headers, is_delete)
+      @logger.debug("#{is_delete ? "Deleting" : "Requesting"} #{uri} " +
+                    "(token: #{!!@token})")
+
+      response = Net::HTTP.start(
+        uri.hostname,
+        uri.port,
+        use_ssl: uri.scheme == 'https'
+      ) { |http|
+        next is_delete                      ?
+          http.delete(uri.path, headers)    :
+          http.request_get(uri, headers)
+      }
+
+      @logger.debug("Response: #{response}")
+      return response
+    end
+
+    def headers_for(method)
+      headers = {}
+      headers["Authorization"] = "Bearer #{@token}" if @token
+
+      if method == :post
+        extras = {
+          "Indempotency-Key":       SecureRandom.uuid,
+          "Content-Type":           "application/json",
+        }
+        headers.update extras
+      end
+
+      return headers
+    end
+
+    def update_rate_limit(response)
+      @rate_limit.limit = @rate_limit.remaining = @rate_limit.reset = nil
+
+      @rate_limit.limit = response['X-RateLimit-Limit'].to_i
+      @rate_limit.remaining = response['X-RateLimit-Remaining'].to_i
+
+      reset = response['X-RateLimit-Reset']
+      @rate_limit.reset = Time.iso8601(reset) if reset
+
+      @logger.debug "Rate limit: #{rate_limit_desc}"
+    end
+
+    # Retrieve the resource (assumed to be binary) at 'uri' and write
+    # it to 'filename'.  For now, returns false if the request
+    # returned an error code and true on success.
+    def basic_get_binary(uri, filename)
+      headers = headers_for(:get)
+
+      @logger.debug("Requesting #{uri} (token: #{!!@token})")
+      Net::HTTP.get_response(uri, headers) {|response|
+        @logger.debug("Response: #{response.code}")
+
+        update_rate_limit(response)
+
+        if response.is_a? Net::HTTPClientError
+          @logger.warn("Got response #{response} for #{uri}.")
+          return false
+        end
+
+        @logger.debug("Writing body to #{filename}")
+        File.open(filename, "wb") { |outfile|
+          response.read_body { |chunk|
+            @logger.debug("  Writing #{chunk.size} bytes...")
+            outfile.write(chunk)
+          }
+        }
+        @logger.debug("Done (#{filename})")
+      }
+
+      return true
+    end
+
+    def parse_link_header(hdr)
+      result = {}
+      return result unless hdr      # could be nil
+
+      for link in hdr.split(', ')
+        md = link.match(/^<([^>]+)>; rel="([^"]+)"/)
+        assert{md}
+
+        result[ md[2] ] = md[1]
+      end
+
+      return result
+    end
+
+
+    def basic_rest_post_or_put(uri, formdata, is_put: false)
+      headers = headers_for(:post)
+
+      # Do the thing.
+      @logger.debug("Posting #{uri} (token: #{!!@token})")
+      response = http_post_form(uri, headers, formdata, is_put)
+      @logger.debug("Response: #{response}")
+
+      update_rate_limit(response)
+
+      result = response.body() if response.class.body_permitted?
+      raise Error::Http.new(response) if response.is_a? Net::HTTPClientError
+
+      result_obj = JSON.parse(result)
+
+      if result.is_a?(Hash) && result_obj.has_key?("error")
+        raise Error::Server.new(result_obj["error"])
+      end
+
+      return result_obj
+    rescue JSON::JSONError => e
+      raise Error::Remote.new("Error parsing result JSON: #{e}")
+    end
+
+    def http_post_form(url, headers, formdata, is_put)
+      request = is_put                          ?
+        Net::HTTP::Put.new(url, headers)        :
+        Net::HTTP::Post.new(url, headers)
+
+      enctype = 'multipart/form-data' if formdata.is_a?(Array)
+      enctype = 'application/x-www-form-urlencoded' if
+        formdata.is_a?(Hash)
+      enctype or
+        raise Error::Caller.new("Unknown formdate type: #{formdata.class}")
+      request.set_form(formdata, enctype)
+
+
+      http = Net::HTTP.new(url.hostname, url.port)
+      http.use_ssl = (url.scheme == 'https')
+
+      if @debug_http
+        http.set_debug_output(STDERR)
+        request['Accept-Encoding'] = 'identity'
+      end
+
+      return http.start {|http|
+        http.request(request)
+      }
+    end
+  end
+end