A Golang library and framework for the Discord API.
Go to file
Hamza Ali 34a7c3ba2e
gateway: Skip unknown events while reconnecting (#255)
This change skips events that are unknown while the bot reconnects. This
is an event that is particularly rare as it requires unimplemented
events being called in the time before a bot's HELLO -> RESUME events
are called. This change explicitly returns unknown events as a special
time defined in wsutil/op.go and ignores them from reaching gateway/op.go
2021-10-27 20:16:03 -07:00
.github Fixed FUNDING.yml 2020-12-11 16:50:47 -08:00
_example Bot: Added Run(); updated examples 2021-02-23 21:40:44 -08:00
api api: Update SendMessageData.Embed to .Embeds (#248) 2021-08-02 02:05:14 -07:00
bot api: Update SendMessageData.Embed to .Embeds (#248) 2021-08-02 02:05:14 -07:00
discord discord: Add Emoji.IsCustom() & IsUnicode() methods 2021-05-20 22:53:46 -07:00
gateway gateway: Skip unknown events while reconnecting (#255) 2021-10-27 20:16:03 -07:00
internal State: Fix data race between ready and guild create handler 2021-05-29 12:38:22 -07:00
session Bot: Close gracefully by default 2021-01-29 23:25:15 -08:00
state state: Fix voice state removal condition 2021-06-08 02:54:20 -07:00
utils gateway: Skip unknown events while reconnecting (#255) 2021-10-27 20:16:03 -07:00
voice voice: Fix race condition, see #237 2021-06-30 00:19:13 -07:00
.build.yml CI: Properly skip PRs 2021-01-28 13:41:43 -08:00
.editorconfig Minor fixes, undocumented things, and editorconfig 2020-01-19 13:54:16 -08:00
.gitlab-ci.yml CI: Removed perseverance test due to CI time 2021-01-05 13:39:13 -08:00
LICENSE Changed LICENSE. 2020-04-13 19:09:24 -07:00
README.md readme: Fix non-compiling example (#258) 2021-08-08 15:02:11 -07:00
arikawa.go *: Migrated Go Modules to v2 2020-10-28 15:39:59 -07:00
go.mod Moreatomic: Replaced invalid mutex with modified sync.Map impl 2020-12-19 02:35:13 -08:00
go.sum Moreatomic: Replaced invalid mutex with modified sync.Map impl 2020-12-19 02:35:13 -08:00

README.md

arikawa

 Pipeline Status  Coverage         Report Card      Godoc Reference  Examples         Discord Gophers  Hime Arikawa

A Golang library for the Discord API.

Examples

Simple

Simple bot example without any state. All it does is logging messages sent into the console. Run with BOT_TOKEN="TOKEN" go run .. This example only demonstrates the most simple needs; in most cases, bots should use the state or the bot router.

Undeleter

A slightly more complicated example. This bot uses a local state to cache everything, including messages. It detects when someone deletes a message, logging the content into the console.

This example demonstrates the PreHandler feature of the state library. PreHandler calls all handlers that are registered (separately from the session), calling them before the state is updated.

Bare Minimum Bot

The least amount of code for a basic ping-pong bot. It's similar to Serenity's Discord bot example in the README.

package main

import (
	"os"

	"github.com/diamondburned/arikawa/v2/bot"
	"github.com/diamondburned/arikawa/v2/gateway"
)

func main() {
	bot.Run(os.Getenv("DISCORD_TOKEN"), &Bot{},
		func(ctx *bot.Context) error {
			ctx.HasPrefix = bot.NewPrefix("!")
			return nil
		},
	)
}

type Bot struct {
	Ctx *bot.Context
}

func (b *Bot) Ping(*gateway.MessageCreateEvent) (string, error) {
	return "Pong!", nil
}

Advanced Bot

A complex example demonstrating the reflect-based command router that's built-in. The router turns exported struct methods into commands, its arguments into command arguments, and more.

The library is documented in details in the package documentation.

Comparison: Why not discordgo?

Discordgo is great. It's the first library that I used when I was learning Go. Though there are some things that I disagree on. Here are some ways that this library is different:

  • Better package structure: this library divides the Discord library up into smaller packages.
  • Cleaner API/Gateway structure separation: this library separates fields that would only appear in Gateway events, so to not cause confusion.
  • Automatic un-pagination: this library automatically un-paginates endpoints that would otherwise not return everything fully.
  • Flexible underlying abstractions: this library allows plugging in different JSON and Websocket implementations, as well as direct access to the HTTP client.
  • Flexible API abstractions: because packages are separated, the developer could choose to use a lower level package (such as gateway) or a higher level package (such as state).
  • Pre-handlers in the state: this allows the developers to access items from the state storage before they're removed.
  • Pluggable state storages: although only having a default state storage in the library, it is abstracted with an interface, making it possible to implement a custom remote or local state storage.
  • REST-updated state: this library will call the REST API if it can't find things in the state, which is useful for keeping it updated.
  • No code generation: just so the library is a lot easier to maintain.

Testing

The package includes integration tests that require $BOT_TOKEN. To run these tests, do:

export BOT_TOKEN="<BOT_TOKEN>"
go test -tags integration -race ./...