rubycord 1.0.0

data/lib/rubycord/api/webhook.rb

@@ -0,0 +1,138 @@
+# API calls for Webhook object
+module Rubycord::API::Webhook
+  module_function
+
+  # Get a webhook
+  # https://discord.com/developers/docs/resources/webhook#get-webhook
+  def webhook(token, webhook_id)
+    Rubycord::API.request(
+      :webhooks_wid,
+      nil,
+      :get,
+      "#{Rubycord::API.api_base}/webhooks/#{webhook_id}",
+      Authorization: token
+    )
+  end
+
+  # Get a webhook via webhook token
+  # https://discord.com/developers/docs/resources/webhook#get-webhook-with-token
+  def token_webhook(webhook_token, webhook_id)
+    Rubycord::API.request(
+      :webhooks_wid,
+      nil,
+      :get,
+      "#{Rubycord::API.api_base}/webhooks/#{webhook_id}/#{webhook_token}"
+    )
+  end
+
+  # Execute a webhook via token.
+  # https://discord.com/developers/docs/resources/webhook#execute-webhook
+  def token_execute_webhook(webhook_token, webhook_id, wait = false, content = nil, username = nil, avatar_url = nil, tts = nil, file = nil, embeds = nil, allowed_mentions = nil, flags = nil, components = nil)
+    body = {content: content, username: username, avatar_url: avatar_url, tts: tts, embeds: embeds&.map(&:to_hash), allowed_mentions: allowed_mentions, flags: flags, components: components}
+    body = if file
+      {file: file, payload_json: body.to_json}
+    else
+      body.to_json
+    end
+
+    headers = {content_type: :json} unless file
+
+    Rubycord::API.request(
+      :webhooks_wid,
+      webhook_id,
+      :post,
+      "#{Rubycord::API.api_base}/webhooks/#{webhook_id}/#{webhook_token}?wait=#{wait}",
+      body,
+      headers
+    )
+  end
+
+  # Update a webhook
+  # https://discord.com/developers/docs/resources/webhook#modify-webhook
+  def update_webhook(token, webhook_id, data, reason = nil)
+    Rubycord::API.request(
+      :webhooks_wid,
+      webhook_id,
+      :patch,
+      "#{Rubycord::API.api_base}/webhooks/#{webhook_id}",
+      data.to_json,
+      Authorization: token,
+      content_type: :json,
+      "X-Audit-Log-Reason": reason
+    )
+  end
+
+  # Update a webhook via webhook token
+  # https://discord.com/developers/docs/resources/webhook#modify-webhook-with-token
+  def token_update_webhook(webhook_token, webhook_id, data, reason = nil)
+    Rubycord::API.request(
+      :webhooks_wid,
+      webhook_id,
+      :patch,
+      "#{Rubycord::API.api_base}/webhooks/#{webhook_id}/#{webhook_token}",
+      data.to_json,
+      content_type: :json,
+      "X-Audit-Log-Reason": reason
+    )
+  end
+
+  # Deletes a webhook
+  # https://discord.com/developers/docs/resources/webhook#delete-webhook
+  def delete_webhook(token, webhook_id, reason = nil)
+    Rubycord::API.request(
+      :webhooks_wid,
+      webhook_id,
+      :delete,
+      "#{Rubycord::API.api_base}/webhooks/#{webhook_id}",
+      Authorization: token,
+      "X-Audit-Log-Reason": reason
+    )
+  end
+
+  # Deletes a webhook via webhook token
+  # https://discord.com/developers/docs/resources/webhook#delete-webhook-with-token
+  def token_delete_webhook(webhook_token, webhook_id, reason = nil)
+    Rubycord::API.request(
+      :webhooks_wid,
+      webhook_id,
+      :delete,
+      "#{Rubycord::API.api_base}/webhooks/#{webhook_id}/#{webhook_token}",
+      "X-Audit-Log-Reason": reason
+    )
+  end
+
+  # Get a message that was created by the webhook corresponding to the provided token.
+  # https://discord.com/developers/docs/resources/webhook#get-webhook-message
+  def token_get_message(webhook_token, webhook_id, message_id)
+    Rubycord::API.request(
+      :webhooks_wid_messages_mid,
+      webhook_id,
+      :get,
+      "#{Rubycord::API.api_base}/webhooks/#{webhook_id}/#{webhook_token}/messages/#{message_id}"
+    )
+  end
+
+  # Edit a webhook message via webhook token
+  # https://discord.com/developers/docs/resources/webhook#edit-webhook-message
+  def token_edit_message(webhook_token, webhook_id, message_id, content = nil, embeds = nil, allowed_mentions = nil, components = nil)
+    Rubycord::API.request(
+      :webhooks_wid_messages,
+      webhook_id,
+      :patch,
+      "#{Rubycord::API.api_base}/webhooks/#{webhook_id}/#{webhook_token}/messages/#{message_id}",
+      {content: content, embeds: embeds, allowed_mentions: allowed_mentions, components: components}.to_json,
+      content_type: :json
+    )
+  end
+
+  # Delete a webhook message via webhook token.
+  # https://discord.com/developers/docs/resources/webhook#delete-webhook-message
+  def token_delete_message(webhook_token, webhook_id, message_id)
+    Rubycord::API.request(
+      :webhooks_wid_messages,
+      webhook_id,
+      :delete,
+      "#{Rubycord::API.api_base}/webhooks/#{webhook_id}/#{webhook_token}/messages/#{message_id}"
+    )
+  end
+end

