Welcome to this next major release in Discord4J, a reactive wrapper library for the Discord REST API and real-time Bot Gateway with voice capabilities.
After a year of feedback from users since releasing v3.0, we collected a series of changes to provide and support more use cases and bot configurations. While some of these changes could make their way into following v3.0 minor releases, some involve deeper design work that would have an impact on present releases in terms of binary and behavior changes.
In addition, since Discord is an evolving platform, some of its changes also have impact in the type structure that makes it difficult to implement every change in minor releases. As such, a new major release is the opportunity to include all of these changes and prepare the library structure for future additions more rapidly.
After v3.1.0 releases, only bugfixes will be accepted in the 3.0.x branch.
In order to support more use cases, such as bots that don't use the Gateway to perform some actions, components related to REST API operations are now structurally separated from the Gateway operations.
This means a
DiscordClient no longer gives you access to the Store abstraction for cached entities from the Gateway and is now used to spawn Gateway connections and operating the REST API directly.
Moving forward, the new
GatewayDiscordClient represents the place to fetch and work with Gateway-based entities. You now acquire this instance every time to subscribe to
GatewayBootstrap::login after creating it with
One of the main goals for this release is to lay the groundwork to build distributed bot architectures, a model where bot components are split across multiple processes.
Since many configurations exist, we decided to orient the creation of
GatewayDiscordClient towards "shard groups" that encapsulate caches and events around an arbitrary number of shards. A brand new
GatewayBootstrap API provides creating simple, sharded, monolithic or distributed bots from a single place.
Building a shard group creates a context that aggregates payloads from joining Gateway connections, publishing
Event instances to a single
EventDispatcher, simplifying managing a sharded bot within a process.
For this reason,
Event instances are now aware of the shard they were created by.
Since Gateway updates are processed within a shard group, Stores, our entity cache abstraction, are created once per group. This eases management for single-process sharded bots.
For a more exhaustive list, please look at API changes.
Snowflake class to common module#
We moved the
discord4j.core.object.util.Snowflake type to
discord4j.common.util.Snowflake in order to support all modules across the Discord4J project using it. We feel it is a great abstraction to handle IDs and the primary token of addressing particular Discord entities across the lifetime of your application.
Other types affected by module promotion:
PermissionSet. See Moved types.
An important change in this major update is the change of the
login() method existing in
DiscordClient. We feel that the method makes most sense if it returns a
Mono that completes as login succeeds, instead of logout, and to return a
GatewayDiscordClient handle for the underlying gateway connections.
Previously in v3.0,
Spec consumers were called on assembly time, meaning when a reactive pipeline was declared. This could lead to unexpected code execution so moving forward this was changed in alignment to the expectation of reactive programming where no significant work should happen until you subscribe.
Add support to establish Gateway connections using the Intent system, reducing the inbound event load on your bot. See
Allow customizing the behavior whether a
GatewayDiscordClient should be obtained immediately (similar to v3.0 behavior) or to wait until all shards in the group have connected (Discord "READY" status). Check
Allow changing the
EventDispatcher implementation for event handling. Check the class for builders and factories.
Allow modifying the behavior of the
getXById methods in
GatewayDiscordClient. By default, like in v3.0, if a requested entity is not present in the
Store, a REST API request is made. Since this might not be desired, you can globally change the behavior at
GatewayBootstrap::setEntityRetrievalStrategy or per-call through
All Reactor resources used by Discord4J can be configured, across REST, Gateway and Voice operations. You can now control almost every aspect of Discord4J threading model.
Allow providing a custom
MemberRequestFilter to more explicitly control member requests should be automatically issued. Check
Add methods to directly request for guild members, such as
Allow working with Discord4J without an active Gateway connection. Just create a
DiscordClient and perform calls through the
getXById methods to use REST API directly.
You can also obtain a "REST entity" which wraps a particular entity with its ID (no actual data) and can be used to perform actions without unneeded API requests. These are available directly through one of the entity types supported:
RestClient can be done through
GatewayDiscordClient::rest or any
DiscordClient instance, capable of directly querying the API or creating such REST entities.
A large effort is made into converging our many internal data structures into a more maintainable approach. We decide to use Immutables library to model the Discord domain through
Data classes. All are created with a
Builder that can simplify their usage when interacting with some API, particularly through REST-only entities.
A new abstraction is created to support coordination of Gateway IDENTIFY requests across multiple processes.
A builder to configure how a shard group creates shards is available through
ShardingStrategy and can be set at
GatewayBootstrap. The total shard count can be fixed or used as recommended by Discord, connect specific shards by index, and support a sharding concurrency value or "very large bot sharding system".
Provide a new approach to rate limit which increases throughput without locking structures. This is used across all of Discord4J: REST request queue, REST global rate limiter, Gateway identify limit and Gateway outbound limit.
Bring back a setting from v2 to help deal with connection instability by avoiding detecting zombie connections too early.
Provide new API to customize Voice operations and tasks, in an effort to help integrate it with other tools and frameworks.
Allow customizing the actions that should occur on the entity cache on shard invalidation (non-resumable disconnections)
Allow customizing the actions that should occur when logging out a shard group from the Gateway.
Allow customizing how are
Event instances created from the Gateway updates, potentially enriching or disabling the original handling.
Provide access to the low-level
GatewayClient configuration, allowing extension for custom
GatewayClient factories. This is particularly useful to create distributed bot architectures.
- Login returns
Mono<GatewayDiscordClient>and emits on Gateway connection instead of disconnection.
- Can only be created from factory methods.
- Methods that retrieved entities like
getGuildByIdnow return REST-only entities. If you want to keep the old behavior, create a
GatewayDiscordClientthrough one of the login methods.
- Methods that configured Gateway-specific options were moved to
It is now a
Constructor made private. This class was also made immutable with a rich set of methods to customize more options.
Migrate to reactive API.
getReason now returns Optional. In addition, improved
toString() method and added
getContext(). A related class
CloseStatus also had its
getReason method changed in the same way.
getTrace now returns a List<String>.
getChannel now returns a Mono<TextChannel> instead of Mono<MessageChannel>.
Our own color class to avoid a java.desktop module dependency.
A place to customize many Reactor related options.
A read-only view for the entity cache (store) contents.
New class to group shard operations across JVM boundaries.
New class to group shard index and count.
New class to group sessionId and sequence.
Introduce types related to rest module operations.
Refactored all parameters used by DefaultGatewayClient and extracted them to this new class.
Allow customizing the process in which Gateway payloads are processed and converted into Events.
- New event: ReactionRemoveEmojiEvent
Moved to the discord-json project which is now a dependency of discord4j-common.
RetryOptions, it is now immutable, split from the stateful
Shard information can now be obtained from each
State and resources held by this class were relocated to appropriate components:
- GatewayClient are now located in GatewayClientGroup which is accessible from a GatewayDiscordClient
- RestClient is now the parent class of DiscordClient so methods can be called directly from it
- StateHolder is now available at GatewayResources, accessible from GatewayDiscordClient
- EventDispatcher is accessible from GatewayDiscordClient
- VoiceClient was replaced by a VoiceConnectionRegistry, a far more powerful alternative, accessible from GatewayDiscordClient
GatewayClientFactory was removed as it can be now be used in a functional way within
Removed interface, along with SimpleBucket, as part of the rate limiting implementations rework.
Add resume states to
Add new methods related to chunk index, count, etc.
- No longer possible to set debug mode. Use the reactor-debug-agent or
Hooks.onOperatorDebug()at the start of your application if you wish to retain this capability.