github.com/dev-kittens/disgd
Package disgd provides Go bindings for the documented Discord API, and allows for a stateful Client using the Session interface, with the option of a configurable caching system or bypass the built-in caching logic all together. Create a Disgord client to get access to the REST API and gateway functionality. In the following example, we listen for new messages and respond with "hello". Session interface: https://pkg.go.dev/github.com/dev-kittens/disgd?tab=doc#Session You don't have to use a callback function, channels are supported too! Never close a channel without removing the handler from Disgord, as it will cause a panic. You can control the lifetime of a handler or injected channel by in injecting a controller: disgd.HandlerCtrl. Since you are the owner of the channel, disgd will never close it for you. Disgord handles sharding for you automatically; when starting the bot, when discord demands you to scale up your shards (during runtime), etc. It also gives you control over the shard setup in case you want to run multiple instances of Disgord (in these cases you must handle scaling yourself as Disgord can not). Sharding is done behind the scenes, so you do not need to worry about any settings. Disgord will simply ask Discord for the recommended amount of shards for your bot on startup. However, to set specific amount of shards you can use the `disgd.ShardConfig` to specify a range of valid shard IDs (starts from 0). starting a bot with exactly 5 shards Running multiple instances each with 1 shard (note each instance must use unique shard ids) Handle scaling options yourself You can inject your own cache implementation. By default a read only LFU implementation is used, this should be sufficient for the average user. But you can overwrite certain methods as well! Say you dislike the implementation for MESSAGE_CREATE events, you can embed the default cache and define your own logic: > Note: if you inject your own cache, remember that the cache is also responsible for initiating the objects. > See disgd.CacheNop Whenever you call a REST method from the Session interface; the cache is always checked first. Upon a cache hit, no REST request is executed and you get the data from the cache in return. However, if this is problematic for you or there exist a bug which gives you bad/outdated data, you can bypass it by using Disgord flags. In addition to disgd.IgnoreCache, as shown above, you can pass in other flags such as: disgd.SortByID, disgd.OrderAscending, etc. You can find these flags in the flag.go file. `disgd_diagnosews` will store all the incoming and outgoing JSON data as files in the directory "diagnose-report/packets". The file format is as follows: unix_clientType_direction_shardID_operationCode_sequenceNumber[_eventName].json `disgdperf` does some low level tweaking that can help boost json unmarshalling and drops json validation from Discord responses/events. Other optimizations might take place as well.
Readme
Go module with context support that handles some of the difficulties from interacting with Discord's bot interface for you; websocket sharding, auto-scaling of websocket connections, advanced caching, helper functions, middlewares and lifetime controllers for event handlers, etc.
Remember to read the docs/code for whatever version of disgd you are using. This README file tries reflects the latest state in the develop branch.
By default DM capabilities are disabled. If you want to activate these, or some, specify their related intent.
client := disgd.New(disgd.Config{
Intents: disgd.IntentDirectMessages | disgd.IntentDirectMessageReactions | disgd.IntentDirectMessageTyping,
})
This project uses Go Modules for dealing with dependencies, remember to activate module support in your IDE
Examples can be found in docs/examples and some open source projects Disgord projects in the wiki
I highly suggest reading the Discord API documentation and the Disgord go doc.
Simply use this github template to create your first new bot!
In short Disgord uses the builder pattern by respecting resources
The Client or Session holds are the relevant methods for interacting with Discord. The API is split by resource, such that Guild related information is found in Client.Guild(guild_id), while user related info is found in Client.User(user_id), gateway interaction is found in Client.Gateway(), the same for Channel, CurrentUser, Emoji, AuditLog, etc.
Cancellation is supported by calling .WithContext(context.Context before the final REST call (.Get(), .Update(), etc.).
every event goes through the cache layer!
For Events, Disgord uses the reactor pattern. This supports both channels and functions. You chose your preference.
If the request is a standard GET request, the cache is always checked first to reduce delay, network traffic and load on the Discord servers. And on responses, regardless of the http method, the data is copied into the cache.
// bypasses local cache
client.CurrentUser().Get(disgd.IgnoreCache)
client.Guild(guildID).GetMembers(disgd.IgnoreCache)
// always checks the local cache first
client.CurrentUser().Get()
client.Guild(guildID).GetMembers()
// with cancellation
deadline, _ := context.WithDeadline(context.Background(), time.Now().Add(2*time.Second))
client.CurrentUser().WithContext(deadline).Get()
Whenever you want the bot to join a voice channel, a websocket and UDP connection is established. So if your bot is currently in 5 voice channels, then you have 5 websocket connections and 5 udp connections open to handle the voice traffic.
The cache tries to represent the Discord state as accurate as it can. Because of this, the cache is immutable by default. Meaning the does not allow you to reference any cached objects directly, and every incoming and outgoing data of the cache is deep copied.
Please see the CONTRIBUTING.md file (Note that it can be useful to read this regardless if you have the time)
You can contribute with pull requests, issues, wiki updates and helping out in the discord servers mentioned above.
To notify about bugs or suggesting enhancements, simply create a issue. The more the better. But be detailed enough that it can be reproduced and please provide logs.
To contribute with code, always create an issue before you open a pull request. This allows automating change logs and releases.
A Special thanks to the following companies for sponsoring this project!
NOTE: To see more examples go to the docs/examples folder. See the GoDoc for a in-depth introduction on the various topics.
1. How do I find my bot token and/or add my bot to a server?
Tutorial here: https://github.com/andersfylling/disgd/wiki/Get-bot-token-and-add-it-to-a-server
2. Is there an alternative Go package?
Yes, it's called DiscordGo (https://github.com/bwmarrin/discordgo). Its purpose is to provide a
minimalistic API wrapper for Discord, it does not handle multiple websocket sharding, scaling, etc.
behind the scenes such as Disgord does. Currently I do not have a comparison chart of Disgord and
DiscordGo. But I do want to create one in the future, for now the biggest difference is that
Disgord does not support self bots.
3. Why make another Discord lib in Go?
I'm trying to take over the world and then become a intergalactic war lord. Have to start somewhere.
4. Will Disgord support self bots?
No. Self bots are againts ToS and could result in account termination (see
https://support.discord.com/hc/en-us/articles/115002192352-Automated-user-accounts-self-bots-).
In addition, self bots aren't a part of the official Discord API, meaning support could change at
any time and Disgord could break unexpectedly if this feature were to be added.
FAQs
Package disgd provides Go bindings for the documented Discord API, and allows for a stateful Client using the Session interface, with the option of a configurable caching system or bypass the built-in caching logic all together. Create a Disgord client to get access to the REST API and gateway functionality. In the following example, we listen for new messages and respond with "hello". Session interface: https://pkg.go.dev/github.com/dev-kittens/disgd?tab=doc#Session You don't have to use a callback function, channels are supported too! Never close a channel without removing the handler from Disgord, as it will cause a panic. You can control the lifetime of a handler or injected channel by in injecting a controller: disgd.HandlerCtrl. Since you are the owner of the channel, disgd will never close it for you. Disgord handles sharding for you automatically; when starting the bot, when discord demands you to scale up your shards (during runtime), etc. It also gives you control over the shard setup in case you want to run multiple instances of Disgord (in these cases you must handle scaling yourself as Disgord can not). Sharding is done behind the scenes, so you do not need to worry about any settings. Disgord will simply ask Discord for the recommended amount of shards for your bot on startup. However, to set specific amount of shards you can use the `disgd.ShardConfig` to specify a range of valid shard IDs (starts from 0). starting a bot with exactly 5 shards Running multiple instances each with 1 shard (note each instance must use unique shard ids) Handle scaling options yourself You can inject your own cache implementation. By default a read only LFU implementation is used, this should be sufficient for the average user. But you can overwrite certain methods as well! Say you dislike the implementation for MESSAGE_CREATE events, you can embed the default cache and define your own logic: > Note: if you inject your own cache, remember that the cache is also responsible for initiating the objects. > See disgd.CacheNop Whenever you call a REST method from the Session interface; the cache is always checked first. Upon a cache hit, no REST request is executed and you get the data from the cache in return. However, if this is problematic for you or there exist a bug which gives you bad/outdated data, you can bypass it by using Disgord flags. In addition to disgd.IgnoreCache, as shown above, you can pass in other flags such as: disgd.SortByID, disgd.OrderAscending, etc. You can find these flags in the flag.go file. `disgd_diagnosews` will store all the incoming and outgoing JSON data as files in the directory "diagnose-report/packets". The file format is as follows: unix_clientType_direction_shardID_operationCode_sequenceNumber[_eventName].json `disgdperf` does some low level tweaking that can help boost json unmarshalling and drops json validation from Discord responses/events. Other optimizations might take place as well.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A hospital in Mobile, Alabama, agreed to a settlement in a landmark ransomware death lawsuit, but is now reportedly reconsidering the agreement and refusing to pay.
Security News
A new report explores how advancements in LLMs are enhancing cyber threats, including polymorphic malware, personalized spearphishing, and the risk of hijacking customer service bots.
Security News
ESLint has approved an RFC that adds support for TypeScript configuration files, which is aimed at improving the developer experience and recognizing changes in the evolving JavaScript ecosystem.