discordrb 3.1.1 → 3.4.0

data/lib/discordrb/id_object.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Discordrb
+  # Mixin for objects that have IDs
+  module IDObject
+    # @return [Integer] the ID which uniquely identifies this object across Discord.
+    attr_reader :id
+    alias_method :resolve_id, :id
+    alias_method :hash, :id
+
+    # ID based comparison
+    def ==(other)
+      Discordrb.id_compare(@id, other)
+    end
+
+    alias_method :eql?, :==
+
+    # Estimates the time this object was generated on based on the beginning of the ID. This is fairly accurate but
+    # shouldn't be relied on as Discord might change its algorithm at any time
+    # @return [Time] when this object was created at
+    def creation_time
+      # Milliseconds
+      ms = (@id >> 22) + DISCORD_EPOCH
+      Time.at(ms / 1000.0)
+    end
+
+    # Creates an artificial snowflake at the given point in time. Useful for comparing against.
+    # @param time [Time] The time the snowflake should represent.
+    # @return [Integer] a snowflake with the timestamp data as the given time
+    def self.synthesise(time)
+      ms = (time.to_f * 1000).to_i
+      (ms - DISCORD_EPOCH) << 22
+    end
+
+    class << self
+      alias_method :synthesize, :synthesise
+    end
+  end
+end

data/lib/discordrb/light.rb

@@ -2,7 +2,7 @@
 
 require 'discordrb/light/light_bot'
 
-# This module contains classes to allow connections to bots without a connection to the gateway socket, i. e. bots
+# This module contains classes to allow connections to bots without a connection to the gateway socket, i.e. bots
 # that only use the REST part of the API.
 module Discordrb::Light
 end

data/lib/discordrb/light/integrations.rb

@@ -49,7 +49,7 @@ module Discordrb::Light
     #   Twitch account connection of the server owner).
     attr_reader :server_connection
 
-    # @return [Connection] the connection integrated with the server (i. e. your connection)
+    # @return [Connection] the connection integrated with the server (i.e. your connection)
     attr_reader :integrated_connection
 
     # @!visibility private

data/lib/discordrb/light/light_bot.rb

@@ -6,7 +6,7 @@ require 'discordrb/api/user'
 require 'discordrb/light/data'
 require 'discordrb/light/integrations'
 
-# This module contains classes to allow connections to bots without a connection to the gateway socket, i. e. bots
+# This module contains classes to allow connections to bots without a connection to the gateway socket, i.e. bots
 # that only use the REST part of the API.
 module Discordrb::Light
   # A bot that only uses the REST part of the API. Hierarchically unrelated to the regular {Discordrb::Bot}. Useful to

data/lib/discordrb/logger.rb

@@ -2,7 +2,7 @@
 
 module Discordrb
   # The format log timestamps should be in, in strftime format
-  LOG_TIMESTAMP_FORMAT = '%Y-%m-%d %H:%M:%S.%L'.freeze
+  LOG_TIMESTAMP_FORMAT = '%Y-%m-%d %H:%M:%S.%L'
 
   # Logs debug messages
   class Logger
@@ -18,7 +18,7 @@ module Discordrb
     # Creates a new logger.
     # @param fancy [true, false] Whether this logger uses fancy mode (ANSI escape codes to make the output colourful)
     # @param streams [Array<IO>, Array<#puts & #flush>] the streams the logger should write to.
-    def initialize(fancy = false, streams = [STDOUT])
+    def initialize(fancy = false, streams = [$stdout])
       @fancy = fancy
       self.mode = :normal
 
@@ -33,14 +33,15 @@ module Discordrb
       warn: { long: 'WARN', short: '!', format_code: "\u001B[33m" }, # yellow
       error: { long: 'ERROR', short: '✗', format_code: "\u001B[31m" }, # red
       out: { long: 'OUT', short: '→', format_code: "\u001B[36m" }, # cyan
