Skip to content

About

Discord bot version of https://hammertime.cyou using slash commands

Topics

Resources

Stars

14 stars

Watchers

1 watching

Forks

Latest commit

 

History

1,885 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

HammerTimeBot Build

Discord bot written in Node.js (using discord.js) for HammerTime

$ pnpm install
$ cp .env.example .env
$ nano .env # Fill in the neccessary environment variables
$ pnpm run build
$ pnpm start

Production runs the container image (ghcr.io/wentthefox/hammertimebot, tagged sha-<commit>) on a Kubernetes cluster managed by Argo CD. Every push to main builds the image, and production is only synced on purpose by running the Deploy workflow (.github/workflows/deploy.yml), see Deploying.

Deploying

Production deploys by itself: every push to main builds an image, Image Updater pins it on the Argo CD Application hammertimebot-prod (webhook and API server, two copies of each) and Argo CD syncs it automatically. The Deploy workflow is a manual "sync now" button: it runs only when started by hand (workflow_dispatch), and makes GitHub send a signed workflow_run webhook to a receiver in the cluster, which asks Argo CD to sync that Application right away with the sha image that Image Updater has pinned. Cluster configuration, such as the environment of the webhook, lives in the cluster's own repository, not here. Registering commands and syncing FAQ/timezone data (sync-commands) runs as an Argo CD PostSync Job, and keeps its state at COMMAND_SYNC_STATE_PATH.

Webhook deployment

src/webhook.ts is the bot's only entry point (pnpm start, the image's command) - it receives interactions over Discord's HTTP Interactions Endpoint rather than a gateway connection, so there's no ShardingManager/gateway mode to speak of. Setting an Interactions Endpoint URL on the application in the Discord Developer Portal is what actually switches interaction delivery over - once set, Discord stops sending INTERACTION_CREATE over the gateway entirely for that application, which is why this needs to be a real HTTP server rather than something that only starts reacting once you're sure: there's no dual-running fallback. Don't set that URL against production until you're confident in the webhook path (test it against a dev subdomain / secondary application first).

One-time setup of a server that is not the cluster (the cluster has its own configuration; pm2.json and deploy/nginx/ are what the former pm2 host used):

  1. deploy/nginx/ → symlink the config into /etc/nginx/sites-available/ and /etc/nginx/sites-enabled/, matching how this project's other nginx configs are laid out on that host.
  2. Expand (or issue) a cert covering the webhook subdomain, e.g. via certbot --expand.
  3. sudo nginx -t && sudo systemctl reload nginx
  4. Set DISCORD_PUBLIC_KEY (the app's Ed25519 public key, from the Developer Portal), WEBHOOK_PATH_SECRET (a long random URL-safe token - see its doc comment in src/env.ts for how to generate one), and optionally WEBHOOK_PORT (defaults to 3939) and WEBHOOK_HOST (defaults to 127.0.0.1, so only the reverse proxy in front of it can reach the endpoint) in the server's .env.
  5. Start the webhook, pnpm start (on the former pm2 host: pm2 startOrReload pm2.json --only HammerTimeBot:Webhook, see Clustering).
  6. Once confident locally/in staging, set the Interactions Endpoint URL to https://<webhook subdomain>/<WEBHOOK_PATH_SECRET> in the Developer Portal - this is the actual cutover step (see above). The endpoint only serves interactions at that secret path. A GET or HEAD of / redirects to ${API_URL}/app (the web app), anything else 404s, so scanner/health-check noise never reaches signature verification.

Clustering

Several copies of the webhook and of the API server can run at once, sharing a port or behind a load balancer, so more requests can be handled at once and one copy can be replaced while the others answer. Nothing is kept in memory between interactions, which is why any copy can take any of them. A copy sends ready once it is listening (announceReady()) and stops on SIGINT/SIGTERM by finishing the requests in flight (shutdownGracefully()).

The former pm2 host ran each as a cluster of two workers (pm2.json: instances, wait_ready, kill_timeout), reloaded one at a time by deploy.conf of the git-deploy toolkit. That setup is kept in the repository but production no longer uses it.

Each copy has its own copy of what the process keeps in memory: for the API server that is a cache of validated keys, and the rate limits, which are counted per copy unless REDIS_URL or REDIS_HOST is set (in packages/api/.env or the environment), then they are shared.

API and MCP server

The same commands are also available outside Discord, as a public REST API and as an MCP server, both served by packages/api at https://api.hammertime.cyou:

  • REST API: one POST endpoint per timestamp command (/at, /in, /snowflake, ...) with the command's options as the JSON body, GET/PATCH /settings for the bot settings, and GET /me for the key in use. Requests follow the settings of the Discord account the key was created for, and are counted like bot commands. The interactive reference is at api.hammertime.cyou, the OpenAPI document at /generated/api-docs.json (and in this repository as docs/openapi/api-docs.json).
  • MCP server: the Streamable HTTP endpoint https://api.hammertime.cyou/mcp, with one tool per command plus settings. It uses the same keys, and only offers the tools a key's permissions allow, so any MCP consumer can use it. It is listed in the MCP Registry as io.github.WentTheFox/hammertime.
  • Keys: created, rotated and revoked on the API page of the website, after logging in with Discord. A key acts as one linked Discord account and has permissions (timestamps:create, settings:read, settings:write), which the page lists together with the endpoints.

The commands, their options and the OpenAPI document are generated from src/commands.json, so the API can not drift from the bot, and the bot can use the API itself for the timestamp commands (COMMANDS_API_URL and COMMANDS_API_KEY in .env, falling back to its own logic when the API does not answer). The users, keys and settings stay in the website's database, the API server only talks to it over HTTP. How it is built, configured and released is in packages/api/README.md.

Translation

New language contributions are welcome! They are handled through Crowdin. If you don't see your language listed, that means it's likely not supported by the Discord client itself, meaning translations would be pointless. If a language is available in Discord's settings but is not listed on Crowdin, or you want to help with the translations of an existing language, please join our Discord server and ask for your language to be added to the project in the #translator-signup channel. You will be given the Translator role and granted access to a language-specific channel for further discussion. This is necessary so that when new translations are needed for any potential new bot features, I have an easy way to reach everyone at once.

English and Hungarian translations have been included, so no translators will be needed for these two languages.

Credits

About

Discord bot version of https://hammertime.cyou using slash commands

Topics

Resources

Stars

14 stars

Watchers

1 watching

Forks

Packages

Used by

Contributors

Languages