discordrb 1.6.6 → 1.7.0

data/lib/discordrb/errors.rb

@@ -0,0 +1,24 @@
+module Discordrb
+  # Custom errors raised in various places
+  module Errors
+    # Raised when authentication data is invalid or incorrect.
+    class InvalidAuthenticationError < RuntimeError; end
+
+    # Raised when a HTTP status code indicates a failure
+    class HTTPStatusError < RuntimeError
+      attr_reader :status
+      def initialize(status)
+        @status = status
+      end
+    end
+
+    # Raised when a message is over the character limit
+    class MessageTooLong < RuntimeError; end
+
+    # Raised when the bot can't do something because its permissions on the server are insufficient
+    class NoPermission < RuntimeError; end
+
+    # Raised when the bot gets a HTTP 502 error, which is usually caused by Cloudflare.
+    class CloudflareError < RuntimeError; end
+  end
+end

data/lib/discordrb/events/bans.rb

@@ -36,13 +36,13 @@ module Discordrb::Events
           end
         end,
         matches_all(@attributes[:server], event.server) do |a, e|
-          if a.is_a? String
-            a == e.name
-          elsif a.is_a? Integer
-            a == e.id
-          else
-            a == e
-          end
+          a == if a.is_a? String
+                 e.name
+               elsif a.is_a? Integer
+                 e.id
+               else
+                 e
+               end
         end
       ].reduce(true, &:&)
     end
@@ -50,5 +50,7 @@ module Discordrb::Events
 
   # Raised when a user is unbanned from a server
   class UserUnbanEvent < UserBanEvent; end
+
+  # Event handler for {UserUnbanEvent}
   class UserUnbanEventHandler < UserBanEventHandler; end
-end
+end

data/lib/discordrb/events/generic.rb

@@ -2,7 +2,8 @@ require 'active_support/core_ext/module'
 
 # Events used by discordrb
 module Discordrb::Events
-  # A negated object, used to not match something in event parameters
+  # A negated object, used to not match something in event parameters.
+  # @see Discordrb::Events.matches_all
   class Negated
     attr_reader :object
 
@@ -11,6 +12,24 @@ module Discordrb::Events
     end
   end
 
+  # Attempts to match possible formats of event attributes to a set comparison value, using a comparison block.
+  # It allows five kinds of attribute formats:
+  #  0. nil -> always returns true
+  #  1. A single attribute, not negated
+  #  2. A single attribute, negated
+  #  3. An array of attributes, not negated
+  #  4. An array of attributes, not negated
+  # Note that it doesn't allow an array of negated attributes. For info on negation stuff, see {not!}
+  # @param attributes [Object, Array<Object>, Negated<Object>, Negated<Array<Object>>, nil] One or more attributes to
+  #   compare to the to_check value.
+  # @param to_check [Object] What to compare the attributes to.
+  # @yield [a, e] The block will be called when a comparison happens.
+  # @yieldparam [Object] a The attribute to compare to the value to check. Will always be a single not-negated object,
+  #   all the negation and array handling is done by the method
+  # @yieldparam [Object] e The value to compare the attribute to. Will always be the value passed to the function as
+  #   to_check.
+  # @yieldreturn [true, false] Whether or not the attribute a matches the given comparison value e.
+  # @return [true, false] whether the attributes match the comparison value in at least one way.
   def self.matches_all(attributes, to_check, &block)
     # "Zeroth" case: attributes is nil
     return true if attributes.nil?
@@ -37,31 +56,48 @@ module Discordrb::Events
       @block = block
     end
 
+    # Whether or not this event handler matches the given event with its attributes.
+    # @raise [RuntimeError] if this method is called - overwrite it in your event handler!
     def matches?(_)
       fail 'Attempted to call matches?() from a generic EventHandler'
     end
 
+    # Checks whether this handler matches the given event, and then calls it.
+    # @param event [Object] The event object to match and call the handler with
     def match(event)
       call(event) if matches? event
     end
 
+    # Calls this handler
+    # @param event [Object] The event object to call this handler with
     def call(event)
       @block.call(event)
     end
 
+    # to be overwritten by extending event handlers
+    def after_call(event); end
+
+    # @see Discordrb::Events::matches_all
     def matches_all(attributes, to_check, &block)
       Discordrb::Events.matches_all(attributes, to_check, &block)
     end
   end
 
