spinels-redd 0.9.0

data/lib/redd/client.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'http'
+require 'json'
+
+module Redd
+  # The base class for JSON-based HTTP clients. Generic enough to be used for basically anything.
+  class Client
+    # The default User-Agent to use if none was provided.
+    USER_AGENT = "Ruby:Redd:v#{Redd::VERSION} (by unknown)"
+
+    # Holds a returned HTTP response.
+    Response = Struct.new(:code, :headers, :raw_body) do
+      def body
+        @body ||= JSON.parse(raw_body, symbolize_names: true)
+      end
+    end
+
+    # Create a new client.
+    # @param endpoint [String] the base endpoint to make all requests from
+    # @param user_agent [String] a user agent string
+    def initialize(endpoint:, user_agent: USER_AGENT)
+      @endpoint = endpoint
+      @user_agent = user_agent
+    end
+
+    # Make an HTTP request.
+    # @param verb [:get, :post, :put, :patch, :delete] the HTTP verb to use
+    # @param path [String] the path relative to the endpoint
+    # @param options [Hash] the request parameters
+    # @option options [Hash] :params the parameters to supply with the url
+    # @option options [Hash] :form the parameters to supply in the body
+    # @option options [Hash] :body the direct body contents
+    # @return [Response] the response
+    def request(verb, path, options = {})
+      # puts "#{verb.to_s.upcase} #{path}", '  ' + options.inspect
+      response = connection.request(verb, path, **options)
+      Response.new(response.status.code, response.headers, response.body.to_s)
+    end
+
+    # Make a GET request.
+    # @param path [String] the path relative to the endpoint
+    # @param options [Hash] the parameters to supply
+    # @return [Response] the response
+    def get(path, options = {})
+      request(:get, path, params: options)
+    end
+
+    # Make a POST request.
+    # @param path [String] the path relative to the endpoint
+    # @param options [Hash] the parameters to supply
+    # @return [Response] the response
+    def post(path, options = {})
+      request(:post, path, form: options)
+    end
+
+    # Make a PUT request.
+    # @param path [String] the path relative to the endpoint
+    # @param options [Hash] the parameters to supply
+    # @return [Response] the response
+    def put(path, options = {})
+      request(:put, path, form: options)
+    end
+
+    # Make a PATCH request.
+    # @param path [String] the path relative to the endpoint
+    # @param options [Hash] the parameters to supply
+    # @return [Response] the response
+    def patch(path, options = {})
+      request(:patch, path, form: options)
+    end
+
+    # Make a DELETE request.
+    # @param path [String] the path relative to the endpoint
+    # @param options [Hash] the parameters to supply
+    # @return [Response] the response
+    def delete(path, options = {})
+      request(:delete, path, form: options)
+    end
+
+    private
+
+    # @return [HTTP::Connection] the base connection object
+    def connection
+      # TODO: Make timeouts configurable
+      @connection ||= HTTP.persistent(@endpoint)
+                          .headers('User-Agent' => @user_agent)
+                          .timeout(write: 5, connect: 5, read: 5)
+    end
+  end
+end

data/lib/redd/errors.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Redd
+  # Namespace for Redd errors.
+  module Errors
+    # An error raised by {Redd::Middleware} when there was an error returned by reddit.
+    class TokenRetrievalError < StandardError; end
+
+    # An error with the API.
+    class APIError < StandardError
+      attr_reader :response, :name
+
+      def initialize(response)
+        @response = response
+        super(response.body[:json][:errors][0].join(', '))
+      end
+    end
+
+    # Indicates that you were rate limited. This should be taken care of automatically.
+    class RateLimitError < APIError
+      attr_reader :duration
+
+      def initialize(response)
+        super(response)
+        @duration = response.body[:json][:ratelimit]
+      end
+    end
+
+    # Represents an error from reddit returned in a response.
+    class ResponseError < StandardError
+      attr_accessor :response
+
+      def initialize(response)
+        super(response.raw_body.length <= 80 ? response.raw_body : "#{response.raw_body[0..80]}...")
+        @response = response
+      end
+    end
+
+    # An error returned by AuthStrategy.
+    # @note A common cause of this error is not having a bot account registered as a developer on
+    #   the app.
+    class AuthenticationError < ResponseError; end
+
+    # An error with Redd, probably (let me know!)
+    class BadRequest < ResponseError; end
+
+    # Whatever it is, you're not allowed to do it.
+    class Forbidden < ResponseError; end
+
+    # You don't have the correct scope to do this.
+    class InsufficientScope < ResponseError; end
+
+    # The access object supplied was invalid.
+    class InvalidAccess < ResponseError; end
+
+    # Returned when reddit raises a 404 error.
+    class NotFound < ResponseError; end
+
+    # Too many requests and not enough rate limiting.
+    class TooManyRequests < ResponseError; end
+
+    # An unknown error on reddit's end. Usually fixed with a retry.
+    class ServerError < ResponseError; end
+  end
+end

