Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

To put it simply, Seabird is an overengineered chat framework. It comes with a broker service, chat backends, and plugins. The goal is to provide a unified interface for linking channels together and interacting with messages.

History

The first version of Seabird was an IRC bot written to learn Go. It has since been rewritten countless times and eventually turned into the project you see today.

What is Seabird?

These days, Seabird is a combination of seabird-core (an RPC service acting as a broker for other components), chat backends (which act as plumbing for hooking up a chat network like Discord), and plugins (which most closely resemble the original bot functionality).

What Should I Look At?

Looking to run a Seabird instance of your own? Check out the Administrator Guide, probably starting with dependencies.

Hoping to contribute or write a plugin? Check out the Developer Guide, starting with the contributing page.

Architecture

At its core, Seabird is an RPC API.

Currently, seabird exports 2 apis: a chat ingestion API, and a plugin API. In general, all components only interact with one of these.

seabird-core

Chat Ingestion API

The chat ingestion API consists of a single endpoint IngestEvents which starts a bidirectional stream. Outgoing messages are "commands" which allow seabird to inform the ingestion process to perform some sort of action, like sending a message or joining a channel. Incoming messages are the ingested events, allowing users of this API to inform seabird of new messages or other events.

Plugin API

The plugin API consists of both an event stream and a number of methods which can be used to cause things to happen.

The streaming endpoint StreamEvents is a firehose of all events occuring across all seabird chat backends.

For callable methods, the SendMessage endpoint is the most commonly used.

Chat Backends

Chat backends interact with the Chat Ingestion API and are used to connect some sort of chat server or network into the Seabird ecosystem.

Plugins

Plugins interact with the Plugin API and are used to provide some sort of additional functionality, similar to what a chat bot would do.

seabird-core

Static Badge GitHub Actions Workflow Status

Configuration

Environment Variables

  • DATABASE_URL (required) - where to place the sqlite database seabird-core will use. This should be in a URL format, so sqlite:tokens.db will be relative to the current directory and sqlite:///path/to/tokens.db will be absolute.
  • SEABIRD_BIND_HOST (optional, defaults to 0.0.0.0:11235) - which host/port to bind the gRPC service to. Note that it will not be tls encrypted, so you may want to put it behind a reverse proxy.
  • RUST_LOG (optional, defaults to info,seabird::server=trace) - this is a common rust environment variable documented here because we set a default. All seabird functionality is exposed under seabird.

seabird-proxy-plugin

Static Badge GitHub Actions Workflow Status

Dependencies

  • seabird-core

Configuration

Environment Variables

Common settings:

  • SEABIRD_HOST (required) - this is the URL of the seabird-core instance. Most users should use https://core.seabird.chat
  • SEABIRD_TOKEN (required) - the seabird token

Proxy-specific settings

  • PROXY_CONFIG_FILE (required) - path to the config file for the plugin
  • RUST_LOG (optional, defaults to info,seabird-proxy-plugin=debug) - this is a common rust environment variable documented here because we set a default. All seabird functionality is exposed under the seabird logger.

Config File

The config file is a list of proxied channels, each containing the following structure:

  • source (required) - the Seabird Channel ID messages should be copied from
  • target (required) - the Seabird Channel ID messages should be copied to
  • user_prefix - a raw string to insert before the username in proxied messages
  • user_suffix - a raw string to insert between the username and text in proxied messages

Note that we use source and target rather than linked_channels or something similar. This is to allow configuring the user_prefix and user_suffix on a per-target-channel basis.

A few helpful user_prefix/user_suffix combinations:

# Discord target
user_prefix: "**"
user_suffix: " (Source Name)**"

# IRC target
user_prefix: "\u0002"
user_suffix: "[source name]\u000f"

# Minecraft target
user_prefix: ""
user_suffix: " (Source Name)"

Runtime Config Updates

In order to force the config to reload, send a SIGHUP to the seabird-proxy-plugin process.

seabird-discord-backend

Static Badge GitHub Actions Workflow Status

Dependencies

  • seabird-core

Configuration

Environment Variables

Common settings:

  • SEABIRD_ID (optional, defaults to seabird) - internal "id" of the backend, used for identification purposes. This must be unique between backends. It may be dropped or ignored in future versions of the seabird APIs.
  • SEABIRD_HOST (required) - this is the URL of the seabird-core instance. Most users should use https://core.seabird.chat
  • SEABIRD_TOKEN (required) - the seabird token