-  # Event handler that matches all events
+  # Event handler that matches all events. Only useful for making an event that has no attributes, such as {ReadyEvent}.
   class TrueEventHandler < EventHandler
+    # Always returns true.
+    # @return [true]
     def matches?(_)
       true
     end
   end
 end
 
+# Utility function that creates a negated object for {Discordrb::Events.matches_all}
+# @param [Object] object The object to negate
+# @see Discordrb::Events::Negated
+# @see Discordrb::Events.matches_all
+# @return [Negated<Object>] the object, negated, as an attribute to pass to matches_all
 def not!(object)
   Discordrb::Events::Negated.new(object)
 end

data/lib/discordrb/events/guilds.rb

@@ -10,6 +10,8 @@ module Discordrb::Events
       init_server(data, bot)
     end
 
+    # Initializes this event with server data. Should be overwritten in case the server doesn't exist at the time
+    # of event creation (e. g. {GuildDeleteEvent})
     def init_server(data, bot)
       @server = bot.server(data['id'].to_i)
     end
@@ -35,21 +37,29 @@ module Discordrb::Events
     end
   end
 
-  # Specialized subclasses
   # Server is created
+  # @see Discordrb::EventContainer#server_create
   class GuildCreateEvent < GuildEvent; end
+
+  # Event handler for {GuildCreateEvent}
   class GuildCreateEventHandler < GuildEventHandler; end
 
   # Server is updated (e.g. name changed)
+  # @see Discordrb::EventContainer#server_update
   class GuildUpdateEvent < GuildEvent; end
+
+  # Event handler for {GuildUpdateEvent}
   class GuildUpdateEventHandler < GuildEventHandler; end
 
   # Server is deleted
+  # @see Discordrb::EventContainer#server_delete
   class GuildDeleteEvent < GuildEvent
     # Overide init_server to account for the deleted server
     def init_server(data, bot)
       @server = Discordrb::Server.new(data, bot)
     end
   end
+
+  # Event handler for {GuildDeleteEvent}
   class GuildDeleteEventHandler < GuildEventHandler; end
 end

data/lib/discordrb/events/lifetime.rb

@@ -1,9 +1,15 @@
 require 'discordrb/events/generic'
 
 module Discordrb::Events
+  # @see Discordrb::EventContainer#ready
   class ReadyEvent; end
+
+  # Event handler for {ReadyEvent}
   class ReadyEventHandler < TrueEventHandler; end
 
+  # @see Discordrb::EventContainer#disconnected
   class DisconnectEvent; end
+
+  # Event handler for {DisconnectEvent}
   class DisconnectEventHandler < TrueEventHandler; end
 end

data/lib/discordrb/events/members.rb

@@ -49,21 +49,29 @@ module Discordrb::Events
     end
   end
 
-  # Specialized subclasses
   # Member joins
+  # @see Discordrb::EventContainer#member_join
   class GuildMemberAddEvent < GuildMemberEvent; end
+
+  # Event handler for {GuildMemberAddEvent}
   class GuildMemberAddEventHandler < GuildMemberEventHandler; end
 
   # Member is updated (e.g. name changed)
+  # @see Discordrb::EventContainer#member_update
   class GuildMemberUpdateEvent < GuildMemberEvent; end
+
+  # Event handler for {GuildMemberUpdateEvent}
   class GuildMemberUpdateEventHandler < GuildMemberEventHandler; end
 
   # Member leaves
+  # @see Discordrb::EventContainer#member_leave
   class GuildMemberDeleteEvent < GuildMemberEvent
     # Overide init_user to account for the deleted user on the server
     def init_user(data, bot)
       @user = Discordrb::User.new(data['user'], bot)
     end
   end
+
+  # Event handler for {GuildMemberDeleteEvent}
   class GuildMemberDeleteEventHandler < GuildMemberEventHandler; end
 end

data/lib/discordrb/events/message.rb

@@ -3,7 +3,7 @@ require 'discordrb/events/generic'
 module Discordrb::Events
   # Event raised when a text message is sent to a channel
   class MessageEvent
-    attr_reader :message
+    attr_reader :message, :saved_message
 
     delegate :author, :channel, :content, :timestamp, to: :message
     delegate :server, to: :channel