data/lib/rubycord/api.rb

@@ -0,0 +1,356 @@
+require "rest-client"
+require "json"
+require "time"
+
+require "rubycord/errors"
+
+# List of methods representing endpoints in Discord's API
+module Rubycord::API
+  # The base URL of the Discord REST API.
+  APIBASE = "https://discord.com/api/v9"
+
+  # The URL of Discord's CDN
+  CDN_URL = "https://cdn.discordapp.com"
+
+  module_function
+
+  # @return [String] the currently used API base URL.
+  def api_base
+    @api_base || APIBASE
+  end
+
+  # Sets the API base URL to something.
+  def api_base=(value)
+    @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
+  end
+
+  # Sets the bot name to something. Used in {.user_agent}. For the bot's username, see {Profile#username=}.
+  def bot_name=(value)
+    @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 rubycord.
+  def user_agent
+    # This particular string is required by the Discord devs.
+    required = "DiscordBot (https://github.com/dakurei-gems/rubycord, v#{Rubycord::VERSION})"
+    @bot_name ||= ""
+
+    "#{required} rest-client/#{RestClient::VERSION} #{RUBY_ENGINE}/#{RUBY_VERSION}p#{RUBY_PATCHLEVEL} rubycord/#{Rubycord::VERSION} #{@bot_name}"
+  end
+
+  # Resets all rate limit mutexes
+  def reset_mutexes
+    @mutexes = {}
+    @global_mutex = Mutex.new
+  end
+
+  # Wait a specified amount of time synchronised with the specified mutex.
+  def sync_wait(time, mutex)
+    mutex.synchronize { sleep time }
+  end
+
+  # Wait for a specified mutex to unlock and do nothing with it afterwards.
+  def mutex_wait(mutex)
+    mutex.lock
+    mutex.unlock
+  end
+
+  # Performs a RestClient request.
+  # @param type [Symbol] The type of HTTP request to use.
+  # @param attributes [Array] The attributes for the request.
+  def raw_request(type, attributes)
+    RestClient.send(type, *attributes)
+  rescue RestClient::Forbidden => e
+    # HACK: for #request, dynamically inject restclient's response into NoPermission - this allows us to rate limit
+    noprm = Rubycord::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
+    Rubycord::LOGGER.warn("Got a 502 while sending a request! Not a big deal, retrying the request")
+    retry
+  end
+
+  # Make an API request, including rate limit handling.
+  def request(key, major_parameter, type, *attributes)
+    # Add a custom user agent
+    attributes.last[:user_agent] = user_agent if attributes.last.is_a? Hash
+
+    # The most recent Discord rate limit requirements require the support of major parameters, where a particular route
+    # and major parameter combination (*not* the HTTP method) uniquely identifies a RL bucket.
+    key = [key, major_parameter].freeze
+
+    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
+      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 = nil
+      begin
+        response = raw_request(type, attributes)
+      rescue RestClient::Exception => e
+        response = e.response
+
+        if response.body && !e.is_a?(RestClient::TooManyRequests)
+          data = JSON.parse(response.body)
+          err_klass = Rubycord::Errors.error_class_for(data["code"] || 0)
+          e = err_klass.new(data["message"], data["errors"])
+
+          Rubycord::LOGGER.error(e.full_message)
+        end
+
+        raise e
+      rescue Rubycord::Errors::NoPermission => e
+        if e.respond_to?(:_rc_response)
+          response = e._rc_response
+        else
+          Rubycord::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
+          Rubycord::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.
+      mutex = @global_mutex if e.response.headers[:x_ratelimit_global] == "true"
+
+      unless mutex.locked?
+        response = JSON.parse(e.response)
+        wait_seconds = response["retry_after"] ? response["retry_after"].to_f : e.response.headers[:retry_after].to_i
+        Rubycord::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
+        sync_wait(wait_seconds, mutex)
+      end
+
+      retry
+    end
+
+    response
+  end
+
+  # Handles pre-emptive rate limiting 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)
+    Rubycord::LOGGER.ratelimit "RL bucket depletion detected! Date: #{headers[:date]} Reset: #{headers[:x_ratelimit_reset]}"
+    delta = headers[:x_ratelimit_reset_after].to_f
+    Rubycord::LOGGER.warn("Locking RL mutex (key: #{key}) for #{delta} seconds pre-emptively")
+    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
+      Rubycord::LOGGER.debug("trace was called with reason #{reason}, but tracing is not enabled")
+      return
+    end
+
+    Rubycord::LOGGER.ratelimit("Trace (#{reason}):")
+
+    caller.each do |str|
+      Rubycord::LOGGER.ratelimit(" #{str}")
+    end
+  end
+
+  # Make an icon URL from server and icon IDs
+  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, format = "webp")
+    "#{cdn_url}/app-icons/#{app_id}/#{icon_id}.#{format}"
+  end
+
+  # Make a widget picture URL from server ID
+  def widget_url(server_id, style = "shield")
+    "#{api_base}/guilds/#{server_id}/widget.png?style=#{style}"
+  end
+
+  # Make a splash URL from server and splash IDs
+  def splash_url(server_id, splash_id, format = "webp")
+    "#{cdn_url}/splashes/#{server_id}/#{splash_id}.#{format}"
+  end
+
+  # Make a banner URL from server and banner IDs
+  def banner_url(server_id, banner_id, format = "webp")
+    "#{cdn_url}/banners/#{server_id}/#{banner_id}.#{format}"
+  end
+
+  # Make an emoji icon URL from emoji ID
+  def emoji_icon_url(emoji_id, format = "webp")
+    "#{cdn_url}/emojis/#{emoji_id}.#{format}"
+  end
+
+  # Make an asset URL from application and asset IDs
+  def asset_url(application_id, asset_id, format = "webp")
+    "#{cdn_url}/app-assets/#{application_id}/#{asset_id}.#{format}"
+  end
+
+  # Make an achievement icon URL from application ID, achievement ID, and icon hash
+  def achievement_icon_url(application_id, achievement_id, icon_hash, format = "webp")
+    "#{cdn_url}/app-assets/#{application_id}/achievements/#{achievement_id}/icons/#{icon_hash}.#{format}"
+  end
+
+  # @param role_id [String, Integer]
+  # @param icon_hash [String]
+  # @param format ['webp', 'png', 'jpeg']
+  # @return [String]
+  def role_icon_url(role_id, icon_hash, format = "webp")
+    "#{cdn_url}/role-icons/#{role_id}/#{icon_hash}.#{format}"
+  end
+
+  # Login to the server
+  def login(email, password)
+    request(
+      :auth_login,
+      nil,
+      :post,
+      "#{api_base}/auth/login",
+      email: email,
+      password: password
+    )
+  end
+
+  # Logout from the server
+  def logout(token)
+    request(
+      :auth_logout,
+      nil,
+      :post,
+      "#{api_base}/auth/logout",
+      nil,
+      Authorization: token
+    )
+  end
+
+  # Create an OAuth application
+  def create_oauth_application(token, name, redirect_uris)
+    request(
+      :oauth2_applications,
+      nil,
+      :post,
+      "#{api_base}/oauth2/applications",
+      {name: name, redirect_uris: redirect_uris}.to_json,
+      Authorization: token,
+      content_type: :json
+    )
+  end
+
+  # Change an OAuth application's properties
+  def update_oauth_application(token, name, redirect_uris, description = "", icon = nil)
+    request(
+      :oauth2_applications,
+      nil,
+      :put,
+      "#{api_base}/oauth2/applications",
+      {name: name, redirect_uris: redirect_uris, description: description, icon: icon}.to_json,
+      Authorization: token,
+      content_type: :json
+    )
+  end
+
+  # Get the bot's OAuth application's information
+  def oauth_application(token)
+    request(
+      :oauth2_applications_me,
+      nil,
+      :get,
+      "#{api_base}/oauth2/applications/@me",
+      Authorization: token
+    )
+  end
+
+  # Acknowledge that a message has been received
+  # The last acknowledged message will be sent in the ready packet,
+  # so this is an easy way to catch up on messages
+  def acknowledge_message(token, channel_id, message_id)
+    request(
+      :channels_cid_messages_mid_ack,
+      nil, # This endpoint is unavailable for bot accounts and thus isn't subject to its rate limit requirements.
+      :post,
+      "#{api_base}/channels/#{channel_id}/messages/#{message_id}/ack",
+      nil,
+      Authorization: token
+    )
+  end
+
+  # Get the gateway to be used
+  def gateway(token)
+    request(
+      :gateway,
+      nil,
+      :get,
+      "#{api_base}/gateway",
+      Authorization: token
+    )
+  end
+
+  # Get the gateway to be used, with additional information for sharding and
+  # session start limits
+  def gateway_bot(token)
+    request(
+      :gateway_bot,
+      nil,
+      :get,
+      "#{api_base}/gateway/bot",
+      Authorization: token
+    )
+  end
+
+  # Validate a token (this request will fail if the token is invalid)
+  def validate_token(token)
+    request(
+      :auth_login,
+      nil,
+      :post,
+      "#{api_base}/auth/login",
+      {}.to_json,
+      Authorization: token,
+      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
+
+Rubycord::API.reset_mutexes

data/lib/rubycord/await.rb

@@ -0,0 +1,49 @@
+module Rubycord
+  # Awaits are a way to register new, temporary event handlers on the fly. Awaits can be
+  # registered using {Bot#add_await}, {User#await}, {Message#await} and {Channel#await}.
+  #
+  # Awaits contain a block that will be called before the await event will be triggered.
+  # If this block returns anything that is not `false` exactly, the await will be deleted.
+  # If no block is present, the await will also be deleted. This is an easy way to make
+  # temporary events that are only temporary under certain conditions.
+  #
+  # Besides the given block, an {Rubycord::Events::AwaitEvent} will also be executed with the key and
+  # the type of the await that was triggered. It's possible to register multiple events
+  # that trigger on the same await.
+  class Await
+    # The key that uniquely identifies this await.
+    # @return [Symbol] The unique key.
+    attr_reader :key
+
+    # The class of the event that this await listens for.
+    # @return [Class] The event class.
+    attr_reader :type
+
+    # The attributes of the event that will be listened for.
+    # @return [Hash] A hash of attributes.
+    attr_reader :attributes
+
+    # Makes a new await. For internal use only.
+    # @!visibility private
+    def initialize(bot, key, type, attributes, block = nil)
+      @bot = bot
+      @key = key
+      @type = type
+      @attributes = attributes
+      @block = block
+    end
+
+    # Checks whether the await can be triggered by the given event, and if it can, execute the block
+    # and return its result along with this await's key.
+    # @param event [Event] An event to check for.
+    # @return [Array] This await's key and whether or not it should be deleted. If there was no match, both are nil.
+    def match(event)
+      dummy_handler = EventContainer.handler_class(@type).new(@attributes, @bot)
+      return [nil, nil] unless event.instance_of?(@type) && dummy_handler.matches?(event)
+
+      should_delete = true if (@block && @block.call(event) != false) || !@block
+
+      [@key, should_delete]
+    end
+  end
+end