data/lib/redd/middleware.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'rack'
+require 'securerandom'
+
+require_relative '../redd'
+
+module Redd
+  # Rack middleware.
+  class Middleware
+    # @param opts [Hash] the options to create the object with
+    # @option opts [String] :user_agent your app's *unique* and *descriptive* user agent
+    # @option opts [String] :client_id the client id of your app
+    # @option opts [String] :redirect_uri the provided redirect URI
+    # @option opts [String] :secret ('') the app secret (for the web type)
+    # @option opts [Array<String>] :scope (['identity']) a list of scopes to request
+    # @option opts ['temporary', 'permanent'] :duration ('permanent') the duration to request the
+    #   code for.
+    # @option opts [Boolean] :auto_refresh (true) allow refreshing a permanent access automatically
+    #   (only if duration is 'permanent')
+    # @option opts [String] :via ('/auth/reddit') the relative path in the application that
+    #   redirects a user to reddit
+    def initialize(app, opts = {})
+      @app = app
+      strategy_opts = opts.select { |k| %i[user_agent client_id secret redirect_uri].include?(k) }
+      @strategy = Redd::AuthStrategies::Web.new(strategy_opts)
+
+      @user_agent   = opts.fetch(:user_agent, "Redd:Web Application:v#{Redd::VERSION} (by unknown)")
+      @client_id    = opts.fetch(:client_id)
+      @redirect_uri = opts.fetch(:redirect_uri)
+      @scope        = opts.fetch(:scope, ['identity'])
+      @duration     = opts.fetch(:duration, 'permanent')
+      @auto_refresh = opts.fetch(:auto_refresh, true) && @duration == 'permanent'
+      @via          = opts.fetch(:via, '/auth/reddit')
+    end
+
+    def call(env)
+      # This is done for thread safety so that each thread has its own copy
+      # of the middleware logic.
+      dup._call(env)
+    end
+
+    protected
+
+    def _call(env)
+      @request = Rack::Request.new(env)
+      return redirect_to_reddit! if @request.path == @via
+
+      before_call
+      response = @app.call(env)
+      after_call
+      response
+    end
+
+    private
+
+    # Creates a unique state and redirects the user to reddit for authentication.
+    def redirect_to_reddit!
+      state = SecureRandom.urlsafe_base64
+      url = Redd.url(
+        client_id: @client_id,
+        redirect_uri: @redirect_uri,
+        scope: @scope,
+        duration: @duration,
+        state: state
+      )
+      @request.session[:redd_state] = state
+      [302, { 'Location' => url }, []]
+    end
+
+    # Do any setup before calling the rest of the application.
+    def before_call
+      # Convert the code to an access token if returning from authentication.
+      create_session! if @request.base_url + @request.path == @redirect_uri
+      # Clear the state for any other request.
+      @request.session.delete(:redd_state)
+      # Load a Session model from the access token in the user's cookies.
+      @request.env['redd.session'] = (@request.session[:redd_session] ? parse_session : nil)
+    end
+
+    # Do any cleanup or changes after calling the application.
+    def after_call
+      env_session = @request.env['redd.session']
+      if env_session&.client&.access
+        # Make sure to flush any changes made to the Session client to the browser.
+        @request.session[:redd_session] = env_session.client.access.to_h
+      else
+        # Clear the session if the app explicitly set 'redd.session' to nil.
+        @request.session.delete(:redd_session)
+      end
+    end
+
+    # Assigns a single string representing a reddit authentication errors.
+    def handle_token_error
+      message = nil
+      message = 'invalid_state' if @request.GET['state'] != @request.session[:redd_state]
+      message = @request.GET['error'] if @request.GET['error']
+      raise Errors::TokenRetrievalError, message if message
+    end
+
+    # Store the access token and other details in the user's browser, assigning any errors to
+    # the 'redd.error' env variable.
+    def create_session!
+      # Skip authorizing if there was an error from the authorization.
+      handle_token_error
+      # Try to get a code (the rescue block will also prevent crazy crashes)
+      access = @strategy.authenticate(@request.GET['code'])
+      @request.session[:redd_session] = access.to_h
+    rescue Errors::TokenRetrievalError, Errors::ResponseError => e
+      @request.env['redd.error'] = e
+    end
+
+    # Return a {Redd::Models::Session} based on the hash saved into the browser's session.
+    def parse_session
+      parsed_session = @request.session[:redd_session].transform_keys(&to_sym)
+
+      client = Redd::APIClient.new(@strategy,
+                                   user_agent: @user_agent,
+                                   limit_time: 0,
+                                   auto_refresh: @auto_refresh)
+      client.access = Redd::Models::Access.new(@strategy, parsed_session)
+      Redd::Models::Session.new(client)
+    end
+  end
+end

