Skip to content

README.md

Latest commit

 

History

History
98 lines (75 loc) · 4.64 KB

README.md

File metadata and controls

98 lines (75 loc) · 4.64 KB

MasterBot

MasterBot is the host repo. It discovers bots under bots/<botName>/, loads each bot config and .env, and can start them either in shared host mode or as one PM2-managed worker per bot. It also generates PM2 config for a separate optional Rust watchdog process that reads PM2 status and reports guardrail allocation.

What it does

  • Loads bot configs from bots/<botName>/index.js
  • Loads bot env files from bots/<botName>/.env
  • Builds one Discord client per bot
  • Loads shared tools from src/functions/tools
  • Loads shared functions from src/functions/handlers
  • Loads shared events from src/events
  • Lets bots override paths, tools, functions, and events through their own config
  • Generates ecosystem.config.js from the bots/ folder and includes the PM2 health monitor process
  • Adds masterbot-watchdog to PM2 only when the release binary exists

Layout

  • index.js - entrypoint
  • src/core/ - bot discovery, client setup, loaders, and database bootstrapping
  • src/worker/ - single-bot worker entry used by PM2
  • src/pm2/ - PM2 client helpers, health monitor, alert sink, and allocation logic
  • src/functions/ - shared tools and handlers
  • src/events/ - shared events
  • bots/<botName>/ - bot-specific config, env, commands, events, and tools
  • ecosystem.config.js - generated PM2 app list
  • rust/masterbot-watchdog/ - optional Rust watchdog binary and workspace files

Bot conventions

  • botConfig.enabled === false prevents that bot from starting
  • bot.env.TOKEN or botConfig.token supplies the login token
  • bot.env.CLIENT_ID or botConfig.clientId supplies the slash command application id
  • botPaths.commands points at the bot command root
  • client.handleCommands() is owned by the host and registers slash commands for the bot
  • Slash command registration is hash-gated and skips REST refreshes when the command definitions have not changed
  • client.lazyFunctions.<name>() loads configured lazy functions on first use and keeps the module cached after that
  • PM2 status readers use an in-memory cache that refreshes every few seconds instead of calling pm2 jlist on each request
  • Startup profiling logs timing marks for the main boot phases when a bot finishes starting
  • BOT_NAME is set per PM2 worker so src/worker/botWorker.js can start exactly one bot
  • The Rust watchdog is optional and only added to PM2 when rust/masterbot-watchdog/target/release/masterbot-watchdog exists

Running

  • npm start - rebuilds ecosystem.config.js and runs pm2-runtime
  • npm run build:ecosystem - rebuilds the generated PM2 config without starting bots
  • npm run watchdog:build - builds the Rust watchdog release binary
  • npm run watchdog - runs the built watchdog in watch mode
  • npm run pm2:start - rebuilds the generated PM2 config and starts PM2 in the background
  • npm run pm2:list, npm run pm2:logs, npm run pm2:monit
  • node index.js - shared host mode, starts all bots in one Node process
  • ./masterbot-linux.sh - installs npm deps, builds the watchdog, regenerates PM2, and starts PM2

Linux Helper

If you want one command to bring the stack up on Linux, use:

./masterbot-linux.sh

It does this in order:

  1. npm install --no-audit --no-fund
  2. cargo build --release --manifest-path rust/masterbot-watchdog/Cargo.toml
  3. npm run build:ecosystem
  4. npm run pm2:start

The watchdog stays optional. If the release binary is not present, ecosystem generation skips the watchdog app and the rest of PM2 still works.

Watchdog Build/Test

Run these in order when you want to verify the hybrid setup:

cargo check --manifest-path rust/masterbot-watchdog/Cargo.toml
cargo build --release --manifest-path rust/masterbot-watchdog/Cargo.toml
./rust/masterbot-watchdog/target/release/masterbot-watchdog --json
npm run build:ecosystem

If you want to exercise the watchdog against a live PM2 daemon, run:

npm run watchdog

If the release binary does not exist, npm run build:ecosystem will skip the watchdog app and keep the rest of PM2 generation working.

Notes

  • PM2 here is process control and restart/memory guardrails, not a hard CPU or cgroup limiter.
  • Each worker uses instances: 1, autorestart: true, per-bot NODE_OPTIONS, and per-bot max_memory_restart.
  • The Rust watchdog uses PM2 status as input and reports guardrail allocation for bots only. It is not a hard resource cap.
  • The generated ecosystem file is only rewritten when the content changes.
  • The host currently supports shared command loading, shared query helpers, startup caches, and per-bot overrides.
  • Bot-specific code should stay inside the bot folder unless it is meant to be shared across every bot.