Operational Notes

This document covers runtime behaviors, limits, and maintenance considerations for operating a cg.cx instance.

Telegram API Rate Limits

The bot does not implement explicit request throttling for Telegram API calls. It relies on Teloxide's default behavior and the Telegram Bot API flood-control semantics.

Forwarding / posting messages — Subject to standard Bot API rate limits (roughly ~30 messages/second in groups, lower in smaller chats). Rapid approval of many submissions may trigger RetryAfter errors; the bot currently does not back off explicitly.
Banning / restricting members — banChatMember and restrictChatMember have aggressive per-chat limits. Issuing many punishment commands in quick succession may result in temporary API rejections.
Message deletion — deleteMessage is limited to ~300 deletions per chat per 24 hours for bots. The automatic service-message cleanup (see below) contributes to this budget.

Operational recommendation: If running in high-traffic groups, monitor bot logs for RetryAfter or 429 errors and consider spacing out bulk operations.

System Message Deletion Limits

The bot automatically deletes service messages in groups and channels to reduce noise. In handle_message_inner, the following 17 message types are detected and deleted in non-private chats:

new_chat_members
left_chat_member
new_chat_title
new_chat_photo
delete_chat_photo
group_chat_created
supergroup_chat_created
channel_chat_created
migrate_to_chat_id
migrate_from_chat_id
pinned_message
video_chat_scheduled
video_chat_started
video_chat_ended
video_chat_participants_invited
message_auto_delete_timer_changed
proximity_alert_triggered

Limitations:

Some service messages (e.g., channel_chat_created) cannot be deleted by bots and will silently fail. The code handles this with let _ = bot.delete_message(...).await;.
Deletion failures do not crash the bot or block subsequent message processing.

Storage & Directories

Encrypted content is organized into the following directories (configured in config/default.toml under [storage.paths]):

Directory	Purpose
`data/media`	Image, video, and audio files (`image/`, `video/`, `audio/*`).
`data/documents`	All other file types (archives, binaries, etc.).
`data/text`	Plain text uploads (`text/*` MIME types).
`data/temp`	Temporary files during encryption and upload processing.
`data/logs`	Rolling log output from the bot and server.

Directory creation: Both the bot and server call storage.ensure_dirs().await at startup, creating missing directories automatically.

Rolling Log Files

Both the bot (crates/cgcx-bot/src/main.rs) and the server (crates/cgcx-server/src/main.rs) use tracing-appender for daily log rotation:

tracing_appender::rolling::Builder::new()
    .rotation(tracing_appender::rolling::Rotation::DAILY)
    .filename_prefix(log_prefix)
    .max_log_files(config.logging.max_files)
    .build(log_dir)

Rotation: Daily.
Retention: max_files (default: 7).
Paths:
- Bot: data/logs/cgcx-bot.log (or configured logging.file_path)
- Server: data/logs/cgcx-server.log
Format: Plain text, ANSI colors disabled for file output.
Fallback: If the rolling appender fails to initialize, the process falls back to console-only logging.

SQLite WAL Mode

Every database connection is opened with:

PRAGMA journal_mode = WAL;
PRAGMA foreign_keys = ON;
PRAGMA busy_timeout = 5000;

Implications:

WAL (Write-Ahead Logging) allows readers to proceed without blocking on writers, which is important because the bot and server may share the same SQLite file.
A busy_timeout of 5000 ms reduces "database is locked" errors under concurrent load.
WAL produces companion files (db.sqlite-wal, db.sqlite-shm) in the same directory as the database. These are safe to leave in place during normal operation and are automatically checkpointed by SQLite.

Background Task Intervals

Task	Interval	Description
Punishment expiration	60 seconds	Bot task that queries `punishments` for expired timed bans/mutes and lifts them.
Orphan cleanup	24 hours	Server task that runs `FilePipeline::cleanup_orphans()` to remove files belonging to deleted/blacklisted content (only if `keep_content = false`).

Note: The orphan sweeper skips its first tick on startup to avoid immediate load spikes.

Frontend Chunk Size Warning

The frontend build uses Vite with its default configuration. During npm run build, Vite may emit warnings such as:

(!) Some chunks are larger than 500 kBs after minification.

This is a non-blocking warning; the build completes successfully.
The warning typically comes from large vendor dependencies (e.g., PDF.js, syntax highlighters).
No custom chunkSizeWarningLimit is configured; the default Vite behavior is accepted.

HTTP Rate Limiting (Server)

The Axum server uses tower-governor for per-IP rate limiting:

Route Group	Config Key	Default	Burst
General API (`/api/health`, `/api/content/...`)	`rate_limiting.requests_per_minute`	60	10
Password verification (`POST /api/content/:cxid/verify-password`)	`rate_limiting.password_attempts_per_minute`	4	3

Exceeding the general limit returns 429 Too Many Requests.
The password endpoint has a separate, stricter limit to mitigate brute-force attacks.

5.6 KiB Raw Blame History