@@ -11,16 +11,31 @@ module Discordrb::Events
     def initialize(message, bot)
       @bot = bot
       @message = message
+      @saved_message = ''
     end
 
+    # Sends a message to the channel this message was sent in, right now. It is usually preferable to use {#<<} instead
+    # because it avoids rate limiting problems
+    # @param content [String] The message to send to the channel
+    # @return [Discordrb::Message] the message that was sent
     def send_message(content)
       @message.channel.send_message(content)
     end
 
+    # @return [true, false] whether or not this message was sent by the bot itself
     def from_bot?
       @message.user.id == @bot.bot_user.id
     end
 
+    # Adds a string to be sent after the event has finished execution. Avoids problems with rate limiting because only
+    # one message is ever sent. If it is used multiple times, the strings will bunch up into one message (separated by
+    # newlines)
+    # @param message [String] The message to send to the channel
+    def <<(message)
+      @saved_message += "#{message}\n"
+      nil
+    end
+
     alias_method :user, :author
     alias_method :text, :content
     alias_method :send, :send_message
@@ -88,12 +103,23 @@ module Discordrb::Events
         matches_all(@attributes[:private], event.channel.private?) { |a, e| !e == !a }
       ].reduce(true, &:&)
     end
+
+    # @see EventHandler#after_call
+    def after_call(event)
+      event.send_message(event.saved_message) unless event.saved_message.empty?
+    end
   end
 
+  # @see Discordrb::EventContainer#mention
   class MentionEvent < MessageEvent; end
+
+  # Event handler for {MentionEvent}
   class MentionEventHandler < MessageEventHandler; end
 
+  # @see Discordrb::EventContainer#pm
   class PrivateMessageEvent < MessageEvent; end
+
+  # Event handler for {PrivateMessageEvent}
   class PrivateMessageEventHandler < MessageEventHandler; end
 
   # A subset of MessageEvent that only contains a message ID and a channel
@@ -137,10 +163,16 @@ module Discordrb::Events
   end
 
   # Raised when a message is edited
+  # @see Discordrb::EventContainer#message_edit
   class MessageEditEvent < MessageIDEvent; end
+
+  # Event handler for {MessageEditEvent}
   class MessageEditEventHandler < MessageIDEventHandler; end
 
   # Raised when a message is deleted
+  # @see Discordrb::EventContainer#message_delete
   class MessageDeleteEvent < MessageIDEvent; end
+
+  # Event handler for {MessageDeleteEvent}
   class MessageDeleteEventHandler < MessageIDEventHandler; end
 end

data/lib/discordrb/logger.rb

@@ -1,12 +1,18 @@
 module Discordrb
   # Logs debug messages
   class Logger
+    # @return [true, false] whether or not this logger should be in debug mode (all debug messages will be printed)
     attr_writer :debug
 
+    # Writes a debug message to the console.
+    # @param important [true, false] Whether this message should be printed regardless of debug mode being on or off.
     def debug(message, important = false)
-      puts "[DEBUG : #{Thread.current[:discordrb_name]} @ #{Time.now}] #{message}" if @debug || important
+      puts "[DEBUG : #{Thread.current[:discordrb_name]} @ #{Time.now.strftime('%Y-%m-%d %H:%M:%S.%L %z')}] #{message}" if @debug || important
     end
 
+    # Logs an exception to the console.
+    # @param e [Exception] The exception to log.
+    # @param important [true, false] Whether this exception should be printed regardless of debug mode being on or off.
     def log_exception(e, important = true)
       debug("Exception: #{e.inspect}", important)
       e.backtrace.each { |line| debug(line, important) }

data/lib/discordrb/permissions.rb

@@ -52,11 +52,14 @@ module Discordrb
 
     attr_reader :bits
 
+    # Set the raw bitset of this permission object
+    # @param bits [Fixnum] A number whose binary representation is the desired bitset.
     def bits=(bits)
       @bits = bits
       init_vars
     end
 
+    # Initialize the instance variables based on the bitset.
     def init_vars
       Flags.each do |position, flag|
         flag_set = ((@bits >> position) & 0x1) == 1

data/lib/discordrb/token_cache.rb

@@ -22,6 +22,7 @@ module Discordrb
       end
     end
 
