discordrb 3.3.0 → 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/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
 
@@ -38,10 +38,10 @@ module Discordrb
     }.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|

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
@@ -16,7 +15,7 @@ module Discordrb
       6 => :add_reactions,         # 64
       7 => :view_audit_log,        # 128
       8 => :priority_speaker,      # 256
-      # 9                          # 512
+      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
@@ -40,8 +39,9 @@ module Discordrb
       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
@@ -49,7 +49,7 @@ module Discordrb
         else
           new_bits &= ~(1 << position)
         end
-        @writer.write(new_bits) if @writer
+        @writer&.write(new_bits)
         @bits = new_bits
         init_vars
       end
@@ -69,7 +69,7 @@ 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
@@ -85,7 +85,7 @@ module Discordrb
     def self.bits(list)
       value = 0
 
-      Flags.each do |position, flag|
+      FLAGS.each do |position, flag|
         value += 2**position if list.include? flag
       end
 
@@ -121,4 +121,99 @@ module Discordrb
       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.3.0'.freeze
+  VERSION = '3.4.0'
 end

data/lib/discordrb/voice/encoder.rb

@@ -30,6 +30,7 @@ module Discordrb::Voice
       @filter_volume = 1
 
       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
 
@@ -86,10 +87,8 @@ module Discordrb::Voice
     # @param options [String] ffmpeg options to pass after the -i flag
     # @return [IO] the audio, encoded as s16le PCM
     def encode_io(io, options = '')
-      ret_io, writer = IO.pipe
       command = "#{ffmpeg_command} -loglevel 0 -i - #{options} -f s16le -ar 48000 -ac 2 #{filter_volume_argument} pipe:1"
-      spawn(command, in: io, out: writer)
-      ret_io
+      IO.popen(command, in: io)
     end
 
     private
@@ -100,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

data/lib/discordrb/voice/network.rb

@@ -1,58 +1,66 @@
 # frozen_string_literal: true
 
 require 'websocket-client-simple'
-require 'resolv'
 require 'socket'
 require 'json'
 
 require 'discordrb/websocket'
 
 begin
-  RBNACL_AVAILABLE = if ENV['DISCORDRB_NONACL']
-                       false
-                     else
-                       require 'rbnacl'
-                       true
-                     end
+  LIBSODIUM_AVAILABLE = if ENV['DISCORDRB_NONACL']
+                          false
+                        else
+                          require 'discordrb/voice/sodium'
+                        end
 rescue LoadError
   puts "libsodium not available! You can continue to use discordrb as normal but voice support won't work.
-        Read https://github.com/meew0/discordrb/wiki/Installing-libsodium for more details."
-  RBNACL_AVAILABLE = false
+        Read https://github.com/shardlab/discordrb/wiki/Installing-libsodium for more details."
+  LIBSODIUM_AVAILABLE = false
 end
 
 module Discordrb::Voice
   # Signifies to Discord that encryption should be used
-  ENCRYPTED_MODE = 'xsalsa20_poly1305'.freeze
+  # @deprecated Discord now supports multiple encryption options.
+  # TODO: Resolve replacement for this constant.
+  ENCRYPTED_MODE = 'xsalsa20_poly1305'
 
   # Signifies to Discord that no encryption should be used
-  PLAIN_MODE = 'plain'.freeze
+  # @deprecated Discord no longer supports unencrypted voice communication.
+  PLAIN_MODE = 'plain'
+
+  # Encryption modes supported by Discord
+  ENCRYPTION_MODES = %w[xsalsa20_poly1305_lite xsalsa20_poly1305_suffix xsalsa20_poly1305].freeze
 
   # Represents a UDP connection to a voice server. This connection is used to send the actual audio data.
   class VoiceUDP
     # @return [true, false] whether or not UDP communications are encrypted.
+    # @deprecated Discord no longer supports unencrypted voice communication.
     attr_accessor :encrypted
     alias_method :encrypted?, :encrypted
 
     # Sets the secret key used for encryption
     attr_writer :secret_key
 
