redd 0.7.10 → 0.8.0.pre.1

data/lib/redd/api_client.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative 'client'
+require_relative 'error'
+require_relative 'utilities/error_handler'
+require_relative 'utilities/rate_limiter'
+require_relative 'utilities/unmarshaller'
+
+module Redd
+  # The class for API clients.
+  class APIClient < Client
+    # The endpoint to make API requests to.
+    API_ENDPOINT = 'https://oauth.reddit.com'
+
+    # @return [APIClient] the access the client uses
+    attr_reader :access
+
+    # Create a new API client from an auth strategy.
+    # @param auth [AuthStrategies::AuthStrategy] the auth strategy to use
+    # @param endpoint [String] the API endpoint
+    # @param user_agent [String] the user agent to send
+    # @param limit_time [Integer] the minimum number of seconds between each request
+    # @param max_retries [Integer] number of times to retry requests that may be successful if
+    #   retried
+    # @param auto_login [Boolean] (for script and userless) automatically authenticate if not done
+    #   so already
+    # @param auto_refresh [Boolean] (for script and userless) automatically refresh access token if
+    #   nearing expiration
+    def initialize(auth, endpoint: API_ENDPOINT, user_agent: USER_AGENT, limit_time: 1,
+                   max_retries: 5, auto_login: true, auto_refresh: true)
+      super(endpoint: endpoint, user_agent: user_agent)
+
+      @auth            = auth
+      @access          = nil
+      @max_retries     = max_retries
+      @failures        = 0
+      @error_handler   = Utilities::ErrorHandler.new
+      @rate_limiter    = Utilities::RateLimiter.new(limit_time)
+      @unmarshaller    = Utilities::Unmarshaller.new(self)
+
+      # FIXME: hard dependencies on Script and Userless types
+      can_auto      = auth.is_a?(AuthStrategies::Script) || auth.is_a?(AuthStrategies::Userless)
+      @auto_login   = can_auto && auto_login
+      @auto_refresh = can_auto && auto_refresh
+    end
+
+    # Authenticate the client using the provided auth.
+    def authenticate(*args)
+      @access = @auth.authenticate(*args)
+    end
+
+    # Refresh the access currently in use.
+    def refresh(*args)
+      @access = @auth.refresh(*args)
+    end
+
+    # Revoke the current access and remove it from the client.
+    def revoke
+      @auth.revoke(@access)
+      @access = nil
+    end
+
+    def unmarshal(object)
+      @unmarshaller.unmarshal(object)
+    end
+
+    def model(verb, path, params = {})
+      # XXX: make unmarshal explicit in methods?
+      unmarshal(send(verb, path, params).body)
+    end
+
+    private
+
+    # Makes sure a valid access is present, raising an error if nil
+    def ensure_access_is_valid
+      # Authenticate first if auto_login is enabled
+      authenticate if @access.nil? && @auto_login
+      # Refresh access if auto_refresh is enabled
+      refresh if @access.expired? && @auto_refresh
+      # Fuck it, panic
+      raise 'client access is nil, try calling #authenticate' if @access.nil?
+    end
+
+    def connection
+      super.auth("Bearer #{@access.access_token}")
+    end
+
+    # Makes a request, ensuring not to break the rate limit by sleeping.
+    # @see Client#request
+    def request(verb, path, params: {}, form: {})
+      # Make sure @access is populated by a valid access
+      ensure_access_is_valid
+      # Setup base API params and make request
+      api_params = { api_type: 'json', raw_json: 1 }.merge(params)
+      response = @rate_limiter.after_limit { super(verb, path, params: api_params, form: form) }
+      # Check for errors in the returned response
+      response_error = @error_handler.check_error(response)
+      raise response_error unless response_error.nil?
+      # All done, return the response
+      @failures = 0
+      response
+    rescue Redd::ServerError, HTTP::TimeoutError => e
+      @failures += 1
+      raise e if @failures > @max_retries
+      warn "Redd got a #{e.class.name} error (#{e.message}), retrying..."
+      retry
+    end
+  end
+end

