Mediabot v3 — Cleaner Help, Safer Dispatch, and Better Configuration Samples

Suggested forum title

Mediabot v3: safer command dispatch, real internal help, and cleaner sample configuration

Article

This update is mostly about reliability, maintainability, and making Mediabot v3 friendlier for new installs.

The biggest visible change is the new help behavior. Until now, help could easily become stale or misleading because it did not clearly distinguish between internal bot commands and dynamic commands stored in PUBLIC_COMMANDS. That is now fixed.

help <command> now follows a clear order:

1. If the command is an internal Mediabot command, it displays internal help with syntax, level, and description.
2. If the command exists in PUBLIC_COMMANDS, it delegates to showcmd.
3. If the command is unknown, it gives a clean fallback with useful suggestions.

For example:

m help weather

now returns internal command help, such as:

Internal command: weather
Syntax: weather [city]
Level: public
Description: Display weather information.

Dynamic commands remain handled by the database-backed command system:

m help some_dynamic_command

will still use showcmd when that command exists in PUBLIC_COMMANDS, including commands that are currently on hold.

A new internal command listing was also added:

m help internal
m help internals
m help commands

This lists internal bot commands separately from dynamic PUBLIC_COMMANDS. The output is chunked into IRC-safe lines to avoid long NOTICE messages being truncated.

Safety and regression tests

Several new tests were added to protect against future refactoring mistakes.

The test suite now checks that:

• dispatch handlers point to existing functions;
• exported symbols are resolvable at runtime;
• Perl modules do not contain duplicate sub definitions or broken joined use statements;
• internal help entries exist for dispatch-backed commands;
• help correctly handles syntaxes containing pipes, such as <mask|nick> or [timezone|user];
• internal command lists are split safely for IRC;
• sample configuration files document runtime keys actually used by the bot.

This is especially useful after the recent command dispatch cleanup, because it prevents silent regressions such as:

command => sub { missingFunction_ctx($ctx) },

from slipping through unnoticed.

Radio and Icecast cleanup

The radio/Icecast configuration was also cleaned up.

The sample configuration now documents the Icecast keys used by the bot:

RADIO_ICECAST_STATUS_BASE_URL=http://127.0.0.1:8000
RADIO_ICECAST_PUBLIC_BASE_URL=http://example.com:8000
RADIO_ICECAST_TIMEOUT=5
RADIO_ICECAST_PRIMARY_MOUNT=/radio160.mp3

The public code and README no longer fall back to a private deployment URL for Icecast. Local or example values are used instead, which is better for a public repository and safer for new installations.

Sample configuration cleanup

The project now has one official sample configuration file:

mediabot.sample.conf

The duplicate sample under the module directory was removed, and tests were updated so the working tree only knows about the root sample.

The sample configuration was also improved with runtime keys that were already used by the code but not clearly documented:

CHARSET_MODE=utf8mb4
CONN_PASS=

CHARSET_MODE documents the database session charset behavior, and CONN_PASS= makes the optional IRC server password explicit instead of leaving it as a commented-out example.

Why this matters

This update does not try to add flashy new features. It focuses on making the bot more predictable.

The help system is now more honest. The configuration sample is closer to the real runtime behavior. The test suite catches more mistakes before they reach production. And the public repository is cleaner, with fewer private defaults and fewer stale assumptions.

In short: less hidden magic, fewer ghosts in the dispatch table, and a much better foundation for the next round of refactoring.

Suggested commit message

Expecto Dispatchum: teach help its true spells and banish stale config ghosts

Quick test command

After applying the changes, a useful full check is:

cd /home/mediabot/mediabot_v3 || exit 1

find Mediabot -name '*.pm' -print0 | xargs -0 -n1 runuser -u mediabot -- perl -I. -c

runuser -u mediabot -- perl -c mediabot.pl

runuser -u mediabot -- perl t/test_commands.pl

Suggested IRC smoke tests

m help
m help #teuk
m help internal
m help weather
m help ban
m help date
m help <a_dynamic_public_command>
m listeners
m song
m channels