+    # The UDP encryption mode
+    attr_reader :mode # rubocop:disable Style/BisectedAttrAccessor
+
+    # @!visibility private
+    attr_writer :mode # rubocop:disable Style/BisectedAttrAccessor
+
     # Creates a new UDP connection. Only creates a socket as the discovery reply may come before the data is
     # initialized.
     def initialize
       @socket = UDPSocket.new
+      @encrypted = true
     end
 
     # Initializes the UDP socket with data obtained from opcode 2.
-    # @param endpoint [String] The voice endpoint to connect to.
+    # @param ip [String] The IP address to connect to.
     # @param port [Integer] The port to connect to.
     # @param ssrc [Integer] The Super Secret Relay Code (SSRC). Discord uses this to identify different voice users
     #   on the same endpoint.
-    def connect(endpoint, port, ssrc)
-      @endpoint = endpoint
-      @endpoint = @endpoint[6..-1] if @endpoint.start_with? 'wss://'
-      @endpoint = @endpoint.gsub(':80', '') # The endpoint may contain a port, we don't want that
-      @endpoint = Resolv.getaddress @endpoint
-
+    def connect(ip, port, ssrc)
+      @ip = ip
       @port = port
       @ssrc = ssrc
     end
@@ -63,7 +71,7 @@ module Discordrb::Voice
       # Wait for a UDP message
       message = @socket.recv(70)
       ip = message[4..-3].delete("\0")
-      port = message[-2..-1].to_i
+      port = message[-2..-1].unpack1('n')
       [ip, port]
     end
 
@@ -76,10 +84,15 @@ module Discordrb::Voice
       # Header of the audio packet
       header = [0x80, 0x78, sequence, time, @ssrc].pack('CCnNN')
 
-      # Encrypt data, if necessary
-      buf = encrypt_audio(header, buf) if encrypted?
+      nonce = generate_nonce(header)
+      buf = encrypt_audio(buf, nonce)
 
-      send_packet(header + buf)
+      data = header + buf
+
+      # xsalsa20_poly1305 does not require an appended nonce
+      data += nonce unless @mode == 'xsalsa20_poly1305'
+
+      send_packet(data)
     end
 
     # Sends the UDP discovery packet with the internally stored SSRC. Discord will send a reply afterwards which can
@@ -94,22 +107,47 @@ module Discordrb::Voice
 
     private
 
-    # Encrypts audio data using RbNaCl
-    # @param header [String] The header of the packet, to be used as the nonce
+    # Encrypts audio data using libsodium
     # @param buf [String] The encoded audio data to be encrypted
+    # @param nonce [String] The nonce to be used to encrypt the data
     # @return [String] the audio data, encrypted
-    def encrypt_audio(header, buf)
+    def encrypt_audio(buf, nonce)
       raise 'No secret key found, despite encryption being enabled!' unless @secret_key
-      box = RbNaCl::SecretBox.new(@secret_key)
 
-      # The nonce is the header of the voice packet with 12 null bytes appended
-      nonce = header + ([0] * 12).pack('C*')
+      secret_box = Discordrb::Voice::SecretBox.new(@secret_key)
 
-      box.encrypt(nonce, buf)
+      # Nonces must be 24 bytes in length. We right pad with null bytes for poly1305 and poly1305_lite
+      secret_box.box(nonce.ljust(24, "\0"), buf)
     end
 
     def send_packet(packet)
-      @socket.send(packet, 0, @endpoint, @port)
+      @socket.send(packet, 0, @ip, @port)
+    end
+
+    # @param header [String] The header of the packet, to be used as the nonce
+    # @return [String]
+    # @note
+    #   The nonce generated depends on the encryption mode.
+    #   In xsalsa20_poly1305 the nonce is the header plus twelve null bytes for padding.
+    #   In xsalsa20_poly1305_suffix, the nonce is 24 random bytes
+    #   In xsalsa20_poly1305_lite, the nonce is an incremental 4 byte int.
+    def generate_nonce(header)
+      case @mode
+      when 'xsalsa20_poly1305'
+        header
+      when 'xsalsa20_poly1305_suffix'
+        Random.urandom(24)
+      when 'xsalsa20_poly1305_lite'
+        case @lite_nonce
+        when nil, 0xff_ff_ff_ff
+          @lite_nonce = 0
+        else
+          @lite_nonce += 1
+        end
+        [@lite_nonce].pack('N')
+      else
+        raise "`#{@mode}' is not a supported encryption mode"
+      end
     end
   end
 