data/lib/redd/models/access.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative 'model'
+
+module Redd
+  module Models
+    # Models access_token and related keys.
+    # @note This model also supports an additional key, called `:created_at` which is a UNIX time
+    #   representing the time the access was created. The default value is the time the object was
+    #   initialized.
+    class Access < Model
+      # Create a non-lazily initialized Access.
+      # @param attributes [Hash] the access's attributes
+      # @example
+      #   access = Redd::Models::Access.new(access_token: ...)
+      def initialize(attributes = {})
+        super(nil, attributes)
+        @creation_time = Time.now
+      end
+
+      # Whether the access has expired.
+      # @param grace_period [Integer] the grace period where the model expires early
+      # @return [Boolean] whether the access has expired
+      def expired?(grace_period = 60)
+        Time.now > read_attribute(:created_at) + read_attribute(:expires_in) - grace_period
+      end
+
+      # @return [Boolean] whether the access can be refreshed
+      def permanent?
+        read_attribute(:refresh_token).nil?
+      end
+
+      # @!attribute [r] access_token
+      #   @return [String] the access token
+      property :access_token
+
+      # @!attribute [r] refresh_token
+      #   @return [String] the (optional) refresh token
+      property :refresh_token, :nil
+
+      # @!attribute [r] expires_in
+      #   @return [Integer] the number of seconds before the access expires
+      property :expires_in
+
+      # @!attribute [r] created_at
+      #   @return [Time] the time the access was created
+      property :created_at, default: -> { @creation_time }
+
+      # @!attribute [r] scope
+      #   @return [Array<String>] the scopes that the user is allowed to access
+      property :scope, with: ->(scope) { scope.split(' ') }
+    end
+  end
+end

