Discord API for Ruby
3.3.0 brings discordrb up to speed with new features added to Discord's API over the last year. Included is a large number of fixes, optimizations, and library features.
Since there is a lot here, here are highlights of the more notable changes in this release:
We now use SSL certificate validation in our gateway connections, and enforce use of TLSv1.2. If this is an issue for your platform or environment (you get errors related to SSL), please report this with relevant details. You can revert to the old codepath at any time by setting DISCORDRB_SSL_VERIFY_NONE`. This environment variable will be removed in a later release when this proves to be a stable default.
CommandBot now supports a new method of "aliasing" commands with the aliases: keyword. It accepts an array of symbols of alternate command names. Currently this is supported by passing an array of symbols for the command name itself, but this essentially makes "copies" of the command, meaning each alias will show up in your help command. Using aliases instead, the library will recognize that these other names are aliases instead of copying the command. Aliases will be listed when users use !help with the command name, or any of its aliases. For now you may chose to use either style, but you cannot use both. Specifying an array for the command name is now considered deprecated.
There are now two methods of creating "awaits" in discordrb. The new style is a blocking (synchronous) method that uses threads and regular event handlers in the background. The new methods are all named with a bang (!), i.e. user.await!, message.await!, and simply return the raised event. This system should be less confusing that the current asynchronous one. These blocking awaits no longer have an identifying key and only accept the event attributes as an argument. There is also a special reserved attribute called timeout that will stop waiting for an event and return nil if the given number of seconds has passed. Eventually this new system of awaits will replace the old one in a later breaking change. A short example:
bot.message(content: '!test') do |event|
event.respond 'What is your name?'
response = event.message.await!(timeout: 3)
if response
event.respond "Hello, #{response.message.content}!"
else
event.respond 'You took too long!'
end
end
The entire changelog follows, with items that contain breaking changes noted. If you use parts of the library mentioned in a breaking change, you can read the PR and diff for the full details. If you need help with understanding, updating your bot, or have any other questions, please feel free to join us on Discord or open an issue if necessary.
Thank you to all of our contributors!
Server methods to prune members and to get the number of members available for pruning (#315)Channel#default_channel?, for checking if a channel is the default channel of a server (#320, thanks @Reaver01)Server's @everyone role#to_s to be used in Message#react more easily (#342)nsfw property (#380):administrator permissions value is aliased as :administrate (#322)Permissions for easily building permissions bits values (#322)Gateway#send_packet and Gateway#send_raw methods to send custom data payloads to the gatewayicon_url and proxy_icon_url in EmbedAuthor
Member for kicking and banning (#404):rescue argument, to provide a message or callback when an unhandled exception is raised when executing the command (#360)Server properties for verification levels, default message notification levels, and explicit content filter settings (#414, thanks @PixeLInc)nonce is accepted in API::Channel.create_message (#414, thanks @PixeLInc)Bot#listening=, Bot#watching=) (#432, thanks @PixeLInc)#send_embed (#420)Invite now supplies max_age and created_at
Invite now supplies member_count and online_member_count (#454, thanks @Snazzah)Server methods for managing a server's embed (widget) settings (#435)Server and Channel (#415, #477, thanks @omnilord)CommandBot and commands channel whitelist can now be modified after creation (#446, thanks @omnilord)Role's position can now be sorted relative to other roles (#445, thanks @mattantonelli)return keyword inside of commands can be used to return content to Discord (#462, thanks @TrenchFroast)Emoji now supplies animated (#464, thanks @PixeLInc)Server API for retrieving a server's audit logs (#353, thanks @Snazzah)EventContainer methods for server role create, delete, and update events (#494, thanks @Daniel-Worrall)PlayingEvent now returns details (#486, thanks @xTVaser)Role now supplies server (#505, thanks @micke)discordrb-webhooks gem in README.md (#460)#await! (#499)Channel#sort_after, for moving a channel around a server within categories easily (#497)allowed_roles or required_roles (#469, thanks @elfenars)Bot#parse_mention parses Channel mentions (#525, thanks @estherbolik)zlib-stream gateway compression, as well as options to configure the compression mode in Bot#initialize (#527, thanks @oct2pus for additional testing)aliases attribute in commands, for an improved alternative to "command copying" by passing an array to the command name (#524)Channel's slowmode settings (#573, thanks @badBlackShark)Channel#make_invite now accepts an argument to always return a unique invite code (#312)#resolve_id (#313, #328, thanks @Likelakers2)Channel#history and API::Channel.messages now accepts around_id (#314)API::Server.prune_count accepts days (#315)Channel overwrite-related API now returns an Overwrite object (#321):ratelimit logging level and can be configuredclient_id in Bot#initilalize is now optional, and will be cached automatically by the API when needed (#337)Voice::Encoder#encode_file now accepts options for ffmpeg (#341, thanks @oyisre)IDObject can now be compared using more operators (#346, thanks @mattantonelli)parse_self (#350, thanks @Daniel-Worrall)Webhooks::Embed#initialize parses its color/colour argument (#364, thanks @Daniel-Worrall)Cache#find_user can now find individual users if name and discriminator is given (#384)ReactionEvent provides both server and member, if possible (#351, thanks @Daniel-Worrall)default_channel implementation is updated to reflect Discord changes (#382, #534)nil is clarified (#395, thanks @LikeLakers2)Server returned to us from making changes to itCache#server now returns nil if a server is not found instead of raising an exception (#424, thanks @soukouki)Bucket#rate_limited? now accepts an increment value for weighted rate limits (#427, thanks @Lavode)Server#bans now returns Array<ServerBan>, which contains reason data in addition to the user banned (#404)Channel#prune now accepts a block that can be used to filter the messages to be pruned (#421, thanks @snapcase)API::Server.update_channel is now API::Server.update_channel_positions
Channel are refactored (#481, thanks @Daniel-Worrall)module namespaces (#520, thanks @Daniel-Worrall)Bot now logs to LOGGER.info when the bot successfully resumesBot#parse_mention will now return an Emoji object for a mention of an emoji the bot isn't connected to (#473)Bot#run documentation is adjusted to clarify the use of its async argument (#521)Bot#join is renamed to Bot#accept_invite (#521)Embed#colour=/Embed#color= now accepts instances of ColourRGB/ColorRGB (#523)Gateway now performs certificate validation, and enforces use of TLSv1.2. If you experience issues (please report them!), you can return to the old codepath by setting DISCORDRB_SSL_VERIFY_NONE (#528, thanks @cky)voice_state_update, member_update, and server_create (#531)ffi gem is restricted to >= 1.9.24 to prevent a security exploit on Windows, per CVE-2018-1000201 (#544)mentions argument in Create Message API (#420)TrueClass is no longer an alias for :debug logging in Bot#initialize
Errors::MessageTooLong is now raised correctly (#325, thanks @Daniel-Worrall)Reaction related events properly inherit Event (#329, thanks @valeth)@everyone role permissions into consideration (additional work by #357, thanks @mattantonelli)Role#members had a typo preventing it from working (#340)Message#my_reactions now correctly returns Array<Reaction> (#342)TypingEvent is now more accurate (#367, thanks @Snazzah)reason parameter in various API (#372)CommandBot's advanced functionality properly handles empty strings in certain settings (#379, thanks @LikeLakers2)ArgumentError from being raised when processing arg_types (#400, thanks @Daniel-Worrall)Server#create_role correctly accepts a ColourRGB/ColorRGB via #combined
EventContainer#add_handler correctly adds handlers for events that haven't had internal storage created for them yetnil elements, which caused unexpected behavior (#456)User objects are now cached from messages instead of making an API request that may failrest-client is upgraded to >= 2.1.0.rc1, as 2.1.0 is completely broken on Windows with Ruby 2.5 (#478, thanks @Daniel-Worrall and @swarley)EmbedAuthor sets the correct instance variable for proxy_icon_url
ReactionEvent correctly returns the server on which it occurred (#484, thanks @charagarlnad)ServerRoleCreateEvent no longer fails to match when supplying a name attribute (#493, #506, thanks @Daniel-Worrall and @micke)PlayingEvent now correctly returns server (#486, thanks @xTVaser)Server#create_role (#488)execute_command fails, fixing some possible errors that could occur with advanced_functionality (#517, thanks @unleashy)end_with attribute in MessageEventHandler now accepts group-less regular expressions without throwing exceptions (#571, thanks @badBlackShark)PresenceEvent is correctly raised when dispatched (#574)Attachment#initialize correctly sets @id instance variable (#575, thanks @kandayo)This version of discordrb is functionally identical to v1.8.1 but purely uses WSCS as the WebSocket library. This avoids the annoying problems posed by EventMachine relying on external OpenSSL bindings. It's not released on RubyGems because you should know about this when installing it. v2.0.0 will use pure WSCS too so once that is released, you can just update and you don't have to worry about the dependencies.
Install it using gem install discordrb-pure-wscs.gem in the folder where you downloaded it. It still requires the DevKit but no OpenSSL libraries.
Note that while everyone I've given the file to has used it without problems so far, it's by far not tested as well as the main version - if you encounter any bug, just report an issue.