+    # @return [Hash<Symbol => String>] the data representing the token and encryption data, all encrypted and base64-encoded
     def data
       {
         verify_salt: Base64.encode64(@verify_salt),
@@ -32,23 +33,37 @@ module Discordrb
       }
     end
 
+    # Verifies this encrypted token with a given password
+    # @param password [String] A plaintext password to verify
+    # @see #hash_password
+    # @return [true, false] whether or not the verification succeeded
     def verify_password(password)
       hash_password(password) == @password_hash
     end
 
+    # Sets the given password as the verification password
+    # @param password [String] A plaintext password to set
+    # @see #hash_password
     def generate_verify_hash(password)
       @password_hash = hash_password(password)
     end
 
+    # Generates a key from a given password using PBKDF2 with a SHA1 HMAC, 300k iterations and 32 bytes long
+    # @param password [String] A password to use as the base for the key
+    # @return [String] The generated key
     def obtain_key(password)
       @key = OpenSSL::PKCS5.pbkdf2_hmac_sha1(password, @encrypt_salt, 300_000, KEYLEN)
     end
 
+    # Generates cryptographically random salts for this token
     def generate_salts
       @verify_salt = OpenSSL::Random.random_bytes(KEYLEN)
       @encrypt_salt = OpenSSL::Random.random_bytes(KEYLEN)
     end
 
+    # Decrypts a token using a given password
+    # @param password [String] The plaintext password to decrypt the token with
+    # @return [String] the plaintext token
     def decrypt_token(password)
       key = obtain_key(password)
       decipher = OpenSSL::Cipher::AES256.new(:CBC)
@@ -58,6 +73,10 @@ module Discordrb
       decipher.update(@encrypted_token) + decipher.final
     end
 
+    # Encrypts a given token with the given password, using AES256 CBC
+    # @param password [String] The plaintext password to encrypt the token with
+    # @param token [String] The plaintext token to encrypt
+    # @return [String] the encrypted token
     def encrypt_token(password, token)
       key = obtain_key(password)
       cipher = OpenSSL::Cipher::AES256.new(:CBC)
@@ -67,12 +86,15 @@ module Discordrb
       @encrypted_token = cipher.update(token) + cipher.final
     end
 
+    # Tests a token by making an API request, throws an error if not successful
+    # @param token [String] A plaintext token to test
     def test_token(token)
-      Discordrb::API.gateway(token)
+      Discordrb::API.validate_token(token + 'a')
     end
 
-    private
-
+    # Hashes a password using PBKDF2 with a SHA256 digest
+    # @param password [String] The password to hash
+    # @return [String] The hashed password
     def hash_password(password)
       digest = OpenSSL::Digest::SHA256.new
       OpenSSL::PKCS5.pbkdf2_hmac(password, @verify_salt, 300_000, digest.digest_length, digest)
@@ -98,6 +120,10 @@ module Discordrb
       @data = {}
     end
 
+    # Gets a token from this token cache
+    # @param email [String] The email to get the token for
+    # @param password [String] The plaintext password to get the token for
+    # @return [String, nil] the stored token, or nil if unsuccessful (e. g. token not cached or cached token invalid)
     def token(email, password)
       if @data[email]
         begin
@@ -108,7 +134,10 @@ module Discordrb
               begin
                 cached.test_token(token)
                 token
-              rescue => e; fail_token('Token cached, verified and decrypted, but rejected by Discord', email, e)
+              rescue => e
+                fail_token('Token cached, verified and decrypted, but rejected by Discord', email, e)
+                sleep 1 # wait some time so we don't get immediately rate limited
+                nil
               end
             else; fail_token('Token cached and verified, but decryption failed', email)
             end
@@ -120,6 +149,10 @@ module Discordrb
       end
     end
 
+    # Caches a token
+    # @param email [String] The email to store this token under
+    # @param password [String] The plaintext password to encrypt the token with
+    # @param token [String] The plaintext token to cache
     def store_token(email, password, token)
       cached = CachedToken.new
       cached.generate_verify_hash(password)
@@ -128,6 +161,7 @@ module Discordrb
       write_cache
     end
 
+    # Writes the cache to a file
     def write_cache
       File.write(CACHE_PATH, @data.to_json)
     end