Module: Discordrb::API
- Defined in:
- lib/discordrb/api.rb
Overview
List of methods representing endpoints in Discord's API
Defined Under Namespace
Modules: Application, Channel, Interaction, Invite, Server, User, Webhook
Constant Summary collapse
- APIBASE =
The base URL of the Discord REST API.
'https://discord.com/api/v9'
- CDN_URL =
The URL of Discord's CDN
'https://cdn.discordapp.com'
Class Method Summary collapse
-
.achievement_icon_url(application_id, achievement_id, icon_hash, format = 'webp') ⇒ Object
Make an achievement icon URL from application ID, achievement ID, and icon hash.
-
.acknowledge_message(token, channel_id, message_id) ⇒ Object
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.
-
.api_base ⇒ String
The currently used API base URL.
-
.api_base=(value) ⇒ Object
Sets the API base URL to something.
-
.app_icon_url(app_id, icon_id, format = 'webp') ⇒ Object
Make an icon URL from application and icon IDs.
-
.asset_url(application_id, asset_id, format = 'webp') ⇒ Object
Make an asset URL from application and asset IDs.
-
.banner_url(server_id, banner_id, format = 'webp') ⇒ Object
Make a banner URL from server and banner IDs.
-
.bot_name ⇒ String
The bot name, previously specified using API.bot_name=.
-
.bot_name=(value) ⇒ Object
Sets the bot name to something.
-
.cdn_url ⇒ String
The currently used CDN url.
-
.create_oauth_application(token, name, redirect_uris) ⇒ Object
Create an OAuth application.
-
.emoji_icon_url(emoji_id, format = 'webp') ⇒ Object
Make an emoji icon URL from emoji ID.
-
.gateway(token) ⇒ Object
Get the gateway to be used.
-
.gateway_bot(token) ⇒ Object
Get the gateway to be used, with additional information for sharding and session start limits.
-
.handle_preemptive_rl(headers, mutex, key) ⇒ Object
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.
-
.icon_url(server_id, icon_id, format = 'webp') ⇒ Object
Make an icon URL from server and icon IDs.
-
.login(email, password) ⇒ Object
Login to the server.
-
.logout(token) ⇒ Object
Logout from the server.
-
.mutex_wait(mutex) ⇒ Object
Wait for a specified mutex to unlock and do nothing with it afterwards.
-
.oauth_application(token) ⇒ Object
Get the bot's OAuth application's information.
-
.raw_request(type, attributes) ⇒ Object
Performs a RestClient request.
-
.request(key, major_parameter, type, *attributes) ⇒ Object
Make an API request, including rate limit handling.
-
.reset_mutexes ⇒ Object
Resets all rate limit mutexes.
- .role_icon_url(role_id, icon_hash, format = 'webp') ⇒ String
-
.splash_url(server_id, splash_id, format = 'webp') ⇒ Object
Make a splash URL from server and splash IDs.
-
.sync_wait(time, mutex) ⇒ Object
Wait a specified amount of time synchronised with the specified mutex.
-
.trace(reason) ⇒ Object
Perform rate limit tracing.
-
.trace=(value) ⇒ Object
Changes the rate limit tracing behaviour.
-
.update_oauth_application(token, name, redirect_uris, description = '', icon = nil) ⇒ Object
Change an OAuth application's properties.
-
.user_agent ⇒ Object
Generate a user agent identifying this requester as discordrb.
-
.validate_token(token) ⇒ Object
Validate a token (this request will fail if the token is invalid).
-
.voice_regions(token) ⇒ Object
Get a list of available voice regions.
-
.widget_url(server_id, style = 'shield') ⇒ Object
Make a widget picture URL from server ID.
Class Method Details
.achievement_icon_url(application_id, achievement_id, icon_hash, format = 'webp') ⇒ Object
Make an achievement icon URL from application ID, achievement ID, and icon hash
222 223 224 |
# File 'lib/discordrb/api.rb', line 222 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 |
.acknowledge_message(token, channel_id, message_id) ⇒ Object
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
298 299 300 301 302 303 304 305 306 307 |
# File 'lib/discordrb/api.rb', line 298 def (token, channel_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/#{}/ack", nil, Authorization: token ) end |
.api_base ⇒ String
Returns the currently used API base URL.
20 21 22 |
# File 'lib/discordrb/api.rb', line 20 def api_base @api_base || APIBASE end |
.api_base=(value) ⇒ Object
Sets the API base URL to something.
25 26 27 |
# File 'lib/discordrb/api.rb', line 25 def api_base=(value) @api_base = value end |
.app_icon_url(app_id, icon_id, format = 'webp') ⇒ Object
Make an icon URL from application and icon IDs
192 193 194 |
# File 'lib/discordrb/api.rb', line 192 def app_icon_url(app_id, icon_id, format = 'webp') "#{cdn_url}/app-icons/#{app_id}/#{icon_id}.#{format}" end |
.asset_url(application_id, asset_id, format = 'webp') ⇒ Object
Make an asset URL from application and asset IDs
217 218 219 |
# File 'lib/discordrb/api.rb', line 217 def asset_url(application_id, asset_id, format = 'webp') "#{cdn_url}/app-assets/#{application_id}/#{asset_id}.#{format}" end |
.banner_url(server_id, banner_id, format = 'webp') ⇒ Object
Make a banner URL from server and banner IDs
207 208 209 |
# File 'lib/discordrb/api.rb', line 207 def (server_id, , format = 'webp') "#{cdn_url}/banners/#{server_id}/#{}.#{format}" end |
.bot_name ⇒ String
Returns the bot name, previously specified using bot_name=.
35 36 37 |
# File 'lib/discordrb/api.rb', line 35 def bot_name @bot_name end |
.bot_name=(value) ⇒ Object
Sets the bot name to something. Used in user_agent. For the bot's username, see Profile#username=.
40 41 42 |
# File 'lib/discordrb/api.rb', line 40 def bot_name=(value) @bot_name = value end |
.cdn_url ⇒ String
Returns the currently used CDN url.
30 31 32 |
# File 'lib/discordrb/api.rb', line 30 def cdn_url @cdn_url || CDN_URL end |
.create_oauth_application(token, name, redirect_uris) ⇒ Object
Create an OAuth application
259 260 261 262 263 264 265 266 267 268 269 |
# File 'lib/discordrb/api.rb', line 259 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 |
.emoji_icon_url(emoji_id, format = 'webp') ⇒ Object
Make an emoji icon URL from emoji ID
212 213 214 |
# File 'lib/discordrb/api.rb', line 212 def emoji_icon_url(emoji_id, format = 'webp') "#{cdn_url}/emojis/#{emoji_id}.#{format}" end |
.gateway(token) ⇒ Object
Get the gateway to be used
310 311 312 313 314 315 316 317 318 |
# File 'lib/discordrb/api.rb', line 310 def gateway(token) request( :gateway, nil, :get, "#{api_base}/gateway", Authorization: token ) end |
.gateway_bot(token) ⇒ Object
Get the gateway to be used, with additional information for sharding and session start limits
322 323 324 325 326 327 328 329 330 |
# File 'lib/discordrb/api.rb', line 322 def gateway_bot(token) request( :gateway_bot, nil, :get, "#{api_base}/gateway/bot", Authorization: token ) end |
.handle_preemptive_rl(headers, mutex, key) ⇒ Object
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.
163 164 165 166 167 168 |
# File 'lib/discordrb/api.rb', line 163 def handle_preemptive_rl(headers, mutex, key) Discordrb::LOGGER.ratelimit "RL bucket depletion detected! Date: #{headers[:date]} Reset: #{headers[:x_ratelimit_reset]}" delta = headers[:x_ratelimit_reset_after].to_f Discordrb::LOGGER.warn("Locking RL mutex (key: #{key}) for #{delta} seconds pre-emptively") sync_wait(delta, mutex) end |
.icon_url(server_id, icon_id, format = 'webp') ⇒ Object
Make an icon URL from server and icon IDs
187 188 189 |
# File 'lib/discordrb/api.rb', line 187 def icon_url(server_id, icon_id, format = 'webp') "#{cdn_url}/icons/#{server_id}/#{icon_id}.#{format}" end |
.login(email, password) ⇒ Object
Login to the server
235 236 237 238 239 240 241 242 243 244 |
# File 'lib/discordrb/api.rb', line 235 def login(email, password) request( :auth_login, nil, :post, "#{api_base}/auth/login", email: email, password: password ) end |
.logout(token) ⇒ Object
Logout from the server
247 248 249 250 251 252 253 254 255 256 |
# File 'lib/discordrb/api.rb', line 247 def logout(token) request( :auth_logout, nil, :post, "#{api_base}/auth/logout", nil, Authorization: token ) end |
.mutex_wait(mutex) ⇒ Object
Wait for a specified mutex to unlock and do nothing with it afterwards.
72 73 74 75 |
# File 'lib/discordrb/api.rb', line 72 def mutex_wait(mutex) mutex.lock mutex.unlock end |
.oauth_application(token) ⇒ Object
Get the bot's OAuth application's information
285 286 287 288 289 290 291 292 293 |
# File 'lib/discordrb/api.rb', line 285 def oauth_application(token) request( :oauth2_applications_me, nil, :get, "#{api_base}/oauth2/applications/@me", Authorization: token ) end |
.raw_request(type, attributes) ⇒ Object
Performs a RestClient request.
80 81 82 83 84 85 86 87 88 89 90 |
# File 'lib/discordrb/api.rb', line 80 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 = 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 end |
.request(key, major_parameter, type, *attributes) ⇒ Object
Make an API request, including rate limit handling.
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 |
# File 'lib/discordrb/api.rb', line 93 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 = Discordrb::Errors.error_class_for(data['code'] || 0) e = err_klass.new(data['message'], data['errors']) Discordrb::LOGGER.error(e.) end 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. 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 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 sync_wait(wait_seconds, mutex) end retry end response end |
.reset_mutexes ⇒ Object
Resets all rate limit mutexes
61 62 63 64 |
# File 'lib/discordrb/api.rb', line 61 def reset_mutexes @mutexes = {} @global_mutex = Mutex.new end |
.role_icon_url(role_id, icon_hash, format = 'webp') ⇒ String
230 231 232 |
# File 'lib/discordrb/api.rb', line 230 def role_icon_url(role_id, icon_hash, format = 'webp') "#{cdn_url}/role-icons/#{role_id}/#{icon_hash}.#{format}" end |
.splash_url(server_id, splash_id, format = 'webp') ⇒ Object
Make a splash URL from server and splash IDs
202 203 204 |
# File 'lib/discordrb/api.rb', line 202 def splash_url(server_id, splash_id, format = 'webp') "#{cdn_url}/splashes/#{server_id}/#{splash_id}.#{format}" end |
.sync_wait(time, mutex) ⇒ Object
Wait a specified amount of time synchronised with the specified mutex.
67 68 69 |
# File 'lib/discordrb/api.rb', line 67 def sync_wait(time, mutex) mutex.synchronize { sleep time } end |
.trace(reason) ⇒ Object
Perform rate limit tracing. All this method does is log the current backtrace to the console with the :ratelimit
level.
173 174 175 176 177 178 179 180 181 182 183 184 |
# File 'lib/discordrb/api.rb', line 173 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 |
.trace=(value) ⇒ Object
Changes the rate limit tracing behaviour. If rate limit tracing is on, a full backtrace will be logged on every RL hit.
47 48 49 |
# File 'lib/discordrb/api.rb', line 47 def trace=(value) @trace = value end |
.update_oauth_application(token, name, redirect_uris, description = '', icon = nil) ⇒ Object
Change an OAuth application's properties
272 273 274 275 276 277 278 279 280 281 282 |
# File 'lib/discordrb/api.rb', line 272 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 |
.user_agent ⇒ Object
Generate a user agent identifying this requester as discordrb.
52 53 54 55 56 57 58 |
# File 'lib/discordrb/api.rb', line 52 def user_agent # This particular string is required by the Discord devs. required = "DiscordBot (https://github.com/shardlab/discordrb, v#{Discordrb::VERSION})" @bot_name ||= '' "#{required} rest-client/#{RestClient::VERSION} #{RUBY_ENGINE}/#{RUBY_VERSION}p#{RUBY_PATCHLEVEL} discordrb/#{Discordrb::VERSION} #{@bot_name}" end |
.validate_token(token) ⇒ Object
Validate a token (this request will fail if the token is invalid)
333 334 335 336 337 338 339 340 341 342 343 |
# File 'lib/discordrb/api.rb', line 333 def validate_token(token) request( :auth_login, nil, :post, "#{api_base}/auth/login", {}.to_json, Authorization: token, content_type: :json ) end |
.voice_regions(token) ⇒ Object
Get a list of available voice regions
346 347 348 349 350 351 352 353 354 355 |
# File 'lib/discordrb/api.rb', line 346 def voice_regions(token) request( :voice_regions, nil, :get, "#{api_base}/voice/regions", Authorization: token, content_type: :json ) end |
.widget_url(server_id, style = 'shield') ⇒ Object
Make a widget picture URL from server ID
197 198 199 |
# File 'lib/discordrb/api.rb', line 197 def (server_id, style = 'shield') "#{api_base}/guilds/#{server_id}/widget.png?style=#{style}" end |