Discord-specific settings

  • DISCORD_TOKEN (required) - Both an application and a bot user must be set up in Discord, and connected to the relevant Discord server by an admin on that server. The correct OAuth URL has been lost to time, but make sure priviledged intents (presence, server members, and message content) are enabled. Note that tokens must be prefixed with Bot in order for Discord to use them as a bot token.
  • DISCORD_COMMAND_PREFIX (optional, defaults to !)
  • DISCORD_CHANNEL_MAP (optional, defaults to empty) - a comma separated list of Discord voice channels, followed by a : and then a channel which should be notified when someone joins.

Known Issues

  • There is not true Discord "command" support, so all commands need to be prefixed by the DISCORD_COMMAND_PREFIX setting.

seabird-irc-backend

Static Badge GitHub Actions Workflow Status

Dependencies

  • seabird-core

Configuration

Environment Variables

Common settings

  • SEABIRD_HOST (required) - this is the URL of the seabird-core instance. Most users should use https://core.seabird.chat
  • SEABIRD_TOKEN (required) - the seabird token

IRC-specific settings

  • IRC_ID (optional, defaults to seabird) - internal "id" of the backend, used for identification purposes. This must be unique between backends. It may be dropped or ignored in future versions of the seabird APIs. This is known as SEABIRD_ID in many other plugins.
  • IRC_HOST (required) - URL of the IRC server to connect to. Supported schemes are irc, ircs, and ircs+unsafe. The port will default to 6667 for irc and 6697 for ircs.
  • IRC_PASS (optional) - password for connecting to the IRC server.
  • IRC_NICKSERV_PASS (optional) - password which is sent to NickServ along with the "identify" command when connected.
  • IRC_CHANNELS (optional) - a comma-separated list of channels to join on connection.
  • IRC_NICK (required) - the IRC nickname of the bot user
  • IRC_USER (optional, defaults to the value of IRC_NICK) - the IRC username reported to the server for the bot.
  • IRC_NAME (optional, defaults to the value of IRC_USER) - the full name reported to the IRC server for the bot user.
  • IRC_DEBUG (optional, defaults to false) - enable internal IRC debug logging.
  • IRC_COMMAND_PREFIX (optional, defaults to !)
  • NICK_CHECK_DURATION (optional, defaults to 1m) - how frequently to try and re-claim the bot user's target nick.

seabird-minecraft-backend

Static Badge

Dependencies

  • seabird-core
  • a Fabric Minecraft server

Configuration

Config File

The config file is a json file located at config/seabird-minecraft-backend.json, with the following properties:

  • seabirdHost (optional, defaults to seabird-core.elwert.cloud)
  • seabirdPort (optional, defaults to 443)
  • seabirdToken (required)
  • backendId (optional, defaults to minecraft)
  • backendChannel (optional, defaults to minecraft)
  • systemDisplayName (optional, defaults to Minecraft)

seabird-adventofcode-plugin

Static Badge GitHub Actions Workflow Status

Dependencies

  • seabird-core

Configuration

Environment Variables

Common settings:

  • SEABIRD_HOST (required) - this is the URL of the seabird-core instance. Most users should use https://core.seabird.chat
  • SEABIRD_TOKEN (required) - the seabird token

Advent of Code-specific settings

  • AOC_SESSION (required) - the session cookie, usually manually obtained from a valid login. This must be updated once monthly to ensure it continues to work.
  • AOC_LEADERBOARD (required) - leaderboard ID from Advent of Code to report updates from. Note that the user the bot is logged in as must be joined to the leaderboard.
  • AOC_CHANNEL (required) - the ID of the seabird channel which notifications should be sent to.
  • TIMESTAMP_FILE (optional, defaults to ./aoc_timestamp.txt) - path to the file which is used to track the last timestamp we've processed from AOC.

Contributors

Here is a list of the contributors who have helped improving Seabird. Big shout-out to them!

If you feel you're missing from this list, feel free to add yourself in a PR.

Acknowledgements

"Here's the documentation" said belak, handing out a sheet of paper with nothing but the word TODO scribbled on it in marker

-- dementeddr

This site contains the comprehensive documentation for Seabird. It is a direct attempt to prove dementeddr wrong and would most likely not exist otherwise.