Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cottoncammy/disquark
Reactive JVM wrapper for Discord's REST API
https://github.com/cottoncammy/disquark
discord discord-api java kotlin smallrye-mutiny vertx
Last synced: about 1 month ago
JSON representation
Reactive JVM wrapper for Discord's REST API
- Host: GitHub
- URL: https://github.com/cottoncammy/disquark
- Owner: cottoncammy
- License: mpl-2.0
- Created: 2022-09-19T08:37:47.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2023-07-21T21:07:06.000Z (over 1 year ago)
- Last Synced: 2024-09-27T07:40:55.068Z (about 2 months ago)
- Topics: discord, discord-api, java, kotlin, smallrye-mutiny, vertx
- Language: Java
- Homepage:
- Size: 175 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# DisQuark
[](https://search.maven.org/artifact/io.disquark/disquark-rest)
[](https://www.mozilla.org/en-US/MPL/2.0/)
[![Main branch build]()](https://github.com/cottoncammy/disquark/actions/workflows/ci-main.yml)
DisQuark is a reactive library that enables developers to write fast and performant JVM applications that leverage [Discord's REST API](https://discord.com/developers/docs/intro). Includes support for REST interactions, OAuth2, and responding to interactions and executing webhooks without a bot token.
Powered by [Vert.x](https://vertx.io), [SmallRye Mutiny](https://smallrye.io/smallrye-mutiny), and [Immutables](https://immutables.github.io).
## Installation
Get DisQuark by importing the `io.disquark:disquark-rest` artifact (or the `io.disquark:disquark-rest-kotlin` artifact if you prefer Kotlin) dependency using your preferred build tool.
## Getting Started
The entrypoint to your DisQuark application depends on your use case.
* `DiscordBotClient` - a client tied to a bot account capable of doing anything a bot token allows you to do; can also receive and respond to interactions and execute webhooks using interaction and webhook tokens
* `DiscordOAuth2Client` - a client tied to a user account's OAuth2 token capable of doing anything a bearer token allows you to do; can also receive and respond to interactions and execute webhooks using interaction and webhook tokens
* `DiscordInteractionsClient` - a client capable of receiving and responding to incoming interactions using interaction tokens, not tied to a bot or user account
* `DiscordWebhookClient` - a client capable of executing webhooks using webhook tokens, not tied to a bot or user account
Each client is created using `create` or `builder` static methods.
## Kotlin API
DisQuark provides a (WIP) idiomatic Kotlin API for users who prefer Kotlin. The API provides Kotlin DSLs as alternatives to Java builders and offers extension methods to translate SmallRye Mutiny constructs to Kotlin Coroutine `Flow`s and suspended values. **The Kotlin API is strongly recommended**; the Kotlin DSL syntax is much easier to use to build requests than the Java builder syntax.
Get the Kotlin API by importing the `io.disquark:disquark-rest-kotlin` dependency using your preferred build tool.
## API Status
DisQuark's API should not be considered stable for now.
**DisQuark currently does not support Discord's Gateway or Voice APIs**. Interest in the project will determine whether time is invested to develop corresponding modules. For now, the project's development efforts are focused on improving and maintaining the REST module.
## Examples
### Creating a message
Using `io.disquark:disquark-rest`:
```java
class MyApp {
public static void main(String[] args) {
var botClient = DiscordBotClient.create(Vertx.vertx(), "TOKEN");
botClient.createMessage(new Snowflake(0L))
.withContent("Hello World!")
.subscribe().with(x -> {});
}
}
```
Using `io.disquark:disquark-rest-kotlin`:
```kotlin
suspend fun main() {
val botClient = DiscordBotClient.create(Vertx.vertx(), "TOKEN")
botClient.createMessage(channelId = Snowflake(0L)) {
content = "Hello World!"
}.awaitSuspending()
}
```
### Creating application commands
Using `io.disquark:disquark-rest`:
```java
class MyApp {
public static void main(String[] args) {
var botClient = DiscordBotClient.create(Vertx.vertx(), "TOKEN");
botClient.bulkOverwriteGlobalApplicationCommands(new Snowflake(0L))
.withOverwrites(new GlobalApplicationCommandOverwrite("foo")
.withType(ApplicationCommand.Type.CHAT_INPUT)
.withDescription("Foo commands")
.withOptions(List.of(
new ApplicationCommand.Option(ApplicationCommand.Option.Type.SUB_COMMAND, "bar", "Foo bar command")
.withOptions(List.of(
new ApplicationCommand.Option(ApplicationCommand.Option.Type.STRING, "baz", "Baz option")
.withRequired(true)))))
).subscribe().with(x -> {});
}
}
```
Using `io.disquark:disquark-rest-kotlin`:
```kotlin
suspend fun main() {
val botClient = DiscordBotClient.create(Vertx.vertx(), "TOKEN")
botClient.bulkOverwriteGlobalApplicationCommands(applicationId = Snowflake(0L)) {
chatInputCommand(name = "foo") {
description = "Foo commands"
subcommand(name = "bar", description = "Foo bar command") {
stringOption(name = "baz", description = "Baz option") {
required = true
}
}
}
}.onItem().ignoreAsUni().awaitSuspending()
}
```
### Listening and responding to incoming interactions via HTTP
By default, the web server launched by DisQuark will listen for incoming interactions on `localhost:80`.
Verification of incoming interactions requires the `org.bouncycastle:bcprov-jdk18on` dependency to be installed and for the `BouncyCastleProvider` to be configured as Java's `java.security.Provider` in your application. **Incoming interactions won't have their signatures verified if you don't setup a `BouncyCastleProvider` or change the default `InteractionsValidator`.**
```java
class MyApp {
static {
Security.addProvider(new BouncyCastleProvider());
}
public static void main(String[] args) {
var botClient = DiscordBotClient.create(Vertx.vertx(), "TOKEN");
botClient.on(applicationCommand().name("foo").with(option().type(ApplicationCommand.Option.Type.SUB_COMMAND).name("bar").with(option().name("baz"))))
.onItem().transformToUniAndMerge(interaction -> interaction.respond().withContent("Hello World!"))
.onItem().ignoreAsUni().await().indefinitely();
}
}
```
**It's strongly recommended to use DisQuark with our [Quarkiverse extension](https://github.com/quarkiverse/quarkus-disquark) which minimizes the boilerplate needed to listen and respond to interactions.**
## Client Configuration
DisQuark clients expose several configuration options via `Builder`s accessible from corresponding static `builder` methods.
### Token source
You can configure your client's `AccessTokenSource` to receive your access token asynchronously from an alternative source.
### Rate limit configuration
You can change the `RateLimitStrategy` and the `GlobalRateLimiter` implementation used by DisQuark to avoid being rate limited by Discord's API. There are pre-configured strategies to disable rate limiting logic or to only apply bucket or global rate limiting logic. This can be useful when you are creating a distributed application and want to synchronize rate limiting logic across your DisQuark application instances.
### Requester factory
You can change the `RequesterFactory` used to construct a `Requester` instance that performs the actual request logic to Discord. This is useful if you need to configure the underlying `HttpClient` used by the default `Requester` or if you want to provide a different implementation altogether.
### Logging
Logging in DisQuark is provided by the SLF4J API. Install an implementation using your preferred build tool and configure it appropriately to receive trace- and debug-level logs from your application.
### Interactions client configuration
The following configuration options are available for applications leveraging HTTP interactions:
* `router` - the Vert.x `Router` instance used to setup the interactions handler
* `verifyKey` - your Discord application's public key used to verify incoming interaction signatures, lazily fetched if not provided
* `handleCors` - whether to install a CORS handler to the `Router` to accept incoming `POST` requests from `discord.com`, `true` by default
* `interactionsUrl` - the relative URL to receive interactions from, `/` by default
* `startHttpServer` - whether to construct and start an `HttpServer` when listening for incoming interactions, `true` by default
* `httpServerSupplier` - the factory used to construct the `HttpServer` if `startHttpServer` is enabled
* `validatorFactory` - the factory used to construct an `InteractionsValidator` implementation from the `verifyKey`
## Using Snapshots
DisQuark snapshots are automatically published with the version `999-SNAPSHOT` when commits are pushed to the main branch.
To use the latest snapshot in Maven, add the following repository to your `pom.xml`:
```xml
ossrh
https://s01.oss.sonatype.org/content/repositories/snapshots/
true
```