data/lib/redd/models/comment.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require_relative 'model'
+require_relative 'gildable'
+require_relative 'inboxable'
+require_relative 'moderatable'
+require_relative 'postable'
+require_relative 'replyable'
+require_relative 'reportable'
+
+require_relative 'listing'
+require_relative 'subreddit'
+require_relative 'user'
+
+module Redd
+  module Models
+    # A comment.
+    class Comment < Model
+      include Gildable
+      include Inboxable
+      include Moderatable
+      include Postable
+      include Replyable
+      include Reportable
+
+      # @!attribute [r] subreddit_id
+      #   @return [String] the subreddit fullname
+      property :subreddit_id
+
+      # @!attribute [r] approved_at
+      #   @return [Time, nil] the time when the comment was approved
+      property :approved_at, from: :approved_at_utc, with: ->(t) { Time.at(t) if t }
+
+      # @!attribute [r] banned_by
+      #   @return [String] the user (?) that banned this comment
+      property :banned_by
+
+      # @!attribute [r] removal_reason
+      #   @return [String, nil] the reason for comment removal
+      property :removal_reason
+
+      # @!attribute [r] link
+      #   @return [Submission] the link that the comment was posted to
+      property :link, from: :link_id, with: ->(id) { Submission.new(client, name: id) }
+
+      # @!attribute [r] upvoted?
+      #   @return [Boolean, nil] whether the user liked/disliked this comment
+      property :upvoted?, from: :likes
+
+      # @!attribute [r] replies
+      #   @return [Listing<Comment>] the comment replies
+      property :replies,
+               with: ->(r) { r.is_a?(Hash) ? Listing.new(client, r[:data]) : Listing.empty(client) }
+
+      # @!attribute [r] user_reports
+      #   @return [Array<String>] user reports
+      property :user_reports
+
+      # @!attribute [r] saved?
+      #   @return [Boolean] whether the submission was saved by the logged-in user
+      property :saved?, from: :saved
+
+      # @!attribute [r] id
+      #   @return [String] the comment id
+      property :id
+
+      # @!attribute [r] title
+      #   @return ["comment reply", "post reply", "username mention"] the comment "title" (only
+      #     visible in messages)
+      property :title, :nil
+
+      # @!attribute [r] banned_at
+      #   @return [Time, nil] the time when the comment was banned
+      property :banned_at, from: :banned_at_utc, with: ->(t) { Time.at(t) if t }
+
+      # @!attribute [r] gilded
+      #   @return [Integer] the number of times the comment was gilded
+      property :gilded
+
+      # @!attribute [r] archived?
+      #   @return [Boolean] whether this comment was archived
+      property :archived?, from: :archived
+
+      # @!attribute [r] report_reasons
+      #   @return [Array<String>] report reasons
+      property :report_reasons
+
+      # @!attribute [r] author
+      #   @return [User] the comment author
+      property :author, with: ->(name) { User.new(client, name: name) }
+
+      # @!attribute [r] can_mod_post?
+      #   @return [Boolean] whether the logged-in user can mod post
+      property :can_mod_post?, from: :can_mod_post
+
+      # @!attribute [r] ups
+      #   @return [Integer] the comment upvotes
+      #   @deprecated use {#score} instead
+      property :ups
+
+      # @!attribute [r] downs
+      #   @return [Integer] the comment downvotes
+      #   @deprecated is always 0; use {#score} instead
+      property :downs
+
+      # @!attribute [r] parent_id
+      #   @return [String] the parent fullname
+      property :parent_id
+
+      # @!attribute [r] parent
+      #   @return [Comment, Submission] the comment parent
+      property :parent,
+               from: :parent_id,
+               with: ->(id) { Session.new(client).from_fullnames(id).first }
+
+      # @!attribute [r] score
+      #   @return [Integer] the comment score
+      property :score
+
+      # @!attribute [r] approved_by
+      #   @return [String] the user that approved the comment
+      property :approved_by
+
+      # @!attribute [r] body
+      #   @return [String] the markdown comment body
+      property :body
+
+      # @!attribute [r] body_html
+      #   @return [String] the html-rendered version of the body
+      property :body_html
+
+      # @!attribute [r] edited_at
+      #   @return [Time, nil] the time when the comment was edited
+      property :edited_at, from: :edited, with: ->(t) { Time.at(t) if t }
+
+      # @!attribute [r] author_flair_css_class
+      #   @return [String] the author flair css class
+      property :author_flair_css_class
+
+      # @!attribute [r] collapsed?
+      #   @return [Boolean] whether the comment was collapsed
+      property :collapsed?, from: :collapsed
+
+      # @!attribute [r] submitter?
+      #   @return [Boolean] whether the comment author is the link submitter
+      property :submitter?, from: :is_submitter
+
+      # @!attribute [r] collapsed_reason
+      #   @return [String] the reason for collapse (?)
+      property :collapsed_reason
+
+      # @!attribute [r] stickied?
+      #   @return [Boolean] whether the comment was stickied
+      property :stickied?, from: :stickied
+
+      # @!attribute [r] can_gild?
+      #   @return [Boolean] whether the comment is gildable
+      property :can_gild?, from: :can_gild
+
+      # @!attribute [r] subreddit
+      #   @return [Subreddit] the comment's subreddit
+      property :subreddit, with: ->(n) { Subreddit.new(client, display_name: n) }
+
+      # @!attribute [r] score_hidden
+      #   @return [Boolean] whether the comment score is hidden
+      property :score_hidden?, from: :score_hidden
+
+      # @!attribute [r] subreddit_type
+      #   @return [String] subreddit type
+      property :subreddit_type
+
+      # @!attribute [r] name
+      #   @return [String] the comment fullname
+      property :name
+
+      # @!attribute [r] author_flair_text
+      #   @return [String] the author flair text
+      property :author_flair_text
+
+      # @!attribute [r] created_at
+      #   @return [String] the time when the model was created
+      property :created_at, from: :created_utc, with: ->(t) { Time.at(t) }
+
+      # @!attribute [r] subreddit_name_prefixed
+      #   @return [String] the subreddit name, prefixed with "r/"
+      property :subreddit_name_prefixed
+
+      # @!attribute [r] controversiality
+      #   @return [Integer] the comment controversiality
+      property :controversiality
+
+      # @!attribute [r] depth
+      #   @return [Integer] the comment depth
+      property :depth
+
+      # @!attribute [r] mod_reports
+      #   @return [Array<String>] the moderator reports
+      property :mod_reports
+
+      # @!attribute [r] report_count
+      #   @return [Integer] the report count
+      property :report_count, from: :num_reports
+
+      # @!attribute [r] distinguished?
+      #   @return [Boolean] whether the comment is distinguished
+      property :distinguished?, from: :distinguished
+
+      private
+
+      def lazer_reload
+        exists_locally?(:link) ? load_with_comments : load_without_comments
+      end
+
+      def load_with_comments
+        fully_loaded!
+        id = exists_locally?(:id) ? read_attribute(:id) : read_attribute(:name).sub('t1_', '')
+        link_id = read_attribute(:link).name.sub('t3_', '')
+        client.get("/comments/#{link_id}/_/#{id}").body[1][:data][:children][0][:data]
+      end
+
+      def load_without_comments
+        id = exists_locally?(:id) ? read_attribute(:id) : read_attribute(:name).sub('t1_', '')
+        response = client.get('/api/info', id: "t1_#{id}").body[:data][:children][0][:data]
+        response.delete(:replies) # Make sure replies are lazy-loaded later.
+        response
+      end
+    end
+  end
+end