@@ -117,6 +155,9 @@ module Discordrb::Voice
   # used to manage general data about the connection, such as sending the speaking packet, which determines the green
   # circle around users on Discord, and obtaining UDP connection info.
   class VoiceWS
+    # The version of the voice gateway that's supposed to be used.
+    VOICE_GATEWAY_VERSION = 4
+
     # @return [VoiceUDP] the UDP voice connection over which the actual audio data is sent.
     attr_reader :udp
 
@@ -127,14 +168,14 @@ module Discordrb::Voice
     # @param session [String] The voice session ID Discord sends over the regular websocket
     # @param endpoint [String] The endpoint URL to connect to
     def initialize(channel, bot, token, session, endpoint)
-      raise 'RbNaCl is unavailable - unable to create voice bot! Please read https://github.com/meew0/discordrb/wiki/Installing-libsodium' unless RBNACL_AVAILABLE
+      raise 'libsodium is unavailable - unable to create voice bot! Please read https://github.com/shardlab/discordrb/wiki/Installing-libsodium' unless LIBSODIUM_AVAILABLE
 
       @channel = channel
       @bot = bot
       @token = token
       @session = session
 
-      @endpoint = endpoint.gsub(':80', '')
+      @endpoint = endpoint.split(':').first
 
       @udp = VoiceUDP.new
     end
@@ -181,12 +222,12 @@ module Discordrb::Voice
 
       @client.send({
         op: 3,
-        d: nil
+        d: millis
       }.to_json)
     end
 
     # Send a speaking packet (op 5). This determines the green circle around the avatar in the voice channel
-    # @param value [true, false] Whether or not the bot should be speaking
+    # @param value [true, false, Integer] Whether or not the bot should be speaking, can also be a bitmask denoting audio type.
     def send_speaking(value)
       @bot.debug("Speaking: #{value}")
       @client.send({
@@ -218,18 +259,23 @@ module Discordrb::Voice
         # Opcode 2 contains data to initialize the UDP connection
         @ws_data = packet['d']
 
-        @heartbeat_interval = @ws_data['heartbeat_interval']
         @ssrc = @ws_data['ssrc']
         @port = @ws_data['port']
-        @udp_mode = mode
 
-        @udp.connect(@endpoint, @port, @ssrc)
+        @udp_mode = (ENCRYPTION_MODES & @ws_data['modes']).first
+
+        @udp.connect(@ws_data['ip'], @port, @ssrc)
         @udp.send_discovery
       when 4
         # Opcode 4 sends the secret key used for encryption
         @ws_data = packet['d']
+
         @ready = true
         @udp.secret_key = @ws_data['secret_key'].pack('C*')
+        @udp.mode = @ws_data['mode']
+      when 8
+        # Opcode 8 contains the heartbeat interval.
+        @heartbeat_interval = packet['d']['heartbeat_interval']
       end
     end
 
@@ -276,11 +322,6 @@ module Discordrb::Voice
 
     private
 
-    # @return [String] the mode string that signifies whether encryption should be used or not
-    def mode
-      @udp.encrypted? ? ENCRYPTED_MODE : PLAIN_MODE
-    end
-
     def heartbeat_loop
       @heartbeat_running = true
       while @heartbeat_running
@@ -295,7 +336,7 @@ module Discordrb::Voice
     end
 
     def init_ws
-      host = "wss://#{@endpoint}:443"
+      host = "wss://#{@endpoint}:443/?v=#{VOICE_GATEWAY_VERSION}"
       @bot.debug("Connecting VWS to host: #{host}")
 
       # Connect the WS