data/lib/redd/auth_strategies/auth_strategy.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative '../client'
+
+module Redd
+  module AuthStrategies
+    # The API client for authentication to reddit.
+    class AuthStrategy < Client
+      # The API to make authentication requests to.
+      AUTH_ENDPOINT = 'https://www.reddit.com'
+
+      # @param client_id [String] the client id of the reddit app
+      # @param secret [String] the app's secret string
+      # @param endpoint [String] the url to contact for authentication requests
+      # @param user_agent [String] the user agent to send with requests
+      def initialize(client_id:, secret:, endpoint: AUTH_ENDPOINT, user_agent: USER_AGENT)
+        super(endpoint: endpoint, user_agent: user_agent)
+        @client_id = client_id
+        @secret = secret
+      end
+
+      # @abstract Perform authentication and return the resulting access object
+      # @return [Access] the access token object
+      def authenticate(*)
+        raise 'abstract method: this strategy cannot authenticate with reddit'
+      end
+
+      # @abstract Refresh the authentication and return the refreshed access
+      # @return [Access] the new access
+      def refresh(*)
+        raise 'abstract method: this strategy cannot refresh access'
+      end
+
+      # Revoke the access token, making it invalid for future requests.
+      # @param access [Access] the access object to revoke
+      def revoke(access)
+        token =
+          if access.is_a?(String)
+            access
+          elsif access.respond_to?(:refresh_token)
+            access.refresh_token
+          else
+            access.access_token
+          end
+        post('/api/v1/revoke_token', token: token).body
+      end
+
+      private
+
+      def connection
+        @connection ||= super.basic_auth(user: @client_id, pass: @secret)
+      end
+
+      def request_access(grant_type, options = {})
+        response = post('/api/v1/access_token', { grant_type: grant_type }.merge(options))
+        Models::Access.new(self, response.body)
+      end
+    end
+  end
+end

data/lib/redd/auth_strategies/installed.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'auth_strategy'
+
+module Redd
+  module AuthStrategies
+    # For non-confidential apps. Different from the implicit grant.
+    class Installed < AuthStrategy
+      def initialize(client_id:, redirect_uri:, **kwargs)
+        super(client_id: client_id, secret: '', **kwargs)
+        @redirect_uri = redirect_uri
+      end
+
+      # Authenticate with a code using the "web" flow.
+      # @param code [String] the code returned by reddit
+      # @return [Access]
+      def authenticate(code)
+        request_access('authorization_code', code: code, redirect_uri: @redirect_uri)
+      end
+    end
+  end
+end

data/lib/redd/auth_strategies/script.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'auth_strategy'
+
+module Redd
+  module AuthStrategies
+    # A password-based authentication scheme. Requests all scopes.
+    class Script < AuthStrategy
+      def initialize(client_id:, secret:, username:, password:, **kwargs)
+        super(client_id: client_id, secret: secret, **kwargs)
+        @username = username
+        @password = password
+      end
+
+      # Perform authentication and return the resulting access object
+      # @return [Access] the access token object
+      def authenticate
+        request_access('password', username: @username, password: @password)
+      end
+      alias refresh authenticate
+    end
+  end
+end

data/lib/redd/auth_strategies/userless.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'auth_strategy'
+
+module Redd
+  module AuthStrategies
+    # A userless authentication scheme.
+    class Userless < AuthStrategy
+      # Perform authentication and return the resulting access object
+      # @return [Access] the access token object
+      def authenticate
+        request_access('client_credentials')
+      end
+      alias refresh authenticate
+    end
+  end
+end

data/lib/redd/auth_strategies/web.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'auth_strategy'
+
+module Redd
+  module AuthStrategies
+    # A typical code-based authentication. I genuinely recommend this for bots.
+    # Only confidential web apps can be refreshed.
+    class Web < AuthStrategy
+      def initialize(client_id:, secret:, redirect_uri:, **kwargs)
+        super(client_id: client_id, secret: secret, **kwargs)
+        @redirect_uri = redirect_uri
+      end
+
+      # Authenticate with a code using the "web" flow.
+      # @param code [String] the code returned by reddit
+      # @return [Access]
+      def authenticate(code)
+        request_access('authorization_code', code: code, redirect_uri: @redirect_uri)
+      end
+
+      # Refresh the authentication and return a new refreshed access
+      # @return [Access] the new access
+      def refresh(access)
+        request_access('refresh_token', refresh_token: must_have(access, :refresh_token))
+      end
+    end
+  end
+end

data/lib/redd/client.rb

@@ -0,0 +1,88 @@
+# 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 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(:per_operation, write: 5, connect: 5, read: 5)
+    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 params [Hash] the parameters to supply with the url
+    # @param form [Hash] the parameters to supply in the body
+    # @return [Response] the response
+    def request(verb, path, params: {}, form: {})
+      response = connection.request(verb, path, params: params, form: form)
+      Response.new(response.status.code, response.headers, response.body.to_s)
+    end
+  end
+end

data/lib/redd/error.rb

