From f746df3453be6cf25ac923943c3712bec9fd0c81 Mon Sep 17 00:00:00 2001 From: Ferdinand99 Date: Thu, 19 Nov 2026 17:45:42 +0100 Subject: [PATCH 1/4] feat(purge): delete messages older than 14 days too /purge now deletes messages of any age. On Discord, messages younger than 14 days are bulk-deleted and older ones are deleted one at a time at the platform's pace, waiting out 429s. Fluxer's bulk route has no age limit, so everything goes through it there. A long purge shows progress with a Stop button (the person who ran it and server admins), one purge runs per channel at a time, and the final reply reports deleted and failed counts. --- docs/modules/moderation.md | 20 +- src/bot/commands/purge.js | 187 ++++++++-- src/bot/lib/purgeMessages.js | 242 +++++++++++++ test/purgeCommand.test.js | 665 +++++++++++++++++++++++++++++++++++ 4 files changed, 1091 insertions(+), 23 deletions(-) create mode 100644 src/bot/lib/purgeMessages.js create mode 100644 test/purgeCommand.test.js diff --git a/docs/modules/moderation.md b/docs/modules/moderation.md index 56f46370..45e8e4b8 100644 --- a/docs/modules/moderation.md +++ b/docs/modules/moderation.md @@ -48,7 +48,7 @@ table in as `warn` cases.) | `/warn add\|list\|remove\|clear` | Issue and manage warnings. Escalation runs after `add`. | | `/ban`, `/unban` | Ban a member or a user id; `/ban duration:2h` schedules an auto-unban. | | `/kick`, `/timeout`, `/untimeout` | Standard actions; `/timeout` takes `10m`, `2h`, `1d` (max 28d). | -| `/purge` | Delete up to 100 messages younger than 14 days. | +| `/purge [user]` | Delete up to 100 recent messages, of any age (see below). | | `/slowmode` | Per-user rate limit on a channel; `0` disables. | | `/lock`, `/unlock` | Deny/restore @everyone's send permissions on a channel. `/unlock` restores the exact prior overwrite. | | `/lockdown start\|end` | Lock or unlock every text channel at once. | @@ -56,3 +56,21 @@ table in as `warn` cases.) The **Infractions** tab lists every case with edit-reason and soft-delete/restore controls, alongside active bans, channel locks and pending temporary bans. + +### Purging messages + +`/purge` deletes up to 100 messages in the channel it is run in, optionally only those from one +user. It needs Manage Messages for the person who runs it and for Sylo in that channel, and every +purge that deletes something is written to the mod log. + +- **Discord:** messages younger than 14 days are deleted in bulk. Older messages cannot be bulk + deleted, so Sylo deletes them one at a time at the pace Discord allows (about one per second, and + it waits whenever Discord asks it to slow down). While that runs, the reply is updated + ("Deleted 40 of 100...") and has a **Stop** button. Only the person who ran the command and server + admins can press it. +- **Fluxer:** Fluxer's bulk delete has no age limit, so every message is deleted in one go and + there is nothing to wait for. +- Only one purge runs per channel at a time; a second `/purge` there is refused until the first has + finished or been stopped. +- The final reply says how many messages were deleted and how many could not be (for example + already deleted by someone else, or a missing permission). diff --git a/src/bot/commands/purge.js b/src/bot/commands/purge.js index 0b3c4c3f..a2e17805 100644 --- a/src/bot/commands/purge.js +++ b/src/bot/commands/purge.js @@ -1,17 +1,39 @@ -// /purge [user] — bulk-delete recent messages in the current channel. +// /purge [user] — delete recent messages in the current channel, of any age. +// +// Messages younger than 14 days go through the bulk route; older ones (Discord only: its bulk route +// refuses them) are deleted one at a time at a pace the platform accepts. Fluxer's bulk route has no +// age limit, so everything goes through it there. See bot/lib/purgeMessages.js. import { SlashCommandBuilder, PermissionFlagsBits, InteractionContextType, MessageFlags, EmbedBuilder, + ActionRowBuilder, + ButtonBuilder, + ButtonStyle, + ComponentType, } from 'discord.js'; import { MOD_COLOR, replyWithoutGuild } from '../lib/moderation.js'; import { postModLog } from '../lib/modlog.js'; +import { + MAX_RUN_MS, + acquirePurgeLock, + canStopPurge, + purgeMessages, + splitByAge, +} from '../lib/purgeMessages.js'; +import { respondSafely } from '../../lib/discordErrors.js'; +import { guildKey, platformOfGuild } from '../../platform/platformOf.js'; +import { log } from '../../lib/log.js'; + +export const STOP_CUSTOM_ID = 'purge:stop'; +/** Edit the progress reply at most this often (Discord allows 5 webhook edits per 5 s). */ +export const PROGRESS_EDIT_MS = 2500; export const data = new SlashCommandBuilder() .setName('purge') - .setDescription('Delete recent messages in this channel (max 100, younger than 14 days).') + .setDescription('Delete recent messages in this channel, of any age (max 100).') .setContexts(InteractionContextType.Guild) .setDefaultMemberPermissions(PermissionFlagsBits.ManageMessages) .addIntegerOption((o) => @@ -24,6 +46,51 @@ export const data = new SlashCommandBuilder() ) .addUserOption((o) => o.setName('user').setDescription('Only delete messages from this user')); +const plural = (n) => `**${n}** message${n === 1 ? '' : 's'}`; + +/** "2 already gone, 1 missing permission" for the failures that happened. */ +export function describeFailures(failures) { + return [ + failures.gone && `${failures.gone} already gone`, + failures.permission && `${failures.permission} missing permission`, + failures.other && `${failures.other} failed for another reason`, + ] + .filter(Boolean) + .join(', '); +} + +/** The reply during a long purge. */ +export function progressText({ deleted, failed, total }) { + return `🧹 Deleted **${deleted}** of **${total}**…${failed ? ` (${failed} could not be deleted)` : ''}`; +} + +/** The final reply. */ +export function summaryText(result, user) { + const from = user ? ` from ${user.tag}` : ''; + const lines = []; + if (result.stopped) { + lines.push( + `⏹️ Stopped. Deleted ${plural(result.deleted)}${from} of **${result.total}**; **${result.remaining}** left untouched.` + ); + } else { + lines.push(`🧹 Deleted ${plural(result.deleted)}${from}.`); + } + if (result.failed) { + lines.push(`⚠️ ${plural(result.failed)} could not be deleted (${describeFailures(result.failures)}).`); + } + return lines.join('\n'); +} + +function stopRow() { + return new ActionRowBuilder().addComponents( + new ButtonBuilder() + .setCustomId(STOP_CUSTOM_ID) + .setEmoji('🛑') + .setLabel('Stop') + .setStyle(ButtonStyle.Danger) + ); +} + /** @param {import('discord.js').ChatInputCommandInteraction} interaction */ export async function execute(interaction) { if (await replyWithoutGuild(interaction)) return; @@ -40,29 +107,105 @@ export async function execute(interaction) { return; } - await interaction.deferReply({ flags: MessageFlags.Ephemeral }); + // One purge at a time per channel; taken before anything is awaited, so two commands cannot both pass. + const release = acquirePurgeLock(`${guildKey(interaction.guild)}:${channel.id}`, interaction.user.id); + if (!release) { + await interaction.reply({ + content: + '⚠️ A purge is already running in this channel. Wait for it to finish, or ask whoever started it (or a server admin) to press Stop.', + flags: MessageFlags.Ephemeral, + }); + return; + } - let messages = await channel.messages.fetch({ limit: amount }); - if (user) messages = messages.filter((m) => m.author.id === user.id); + let collector = null; + try { + await interaction.deferReply({ flags: MessageFlags.Ephemeral }); - const deleted = await channel.bulkDelete(messages, true); // true = ignore messages older than 14 days + let messages = await channel.messages.fetch({ limit: amount }); + if (user) messages = messages.filter((m) => m.author.id === user.id); + const targets = [...messages.values()]; - await interaction.editReply( - `🧹 Deleted **${deleted.size}** message${deleted.size === 1 ? '' : 's'}${user ? ` from ${user.tag}` : ''}.` + - (deleted.size < messages.size ? ' (some were too old to bulk-delete)' : '') - ); + const platform = platformOfGuild(interaction.guild); + // Only a Discord purge with messages past the bulk limit takes long enough for progress and a Stop button. + const longRun = platform !== 'fluxer' && splitByAge(targets).old.length > 0; + + let stopRequested = false; + let pending = Promise.resolve(); + let lastEdit = 0; + const edit = (payload) => { + pending = pending + .then(() => interaction.editReply(payload)) + .catch((err) => log.warn('bot', '/purge progress update failed:', err?.message ?? err)); + }; + + if (longRun) { + await interaction.editReply({ + content: progressText({ deleted: 0, failed: 0, total: targets.length }), + components: [stopRow()], + }); + const message = await interaction.fetchReply(); + collector = message?.createMessageComponentCollector?.({ + componentType: ComponentType.Button, + time: MAX_RUN_MS + 60_000, + }); + collector?.on('collect', (i) => + respondSafely('bot', '/purge stop', async () => { + const allowed = canStopPurge({ + userId: i.user.id, + starterId: interaction.user.id, + permissions: i.memberPermissions, + administrator: PermissionFlagsBits.Administrator, + }); + if (!allowed) { + await i.reply({ + content: 'Only the person who ran this purge, or a server admin, can stop it.', + flags: MessageFlags.Ephemeral, + }); + return; + } + stopRequested = true; + await i.update({ content: '⏹️ Stopping…', components: [] }); + }) + ); + } + + const result = await purgeMessages(channel, targets, { + platform, + isStopped: () => stopRequested, + onProgress: (p) => { + if (!longRun || stopRequested) return; + const now = Date.now(); + if (now - lastEdit < PROGRESS_EDIT_MS) return; + lastEdit = now; + edit({ content: progressText(p) }); + }, + }); + + collector?.stop('done'); + await pending; + await interaction.editReply({ + content: summaryText(result, user), + ...(longRun ? { components: [] } : {}), + }); - if (deleted.size > 0) { - const embed = new EmbedBuilder() - .setColor(MOD_COLOR) - .setTitle('Messages purged') - .addFields( - { name: 'Channel', value: `${channel}` }, - { name: 'Count', value: String(deleted.size) }, - { name: 'Moderator', value: interaction.user.tag }, - ...(user ? [{ name: 'Filtered to', value: user.tag }] : []) - ) - .setTimestamp(Date.now()); - await postModLog(interaction.guild, embed); + if (result.deleted > 0) { + const embed = new EmbedBuilder() + .setColor(MOD_COLOR) + .setTitle('Messages purged') + .addFields( + { name: 'Channel', value: `${channel}` }, + { name: 'Count', value: String(result.deleted) }, + ...(result.failed ? [{ name: 'Failed', value: String(result.failed) }] : []), + ...(result.stopped ? [{ name: 'Stopped early', value: `${result.remaining} left untouched` }] : []), + { name: 'Moderator', value: interaction.user.tag }, + ...(user ? [{ name: 'Filtered to', value: user.tag }] : []) + ) + .setTimestamp(Date.now()); + await postModLog(interaction.guild, embed); + } + } finally { + collector?.stop('done'); + release(); } } diff --git a/src/bot/lib/purgeMessages.js b/src/bot/lib/purgeMessages.js new file mode 100644 index 00000000..5dee3423 --- /dev/null +++ b/src/bot/lib/purgeMessages.js @@ -0,0 +1,242 @@ +// The engine behind /purge: split a set of messages by age, bulk-delete what the platform +// allows, delete the rest one by one at a pace the platform accepts, and report what happened. +// +// Discord: the bulk route takes 2-100 messages younger than 14 days. Older ones can only be +// deleted one at a time (Discord throttles those to roughly one per second per channel). +// Fluxer: the bulk-delete route (fluxer_api, MessageDeleteService.bulkDeleteMessages) takes +// 1-100 ids of any age, so everything goes through the bulk route. Only the single +// delete is rate limited there (20 per 10 s per channel), and it is the fallback. +// +// Both SDKs wait out a 429 themselves; this loop also catches the 429 that comes out of them +// (retries exhausted) and waits `retry_after` before trying that message again. +import { platformOfGuild } from '../../platform/platformOf.js'; + +const DISCORD_EPOCH = 1420070400000n; +const DAY_MS = 86_400_000; + +/** Discord refuses a bulk delete that contains a message 14 days old; keep a margin for clock skew. */ +export const BULK_MAX_AGE_MS = 14 * DAY_MS - 5 * 60_000; +/** The most messages one /purge touches (the command's `amount` maximum). */ +export const PURGE_CAP = 100; +/** Pause between single deletes, per platform (Discord ~1/s for old messages, Fluxer 20 per 10 s). */ +export const SINGLE_DELETE_PACE_MS = { discord: 1100, fluxer: 550 }; +/** Retries of one message after a 429, and the longest wait we accept for one. */ +export const MAX_RATE_LIMIT_RETRIES = 5; +const MIN_RETRY_MS = 250; +const MAX_RETRY_MS = 60_000; +const DEFAULT_RETRY_MS = 2_000; +/** A purge gives up after this long (a Discord interaction token lives 15 minutes). */ +export const MAX_RUN_MS = 10 * 60_000; + +/** When a message was created, from its snowflake id (falls back to the SDK's timestamp). */ +export function messageTimestamp(message) { + const id = String(message?.id ?? ''); + if (/^\d{15,20}$/.test(id)) return Number((BigInt(id) >> 22n) + DISCORD_EPOCH); + return Number.isFinite(message?.createdTimestamp) ? message.createdTimestamp : null; +} + +/** + * Split messages into those the bulk route accepts (younger than 14 days) and the rest. A message + * whose age is unknown goes to `old`: a single delete always works. + * @returns {{ recent: any[], old: any[] }} + */ +export function splitByAge(messages, now = Date.now()) { + const recent = []; + const old = []; + for (const m of messages) { + const ts = messageTimestamp(m); + (ts != null && now - ts < BULK_MAX_AGE_MS ? recent : old).push(m); + } + return { recent, old }; +} + +// --- error classification -------------------------------------------------------- + +const statusOf = (err) => err?.status ?? err?.statusCode ?? err?.httpStatus ?? err?.rawError?.status; +const codeOf = (err) => err?.code ?? err?.rawError?.code; + +export function isRateLimit(err) { + return statusOf(err) === 429 || err?.name === 'RateLimitError' || err?.code === 'RATE_LIMITED'; +} + +/** How long a 429 asks us to wait, in ms. discord.js: `timeToReset` (ms); the API body and Fluxer: seconds. */ +export function retryAfterMs(err) { + let ms; + if (Number.isFinite(err?.timeToReset)) ms = err.timeToReset; + else { + const secs = [err?.retry_after, err?.retryAfter, err?.rawError?.retry_after, err?.body?.retry_after].find( + (v) => Number.isFinite(v) + ); + ms = secs == null ? DEFAULT_RETRY_MS : secs * 1000; + } + return Math.min(MAX_RETRY_MS, Math.max(MIN_RETRY_MS, Math.ceil(ms))); +} + +/** @returns {'gone' | 'permission' | 'tooOld' | 'other'} */ +export function classifyError(err) { + const status = statusOf(err); + const code = codeOf(err); + if (code === 50034) return 'tooOld'; // Discord: "can only bulk delete messages under 14 days old" + if (code === 10008 || code === 'UNKNOWN_MESSAGE' || status === 404) return 'gone'; + if ( + code === 50013 || + code === 50001 || + code === 'MISSING_PERMISSIONS' || + code === 'MISSING_ACCESS' || + status === 403 + ) + return 'permission'; + return 'other'; +} + +// --- one purge at a time per channel ------------------------------------------------- + +/** @type {Map} */ +const running = new Map(); + +/** + * Take the channel's purge lock. Returns a release function, or null when a purge is already + * running there. `key` is `guildKey(guild):channelId`. + */ +export function acquirePurgeLock(key, userId) { + if (running.has(key)) return null; + const entry = { userId, startedAt: Date.now() }; + running.set(key, entry); + return () => { + if (running.get(key) === entry) running.delete(key); + }; +} + +export const purgeLockHolder = (key) => running.get(key) ?? null; + +/** Test seam. */ +export function _resetPurgeLocks() { + running.clear(); +} + +/** May `member` press Stop on a purge started by `starterId`? The starter and server admins (incl. the owner). */ +export function canStopPurge({ userId, starterId, permissions, administrator }) { + if (userId === starterId) return true; + return Boolean(permissions?.has?.(administrator)); +} + +// --- the purge itself ---------------------------------------------------------------- + +const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); + +/** Test seam: the wait between single deletes. */ +export const purgeTuning = { sleep: delay }; + +const emptyFailures = () => ({ gone: 0, permission: 0, other: 0 }); + +/** + * Delete `messages` from `channel`. + * + * @param {any} channel + * @param {any[]} messages at most PURGE_CAP are touched + * @param {object} [opts] + * @param {'discord'|'fluxer'} [opts.platform] default: the channel's guild's platform + * @param {() => boolean} [opts.isStopped] polled between deletes; true ends the run early + * @param {(p: { deleted: number, failed: number, total: number }) => void} [opts.onProgress] + * @param {(ms: number) => Promise} [opts.sleep] + * @param {() => number} [opts.now] + * @param {number} [opts.paceMs] + * @returns {Promise<{ total: number, deleted: number, failed: number, + * failures: { gone: number, permission: number, other: number }, stopped: boolean, remaining: number, + * bulk: number, single: number }>} + */ +export async function purgeMessages(channel, messages, opts = {}) { + const platform = opts.platform ?? platformOfGuild(channel.guild); + const sleep = opts.sleep ?? purgeTuning.sleep; + const now = opts.now ?? Date.now; + const paceMs = opts.paceMs ?? SINGLE_DELETE_PACE_MS[platform] ?? SINGLE_DELETE_PACE_MS.discord; + const isStopped = opts.isStopped ?? (() => false); + const startedAt = now(); + + const targets = [...messages].slice(0, PURGE_CAP); + const total = targets.length; + const failures = emptyFailures(); + const result = { total, deleted: 0, failed: 0, failures, stopped: false, remaining: 0, bulk: 0, single: 0 }; + + const progress = () => opts.onProgress?.({ deleted: result.deleted, failed: result.failed, total }); + const fail = (kind, n = 1) => { + failures[kind === 'tooOld' ? 'other' : kind] += n; + result.failed += n; + }; + + // Which messages go through the bulk route. Fluxer takes any age and a single id; Discord needs 2-100 + // under 14 days (a lone recent message is deleted like an old one). + let bulkable; + let singles; + if (platform === 'fluxer') { + bulkable = targets; + singles = []; + } else { + const { recent, old } = splitByAge(targets, now()); + bulkable = recent.length >= 2 ? recent : []; + singles = recent.length >= 2 ? old : [...recent, ...old]; + } + + // 1. Bulk. + if (bulkable.length && !isStopped()) { + try { + const done = await channel.bulkDelete(bulkable, platform !== 'fluxer'); + const n = done?.size ?? done?.length ?? bulkable.length; + result.deleted += n; + result.bulk += n; + if (n < bulkable.length) { + // The SDK skipped some (for example a message that just turned 14 days old): delete those singly. + const doneIds = new Set(done instanceof Map ? done.keys() : (done ?? []).map((d) => d?.id ?? d)); + singles = [...bulkable.filter((m) => !doneIds.has(m.id)), ...singles]; + } + } catch (err) { + const kind = classifyError(err); + if (kind === 'permission') fail('permission', bulkable.length); + else singles = [...bulkable, ...singles]; // too old, a hiccup, anything else: one by one, each is classified + } + progress(); + } else if (bulkable.length) { + singles = [...bulkable, ...singles]; + } + + // 2. One by one, paced. + for (let i = 0; i < singles.length; i++) { + if (isStopped()) { + result.stopped = true; + result.remaining = singles.length - i; + break; + } + if (now() - startedAt > MAX_RUN_MS) { + result.stopped = true; + result.remaining = singles.length - i; + break; + } + if (i > 0) await sleep(paceMs); + if (isStopped()) { + result.stopped = true; + result.remaining = singles.length - i; + break; + } + const message = singles[i]; + let attempt = 0; + for (;;) { + try { + await message.delete(); + result.deleted += 1; + result.single += 1; + break; + } catch (err) { + if (isRateLimit(err) && attempt < MAX_RATE_LIMIT_RETRIES && !isStopped()) { + attempt += 1; + await sleep(retryAfterMs(err)); + continue; + } + fail(isRateLimit(err) ? 'other' : classifyError(err)); + break; + } + } + progress(); + } + + return result; +} diff --git a/test/purgeCommand.test.js b/test/purgeCommand.test.js new file mode 100644 index 00000000..587c4211 --- /dev/null +++ b/test/purgeCommand.test.js @@ -0,0 +1,665 @@ +// /purge: messages of any age. Split by age (bulk under 14 days, one by one above), single-delete +// pacing with 429s, the Stop button's permissions, one purge at a time per channel, the Fluxer path +// (its bulk route has no age limit) and the 100-message cap. +import './helpers/tmpDb.js'; +import test, { afterEach, beforeEach } from 'node:test'; +import assert from 'node:assert/strict'; +import { EventEmitter } from 'node:events'; +import { Collection, PermissionFlagsBits } from 'discord.js'; +import * as sdk from '@fluxerjs/core'; +import { Collection as FluxerCollection } from '@fluxerjs/collection'; +import { installFluxerCompat } from '../src/platform/compat.js'; +import { runtime } from '../src/runtime.js'; +import { setModlogChannel } from '../src/db/guildSettings.js'; +import * as purge from '../src/bot/commands/purge.js'; +import { + BULK_MAX_AGE_MS, + PURGE_CAP, + SINGLE_DELETE_PACE_MS, + _resetPurgeLocks, + acquirePurgeLock, + canStopPurge, + classifyError, + purgeMessages, + purgeTuning, + retryAfterMs, + splitByAge, +} from '../src/bot/lib/purgeMessages.js'; + +const DAY = 86_400_000; +const EPOCH = 1420070400000n; +let seq = 0; + +/** A message with a real snowflake id created `ageMs` ago. */ +function msg(ageMs, over = {}) { + const ts = BigInt(Date.now() - ageMs); + const id = String(((ts - EPOCH) << 22n) + BigInt(++seq)); + return { id, author: { id: 'a1' }, delete: async () => {}, ...over }; +} +const recent = (n, over) => Array.from({ length: n }, () => msg(DAY, over)); +const old = (n, over) => Array.from({ length: n }, () => msg(20 * DAY, over)); + +function discordChannel(over = {}) { + const calls = []; + return { + calls, + guild: { client: {} }, + async bulkDelete(list, filterOld) { + const arr = [...(list instanceof Map ? list.values() : list)]; + calls.push({ ids: arr.map((m) => m.id), filterOld }); + return new Collection(arr.map((m) => [m.id, m])); + }, + ...over, + }; +} + +const noSleep = { sleep: async () => {} }; +const recordSleeps = () => { + const waits = []; + return { waits, sleep: async (ms) => void waits.push(ms) }; +}; + +beforeEach(() => _resetPurgeLocks()); + +// --- splitting by age -------------------------------------------------------------------------- + +test('splitByAge: the 14-day cut is computed from the snowflake timestamp', () => { + const now = Date.now(); + const young = msg(13 * DAY); + const edge = msg(14 * DAY - 60_000); // inside the 5-minute safety margin: counts as old + const past = msg(15 * DAY); + // The SDK's own timestamp is ignored when the id is a snowflake. + const liar = { ...msg(30 * DAY), createdTimestamp: now }; + const { recent: r, old: o } = splitByAge([young, edge, past, liar], now); + assert.deepEqual(r, [young]); + assert.deepEqual(o, [edge, past, liar]); + assert.ok(BULK_MAX_AGE_MS < 14 * DAY); +}); + +test('splitByAge: a message whose age is unknown is treated as old (a single delete always works)', () => { + const { recent: r, old: o } = splitByAge([{ id: 'x' }, { id: 'y', createdTimestamp: Date.now() }]); + assert.equal(r.length, 1); + assert.equal(o.length, 1); + assert.equal(o[0].id, 'x'); +}); + +// --- Discord: bulk + singles --------------------------------------------------------------------- + +test('Discord: young messages are bulk-deleted, older ones one by one at the platform pace', async () => { + const channel = discordChannel(); + const young = recent(3); + const oldies = old(3); + const deletedIds = []; + for (const m of oldies) m.delete = async () => void deletedIds.push(m.id); + const { waits, sleep } = recordSleeps(); + + const result = await purgeMessages(channel, [...oldies, ...young], { platform: 'discord', sleep }); + + assert.equal(channel.calls.length, 1); + assert.deepEqual(channel.calls[0].ids.sort(), young.map((m) => m.id).sort()); + assert.equal(channel.calls[0].filterOld, true); + assert.deepEqual( + deletedIds, + oldies.map((m) => m.id) + ); + assert.deepEqual(waits, [SINGLE_DELETE_PACE_MS.discord, SINGLE_DELETE_PACE_MS.discord]); // between, not after the last + assert.equal(result.deleted, 6); + assert.equal(result.bulk, 3); + assert.equal(result.single, 3); + assert.equal(result.failed, 0); + assert.equal(result.stopped, false); +}); + +test('Discord: the bulk route needs 2-100 messages, so a lone young message is deleted singly', async () => { + const channel = discordChannel(); + const lone = msg(DAY); + let deleted = 0; + lone.delete = async () => void deleted++; + const result = await purgeMessages(channel, [lone, ...old(1)], { platform: 'discord', ...noSleep }); + assert.equal(channel.calls.length, 0); + assert.equal(deleted, 1); + assert.equal(result.deleted, 2); +}); + +test('the cap is 100 messages per run, and no bulk call carries more than 100', async () => { + const channel = discordChannel(); + const result = await purgeMessages(channel, [...recent(120), ...old(10)], { + platform: 'discord', + ...noSleep, + }); + assert.equal(result.total, PURGE_CAP); + assert.equal(result.deleted, PURGE_CAP); + assert.ok(channel.calls.every((c) => c.ids.length <= 100)); + + const fluxerChannel = discordChannel(); + const fluxer = await purgeMessages(fluxerChannel, [...old(80), ...recent(80)], { + platform: 'fluxer', + ...noSleep, + }); + assert.equal(fluxer.total, PURGE_CAP); + assert.equal(fluxerChannel.calls[0].ids.length, 100); +}); + +test('Discord: a message the bulk route skipped (turned 14 days old during the run) is deleted singly', async () => { + const young = recent(3); + let skippedDeleted = 0; + young[2].delete = async () => void skippedDeleted++; + const channel = discordChannel({ + async bulkDelete(list) { + const arr = [...list]; + return new Collection(arr.slice(0, 2).map((m) => [m.id, m])); + }, + }); + const result = await purgeMessages(channel, young, { platform: 'discord', ...noSleep }); + assert.equal(skippedDeleted, 1); + assert.equal(result.deleted, 3); +}); + +test('Discord: a "too old" bulk error (50034) falls back to single deletes', async () => { + const young = recent(2); + let singles = 0; + for (const m of young) m.delete = async () => void singles++; + const channel = discordChannel({ + async bulkDelete() { + throw Object.assign(new Error('old'), { code: 50034 }); + }, + }); + const result = await purgeMessages(channel, young, { platform: 'discord', ...noSleep }); + assert.equal(singles, 2); + assert.equal(result.deleted, 2); +}); + +test('Discord: missing permission on the bulk route fails the batch without trying every message', async () => { + const young = recent(3); + let singles = 0; + for (const m of young) m.delete = async () => void singles++; + const channel = discordChannel({ + async bulkDelete() { + throw Object.assign(new Error('perm'), { code: 50013, status: 403 }); + }, + }); + const result = await purgeMessages(channel, young, { platform: 'discord', ...noSleep }); + assert.equal(singles, 0); + assert.equal(result.deleted, 0); + assert.equal(result.failed, 3); + assert.deepEqual(result.failures, { gone: 0, permission: 3, other: 0 }); +}); + +// --- single deletes and rate limits -------------------------------------------------------------- + +test('single deletes wait out a 429 (retry_after seconds) and retry the same message', async () => { + let tries = 0; + const m = msg(20 * DAY, { + delete: async () => { + if (++tries <= 2) throw Object.assign(new Error('rate limited'), { status: 429, retry_after: 2.5 }); + }, + }); + const { waits, sleep } = recordSleeps(); + const result = await purgeMessages(discordChannel(), [m], { platform: 'discord', sleep }); + assert.equal(tries, 3); + assert.deepEqual(waits, [2500, 2500]); + assert.equal(result.deleted, 1); + assert.equal(result.failed, 0); +}); + +test('a 429 in the shape of either SDK is understood: discord.js timeToReset (ms), Fluxer RateLimitError (s)', async () => { + assert.equal(retryAfterMs({ timeToReset: 1800 }), 1800); + assert.equal(retryAfterMs({ name: 'RateLimitError', statusCode: 429, retryAfter: 1.5 }), 1500); + assert.equal(retryAfterMs({ rawError: { retry_after: 0.1 } }), 250); // never a busy loop + assert.equal(retryAfterMs({ retry_after: 9999 }), 60_000); // never an unbounded wait + assert.equal(retryAfterMs({}), 2000); + + // Fluxer's SDK throws a RateLimitError (statusCode, retryAfter in seconds) once its own retries are spent. + let tries = 0; + const m = msg(20 * DAY, { + delete: async () => { + if (++tries === 1) { + throw Object.assign(new Error('slow down'), { name: 'RateLimitError', statusCode: 429, retryAfter: 1 }); + } + }, + }); + const { waits, sleep } = recordSleeps(); + const channel = discordChannel({ + async bulkDelete() { + throw new Error('bulk unavailable'); // so the Fluxer purge falls back to single deletes + }, + }); + const result = await purgeMessages(channel, [m], { platform: 'fluxer', sleep }); + assert.equal(result.deleted, 1); + assert.deepEqual(waits, [1000]); +}); + +test('a message that stays rate limited is given up on after the retries and counted as failed', async () => { + const m = msg(20 * DAY, { + delete: async () => { + throw Object.assign(new Error('rl'), { status: 429, retry_after: 1 }); + }, + }); + const next = msg(20 * DAY); + const { waits, sleep } = recordSleeps(); + const result = await purgeMessages(discordChannel(), [m, next], { platform: 'discord', sleep }); + assert.equal(waits.filter((w) => w === 1000).length, 5); + assert.equal(result.deleted, 1); + assert.equal(result.failed, 1); + assert.equal(result.failures.other, 1); +}); + +test('failures are counted by kind: already gone, missing permission, other', async () => { + const fail = (extra) => + msg(20 * DAY, { + delete: async () => { + throw Object.assign(new Error('x'), extra); + }, + }); + const result = await purgeMessages( + discordChannel(), + [ + fail({ code: 10008 }), + fail({ status: 404 }), + fail({ code: 50013 }), + fail({ statusCode: 403 }), + fail({ status: 500 }), + msg(20 * DAY), + ], + { platform: 'discord', ...noSleep } + ); + assert.equal(result.deleted, 1); + assert.equal(result.failed, 5); + assert.deepEqual(result.failures, { gone: 2, permission: 2, other: 1 }); + assert.equal(classifyError({ code: 'UNKNOWN_MESSAGE' }), 'gone'); + assert.equal(classifyError({ code: 'MISSING_PERMISSIONS' }), 'permission'); +}); + +test('a stop request ends the run between deletes and reports what is left', async () => { + const messages = old(6); + let stopped = false; + let n = 0; + for (const m of messages) { + m.delete = async () => { + if (++n === 2) stopped = true; + }; + } + const result = await purgeMessages(discordChannel(), messages, { + platform: 'discord', + isStopped: () => stopped, + ...noSleep, + }); + assert.equal(result.deleted, 2); + assert.equal(result.stopped, true); + assert.equal(result.remaining, 4); +}); + +test('progress is reported after the bulk call and after every single delete', async () => { + const seen = []; + await purgeMessages(discordChannel(), [...recent(2), ...old(2)], { + platform: 'discord', + onProgress: (p) => seen.push(p.deleted), + ...noSleep, + }); + assert.deepEqual(seen, [2, 3, 4]); +}); + +// --- Fluxer: no age limit ------------------------------------------------------------------------- + +test('Fluxer: everything, old included, goes through the bulk route (no age limit) without an age filter', async () => { + const channel = discordChannel(); + const result = await purgeMessages(channel, [...old(30), ...recent(5)], { platform: 'fluxer', ...noSleep }); + assert.equal(channel.calls.length, 1); + assert.equal(channel.calls[0].ids.length, 35); + assert.equal(channel.calls[0].filterOld, false); + assert.equal(result.deleted, 35); + assert.equal(result.single, 0); +}); + +test('Fluxer: a single old message uses the bulk call too (Fluxer takes 1-100 ids)', async () => { + const channel = discordChannel(); + const result = await purgeMessages(channel, old(1), { platform: 'fluxer', ...noSleep }); + assert.equal(channel.calls.length, 1); + assert.equal(result.deleted, 1); +}); + +test("Fluxer: if the bulk call fails for another reason, messages are deleted singly at Fluxer's pace", async () => { + const messages = old(2); + let singles = 0; + for (const m of messages) m.delete = async () => void singles++; + const channel = discordChannel({ + async bulkDelete() { + throw new Error('boom'); + }, + }); + const { waits, sleep } = recordSleeps(); + const result = await purgeMessages(channel, messages, { platform: 'fluxer', sleep }); + assert.equal(singles, 2); + assert.deepEqual(waits, [SINGLE_DELETE_PACE_MS.fluxer]); + assert.equal(result.deleted, 2); +}); + +test('Fluxer adapter: Channel.bulkDelete(messages, false) sends old messages too, even a single one', async () => { + const sent = []; + const Native = class { + async bulkDelete(arg) { + sent.push([...arg]); + return [...arg]; + } + }; + installFluxerCompat({ ...sdk, Channel: Native }, { Collection: FluxerCollection }); + const channel = new Native(); + const batch = [...old(3), ...recent(2)]; + const all = await channel.bulkDelete(batch, false); + assert.equal(all.size, 5); + assert.equal(sent.at(-1).length, 5); + const one = await channel.bulkDelete([batch[0]], false); + assert.equal(one.size, 1); + // With the filter on (what Discord-minded callers pass) the old ones are dropped. + assert.equal((await channel.bulkDelete(batch, true)).size, 2); +}); + +// --- the lock and the stop permission ------------------------------------------------------------- + +test('one purge at a time per channel: the lock is refused while held and free again after release', () => { + const release = acquirePurgeLock('g:c1', 'u1'); + assert.equal(typeof release, 'function'); + assert.equal(acquirePurgeLock('g:c1', 'u2'), null); + assert.equal(typeof acquirePurgeLock('g:c2', 'u2'), 'function'); // another channel is independent + release(); + release(); // idempotent + assert.equal(typeof acquirePurgeLock('g:c1', 'u2'), 'function'); +}); + +test('canStopPurge: the person who ran it and administrators, nobody else', () => { + const admin = { has: (f) => f === PermissionFlagsBits.Administrator }; + const mod = { has: () => false }; + const args = { starterId: 'u1', administrator: PermissionFlagsBits.Administrator }; + assert.equal(canStopPurge({ ...args, userId: 'u1', permissions: mod }), true); + assert.equal(canStopPurge({ ...args, userId: 'u2', permissions: admin }), true); + assert.equal(canStopPurge({ ...args, userId: 'u2', permissions: mod }), false); + assert.equal(canStopPurge({ ...args, userId: 'u2', permissions: null }), false); +}); + +// --- the command --------------------------------------------------------------------------------- + +test('the command description no longer says "younger than 14 days"; every option is kept', () => { + assert.ok(!/14 days/i.test(purge.data.description)); + assert.deepEqual( + purge.data.options.map((o) => o.name), + ['amount', 'user'] + ); +}); + +test('progress and summary texts', () => { + assert.equal(purge.progressText({ deleted: 40, failed: 0, total: 100 }), '🧹 Deleted **40** of **100**…'); + assert.match(purge.progressText({ deleted: 40, failed: 2, total: 100 }), /2 could not be deleted/); + assert.equal( + purge.summaryText({ deleted: 1, failed: 0, failures: {}, stopped: false, total: 1, remaining: 0 }), + '🧹 Deleted **1** message.' + ); + const text = purge.summaryText({ + deleted: 7, + failed: 3, + failures: { gone: 2, permission: 1, other: 0 }, + stopped: false, + total: 10, + remaining: 0, + }); + assert.match(text, /Deleted \*\*7\*\* messages/); + assert.match(text, /\*\*3\*\* messages could not be deleted \(2 already gone, 1 missing permission\)/); + assert.match( + purge.summaryText({ deleted: 4, failed: 0, failures: {}, stopped: true, total: 10, remaining: 6 }), + /Stopped\. Deleted \*\*4\*\* messages of \*\*10\*\*; \*\*6\*\* left untouched/ + ); +}); + +let G = 0; +let guildId; +const fakeFluxerClient = { fluxer: true }; + +beforeEach(() => { + guildId = `5700000000${String(++G).padStart(8, '0')}`; + purgeTuning.sleep = async () => {}; +}); +afterEach(() => { + purgeTuning.sleep = async () => {}; + runtime.clients.fluxer = null; +}); + +/** A fake slash-command interaction; `click` presses the Stop button while the purge runs. */ +function setup({ platform = 'discord', messages, amount = 100, user = null, starter = 'u1' } = {}) { + const client = platform === 'fluxer' ? fakeFluxerClient : {}; + if (platform === 'fluxer') runtime.clients.fluxer = client; + const modlogSent = []; + const modlogChannel = { + id: 'modlog', + isTextBased: () => true, + permissionsFor: () => ({ has: () => true }), + send: async (p) => void modlogSent.push(p), + }; + const guild = { + id: platform === 'fluxer' ? `fluxer:${guildId}` : guildId, + client, + members: { me: {} }, + channels: { cache: new Map([['modlog', modlogChannel]]) }, + }; + const channel = { + id: 'chan1', + guild, + toString: () => '#chan', + permissionsFor: () => ({ has: () => true }), + messages: { + fetch: async ({ limit }) => new Collection(messages.slice(0, limit).map((m) => [m.id, m])), + }, + bulkCalls: [], + async bulkDelete(list, filterOld) { + const arr = [...(list instanceof Map ? list.values() : list)]; + this.bulkCalls.push({ n: arr.length, filterOld }); + return new Collection(arr.map((m) => [m.id, m])); + }, + }; + const replies = []; + const collector = new EventEmitter(); + collector.stop = () => void (collector.stopped = true); + const reply = { id: 'reply1', createMessageComponentCollector: () => collector }; + const interaction = { + guild, + channel, + user: { id: starter, tag: 'starter#0' }, + options: { getInteger: () => amount, getUser: () => user }, + async reply(p) { + replies.push({ kind: 'reply', ...p }); + }, + async deferReply(p) { + replies.push({ kind: 'defer', ...p }); + }, + async editReply(p) { + replies.push({ kind: 'edit', ...p }); + }, + async fetchReply() { + return reply; + }, + }; + /** Press Stop as `who`; resolves to what the click answered. */ + const click = async (who, { admin = false } = {}) => { + const answers = []; + const i = { + user: { id: who }, + customId: purge.STOP_CUSTOM_ID, + memberPermissions: { has: (f) => admin && f === PermissionFlagsBits.Administrator }, + reply: async (p) => void answers.push({ kind: 'reply', ...p }), + update: async (p) => void answers.push({ kind: 'update', ...p }), + }; + collector.emit('collect', i); + await new Promise((r) => setImmediate(r)); + return answers; + }; + return { interaction, channel, collector, replies, modlogSent, click }; +} + +const lastEdit = (replies) => replies.filter((r) => r.kind === 'edit').at(-1); + +test('command, Discord: old messages get a Stop button, progress, a final summary and a mod-log entry', async () => { + await setModlogChannel(guildId, 'modlog'); + const t = setup({ messages: [...recent(2), ...old(3)] }); + purgeTuning.sleep = async () => {}; + await purge.execute(t.interaction); + + const edits = t.replies.filter((r) => r.kind === 'edit'); + assert.match(edits[0].content, /Deleted \*\*0\*\* of \*\*5\*\*/); + assert.equal(edits[0].components.length, 1); + const button = edits[0].components[0].toJSON().components[0]; + assert.equal(button.custom_id, purge.STOP_CUSTOM_ID); + assert.equal(button.label, 'Stop'); + assert.ok(edits.some((e) => /Deleted \*\*2\*\* of \*\*5\*\*/.test(e.content))); // progress after the bulk call + assert.match(lastEdit(t.replies).content, /Deleted \*\*5\*\* messages\./); + assert.deepEqual(lastEdit(t.replies).components, []); // the button is removed at the end + assert.equal(t.channel.bulkCalls.length, 1); + assert.deepEqual(t.channel.bulkCalls[0], { n: 2, filterOld: true }); + assert.equal(t.collector.stopped, true); + // The mod log still gets its entry. + assert.equal(t.modlogSent.length, 1); + assert.equal(t.modlogSent[0].embeds[0].data.title, 'Messages purged'); + assert.ok(t.modlogSent[0].embeds[0].data.fields.some((f) => f.name === 'Count' && f.value === '5')); +}); + +test('command, Discord: only young messages keep the quick single reply, with no Stop button', async () => { + const t = setup({ messages: recent(4) }); + await purge.execute(t.interaction); + const edits = t.replies.filter((r) => r.kind === 'edit'); + assert.equal(edits.length, 1); + assert.match(edits[0].content, /Deleted \*\*4\*\* messages\./); + assert.equal(edits[0].components, undefined); +}); + +test('command: the user filter and the amount are kept', async () => { + const messages = [ + ...recent(2, { author: { id: 'target' } }), + ...recent(3), + ...old(2, { author: { id: 'target' } }), + ]; + const t = setup({ messages, user: { id: 'target', tag: 'target#0' } }); + await purge.execute(t.interaction); + assert.match(lastEdit(t.replies).content, /Deleted \*\*4\*\* messages from target#0\./); + + const t2 = setup({ messages: recent(10), amount: 3 }); + await purge.execute(t2.interaction); + assert.match(lastEdit(t2.replies).content, /Deleted \*\*3\*\* messages\./); +}); + +test('command: the manage-messages check and the no-guild check are kept', async () => { + const t = setup({ messages: recent(2) }); + t.channel.permissionsFor = () => ({ has: () => false }); + await purge.execute(t.interaction); + assert.match(t.replies[0].content, /Manage Messages/); + assert.equal(t.channel.bulkCalls.length, 0); + + const t2 = setup({ messages: recent(2) }); + t2.interaction.guild = null; + await purge.execute(t2.interaction); + assert.equal(t2.replies[0].kind, 'reply'); + assert.equal(t2.channel.bulkCalls.length, 0); +}); + +test('command, Stop button: the starter and an admin may stop, another moderator may not', async () => { + for (const [who, opts, mayStop] of [ + ['u2', {}, false], + ['u1', {}, true], + ['u3', { admin: true }, true], + ]) { + const messages = old(6); + let n = 0; + let answers; + for (const m of messages) m.delete = async () => void n++; + const t = setup({ messages }); + // Press the button in the middle of the run (during the wait after the 2nd delete). + let sleepCalls = 0; + purgeTuning.sleep = async () => { + if (++sleepCalls === 2) answers = await t.click(who, opts); + }; + await purge.execute(t.interaction); + + if (mayStop) { + assert.equal(answers[0].kind, 'update', who); + assert.match(answers[0].content, /Stopping/); + assert.ok(n < 6, `${who}: stopped early`); + assert.match(lastEdit(t.replies).content, /Stopped\./); + assert.match(lastEdit(t.replies).content, /left untouched/); + } else { + assert.equal(answers[0].kind, 'reply', who); + assert.match(answers[0].content, /Only the person who ran this purge, or a server admin/); + assert.equal(n, 6, 'a refused click does not stop the purge'); + assert.match(lastEdit(t.replies).content, /Deleted \*\*6\*\* messages\./); + } + } +}); + +test('command: a second purge in the same channel is refused while one runs, and allowed after', async () => { + const t = setup({ messages: old(3) }); + let second; + purgeTuning.sleep = async () => { + if (second) return; + second = setup({ messages: recent(2) }); + await purge.execute(second.interaction); + }; + await purge.execute(t.interaction); + assert.equal(second.replies.length, 1); + assert.equal(second.replies[0].kind, 'reply'); + assert.match(second.replies[0].content, /already running in this channel/); + assert.equal(second.channel.bulkCalls.length, 0); + + // The first finished: the channel is free again. + const third = setup({ messages: recent(2) }); + await purge.execute(third.interaction); + assert.match(lastEdit(third.replies).content, /Deleted \*\*2\*\* messages\./); +}); + +test('command: the lock is released when the purge throws', async () => { + const t = setup({ messages: recent(2) }); + t.channel.messages.fetch = async () => { + throw new Error('no history'); + }; + await assert.rejects(purge.execute(t.interaction), /no history/); + const next = setup({ messages: recent(2) }); + await purge.execute(next.interaction); + assert.match(lastEdit(next.replies).content, /Deleted \*\*2\*\*/); +}); + +test('command: the final reply says how many failed and why', async () => { + const messages = old(4); + messages[0].delete = async () => { + throw Object.assign(new Error('gone'), { code: 10008 }); + }; + messages[1].delete = async () => { + throw Object.assign(new Error('perm'), { code: 50013 }); + }; + const t = setup({ messages }); + await purge.execute(t.interaction); + const text = lastEdit(t.replies).content; + assert.match(text, /Deleted \*\*2\*\* messages\./); + assert.match(text, /\*\*2\*\* messages could not be deleted \(1 already gone, 1 missing permission\)/); +}); + +test('command, Fluxer: old messages go through the bulk route unfiltered, with no Stop button and no single deletes', async () => { + const messages = [...old(5), ...recent(3)]; + let singles = 0; + for (const m of messages) m.delete = async () => void singles++; + const t = setup({ platform: 'fluxer', messages }); + await purge.execute(t.interaction); + assert.equal(t.channel.bulkCalls.length, 1); + assert.deepEqual(t.channel.bulkCalls[0], { n: 8, filterOld: false }); + assert.equal(singles, 0); + const edits = t.replies.filter((r) => r.kind === 'edit'); + assert.equal(edits.length, 1); + assert.equal(edits[0].components, undefined); + assert.match(edits[0].content, /Deleted \*\*8\*\* messages\./); +}); + +test('command: the lock is keyed by the guild key, so Fluxer and Discord channels never share one', async () => { + const f = setup({ platform: 'fluxer', messages: recent(2) }); + const release = acquirePurgeLock(`${f.interaction.guild.id}:chan1`, 'u9'); + await purge.execute(f.interaction); + assert.match(f.replies[0].content, /already running/); + release(); + const d = setup({ messages: recent(2) }); + const releaseFluxerKey = acquirePurgeLock(`fluxer:${guildId}:chan1`, 'u9'); + await purge.execute(d.interaction); + assert.match(lastEdit(d.replies).content, /Deleted/); + releaseFluxerKey(); +}); From 7668584b97b27b460ba22d7241b276911d4ac27e Mon Sep 17 00:00:00 2001 From: Ferdinand99 Date: Thu, 19 Nov 2026 17:46:46 +0100 Subject: [PATCH 2/4] test(purge): give fake messages an SDK timestamp and format --- test/purgeCommand.test.js | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/test/purgeCommand.test.js b/test/purgeCommand.test.js index 587c4211..aacaf7d1 100644 --- a/test/purgeCommand.test.js +++ b/test/purgeCommand.test.js @@ -34,7 +34,7 @@ let seq = 0; function msg(ageMs, over = {}) { const ts = BigInt(Date.now() - ageMs); const id = String(((ts - EPOCH) << 22n) + BigInt(++seq)); - return { id, author: { id: 'a1' }, delete: async () => {}, ...over }; + return { id, createdTimestamp: Number(ts), author: { id: 'a1' }, delete: async () => {}, ...over }; } const recent = (n, over) => Array.from({ length: n }, () => msg(DAY, over)); const old = (n, over) => Array.from({ length: n }, () => msg(20 * DAY, over)); @@ -214,7 +214,11 @@ test('a 429 in the shape of either SDK is understood: discord.js timeToReset (ms const m = msg(20 * DAY, { delete: async () => { if (++tries === 1) { - throw Object.assign(new Error('slow down'), { name: 'RateLimitError', statusCode: 429, retryAfter: 1 }); + throw Object.assign(new Error('slow down'), { + name: 'RateLimitError', + statusCode: 429, + retryAfter: 1, + }); } }, }); From 85dbf071374be71a3c2a1b555b55f7d6bf797c32 Mon Sep 17 00:00:00 2001 From: Ferdinand99 Date: Thu, 19 Nov 2026 18:10:32 +0100 Subject: [PATCH 3/4] fix(purge): respect the interaction deadline, audit before replying, keep old pinned messages - end the run as timed out instead of waiting past the 15-minute interaction token - post the mod-log entry before the final reply and tolerate a failing reply - the progress reply is ephemeral, so only the person who ran the command can stop it; drop the server-admin wording - keep pinned messages older than 14 days, as before, and say how many were kept --- docs/modules/moderation.md | 8 +- src/bot/commands/purge.js | 50 +++++++++--- src/bot/lib/purgeMessages.js | 56 ++++++++----- test/purgeCommand.test.js | 154 +++++++++++++++++++++++++++++++++-- 4 files changed, 228 insertions(+), 40 deletions(-) diff --git a/docs/modules/moderation.md b/docs/modules/moderation.md index 45e8e4b8..c5e3d34a 100644 --- a/docs/modules/moderation.md +++ b/docs/modules/moderation.md @@ -66,11 +66,15 @@ purge that deletes something is written to the mod log. - **Discord:** messages younger than 14 days are deleted in bulk. Older messages cannot be bulk deleted, so Sylo deletes them one at a time at the pace Discord allows (about one per second, and it waits whenever Discord asks it to slow down). While that runs, the reply is updated - ("Deleted 40 of 100...") and has a **Stop** button. Only the person who ran the command and server - admins can press it. + ("Deleted 40 of 100...") and has a **Stop** button. The reply is private to the person who ran the + command, and only they can press Stop. A purge that would run past Discord's 15-minute reply limit + ends early with "Timed out"; run `/purge` again for the rest. - **Fluxer:** Fluxer's bulk delete has no age limit, so every message is deleted in one go and there is nothing to wait for. - Only one purge runs per channel at a time; a second `/purge` there is refused until the first has finished or been stopped. +- Pinned messages: young pinned messages are deleted, as they always were. Pinned messages older than + 14 days are kept (they were never deleted before either, and the reply says how many were kept). + Unpin them first if they should go too. - The final reply says how many messages were deleted and how many could not be (for example already deleted by someone else, or a missing permission). diff --git a/src/bot/commands/purge.js b/src/bot/commands/purge.js index a2e17805..566dd163 100644 --- a/src/bot/commands/purge.js +++ b/src/bot/commands/purge.js @@ -17,10 +17,11 @@ import { import { MOD_COLOR, replyWithoutGuild } from '../lib/moderation.js'; import { postModLog } from '../lib/modlog.js'; import { - MAX_RUN_MS, + INTERACTION_BUDGET_MS, acquirePurgeLock, canStopPurge, purgeMessages, + selectPurgeTargets, splitByAge, } from '../lib/purgeMessages.js'; import { respondSafely } from '../../lib/discordErrors.js'; @@ -65,10 +66,14 @@ export function progressText({ deleted, failed, total }) { } /** The final reply. */ -export function summaryText(result, user) { +export function summaryText(result, user, keptPinned = 0) { const from = user ? ` from ${user.tag}` : ''; const lines = []; - if (result.stopped) { + if (result.timedOut) { + lines.push( + `⏱️ Timed out. Deleted ${plural(result.deleted)}${from} of **${result.total}**; **${result.remaining}** left untouched. Run /purge again for the rest.` + ); + } else if (result.stopped) { lines.push( `⏹️ Stopped. Deleted ${plural(result.deleted)}${from} of **${result.total}**; **${result.remaining}** left untouched.` ); @@ -78,7 +83,11 @@ export function summaryText(result, user) { if (result.failed) { lines.push(`⚠️ ${plural(result.failed)} could not be deleted (${describeFailures(result.failures)}).`); } - return lines.join('\n'); + if (keptPinned) { + lines.push(`📌 ${plural(keptPinned)} older than 14 days ${keptPinned === 1 ? 'was' : 'were'} pinned and kept.`); + } + return lines.join(' +'); } function stopRow() { @@ -112,7 +121,7 @@ export async function execute(interaction) { if (!release) { await interaction.reply({ content: - '⚠️ A purge is already running in this channel. Wait for it to finish, or ask whoever started it (or a server admin) to press Stop.', + '⚠️ A purge is already running in this channel. Wait for it to finish.', flags: MessageFlags.Ephemeral, }); return; @@ -124,12 +133,14 @@ export async function execute(interaction) { let messages = await channel.messages.fetch({ limit: amount }); if (user) messages = messages.filter((m) => m.author.id === user.id); - const targets = [...messages.values()]; + const { targets, keptPinned } = selectPurgeTargets([...messages.values()]); const platform = platformOfGuild(interaction.guild); // Only a Discord purge with messages past the bulk limit takes long enough for progress and a Stop button. const longRun = platform !== 'fluxer' && splitByAge(targets).old.length > 0; + // The interaction token lives 15 minutes; nothing is started or waited for past this. + const deadline = (interaction.createdTimestamp ?? Date.now()) + INTERACTION_BUDGET_MS; let stopRequested = false; let pending = Promise.resolve(); let lastEdit = 0; @@ -147,7 +158,7 @@ export async function execute(interaction) { const message = await interaction.fetchReply(); collector = message?.createMessageComponentCollector?.({ componentType: ComponentType.Button, - time: MAX_RUN_MS + 60_000, + time: Math.max(1000, deadline - Date.now()) + 5000, }); collector?.on('collect', (i) => respondSafely('bot', '/purge stop', async () => { @@ -159,7 +170,7 @@ export async function execute(interaction) { }); if (!allowed) { await i.reply({ - content: 'Only the person who ran this purge, or a server admin, can stop it.', + content: 'Only the person who ran this purge can stop it.', flags: MessageFlags.Ephemeral, }); return; @@ -172,6 +183,7 @@ export async function execute(interaction) { const result = await purgeMessages(channel, targets, { platform, + deadline, isStopped: () => stopRequested, onProgress: (p) => { if (!longRun || stopRequested) return; @@ -184,11 +196,9 @@ export async function execute(interaction) { collector?.stop('done'); await pending; - await interaction.editReply({ - content: summaryText(result, user), - ...(longRun ? { components: [] } : {}), - }); + // The mod log first: the deletions happened, so they are audited even if the final reply fails + // (an expired token, a Discord hiccup). if (result.deleted > 0) { const embed = new EmbedBuilder() .setColor(MOD_COLOR) @@ -197,13 +207,27 @@ export async function execute(interaction) { { name: 'Channel', value: `${channel}` }, { name: 'Count', value: String(result.deleted) }, ...(result.failed ? [{ name: 'Failed', value: String(result.failed) }] : []), - ...(result.stopped ? [{ name: 'Stopped early', value: `${result.remaining} left untouched` }] : []), + ...(result.stopped || result.timedOut + ? [ + { + name: result.timedOut ? 'Timed out' : 'Stopped early', + value: `${result.remaining} left untouched`, + }, + ] + : []), { name: 'Moderator', value: interaction.user.tag }, ...(user ? [{ name: 'Filtered to', value: user.tag }] : []) ) .setTimestamp(Date.now()); await postModLog(interaction.guild, embed); } + + await interaction + .editReply({ + content: summaryText(result, user, keptPinned), + ...(longRun ? { components: [] } : {}), + }) + .catch((err) => log.warn('bot', '/purge final reply failed:', err?.message ?? err)); } finally { collector?.stop('done'); release(); diff --git a/src/bot/lib/purgeMessages.js b/src/bot/lib/purgeMessages.js index 5dee3423..78ebede8 100644 --- a/src/bot/lib/purgeMessages.js +++ b/src/bot/lib/purgeMessages.js @@ -25,8 +25,10 @@ export const MAX_RATE_LIMIT_RETRIES = 5; const MIN_RETRY_MS = 250; const MAX_RETRY_MS = 60_000; const DEFAULT_RETRY_MS = 2_000; -/** A purge gives up after this long (a Discord interaction token lives 15 minutes). */ +/** Default longest run of one purge. */ export const MAX_RUN_MS = 10 * 60_000; +/** A Discord interaction token lives 15 minutes: stop using it 2 minutes before that. */ +export const INTERACTION_BUDGET_MS = 13 * 60_000; /** When a message was created, from its snowflake id (falls back to the SDK's timestamp). */ export function messageTimestamp(message) { @@ -50,6 +52,18 @@ export function splitByAge(messages, now = Date.now()) { return { recent, old }; } +/** + * What a purge deletes out of `messages`: pinned messages that are too old for the bulk route are kept, + * as they always were (the old bulk-only purge skipped every old message, pinned or not). Younger pinned + * messages are deleted, as before. + * @returns {{ targets: any[], keptPinned: number }} + */ +export function selectPurgeTargets(messages, now = Date.now()) { + const old = new Set(splitByAge(messages, now).old); + const targets = messages.filter((m) => !(m.pinned && old.has(m))); + return { targets, keptPinned: messages.length - targets.length }; +} + // --- error classification -------------------------------------------------------- const statusOf = (err) => err?.status ?? err?.statusCode ?? err?.httpStatus ?? err?.rawError?.status; @@ -141,8 +155,9 @@ const emptyFailures = () => ({ gone: 0, permission: 0, other: 0 }); * @param {(ms: number) => Promise} [opts.sleep] * @param {() => number} [opts.now] * @param {number} [opts.paceMs] + * @param {number} [opts.deadline] epoch ms after which no more deletes are started or waited for (default: MAX_RUN_MS from now) * @returns {Promise<{ total: number, deleted: number, failed: number, - * failures: { gone: number, permission: number, other: number }, stopped: boolean, remaining: number, + * failures: { gone: number, permission: number, other: number }, stopped: boolean, timedOut: boolean, remaining: number, * bulk: number, single: number }>} */ export async function purgeMessages(channel, messages, opts = {}) { @@ -152,11 +167,12 @@ export async function purgeMessages(channel, messages, opts = {}) { const paceMs = opts.paceMs ?? SINGLE_DELETE_PACE_MS[platform] ?? SINGLE_DELETE_PACE_MS.discord; const isStopped = opts.isStopped ?? (() => false); const startedAt = now(); + const deadline = opts.deadline ?? startedAt + MAX_RUN_MS; const targets = [...messages].slice(0, PURGE_CAP); const total = targets.length; const failures = emptyFailures(); - const result = { total, deleted: 0, failed: 0, failures, stopped: false, remaining: 0, bulk: 0, single: 0 }; + const result = { total, deleted: 0, failed: 0, failures, stopped: false, timedOut: false, remaining: 0, bulk: 0, single: 0 }; const progress = () => opts.onProgress?.({ deleted: result.deleted, failed: result.failed, total }); const fail = (kind, n = 1) => { @@ -200,23 +216,18 @@ export async function purgeMessages(channel, messages, opts = {}) { } // 2. One by one, paced. + const halt = (i, why) => { + if (why === 'timeout') result.timedOut = true; + else result.stopped = true; + result.remaining = singles.length - i; + return result; + }; for (let i = 0; i < singles.length; i++) { - if (isStopped()) { - result.stopped = true; - result.remaining = singles.length - i; - break; - } - if (now() - startedAt > MAX_RUN_MS) { - result.stopped = true; - result.remaining = singles.length - i; - break; - } + if (isStopped()) return halt(i, 'stop'); + if (now() >= deadline) return halt(i, 'timeout'); if (i > 0) await sleep(paceMs); - if (isStopped()) { - result.stopped = true; - result.remaining = singles.length - i; - break; - } + if (isStopped()) return halt(i, 'stop'); + if (now() >= deadline) return halt(i, 'timeout'); const message = singles[i]; let attempt = 0; for (;;) { @@ -226,9 +237,14 @@ export async function purgeMessages(channel, messages, opts = {}) { result.single += 1; break; } catch (err) { - if (isRateLimit(err) && attempt < MAX_RATE_LIMIT_RETRIES && !isStopped()) { + if (isRateLimit(err) && attempt < MAX_RATE_LIMIT_RETRIES) { + const wait = retryAfterMs(err); + // Never wait past the deadline (the interaction token expires): give up on the rest instead. + if (isStopped()) return halt(i, 'stop'); + if (now() + wait >= deadline) return halt(i, 'timeout'); attempt += 1; - await sleep(retryAfterMs(err)); + await sleep(wait); + if (isStopped()) return halt(i, 'stop'); continue; } fail(isRateLimit(err) ? 'other' : classifyError(err)); diff --git a/test/purgeCommand.test.js b/test/purgeCommand.test.js index aacaf7d1..d2bdeff1 100644 --- a/test/purgeCommand.test.js +++ b/test/purgeCommand.test.js @@ -23,6 +23,7 @@ import { purgeMessages, purgeTuning, retryAfterMs, + selectPurgeTargets, splitByAge, } from '../src/bot/lib/purgeMessages.js'; @@ -68,10 +69,11 @@ test('splitByAge: the 14-day cut is computed from the snowflake timestamp', () = const young = msg(13 * DAY); const edge = msg(14 * DAY - 60_000); // inside the 5-minute safety margin: counts as old const past = msg(15 * DAY); + const justInside = msg(14 * DAY - 6 * 60_000); // 6 minutes short of 14 days: outside the margin, still bulk-able // The SDK's own timestamp is ignored when the id is a snowflake. const liar = { ...msg(30 * DAY), createdTimestamp: now }; - const { recent: r, old: o } = splitByAge([young, edge, past, liar], now); - assert.deepEqual(r, [young]); + const { recent: r, old: o } = splitByAge([young, edge, past, justInside, liar], now); + assert.deepEqual(r, [young, justInside]); assert.deepEqual(o, [edge, past, liar]); assert.ok(BULK_MAX_AGE_MS < 14 * DAY); }); @@ -293,6 +295,85 @@ test('a stop request ends the run between deletes and reports what is left', asy assert.equal(result.remaining, 4); }); +test('a 429 wait that would pass the deadline is not slept: the run ends as timed out with the rest untouched', async () => { + const m = msg(20 * DAY, { + delete: async () => { + throw Object.assign(new Error('rl'), { status: 429, retry_after: 60 }); + }, + }); + const next = msg(20 * DAY); + const { waits, sleep } = recordSleeps(); + const result = await purgeMessages(discordChannel(), [m, next], { + platform: 'discord', + sleep, + deadline: Date.now() + 30_000, + }); + assert.deepEqual(waits, []); // 60 s would end past the 30 s left + assert.equal(result.timedOut, true); + assert.equal(result.stopped, false); + assert.equal(result.remaining, 2); + assert.equal(result.failed, 0); +}); + +test('a retry that fits before the deadline is still waited out', async () => { + let tries = 0; + const m = msg(20 * DAY, { + delete: async () => { + if (++tries === 1) throw Object.assign(new Error('rl'), { status: 429, retry_after: 2 }); + }, + }); + const { waits, sleep } = recordSleeps(); + const result = await purgeMessages(discordChannel(), [m], { + platform: 'discord', + sleep, + deadline: Date.now() + 60_000, + }); + assert.deepEqual(waits, [2000]); + assert.equal(result.deleted, 1); + assert.equal(result.timedOut, false); +}); + +test('a deadline that has passed starts no single delete', async () => { + let deleted = 0; + const messages = old(3, { delete: async () => void deleted++ }); + const result = await purgeMessages(discordChannel(), messages, { + platform: 'discord', + deadline: Date.now() - 1, + ...noSleep, + }); + assert.equal(deleted, 0); + assert.equal(result.timedOut, true); + assert.equal(result.remaining, 3); +}); + +test('a stop that arrives while waiting out a 429 ends the run without another try', async () => { + let stopped = false; + let tries = 0; + const m = msg(20 * DAY, { + delete: async () => { + tries++; + throw Object.assign(new Error('rl'), { status: 429, retry_after: 1 }); + }, + }); + const result = await purgeMessages(discordChannel(), [m], { + platform: 'discord', + isStopped: () => stopped, + sleep: async () => void (stopped = true), + }); + assert.equal(tries, 1); + assert.equal(result.stopped, true); + assert.equal(result.remaining, 1); +}); + +test('selectPurgeTargets: old pinned messages are kept (as before), young pinned ones are deleted', () => { + const youngPinned = msg(DAY, { pinned: true }); + const oldPinned = msg(20 * DAY, { pinned: true }); + const oldPlain = msg(20 * DAY); + const { targets, keptPinned } = selectPurgeTargets([youngPinned, oldPinned, oldPlain]); + assert.deepEqual(targets, [youngPinned, oldPlain]); + assert.equal(keptPinned, 1); +}); + test('progress is reported after the bulk call and after every single delete', async () => { const seen = []; await purgeMessages(discordChannel(), [...recent(2), ...old(2)], { @@ -407,6 +488,21 @@ test('progress and summary texts', () => { }); assert.match(text, /Deleted \*\*7\*\* messages/); assert.match(text, /\*\*3\*\* messages could not be deleted \(2 already gone, 1 missing permission\)/); + const timedOut = purge.summaryText({ + deleted: 4, + failed: 0, + failures: {}, + stopped: false, + timedOut: true, + total: 10, + remaining: 6, + }); + assert.match(timedOut, /Timed out\. Deleted \*\*4\*\* messages of \*\*10\*\*; \*\*6\*\* left untouched/); + assert.doesNotMatch(timedOut, /Stopped/); + assert.match( + purge.summaryText({ deleted: 1, failed: 0, failures: {}, stopped: false, total: 1, remaining: 0 }, null, 2), + /\*\*2\*\* messages older than 14 days were pinned and kept/ + ); assert.match( purge.summaryText({ deleted: 4, failed: 0, failures: {}, stopped: true, total: 10, remaining: 6 }), /Stopped\. Deleted \*\*4\*\* messages of \*\*10\*\*; \*\*6\*\* left untouched/ @@ -494,7 +590,7 @@ function setup({ platform = 'discord', messages, amount = 100, user = null, star await new Promise((r) => setImmediate(r)); return answers; }; - return { interaction, channel, collector, replies, modlogSent, click }; + return { interaction, channel, collector, reply, replies, modlogSent, click }; } const lastEdit = (replies) => replies.filter((r) => r.kind === 'edit').at(-1); @@ -561,7 +657,7 @@ test('command: the manage-messages check and the no-guild check are kept', async assert.equal(t2.channel.bulkCalls.length, 0); }); -test('command, Stop button: the starter and an admin may stop, another moderator may not', async () => { +test('command, Stop button: the starter may stop, another moderator may not (an admin click is still honoured as defence in depth)', async () => { for (const [who, opts, mayStop] of [ ['u2', {}, false], ['u1', {}, true], @@ -587,7 +683,7 @@ test('command, Stop button: the starter and an admin may stop, another moderator assert.match(lastEdit(t.replies).content, /left untouched/); } else { assert.equal(answers[0].kind, 'reply', who); - assert.match(answers[0].content, /Only the person who ran this purge, or a server admin/); + assert.match(answers[0].content, /Only the person who ran this purge can stop it/); assert.equal(n, 6, 'a refused click does not stop the purge'); assert.match(lastEdit(t.replies).content, /Deleted \*\*6\*\* messages\./); } @@ -667,3 +763,51 @@ test('command: the lock is keyed by the guild key, so Fluxer and Discord channel assert.match(lastEdit(d.replies).content, /Deleted/); releaseFluxerKey(); }); + +test('command: a final reply that fails still leaves the mod-log entry, and the command does not throw', async () => { + await setModlogChannel(guildId, 'modlog'); + const t = setup({ messages: recent(3) }); + t.interaction.editReply = async () => { + throw new Error('Unknown Webhook'); + }; + await purge.execute(t.interaction); + assert.equal(t.modlogSent.length, 1); + assert.ok(t.modlogSent[0].embeds[0].data.fields.some((f) => f.name === 'Count' && f.value === '3')); +}); + +test('command: the deadline comes from the interaction, so an old token ends the run as "Timed out"', async () => { + await setModlogChannel(guildId, 'modlog'); + const t = setup({ messages: [...recent(2), ...old(4)] }); + t.interaction.createdTimestamp = Date.now() - 14 * 60_000; // already past the 13-minute budget + await purge.execute(t.interaction); + const text = lastEdit(t.replies).content; + assert.match(text, /Timed out\. Deleted \*\*2\*\* messages of \*\*6\*\*; \*\*4\*\* left untouched/); + assert.doesNotMatch(text, /Stopped/); + assert.ok(t.modlogSent[0].embeds[0].data.fields.some((f) => f.name === 'Timed out')); +}); + +test('command: the collector lives only until the interaction deadline', async () => { + const t = setup({ messages: [...recent(2), ...old(2)] }); + t.interaction.createdTimestamp = Date.now(); + let time; + t.reply.createMessageComponentCollector = (o) => ((time = o.time), t.collector); + await purge.execute(t.interaction); + assert.ok(time <= 13 * 60_000 + 5000 && time > 12 * 60_000, `time ${time}`); +}); + +test('command: old pinned messages are kept and reported, young pinned ones are deleted', async () => { + const oldPinned = msg(20 * DAY, { pinned: true }); + let oldPinnedDeleted = false; + oldPinned.delete = async () => void (oldPinnedDeleted = true); + const t = setup({ messages: [...recent(2, { pinned: true }), oldPinned, ...old(1)] }); + await purge.execute(t.interaction); + assert.equal(oldPinnedDeleted, false); + const text = lastEdit(t.replies).content; + assert.match(text, /Deleted \*\*3\*\* messages\./); + assert.match(text, /\*\*1\*\* message older than 14 days was pinned and kept/); + + const f = setup({ platform: 'fluxer', messages: [...old(2), oldPinned] }); + await purge.execute(f.interaction); + assert.deepEqual(f.channel.bulkCalls[0], { n: 2, filterOld: false }); + assert.match(lastEdit(f.replies).content, /pinned and kept/); +}); From 98b093cf1e56f3cec5e529a0d3f1138cce97f519 Mon Sep 17 00:00:00 2001 From: Ferdinand99 Date: Thu, 19 Nov 2026 18:11:51 +0100 Subject: [PATCH 4/4] style(purge): format --- src/bot/commands/purge.js | 10 +++++----- src/bot/lib/purgeMessages.js | 12 +++++++++++- test/purgeCommand.test.js | 6 +++++- 3 files changed, 21 insertions(+), 7 deletions(-) diff --git a/src/bot/commands/purge.js b/src/bot/commands/purge.js index 566dd163..75211ee5 100644 --- a/src/bot/commands/purge.js +++ b/src/bot/commands/purge.js @@ -84,10 +84,11 @@ export function summaryText(result, user, keptPinned = 0) { lines.push(`⚠️ ${plural(result.failed)} could not be deleted (${describeFailures(result.failures)}).`); } if (keptPinned) { - lines.push(`📌 ${plural(keptPinned)} older than 14 days ${keptPinned === 1 ? 'was' : 'were'} pinned and kept.`); + lines.push( + `📌 ${plural(keptPinned)} older than 14 days ${keptPinned === 1 ? 'was' : 'were'} pinned and kept.` + ); } - return lines.join(' -'); + return lines.join('\n'); } function stopRow() { @@ -120,8 +121,7 @@ export async function execute(interaction) { const release = acquirePurgeLock(`${guildKey(interaction.guild)}:${channel.id}`, interaction.user.id); if (!release) { await interaction.reply({ - content: - '⚠️ A purge is already running in this channel. Wait for it to finish.', + content: '⚠️ A purge is already running in this channel. Wait for it to finish.', flags: MessageFlags.Ephemeral, }); return; diff --git a/src/bot/lib/purgeMessages.js b/src/bot/lib/purgeMessages.js index 78ebede8..62321573 100644 --- a/src/bot/lib/purgeMessages.js +++ b/src/bot/lib/purgeMessages.js @@ -172,7 +172,17 @@ export async function purgeMessages(channel, messages, opts = {}) { const targets = [...messages].slice(0, PURGE_CAP); const total = targets.length; const failures = emptyFailures(); - const result = { total, deleted: 0, failed: 0, failures, stopped: false, timedOut: false, remaining: 0, bulk: 0, single: 0 }; + const result = { + total, + deleted: 0, + failed: 0, + failures, + stopped: false, + timedOut: false, + remaining: 0, + bulk: 0, + single: 0, + }; const progress = () => opts.onProgress?.({ deleted: result.deleted, failed: result.failed, total }); const fail = (kind, n = 1) => { diff --git a/test/purgeCommand.test.js b/test/purgeCommand.test.js index d2bdeff1..92c45d21 100644 --- a/test/purgeCommand.test.js +++ b/test/purgeCommand.test.js @@ -500,7 +500,11 @@ test('progress and summary texts', () => { assert.match(timedOut, /Timed out\. Deleted \*\*4\*\* messages of \*\*10\*\*; \*\*6\*\* left untouched/); assert.doesNotMatch(timedOut, /Stopped/); assert.match( - purge.summaryText({ deleted: 1, failed: 0, failures: {}, stopped: false, total: 1, remaining: 0 }, null, 2), + purge.summaryText( + { deleted: 1, failed: 0, failures: {}, stopped: false, total: 1, remaining: 0 }, + null, + 2 + ), /\*\*2\*\* messages older than 14 days were pinned and kept/ ); assert.match(