discordrb 3.2.1 → 3.3.0

data/CONTRIBUTING.md

@@ -10,4 +10,4 @@ For PRs, please make sure that you tested your code before every push; it's a li
 to a PR because of small avoidable oversights. (Huge bonus points if you're adding specs for your code! This project
 has very few specs in places where it should have more so every added spec is very much appreciated.)
 
-If you have any questions at all, don't be afraid to ask in the [discordrb channel on Discord](https://discord.gg/0SBTUU1wZTWfFQL2).
+If you have any questions at all, don't be afraid to ask in the [discordrb channel on Discord](https://discord.gg/cyK3Hjm).

data/Gemfile

@@ -1,9 +1,5 @@
 source 'https://rubygems.org'
 
-# Test coverage reporting for CodeClimate
-gem 'codeclimate-test-reporter', group: :test, require: nil
-gem 'simplecov', group: :test
-
 # Specify your gem's dependencies in discordrb.gemspec
 gemspec name: 'discordrb'
 gemspec name: 'discordrb-webhooks', development_group: 'webhooks'

data/README.md

@@ -1,10 +1,10 @@
 [![Gem](https://img.shields.io/gem/v/discordrb.svg)](https://rubygems.org/gems/discordrb)
 [![Gem](https://img.shields.io/gem/dt/discordrb.svg)](https://rubygems.org/gems/discordrb)
 [![Build Status](https://travis-ci.org/meew0/discordrb.svg?branch=master)](https://travis-ci.org/meew0/discordrb)
-[![Inline docs](http://inch-ci.org/github/meew0/discordrb.svg?branch=master&style=shields)](http://inch-ci.org/github/meew0/discordrb)
+[![Inline docs](https://inch-ci.org/github/meew0/discordrb.svg?branch=master&style=shields)](https://inch-ci.org/github/meew0/discordrb)
 [![Code Climate](https://codeclimate.com/github/meew0/discordrb/badges/gpa.svg)](https://codeclimate.com/github/meew0/discordrb)
 [![Test Coverage](https://codeclimate.com/github/meew0/discordrb/badges/coverage.svg)](https://codeclimate.com/github/meew0/discordrb/coverage)
-[![Join Discord](https://img.shields.io/badge/discord-join-7289DA.svg)](https://discord.gg/0SBTUU1wZTWfFQL2)
+[![Join Discord](https://img.shields.io/badge/discord-join-7289DA.svg)](https://discord.gg/cyK3Hjm)
 # discordrb
 
 An implementation of the [Discord](https://discordapp.com/) API using Ruby.
@@ -14,16 +14,19 @@ An implementation of the [Discord](https://discordapp.com/) API using Ruby.
 * [Dependencies](https://github.com/meew0/discordrb#dependencies)
 * [Installation](https://github.com/meew0/discordrb#installation)
 * [Usage](https://github.com/meew0/discordrb#usage)
+* [Webhooks Client](https://github.com/meew0/discordrb#webhooks-client)
 * [Support](https://github.com/meew0/discordrb#support)
 * [Development](https://github.com/meew0/discordrb#development), [Contributing](https://github.com/meew0/discordrb#contributing)
 * [License](https://github.com/meew0/discordrb#license)
 
-See also: [Documentation](http://www.rubydoc.info/gems/discordrb), [Tutorials](https://github.com/meew0/discordrb/wiki)
+See also: [Documentation](https://www.rubydoc.info/gems/discordrb), [Tutorials](https://github.com/meew0/discordrb/wiki)
 
 ## Dependencies
 
-* Ruby 2.1+
-* An installed build system for native extensions (on Windows, try the [DevKit](http://rubyinstaller.org/downloads/); installation instructions [here](https://github.com/oneclick/rubyinstaller/wiki/Development-Kit#quick-start) - you only need to do the quick start)
+* Ruby 2.2+
+* An installed build system for native extensions (on Windows for Ruby < 2.4, try the [DevKit](https://rubyinstaller.org/downloads/); installation instructions [here](https://github.com/oneclick/rubyinstaller/wiki/Development-Kit#quick-start) - you only need to do the quick start)
+
+> **Note:** RubyInstaller for Ruby versions 2.4+ will install the DevKit as the last step of the installation.
 
 ### Voice dependencies
 
@@ -36,19 +39,35 @@ In addition to this, if you're on Windows and want to use voice functionality, y
 
 ## Installation
 
-### Linux
+### With Bundler
+
+Using [Bundler](https://bundler.io/#getting-started), you can add discordrb to your Gemfile:
+
+    gem 'discordrb'
+
+And then install via `bundle install`.
+
+Run the [ping example](https://github.com/meew0/discordrb/blob/master/examples/ping.rb) to verify that the installation works (make sure to replace the token and client ID in there with your bots'!):
+
+To run the bot while using bundler:
+
+    bundle exec ruby ping.rb
+
+### With Gem
 
-On Linux, it should be as simple as running:
+Alternatively, while Bundler is the recommended option, you can also install discordrb without it.
+
+#### Linux / macOS
 
     gem install discordrb
 
-### Windows
+#### Windows
 
-On Windows, to install discordrb, run this in a shell **(make sure you have the DevKit installed! See the [Dependencies](https://github.com/meew0/discordrb#dependencies) section)**:
+> **Make sure you have the DevKit installed! See the [Dependencies](https://github.com/meew0/discordrb#dependencies) section)**
 
     gem install discordrb --platform=ruby
 
-Run the [ping example](https://github.com/meew0/discordrb/blob/master/examples/ping.rb) to verify that the installation works (make sure to replace the username and password in there with your own or your bots'!):
+To run the bot:
 
     ruby ping.rb
 
@@ -59,7 +78,23 @@ Run the [ping example](https://github.com/meew0/discordrb/blob/master/examples/p
     ERROR:  Error installing discordrb:
             The 'websocket-driver' native gem requires installed build tools.
 
-You're missing the development kit required to build native extensions. Download the development kit [here](http://rubyinstaller.org/downloads/) (scroll down to "Development Kit", then choose the one for Ruby 2.0 and your system architecture) and extract it somewhere. Open a command prompt in that folder and run:
+You're missing the development kit required to build native extensions.
+
+##### RubyInstaller for ruby 2.4.3-2 and above
+
+RubyInstaller after version 2.3.3 now includes the development kit in the installer. If you do not have the development kit and have installed ruby using RubyInstaller, open a command prompt with administrator privileges and run:
+
+    ridk install
+
+Select option 3, and then run
+
+    ridk enable
+
+To enable the changes
+
+##### RubyInstaller for ruby 2.3.3 and below
+
+Download the development kit [here](https://rubyinstaller.org/downloads/) (scroll down to "Development Kit", then choose the one for Ruby 2.0 and your system architecture) and extract it somewhere. Open a command prompt in that folder and run:
 
     ruby dk.rb init
     ruby dk.rb install
@@ -67,6 +102,9 @@ You're missing the development kit required to build native extensions. Download
 Then reinstall discordrb:
 
     gem uninstall discordrb
+    bundle install
+
+    # Or, if you didn't use bundler:
     gem install discordrb
 
 **If Ruby complains about `ffi_c` not being able to be found:**
@@ -88,7 +126,7 @@ You can make a simple bot like this:
 ```ruby
 require 'discordrb'
 
-bot = Discordrb::Bot.new token: '<token here>', client_id: 168123456789123456
+bot = Discordrb::Bot.new token: '<token here>'
 
 bot.message(with_text: 'Ping!') do |event|
   event.respond 'Pong!'
@@ -99,9 +137,43 @@ bot.run
 
 This bot responds to every "Ping!" with a "Pong!".
 
+See [additional examples here](https://github.com/meew0/discordrb/tree/master/examples).
+
+You can find examples of projects that use discordrb by [searching for the discordrb topic on GitHub](https://github.com/topics/discordrb).
+
+If you've made an open source project on GitHub that uses discordrb, consider adding the `discordrb` topic to your repo!
+
+## Webhooks Client
+
+Also included is a webhooks client, which can be used as a separate gem `discordrb-webhooks`. This special client can be used to form requests to Discord webhook URLs in a high-level manner.
+
+- [`discordrb-webhooks` documentation](https://www.rubydoc.info/gems/discordrb-webhooks)
+- [More information about webhooks](https://support.discordapp.com/hc/en-us/articles/228383668-Intro-to-Webhooks)
+- [Embed visualizer tool](https://leovoel.github.io/embed-visualizer/) - Includes a discordrb code generator for forming embeds
+
+### Usage
+
+```ruby
+require 'discordrb/webhooks'
+
+WEBHOOK_URL = 'https://discordapp.com/api/webhooks/424070213278105610/yByxDncRvHi02mhKQheviQI2erKkfRRwFcEp0MMBfib1ds6ZHN13xhPZNS2-fJo_ApSw'.freeze
+
+client = Discordrb::Webhooks::Client.new(url: WEBHOOK_URL)
+client.execute do |builder|
+  builder.content = 'Hello world!'
+  builder.add_embed do |embed|
+    embed.title = 'Embed title'
+    embed.description = 'Embed description'
+    embed.timestamp = Time.now
+  end
+end
+```
+
+**Note:** The `discordrb` gem relies on `discordrb-webhooks`. If you already have `discordrb` installed, `require 'discordrb/webhooks'` will include all of the `Webhooks` features as well.
+
 ## Support
 
-You can find me (@meew0, ID 66237334693085184) on the unofficial Discord API server - if you have a question, just ask there, I or somebody else will probably answer you: https://discord.gg/0SBTUU1wZTWfFQL2
+You can find me (@meew0, ID 66237334693085184) on the unofficial Discord API server - if you have a question, just ask there, I or somebody else will probably answer you: https://discord.gg/3Trm6FW
 
 ## Development
 
@@ -115,7 +187,6 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/meew0/discordrb.
 
-
 ## License
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -8,8 +8,8 @@ namespace :webhooks do
   Bundler::GemHelper.install_tasks(name: 'discordrb-webhooks')
 end
 
-task build: [:'main:build', :'webhooks:build']
-task release: [:'main:release', :'webhooks:release']
+task build: %i[main:build webhooks:build]
+task release: %i[main:release webhooks:release]
 
 # Make "build" the default task
 task default: :build

data/bin/travis_build_docs.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# Script to build docs for travis usage
+
+set -e
+
+SOURCE_BRANCH=$TRAVIS_BRANCH
+
+if [ -n "$TRAVIS_TAG" ]; then
+    SOURCE_BRANCH=$TRAVIS_TAG
+fi
+
+# Use YARD to build docs
+bundle exec yard
+
+# Move to correct folder
+mkdir -p docs/$SOURCE_BRANCH
+mv doc/* docs/$SOURCE_BRANCH/

data/discordrb-webhooks.gemspec

@@ -1,4 +1,5 @@
 # coding: utf-8
+
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'discordrb/webhooks/version'
@@ -19,7 +20,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'rest-client'
+  spec.add_dependency 'rest-client', '>= 2.1.0.rc1'
 
   spec.required_ruby_version = '>= 2.1.0'
 end

data/discordrb.gemspec

@@ -1,4 +1,5 @@
 # coding: utf-8
+
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'discordrb/version'
@@ -17,21 +18,27 @@ Gem::Specification.new do |spec|
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|examples|lib/discordrb/webhooks)/}) }
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.metadata = {
+    'changelog_uri' => 'https://github.com/meew0/discordrb/blob/master/CHANGELOG.md'
+  }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'rest-client'
+  spec.add_dependency 'rest-client', '>= 2.1.0.rc1'
   spec.add_dependency 'opus-ruby'
   spec.add_dependency 'websocket-client-simple', '>= 0.3.0'
   spec.add_dependency 'rbnacl', '~> 3.4.0' # 24: update
+  spec.add_dependency 'ffi', '>= 1.9.24'
 
-  spec.add_dependency 'discordrb-webhooks', '~> 3.2.0.1'
+  spec.add_dependency 'discordrb-webhooks', '~> 3.3.0'
 
-  spec.required_ruby_version = '>= 2.1.0'
+  spec.required_ruby_version = '>= 2.2.4'
 
   spec.add_development_dependency 'bundler', '~> 1.10'
   spec.add_development_dependency 'rake', '~> 10.0'
-  spec.add_development_dependency 'yard', '~> 0.8.7.6'
+  spec.add_development_dependency 'yard', '~> 0.9.9'
+  spec.add_development_dependency 'redcarpet', '~> 3.4.0' # YARD markdown formatting
   spec.add_development_dependency 'rspec', '~> 3.4.0'
   spec.add_development_dependency 'rspec-prof', '~> 0.0.7'
-  spec.add_development_dependency 'rubocop', '0.45.0'
+  spec.add_development_dependency 'rubocop', '0.49.1'
+  spec.add_development_dependency 'simplecov', '~> 0.16.0'
 end

data/lib/discordrb.rb

@@ -15,7 +15,7 @@ end
 
 # In discordrb, Integer and {String} are monkey-patched to allow for easy resolution of IDs
 class Integer
-  # @return [Integer] The Discord ID represented by this integer, i. e. the integer itself
+  # @return [Integer] The Discord ID represented by this integer, i.e. the integer itself
   def resolve_id
     self
   end
@@ -23,7 +23,7 @@ end
 
 # In discordrb, {Integer} and String are monkey-patched to allow for easy resolution of IDs
 class String
-  # @return [Integer] The Discord ID represented by this string, i. e. the string converted to an integer
+  # @return [Integer] The Discord ID represented by this string, i.e. the string converted to an integer
   def resolve_id
     to_i
   end

data/lib/discordrb/api.rb

@@ -11,6 +11,9 @@ module Discordrb::API
   # The base URL of the Discord REST API.
   APIBASE = 'https://discordapp.com/api/v6'.freeze
 
+  # The URL of Discord's CDN
+  CDN_URL = 'https://cdn.discordapp.com'.freeze
+
   module_function
 
   # @return [String] the currently used API base URL.
@@ -23,6 +26,11 @@ module Discordrb::API
     @api_base = value
   end
 
+  # @return [String] the currently used CDN url
+  def cdn_url
+    @cdn_url || CDN_URL
+  end
+
   # @return [String] the bot name, previously specified using #bot_name=.
   def bot_name
     @bot_name
@@ -33,13 +41,20 @@ module Discordrb::API
     @bot_name = value
   end
 
+  # Changes the rate limit tracing behaviour. If rate limit tracing is on, a full backtrace will be logged on every RL
+  # hit.
+  # @param value [true, false] whether or not to enable rate limit tracing
+  def trace=(value)
+    @trace = value
+  end
+
   # Generate a user agent identifying this requester as discordrb.
   def user_agent
     # This particular string is required by the Discord devs.
     required = "DiscordBot (https://github.com/meew0/discordrb, v#{Discordrb::VERSION})"
     @bot_name ||= ''
 
-    "rest-client/#{RestClient::VERSION} #{RUBY_ENGINE}/#{RUBY_VERSION}p#{RUBY_PATCHLEVEL} discordrb/#{Discordrb::VERSION} #{required} #{@bot_name}"
+    "#{required} rest-client/#{RestClient::VERSION} #{RUBY_ENGINE}/#{RUBY_VERSION}p#{RUBY_PATCHLEVEL} discordrb/#{Discordrb::VERSION} #{@bot_name}"
   end
 
   # Resets all rate limit mutexes
@@ -64,8 +79,11 @@ module Discordrb::API
   # @param attributes [Array] The attributes for the request.
   def raw_request(type, attributes)
     RestClient.send(type, *attributes)
-  rescue RestClient::Forbidden
-    raise Discordrb::Errors::NoPermission, "The bot doesn't have the required permission to do this!"
+  rescue RestClient::Forbidden => e
+    # HACK: for #request, dynamically inject restclient's response into NoPermission - this allows us to ratelimit
+    noprm = Discordrb::Errors::NoPermission.new
+    noprm.define_singleton_method(:_rc_response) { e.response }
+    raise noprm, "The bot doesn't have the required permission to do this!"
   rescue RestClient::BadGateway
     Discordrb::LOGGER.warn('Got a 502 while sending a request! Not a big deal, retrying the request')
     retry
@@ -83,24 +101,32 @@ module Discordrb::API
     begin
       mutex = @mutexes[key] ||= Mutex.new
 
-      # Lock and unlock, i. e. wait for the mutex to unlock and don't do anything with it afterwards
+      # Lock and unlock, i.e. wait for the mutex to unlock and don't do anything with it afterwards
       mutex_wait(mutex)
 
       # If the global mutex happens to be locked right now, wait for that as well.
       mutex_wait(@global_mutex) if @global_mutex.locked?
 
-      response = raw_request(type, attributes)
-
-      if response.headers[:x_ratelimit_remaining] == '0' && !mutex.locked?
-        Discordrb::LOGGER.debug "RL bucket depletion detected! Date: #{response.headers[:date]} Reset: #{response.headers[:x_ratelimit_reset]}"
-
-        now = Time.rfc2822(response.headers[:date])
-        reset = Time.at(response.headers[:x_ratelimit_reset].to_i)
-
-        delta = reset - now
-
-        Discordrb::LOGGER.warn("Locking RL mutex (key: #{key}) for #{delta} seconds preemptively")
-        sync_wait(delta, mutex)
+      response = nil
+      begin
+        response = raw_request(type, attributes)
+      rescue RestClient::Exception => e
+        response = e.response
+        raise e
+      rescue Discordrb::Errors::NoPermission => e
+        if e.respond_to?(:_rc_response)
+          response = e._rc_response
+        else
+          Discordrb::LOGGER.warn("NoPermission doesn't respond_to? _rc_response!")
+        end
+
+        raise e
+      ensure
+        if response
+          handle_preemptive_rl(response.headers, mutex, key) if response.headers[:x_ratelimit_remaining] == '0' && !mutex.locked?
+        else
+          Discordrb::LOGGER.ratelimit('Response was nil before trying to preemptively rate limit!')
+        end
       end
     rescue RestClient::TooManyRequests => e
       # If the 429 is from the global RL, then we have to use the global mutex instead.
@@ -109,7 +135,8 @@ module Discordrb::API
       unless mutex.locked?
         response = JSON.parse(e.response)
         wait_seconds = response['retry_after'].to_i / 1000.0
-        Discordrb::LOGGER.warn("Locking RL mutex (key: #{key}) for #{wait_seconds} seconds due to Discord rate limiting")
+        Discordrb::LOGGER.ratelimit("Locking RL mutex (key: #{key}) for #{wait_seconds} seconds due to Discord rate limiting")
+        trace("429 #{key.join(' ')}")
 
         # Wait the required time synchronized by the mutex (so other incoming requests have to wait) but only do it if
         # the mutex isn't locked already so it will only ever wait once
@@ -122,14 +149,44 @@ module Discordrb::API
     response
   end
 
+  # Handles premeptive ratelimiting by waiting the given mutex by the difference of the Date header to the
+  # X-Ratelimit-Reset header, thus making sure we don't get 429'd in any subsequent requests.
+  def handle_preemptive_rl(headers, mutex, key)
+    Discordrb::LOGGER.ratelimit "RL bucket depletion detected! Date: #{headers[:date]} Reset: #{headers[:x_ratelimit_reset]}"
+
+    now = Time.rfc2822(headers[:date])
+    reset = Time.at(headers[:x_ratelimit_reset].to_i)
+
+    delta = reset - now
+
+    Discordrb::LOGGER.warn("Locking RL mutex (key: #{key}) for #{delta} seconds preemptively")
+    sync_wait(delta, mutex)
+  end
+
+  # Perform rate limit tracing. All this method does is log the current backtrace to the console with the `:ratelimit`
+  # level.
+  # @param reason [String] the reason to include with the backtrace.
+  def trace(reason)
+    unless @trace
+      Discordrb::LOGGER.debug("trace was called with reason #{reason}, but tracing is not enabled")
+      return
+    end
+
+    Discordrb::LOGGER.ratelimit("Trace (#{reason}):")
+
+    caller.each do |str|
+      Discordrb::LOGGER.ratelimit(' ' + str)
+    end
+  end
+
   # Make an icon URL from server and icon IDs
-  def icon_url(server_id, icon_id)
-    "#{api_base}/guilds/#{server_id}/icons/#{icon_id}.jpg"
+  def icon_url(server_id, icon_id, format = 'webp')
+    "#{cdn_url}/icons/#{server_id}/#{icon_id}.#{format}"
   end
 
   # Make an icon URL from application and icon IDs
-  def app_icon_url(app_id, icon_id)
-    "https://cdn.discordapp.com/app-icons/#{app_id}/#{icon_id}.jpg"
+  def app_icon_url(app_id, icon_id, format = 'webp')
+    "#{cdn_url}/app-icons/#{app_id}/#{icon_id}.#{format}"
   end
 
   # Make a widget picture URL from server ID
@@ -138,13 +195,13 @@ module Discordrb::API
   end
 
   # Make a splash URL from server and splash IDs
-  def splash_url(server_id, splash_id)
-    "https://cdn.discordapp.com/splashes/#{server_id}/#{splash_id}.jpg"
+  def splash_url(server_id, splash_id, format = 'webp')
+    "#{cdn_url}/splashes/#{server_id}/#{splash_id}.#{format}"
   end
 
   # Make an emoji icon URL from emoji ID
-  def emoji_icon_url(emoji_id)
-    "https://cdn.discordapp.com/emojis/#{emoji_id}.png"
+  def emoji_icon_url(emoji_id, format = 'webp')
+    "#{cdn_url}/emojis/#{emoji_id}.#{format}"
   end
 
   # Login to the server
@@ -245,6 +302,18 @@ module Discordrb::API
       content_type: :json
     )
   end
+
+  # Get a list of available voice regions
+  def voice_regions(token)
+    request(
+      :voice_regions,
+      nil,
+      :get,
+      "#{api_base}/voice/regions",
+      Authorization: token,
+      content_type: :json
+    )
+  end
 end
 
 Discordrb::API.reset_mutexes