@@ -1,151 +1,28 @@
-module Redd
-  # An error from reddit
-  # TODO: Move Error to an Errors module in next minor version?
-  class Error < StandardError
-    attr_reader :code
-    attr_reader :headers
-    attr_reader :body
-
-    def initialize(env)
-      @code = env[:status]
-      @headers = env[:response_headers]
-      @body = env[:body]
-    end
-
-    def self.from_response(env) # rubocop:disable all
-      status = env[:status]
-      body = parse_error(env[:body]).to_s
-      case status
-      when 200
-        case body
-        when /access_denied/i             then OAuth2AccessDenied
-        when /unsupported_response_type/i then InvalidResponseType
-        when /unsupported_grant_type/i    then InvalidGrantType
-        when /invalid_scope/i             then InvalidScope
-        when /invalid_request/i           then InvalidRequest
-        when /no_text/i                   then NoTokenGiven
-        when /invalid_grant/i             then ExpiredCode
-        when /wrong_password/i            then InvalidCredentials
-        when /bad_captcha/i               then InvalidCaptcha
-        when /ratelimit/i                 then RateLimited
-        when /quota_filled/i              then QuotaFilled
-        when /bad_css_name/i              then InvalidClassName
-        when /too_old/i                   then Archived
-        when /too_much_flair_css/i        then TooManyClassNames
-        when /user_required/i             then AuthenticationRequired
-        end
-      when 400 then BadRequest
-      when 401 then InvalidOAuth2Credentials
-      when 403
-        if /user_required/i =~ body
-          AuthenticationRequired
-        else
-          PermissionDenied
-        end
-      when 404 then NotFound
-      when 409 then Conflict
-      when 500 then InternalServerError
-      when 502 then BadGateway
-      when 503 then ServiceUnavailable
-      when 504 then TimedOut
-      end
-    end
-
-    def self.parse_error(body) # rubocop:disable all
-      return body unless body.is_a?(Hash)
-
-      if body.key?(:json) && body[:json].key?(:errors)
-        body[:json][:errors].first
-      elsif body.key?(:jquery)
-        body[:jquery]
-      elsif body.key?(:error)
-        body[:error]
-      elsif body.key?(:code) && body[:code] == "NO_TEXT"
-        "NO_TEXT"
-      end
-    end
-
-    # This item has been archived and can no longer be edited.
-    Archived = Class.new(Error)
-
-    AuthenticationRequired = Class.new(Error)
-
-    # Bad Gateway. Either a network or a reddit error. Either way, try again.
-    BadGateway = Class.new(Error)
-
-    BadRequest = Class.new(Error)
-
-    Conflict = Class.new(Error)
-
-    # You already received an access token using this code. The user should
-    # grant you access again to get a new code.
-    ExpiredCode = Class.new(Error)
-
-    # There is an issue on reddit's end. Try again.
-    InternalServerError = Class.new(Error)
-
-    InvalidCaptcha = Class.new(Error)
-
-    InvalidClassName = Class.new(Error)
+# frozen_string_literal: true
 
-    # Either your username or your password is wrong.
-    InvalidCredentials = Class.new(Error)
-
-    InvalidGrantType = Class.new(Error)
-
-    InvalidMultiredditName = Class.new(Error)
-
-    # Your client id or your secret is wrong.
-    InvalidOAuth2Credentials = Class.new(Error)
-
-    InvalidResponseType = Class.new(Error)
-
-    InvalidRequest = Class.new(Error)
-
-    # You don't have the proper scope to perform this request.
-    InvalidScope = Class.new(Error)
-
-    # Looks like we didn't get a JSON response. Raise this error.
-    JSONError = Class.new(Error)
-
-    # Four, oh four! The thing you're looking for wasn't found.
-    NotFound = Class.new(Error)
-
-    # No access token was given.
-    NoTokenGiven = Class.new(Error)
-
-    OAuth2AccessDenied = Class.new(Error)
-
-    PermissionDenied = Class.new(Error)
-
-    # Raised when the client needs to wait before making another request
-    class RateLimited < Error
-      # @!attribute [r] time
-      # @return [Integer] the seconds to wait before making another request.
-      attr_reader :time
+module Redd
+  # Represents an error from reddit returned in a response.
+  class ResponseError < StandardError
+    attr_accessor :response
 
-      def initialize(env)
-        super
-        @time = env[:body][:json][:ratelimit] || 3600
-      end
+    def initialize(response)
+      super(response.raw_body.length <= 80 ? response.raw_body : "#{response.raw_body[0..80]}...")
+      @response = response
     end
+  end
 
-    # This seems to be a more OAuth2-focused error.
-    class QuotaFilled < RateLimited
-      def initialize(env)
-        super
-        @time = 3600
-      end
-    end
+  # An error with Redd, probably (let me know!)
+  class BadRequest < ResponseError; end
 
-    RequestError = Class.new(Error)
+  # You don't have the correct scope to do this.
+  class InsufficientScope < ResponseError; end
 
-    # Issue on reddit's end. Try again.
-    ServiceUnavailable = Class.new(Error)
+  # The access object supplied was invalid.
+  class InvalidAccess < ResponseError; end
 
-    # The connection timed out. Try again.
-    TimedOut = Class.new(Error)
+  # Returned when reddit raises a 404 error.
+  class NotFound < ResponseError; end
 
-    TooManyClassNames = Class.new(Error)
-  end
+  # An unknown error on reddit's end. Usually fixed with a retry.
+  class ServerError < ResponseError; end
 end