-      in: { long: 'IN', short: '←', format_code: "\u001B[35m" } # purple
+      in: { long: 'IN', short: '←', format_code: "\u001B[35m" }, # purple
+      ratelimit: { long: 'RATELIMIT', short: 'R', format_code: "\u001B[41m" } # red background
     }.freeze
 
     # The ANSI format code that resets formatting
-    FORMAT_RESET = "\u001B[0m".freeze
+    FORMAT_RESET = "\u001B[0m"
 
     # The ANSI format code that makes something bold
-    FORMAT_BOLD = "\u001B[1m".freeze
+    FORMAT_BOLD = "\u001B[1m"
 
     MODES.each do |mode, hash|
       define_method(mode) do |message|
@@ -65,15 +66,15 @@ module Discordrb
     def mode=(value)
       case value
       when :debug
-        @enabled_modes = [:debug, :good, :info, :warn, :error, :out, :in]
+        @enabled_modes = %i[debug good info warn error out in ratelimit]
       when :verbose
-        @enabled_modes = [:good, :info, :warn, :error, :out, :in]
+        @enabled_modes = %i[good info warn error out in ratelimit]
       when :normal
-        @enabled_modes = [:info, :warn, :error]
+        @enabled_modes = %i[info warn error ratelimit]
       when :quiet
-        @enabled_modes = [:warn, :error]
+        @enabled_modes = %i[warn error]
       when :silent
-        @enabled_modes = []
+        @enabled_modes = %i[]
       end
     end
 
@@ -91,7 +92,7 @@ module Discordrb
       timestamp = Time.now.strftime(LOG_TIMESTAMP_FORMAT)
 
       # Redact token if set
-      log = if @token
+      log = if @token && @token != ''
               message.to_s.gsub(@token, 'REDACTED_TOKEN')
             else
               message.to_s

data/lib/discordrb/paginator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Discordrb
+  # Utility class for wrapping paginated endpoints. It is [Enumerable](https://ruby-doc.org/core-2.5.1/Enumerable.html),
+  # similar to an `Array`, so most of the same methods can be used to filter the results of the request
+  # that it wraps. If you simply want an array of all of the results, `#to_a` can be called.
+  class Paginator
+    include Enumerable
+
+    # Creates a new {Paginator}
+    # @param limit [Integer] the maximum number of items to request before stopping
+    # @param direction [:up, :down] the order in which results are returned in
+    # @yield [Array, nil] the last page of results, or nil if this is the first iteration.
+    #   This should be used to request the next page of results.
+    # @yieldreturn [Array] the next page of results
+    def initialize(limit, direction, &block)
+      @count = 0
+      @limit = limit
+      @direction = direction
+      @block = block
+    end
+
+    # Yields every item produced by the wrapped request, until it returns
+    # no more results or the configured `limit` is reached.
+    def each
+      last_page = nil
+      until limit_check
+        page = @block.call(last_page)
+        return if page.empty?
+
+        enumerator = case @direction
+                     when :down
+                       page.each
+                     when :up
+                       page.reverse_each
+                     end
+
+        enumerator.each do |item|
+          yield item
+          @count += 1
+          break if limit_check
+        end
+
+        last_page = page
+      end
+    end
+
+    private
+
+    # Whether the paginator limit has been exceeded
+    def limit_check
+      return false if @limit.nil?
+
+      @count >= @limit
+    end
+  end
+end

data/lib/discordrb/permissions.rb

@@ -4,8 +4,7 @@ module Discordrb
   # List of permissions Discord uses
   class Permissions
     # This hash maps bit positions to logical permissions.