data/lib/redd/models/front_page.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative 'model'
+
+module Redd
+  module Models
+    # The front page.
+    # FIXME: deal with serious code duplication from Subreddit
+    class FrontPage < Model
+      # @return [Array<String>] reddit's base wiki pages
+      def wiki_pages
+        client.get('/wiki/pages').body[:data]
+      end
+
+      # Get a wiki page by its title.
+      # @param title [String] the page's title
+      # @return [WikiPage]
+      def wiki_page(title)
+        WikiPage.new(client, title: title)
+      end
+
+      # Get the appropriate listing.
+      # @param sort [:hot, :new, :top, :controversial, :comments, :rising, :gilded] the type of
+      #   listing
+      # @param options [Hash] a list of options to send with the request
+      # @option options [String] :after return results after the given fullname
+      # @option options [String] :before return results before the given fullname
+      # @option options [Integer, nil] :limit maximum number of items to return (nil for no limit)
+      # @option options [:hour, :day, :week, :month, :year, :all] :time the time period to consider
+      #   when sorting.
+      #
+      # @note The option :time only applies to the top and controversial sorts.
+      # @return [PaginatedListing<Submission>]
+      def listing(sort, **options)
+        options[:t] = options.delete(:time) if options.key?(:time)
+        PaginatedListing.new(client, **options) do |**req_options|
+          client.model(:get, "/#{sort}", options.merge(req_options))
+        end
+      end
+
+      # @!method hot(**params)
+      # @!method new(**params)
+      # @!method top(**params)
+      # @!method controversial(**params)
+      # @!method comments(**params)
+      # @!method rising(**params)
+      # @!method gilded(**params)
+      #
+      # @see #listing
+      %i[hot new top controversial comments rising gilded].each do |sort|
+        define_method(sort) { |**params| listing(sort, **params) }
+      end
+    end
+  end
+end

data/lib/redd/models/gildable.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Redd
+  module Models
+    # A model that can be gilded.
+    module Gildable
+      # Gift a user one month of reddit gold for their link or comment.
+      def gild
+        client.post("/api/v1/gold/gild/#{read_attribute(:name)}")
+      end
+    end
+  end
+end

data/lib/redd/models/inboxable.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Redd
+  module Models
+    # Things that can be sent to a user's inbox.
+    module Inboxable
+      # Block the user that sent this item.
+      def block
+        client.post('/api/block', id: read_attribute(:name))
+      end
+
+      # Collapse the item.
+      def collapse
+        client.post('/api/collapse_message', id: read_attribute(:name))
+      end
+
+      # Uncollapse the item.
+      def uncollapse
+        client.post('/api/uncollapse_message', id: read_attribute(:name))
+      end
+
+      # Mark this thing as read.
+      def mark_as_read
+        client.post('/api/read_message', id: read_attribute(:name))
+      end
+
+      # Mark one or more messages as unread.
+      def mark_as_unread
+        client.post('/api/unread_message', id: read_attribute(:name))
+      end
+    end
+  end
+end