-    # I'm not sure what the unlabeled bits are reserved for.
-    Flags = {
+    FLAGS = {
       # Bit => Permission # Value
       0 => :create_instant_invite, # 1
       1 => :kick_members,          # 2
@@ -13,10 +12,10 @@ module Discordrb
       3 => :administrator,         # 8
       4 => :manage_channels,       # 16
       5 => :manage_server,         # 32
-      # 6                          # 64
-      # 7                          # 128
-      # 8                          # 256
-      # 9                          # 512
+      6 => :add_reactions,         # 64
+      7 => :view_audit_log,        # 128
+      8 => :priority_speaker,      # 256
+      9 => :stream,                # 512
       10 => :read_messages,        # 1024
       11 => :send_messages,        # 2048
       12 => :send_tts_messages,    # 4096
@@ -26,7 +25,7 @@ module Discordrb
       16 => :read_message_history, # 65536
       17 => :mention_everyone,     # 131072
       18 => :use_external_emoji,   # 262144
-      # 19                         # 524288
+      19 => :view_server_insights, # 524288
       20 => :connect,              # 1048576
       21 => :speak,                # 2097152
       22 => :mute_members,         # 4194304
@@ -35,11 +34,14 @@ module Discordrb
       25 => :use_voice_activity,   # 33554432
       26 => :change_nickname,      # 67108864
       27 => :manage_nicknames,     # 134217728
-      28 => :manage_roles          # 268435456, also Manage Permissions
+      28 => :manage_roles,         # 268435456, also Manage Permissions
+      29 => :manage_webhooks,      # 536870912
+      30 => :manage_emojis         # 1073741824
     }.freeze
 
-    Flags.each do |position, flag|
+    FLAGS.each do |position, flag|
       attr_reader flag
+
       define_method "can_#{flag}=" do |value|
         new_bits = @bits
         if value
@@ -47,18 +49,19 @@ module Discordrb
         else
           new_bits &= ~(1 << position)
         end
-        @writer.write(new_bits) if @writer
+        @writer&.write(new_bits)
         @bits = new_bits
         init_vars
       end
     end
 
     alias_method :can_administrate=, :can_administrator=
+    alias_method :administrate, :administrator
 
     attr_reader :bits
 
     # Set the raw bitset of this permission object
-    # @param bits [Fixnum] A number whose binary representation is the desired bitset.
+    # @param bits [Integer] A number whose binary representation is the desired bitset.
     def bits=(bits)
       @bits = bits
       init_vars
@@ -66,20 +69,151 @@ module Discordrb
 
     # Initialize the instance variables based on the bitset.
     def init_vars
-      Flags.each do |position, flag|
+      FLAGS.each do |position, flag|
         flag_set = ((@bits >> position) & 0x1) == 1
         instance_variable_set "@#{flag}", flag_set
       end
     end
 
+    # Return the corresponding bits for an array of permission flag symbols.
+    # This is a class method that can be used to calculate bits instead
+    # of instancing a new Permissions object.
+    # @example Get the bits for permissions that could allow/deny read messages, connect, and speak
+    #   Permissions.bits [:read_messages, :connect, :speak] #=> 3146752
+    # @param list [Array<Symbol>]
+    # @return [Integer] the computed permissions integer
+    def self.bits(list)
+      value = 0
+
+      FLAGS.each do |position, flag|
+        value += 2**position if list.include? flag
+      end
+
+      value
+    end
+
     # Create a new Permissions object either as a blank slate to add permissions to (for example for
     #   {Channel#define_overwrite}) or from existing bit data to read out.
-    # @param bits [Integer] The permission bits that should be set from the beginning.
+    # @example Create a permissions object that could allow/deny read messages, connect, and speak by setting flags
+    #   permission = Permissions.new
+    #   permission.can_read_messages = true
+    #   permission.can_connect = true
+    #   permission.can_speak = true
+    # @example Create a permissions object that could allow/deny read messages, connect, and speak by an array of symbols
+    #   Permissions.new [:read_messages, :connect, :speak]
+    # @param bits [Integer, Array<Symbol>] The permission bits that should be set from the beginning, or an array of permission flag symbols
     # @param writer [RoleWriter] The writer that should be used to update data when a permission is set.
     def initialize(bits = 0, writer = nil)
       @writer = writer
-      @bits = bits
+
+      @bits = if bits.is_a? Array
+                self.class.bits(bits)
+              else
+                bits
+              end
+
       init_vars
     end
+
+    # Comparison based on permission bits
+    def ==(other)
+      false unless other.is_a? Discordrb::Permissions
+      bits == other.bits
+    end
+  end
+
+  # Mixin to calculate resulting permissions from overrides etc.
+  module PermissionCalculator
+    # Checks whether this user can do the particular action, regardless of whether it has the permission defined,
+    # through for example being the server owner or having the Manage Roles permission
+    # @param action [Symbol] The permission that should be checked. See also {Permissions::FLAGS} for a list.
+    # @param channel [Channel, nil] If channel overrides should be checked too, this channel specifies where the overrides should be checked.
+    # @example Check if the bot can send messages to a specific channel in a server.
+    #   bot_profile = bot.profile.on(event.server)
+    #   can_send_messages = bot_profile.permission?(:send_messages, channel)
+    # @return [true, false] whether or not this user has the permission.
+    def permission?(action, channel = nil)
+      # If the member is the server owner, it irrevocably has all permissions.
+      return true if owner?
+
+      # First, check whether the user has Manage Roles defined.
+      # (Coincidentally, Manage Permissions is the same permission as Manage Roles, and a
+      # Manage Permissions deny overwrite will override Manage Roles, so we can just check for
+      # Manage Roles once and call it a day.)
+      return true if defined_permission?(:administrator, channel)
+
+      # Otherwise, defer to defined_permission
+      defined_permission?(action, channel)
+    end
+
+    # Checks whether this user has a particular permission defined (i.e. not implicit, through for example
+    # Manage Roles)
+    # @param action [Symbol] The permission that should be checked. See also {Permissions::FLAGS} for a list.
+    # @param channel [Channel, nil] If channel overrides should be checked too, this channel specifies where the overrides should be checked.
+    # @example Check if a member has the Manage Channels permission defined in the server.
+    #   has_manage_channels = member.defined_permission?(:manage_channels)
+    # @return [true, false] whether or not this user has the permission defined.
+    def defined_permission?(action, channel = nil)
+      # Get the permission the user's roles have
+      role_permission = defined_role_permission?(action, channel)
+
+      # Once we have checked the role permission, we have to check the channel overrides for the
+      # specific user
+      user_specific_override = permission_overwrite(action, channel, id) # Use the ID reader as members have no ID instance variable
+
+      # Merge the two permissions - if an override is defined, it has to be allow, otherwise we only care about the role
+      return role_permission unless user_specific_override
+
+      user_specific_override == :allow
+    end
+
+    # Define methods for querying permissions
+    Discordrb::Permissions::FLAGS.each_value do |flag|
+      define_method "can_#{flag}?" do |channel = nil|
+        permission? flag, channel
+      end
+    end
+
+    alias_method :can_administrate?, :can_administrator?
+
+    private
+
+    def defined_role_permission?(action, channel)
+      roles_to_check = [@server.everyone_role] + @roles
+
+      # For each role, check if
+      #   (1) the channel explicitly allows or permits an action for the role and
+      #   (2) if the user is allowed to do the action if the channel doesn't specify
+      roles_to_check.sort_by(&:position).reduce(false) do |can_act, role|
+        # Get the override defined for the role on the channel
+        channel_allow = permission_overwrite(action, channel, role.id)
+        if channel_allow
+          # If the channel has an override, check whether it is an allow - if yes,
+          # the user can act, if not, it can't
+          break true if channel_allow == :allow
+
+          false
+        else
+          # Otherwise defer to the role
+          role.permissions.instance_variable_get("@#{action}") || can_act
+        end
+      end
+    end
+
+    def permission_overwrite(action, channel, id)
+      # If no overwrites are defined, or no channel is set, no overwrite will be present
+      return nil unless channel && channel.permission_overwrites[id]
+
+      # Otherwise, check the allow and deny objects
+      allow = channel.permission_overwrites[id].allow
+      deny = channel.permission_overwrites[id].deny
+      if allow.instance_variable_get("@#{action}")
+        :allow
+      elsif deny.instance_variable_get("@#{action}")
+        :deny
+      end
+
+      # If there's no variable defined, nil will implicitly be returned
+    end
   end
 end

data/lib/discordrb/version.rb

@@ -3,5 +3,5 @@
 # Discordrb and all its functionality, in this case only the version.
 module Discordrb
   # The current version of discordrb.
-  VERSION = '3.1.1'.freeze
+  VERSION = '3.4.0'
 end

data/lib/discordrb/voice/encoder.rb

@@ -24,16 +24,14 @@ module Discordrb::Voice
 
     # Create a new encoder
     def initialize
-      @sample_rate = 48_000
-      @frame_size = 960
-      @channels = 2
+      sample_rate = 48_000
+      frame_size = 960
+      channels = 2
       @filter_volume = 1
 
-      if OPUS_AVAILABLE
-        @opus = Opus::Encoder.new(@sample_rate, @frame_size, @channels)
-      else
-        raise LoadError, 'Opus unavailable - voice not supported! Please install opus for voice support to work.'
-      end
+      raise LoadError, 'Opus unavailable - voice not supported! Please install opus for voice support to work.' unless OPUS_AVAILABLE
+
+      @opus = Opus::Encoder.new(sample_rate, frame_size, channels)
     end
 
     # Set the opus encoding bitrate
@@ -76,21 +74,21 @@ module Discordrb::Voice
     # an audio track. For a list of supported formats, see https://ffmpeg.org/general.html#Audio-Codecs. It even accepts
     # URLs, though encoding them is pretty slow - I recommend to make a stream of it and then use {#encode_io} instead.
     # @param file [String] The path or URL to encode.
+    # @param options [String] ffmpeg options to pass after the -i flag
     # @return [IO] the audio, encoded as s16le PCM
-    def encode_file(file)
-      command = "#{ffmpeg_command} -loglevel 0 -i \"#{file}\" -f s16le -ar 48000 -ac 2 #{filter_volume_argument} pipe:1"
+    def encode_file(file, options = '')
+      command = "#{ffmpeg_command} -loglevel 0 -i \"#{file}\" #{options} -f s16le -ar 48000 -ac 2 #{filter_volume_argument} pipe:1"
       IO.popen(command)
     end
 
     # Encodes an arbitrary IO audio stream using ffmpeg. Accepts pretty much any media format, even videos with audio
     # tracks. For a list of supported audio formats, see https://ffmpeg.org/general.html#Audio-Codecs.
     # @param io [IO] The stream to encode.
+    # @param options [String] ffmpeg options to pass after the -i flag
     # @return [IO] the audio, encoded as s16le PCM
-    def encode_io(io)
-      ret_io, writer = IO.pipe
-      command = "#{ffmpeg_command} -loglevel 0 -i - -f s16le -ar 48000 -ac 2 #{filter_volume_argument} pipe:1"
-      spawn(command, in: io, out: writer)
-      ret_io
+    def encode_io(io, options = '')
+      command = "#{ffmpeg_command} -loglevel 0 -i - #{options} -f s16le -ar 48000 -ac 2 #{filter_volume_argument} pipe:1"
+      IO.popen(command, in: io)
     end
 
     private
@@ -101,6 +99,7 @@ module Discordrb::Voice
 
     def filter_volume_argument
       return '' if @filter_volume == 1
+
       @use_avconv ? "-vol #{(@filter_volume * 256).ceil}" : "-af volume=#{@filter_volume}"
     end
   end