Skip to content

HomelabServices and mediareference

Deleting your own Discord messages on a schedule, with an encrypted archive

discordctl is a Go CLI and rolling-retention daemon that deletes a user’s own Discord messages older than a configurable cutoff while preserving an age-encrypted archive of every removed message, its surrounding channel context, and its attachments. It runs as a single-container Compose stack deployed through Composer with its state and archive directories on the host paths covered by declarative homelab backups.

TL;DR:

  • Every delete path is gated by an archive commit (internal/archive/writer.go). For each search page or export channel batch, discordctl writes age(gzip(JSONL)) records and age-encrypted attachment blobs, fsyncs the files and parent directories, and runs DELETE calls only after Commit returns nil.
  • The daemon holds only age X25519 public keys (ARCHIVE_RECIPIENTS). The corresponding private identity stays off the host, so a compromise of the container or NAS mount exposes ciphertext names and sizes without message bodies or attachment filenames.
  • Rate limits are paced from response headers (X-RateLimit-Remaining and X-RateLimit-Reset-After1), bounded below by a hard 0.3 s minDeleteDelay floor (cmd/discordctl/config.go) and ratcheted upward for the rest of a scope whenever an HTTP 429 occurs.
  • Only the authenticated user’s messages can be deleted: search queries hardcode author_id=<me.ID>, export files contain only the user’s own messages, and context or incoming DM messages are stored in read-only archive.Record structs that never feed the delete loop.
  • Known Discord delete refusals have explicit handlers (internal/discord/client.go): error 50083 (archived thread) queues the message for an unarchive-delete-rearchive drain at the end of the page, and error 50021 (system message) records the message ID in state.json under nondeletable so later passes skip it2.

Export reader/data/export/MessagesArchivercontext + CDN streamchannel batchLive search APIauthor_id = me.ID25-hit pageIncoming DM readerGET /channels/{id}/messagesother-author DMsDurable state/data/state/state.jsonincoming_watermarksage archive (/data/archive)segments/*.jsonl.gz.ageblobs/<attachment_id>.agefsync + rename(public key only)Delete loopbucket pacing + 50083 drainCommit == nilToken-less CLIarchive cat / blob / verify / datasetdecrypt withage identityMark deleted /nondeletable

The data flow across the three input paths and the archive gate:

PhaseCodeWhat it does
ExportphaseExport in cmd/discordctl/run.goOn the first pass when /data/export/Messages is present and export_consumed is false, discordctl reads the official Discord data export channel by channel, commits one encrypted segment per channel for messages older than that channel’s cutoff, and deletes those messages.
Live catch-upphaseLiveCatchupAll and liveCatchup in cmd/discordctl/search.goEnumerates every guild and open DM channel via /users/@me/guilds and /users/@me/channels, resolves per-scope retention cutoffs, and pages through Discord’s search endpoint (author_id=<me.ID>, max_id=<cutoff_snowflake>3). Each page of up to 25 hits is archived with surrounding context and attachment blobs into one segment before the page’s delete loop runs.
Incoming DM sweepsweepIncoming in cmd/discordctl/incoming.goReads each open DM and group DM newest-first down to the per-channel snowflake stored in state.json under incoming_watermarks, archiving other participants’ messages and attachments as kind: "incoming" records without generating any delete targets.
Offline decryptioncmd/discordctl/archive_cmd.godiscordctl archive subcommands read /data/archive using an age identity file on a trusted machine without reading DISCORD_TOKEN or opening network connections.

Operating modes: daemon, one-shot purge, and offline archive CLI

Section titled “Operating modes: daemon, one-shot purge, and offline archive CLI”
ModeSubcommandNetwork and tokenDefault retention cutoffPrimary use
Rolling daemondiscordctl run --watchRequires DISCORD_TOKEN14 days (RETENTION_DAYS), repeatable every 24 hours (INTERVAL_HOURS)Unattended container service sweeping all guilds and DMs on a schedule
Single passdiscordctl runRequires DISCORD_TOKEN14 days (RETENTION_DAYS)One-off full-account retention pass from a shell or cron job
Targeted wipediscordctl purgeRequires DISCORD_TOKEN0 days (deletes all matching messages in scope unless --retention-days or --before is passed)Immediate wipe of specific --guild or --channel scopes, optionally narrowed by --content, --after, and --before
Discovery previewdiscordctl searchRequires DISCORD_TOKENRead-only previewInspects matching messages across guilds or DMs before running purge
Offline archive readerdiscordctl archive cat | blob | verify | ingest-export | datasetNo token, no network callsNot applicableDecrypts segments and blobs, verifies SHA-256 digests, folds exports into the archive, or builds JSONL training sets

In compose.yaml, the service runs /discordctl run --watch with restart: unless-stopped, memory capped at 256 MiB, /data/state and /data/archive mounted read-write, and /data/export/Messages mounted read-only. Between passes, the daemon sleeps in 60 s increments (cmd/discordctl/run.go) and rewrites the heartbeat file (/data/state/heartbeat) on each tick so the container health check (["CMD", "/discordctl", "status", "--max-heartbeat-age", "36h"]) can distinguish a sleeping daemon from a wedged pass.

Discord user tokens have no refresh flow. When a condition requires operator action, park() in cmd/discordctl/run.go logs a banner, sends a high-priority webhook notification if NTFY_URL is configured, and blocks on select {} until SIGTERM so Docker does not spin in a restart loop:

  • Token rejected (401): triggered at startup, during preflight GetMe() before each pass, mid-pass during search/delete/archive calls, or by the scheduled-message outbox goroutine.
  • Identity changed: preflight GetMe() before each pass verifies that fresh.ID == me.ID; if the token now resolves to a different user ID, the daemon parks before issuing any search or delete call.
  • Archive misconfigured or unwritable: triggered when ARCHIVE_RECIPIENTS is empty or fails X25519 parsing while archiving is enabled, or when /data/archive fails directory creation, chmod, fsync, or rename.
  • State unwritable: triggered when /data/state cannot be created or written.
  • Restart burst: state.json tracks restart_burst and last_started_at; more than 5 startups within 600 s parks the container, and a successful GetMe() resets restart_burst to 0.
purge gotchaDetail
Search stemming and date boundsdiscordctl purge shares the liveCatchup engine and state.json format with discordctl run, but scopes its work to explicit --guild or --channel flags. Because Discord’s search API stems query words, purge --content <phrase> sends content to the search endpoint and then re-checks every returned hit locally via case-insensitive substring match in ScopedTarget.selects (cmd/discordctl/search.go), skipping non-matching hits without marking them deleted. Date bounds (--after and --before) are parsed strictly as YYYY-MM-DD, RFC3339, or RFC3339Nano; --before can only narrow the retention cutoff (min(beforeSF, cutoffSF)), and --after >= cutoff exits with code 2.
Shared flag defaults and Go init() orderBoth run and purge bind shared package-level flag variables (retentionDays, deleteDelay, searchDelay, statePath, and the archive* flags). Go executes init() functions in filename order, so search.go registers purge’s default retentionDays = 0 after run.go registers 14. To prevent run from inheriting 0 when --retention-days is omitted on the command line, both commands call resolveFloat, resolveString, resolveBool, and resolveSlice at the start of Run (cmd/discordctl/run.go, cmd/discordctl/archiver.go), checking cmd.Flags().Changed(name) before falling back to environment variables and per-command defaults.

Archiving is enabled by default and fails closed (internal/archive/config.go). Unless --no-archive (ARCHIVE_DISABLED=1) is explicitly set, LoadConfig requires at least one valid X25519 public key in --archive-recipient (ARCHIVE_RECIPIENTS)4. A malformed recipient string returns an error immediately.

For each page of search hits in liveCatchup (cmd/discordctl/search.go), arch.archivePage (cmd/discordctl/archiver.go) builds one archive.Record per hit before any DELETE request is sent for that page:

  1. Anchor record construction: stores the raw JSON message object from the search hit (h.Raw), the resolved guild and channel metadata (GuildRef and ChannelRef), kind: "anchor", source: "live", and the UTC archived_at timestamp.
  2. Context window fetch (FetchAround): when ARCHIVE_CONTEXT is greater than 0 (default 100, clamped to Discord’s 1..100 limit because 101 returns HTTP 400 code 500355), the archiver calls GET /channels/{id}/messages?around=<msgID>&limit=100. To avoid redundant fetches when several deleted messages sit near each other in the same channel, a.windows[channelID] caches the [minID, maxID] snowflake bounds of every successful FetchAround in the current pass. If a later anchor ID falls within an existing window, the network call is skipped and the record sets context_covered: true.
  3. Attachment streaming (PutBlobStream): attachments on the anchor message and on context messages are fetched from Discord’s CDN using a separate discord.Downloader (internal/discord/client.go) that never attaches the Authorization header to signed CDN URLs. Bytes stream through io.MultiWriter(enc, sha256) directly into blobs/.<attachment_id>.age.tmp, keeping memory bounded to the age chunk size (avoiding 256 MiB container OOM kills on large video attachments), then fsync, rename to blobs/<attachment_id>.age, and fsync the blobs/ directory (internal/archive/writer.go). Because Discord attachment snowflakes are globally unique, HasBlob skips any attachment ID whose .age file already exists on disk.
  4. Segment commit (Writer.Commit): all non-deferred records for the page are marshalled as JSON Lines, compressed with gzip.BestCompression, encrypted to ARCHIVE_RECIPIENTS, and written to segments/YYYY/MM/<unixnano>-<8_hex_rand>.jsonl.gz.age via temporary file fsync, atomic rename, and directory fsync (including parent YYYY/ and MM/ directories).

discordctl enforces at three boundaries that it never attempts to delete another user’s message:

  1. Search query construction (SearchMessages in internal/discord/client.go): every /guilds/{id}/messages/search and /channels/{id}/messages/search call sets author_id to the authenticated user’s ID returned by /users/@me.
  2. Type separation in the archiver (cmd/discordctl/archiver.go and cmd/discordctl/incoming.go): FetchAround and FetchPage return []json.RawMessage containing messages from all channel participants. Those slices are placed exclusively into archive.Record.Context or kind: "incoming" records; only discord.SearchResult slices from SearchMessages and export.Message slices from the user’s export directory reach DeleteMessage.
  3. Non-retryable 403 on delete (DeleteMessage in internal/discord/client.go): if a DELETE call ever returns HTTP 403 (without error code 50083 or 50021), it maps to "forbidden", increments discord_wipe_deletes_total{outcome="forbidden"}, marks the ID in state.json, and never retries within the pass.

Discord enforces per-route rate limits communicated through response headers and global rate limits communicated via HTTP 429 payloads1. discordctl combines header-driven pacing with hard minimum delays and per-scope 429 floors (internal/discord/client.go, cmd/discordctl/config.go, cmd/discordctl/search.go).

On every 204 or 404 from DeleteMessage, 200 from SetThreadArchived, and 200 from FetchAround/FetchPage, bucketPacing(resp) inspects X-RateLimit-Remaining (rem) and X-RateLimit-Reset-After (reset, in seconds):

Header stateReturned pacing hint (RetryAfter)Behaviour
Headers absent or unparseable0 sCaller uses configured deleteDelay (default 1.0 s)
rem == 0 and reset > 0resetBucket exhausted on this call; wait the full reset window before next request
rem > 0 and reset > 0reset / float64(rem)Spreads remaining requests evenly across the bucket’s remaining window

Within each target scope in liveCatchup (and each channel in phaseExport), the delete loop maintains two floating-point timers alongside the configured deleteDelay (DELETE_DELAY, default 1.0 s): extraSleep and floor429.

  • When DeleteMessage returns "retry" on HTTP 429, parseRetryAfter reads retry_after from the JSON response body (falling back to the Retry-After header, or 1 s if both are zero). The loop sets extraSleep = result.RetryAfter and floor429 = result.RetryAfter, sleeps for result.RetryAfter, and retries the same message ID.
  • On subsequent "ok" or "gone" responses in the same scope, if result.RetryAfter > 0, extraSleep updates to max(result.RetryAfter, floor429). Once a scope hits a 429, inter-delete sleep for that scope never drops below floor429 even if later bucket headers advertise a shorter reset / rem ratio.
  • After each message is processed, the loop sleeps max(deleteDelay, extraSleep).
  • requireDeleteDelayFloor() in cmd/discordctl/config.go enforces minDeleteDelay = 0.3 s across run and purge, exiting with code 2 if --delete-delay or DELETE_DELAY is set below 0.3 s. Policy files (config.toml) also enforce minSearchDelay = 1.0 s (default SEARCH_DELAY = 15.0 s).
  • Transient transport errors inside Client.doBody retry up to DefaultRetry = 8 attempts with exponential backoff 2.0 * 2^(attempt - 1) s capped at RetryCap = 30.0 s (internal/discord/client.go). Search endpoints treat HTTP 202 (search index building), 429, 5xx, and JSON decode errors as unknown states with a retry hint; 8 consecutive search retries (retryStreak >= 8) skip the scope for the current pass without marking any messages deleted.

Retention overrides and channel carve-outs

Section titled “Retention overrides and channel carve-outs”

In discordctl run, retention cutoffs can be tuned per guild, channel, or channel category:

FlagEnvironment variablePurpose
--retention-overrideRETENTION_OVERRIDESPer-guild, per-channel or per-category retention cutoff
--exclude-guildEXCLUDE_GUILDSSkip a whole guild
--exclude-channelEXCLUDE_CHANNELSSkip a channel
TOML policy file$XDG_CONFIG_HOME/discordctl/config.toml or DISCORDCTL_CONFIGThe same policy in a file, parsed in cmd/discordctl/config.go and cmd/discordctl/overrides.go

Each override entry uses the 3-part syntax <scope>:<id>:<days>, where <days> is a non-negative float (0 deletes all messages in that scope on every pass):

Precedence (highest to lowest)Rule syntaxScope matched
1--exclude-guild <id> / --exclude-channel <id> (or exclude = true in TOML)Skips the guild, server channel (plus its threads), DM, or group DM completely
2channel:<snowflake>:<days>Specific server channel (and its threads), DM, or group DM
3guild:<snowflake>:<days>Specific guild
4kind:dm:<days> / kind:groupdm:<days> / kind:discoverable:<days>All 1-on-1 DMs (Type == 1), group DMs (Type == 3), or guilds whose features array includes "DISCOVERABLE"
5--retention-days <days> (RETENTION_DAYS, default 14)Global fallback across all remaining guilds and DMs

Any malformed entry in RETENTION_OVERRIDES or unknown key in config.toml terminates discordctl run with exit code 2 before any API call is made, preventing a typo from falling through to a shorter retention window.

Server-channel carve-outs and thread ownership

Section titled “Server-channel carve-outs and thread ownership”

Discord’s guild search endpoint (/guilds/{id}/messages/search) searches the entire guild unless channel_id is passed, and a search with channel_id=<parent> returns hits from both the parent channel and its child threads. When a server channel has an override or exclusion, phaseLiveCatchupAll (cmd/discordctl/run.go and cmd/discordctl/overrides.go) resolves each configured channel ID via GET /channels/{id} (resolveChannelGuilds) to find its guild_id:

  • If GET /channels/{id} returns any error other than 403 or 404 (or terminal 401), phaseLiveCatchupAll skips all guild targets for that pass so a transient failure cannot cause a protected channel to be swept under its parent guild’s shorter cutoff.
  • buildRunTargets places every carved channel ID for a guild into a shared SkipChannels map on both the guild-wide ScopedTarget (ChannelID: "") and each carved channel’s dedicated ScopedTarget (ChannelID: cid).
  • When a search response arrives, SearchMessages maps top-level threads[].id -> threads[].parent_id onto each SearchResult.ParentID (internal/discord/client.go). ScopedTarget.selects (cmd/discordctl/search.go) assigns each hit a single owner: m.ChannelID if that ID is in SkipChannels, else m.ParentID if the thread’s parent channel is in SkipChannels, else "" (the guild-wide target). A target processes only hits whose computed owner equals t.ChannelID. Excluded channels are placed in SkipChannels without generating a channel target, so no target selects their messages or threads.
  • In phaseExport, export rows lack a parent_id field for threads. Whenever any server-channel override or exclusion is active (deferThreads == true in cmd/discordctl/run.go and exportChannelDays in cmd/discordctl/overrides.go), the export phase skips all *_THREAD export folders and leaves them to liveCatchup, which has thread parent metadata from the search API.

Encrypted archive format and offline decryption

Section titled “Encrypted archive format and offline decryption”

The archive directory (/data/archive, mode 0700) contains two subdirectories (segments/ and blobs/, both mode 0700) and stores no plaintext files (internal/archive/writer.go, internal/archive/record.go):

/data/archive/
├── segments/
│ └── 2026/
│ └── 10/
│ └── 1760227200000000000-a1b2c3d4.jsonl.gz.age
└── blobs/
└── 111111111111111111.age
  • Segments: segments/YYYY/MM/<unixnano>-<8_hex_rand>.jsonl.gz.age (mode 0600). Decrypting with age and decompressing with gzip yields UTF-8 JSON Lines, one archive.Record per line. Because filenames start with time.Now().UnixNano(), lexicographical path order matches chronological commit order.
  • Blobs: blobs/<attachment_id>.age (mode 0600), holding the raw attachment bytes encrypted to ARCHIVE_RECIPIENTS. Filenames on disk use only the numeric Discord attachment ID (validAttachmentID rejects non-digit characters as a path-traversal guard); the original filename, content_type, size, and plaintext sha256 hex digest are stored inside the Record.Blobs array in the segment JSONL.

Each JSONL line in a segment has the archive.Record schema (internal/archive/record.go):

{
"v": 1,
"kind": "anchor",
"source": "live",
"archived_at": "2026-10-12T00:00:00Z",
"guild": { "id": "111111111111111111", "name": "Example Guild" },
"channel": { "id": "222222222222222222", "name": "general", "type": 0, "parent_id": "" },
"message": { "id": "333333333333333333", "channel_id": "222222222222222222", "content": "example message" },
"context": [],
"context_covered": false,
"context_error": "",
"blobs": [
{
"attachment_id": "444444444444444444",
"message_id": "333333333333333333",
"filename": "diagram.png",
"content_type": "image/png",
"size": 18432,
"sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"error": ""
}
]
}

To inspect or process the archive on a machine holding the age private key file (keys.txt), mount or sync /data/archive read-only and run the token-less discordctl archive subcommands (cmd/discordctl/archive_cmd.go):

Terminal window
# Stream all records in chronological order as JSONL to stdout
discordctl archive cat \
--identity /run/secrets/discord-archive-key.txt \
--archive-dir /data/archive
# Stream only segments committed at or after an RFC3339 timestamp
# (skips older segments by filename prefix before decryption, so a key added
# to ARCHIVE_RECIPIENTS at that timestamp can read newer segments cleanly)
discordctl archive cat \
--identity /run/secrets/discord-ingest-key.txt \
--archive-dir /data/archive \
--since 2026-10-15T00:00:00Z
# Stream a single decrypted attachment blob to stdout (never writes plaintext to disk;
# exits 0 on success, 3 if missing, 4 if the identity cannot decrypt the blob)
discordctl archive blob 444444444444444444 \
--identity /run/secrets/discord-archive-key.txt \
--archive-dir /data/archive > diagram.png
# Decrypt every segment and referenced blob, recompute SHA-256 digests, and report counts
discordctl archive verify \
--identity /run/secrets/discord-archive-key.txt \
--archive-dir /data/archive
# Sessionise decrypted anchors and context into an LLM fine-tuning JSONL dataset
discordctl archive dataset \
--identity /run/secrets/discord-archive-key.txt \
--archive-dir /data/archive \
--gap 1h --min-turns 2 \
--out /tmp/discord-sessions.jsonl

Known Discord delete errors and pagination guards

Section titled “Known Discord delete errors and pagination guards”

Discord returns specific JSON error codes inside HTTP 400 and 403 bodies when a message cannot be deleted in its current state2. DeleteMessage (internal/discord/client.go) parses {message, code} from the response body and maps these codes to dedicated status strings so liveCatchup and phaseExport can handle them without stalling pagination.

HTTP status and JSON codeDeleteResult.StatusMeaning in Discord APIdiscordctl action
204 No Content"ok"Message deletedMarks ID in state.Deleted, increments ok counter, paces via bucketPacing
404 Not Found"gone"Message already deletedMarks ID in state.Deleted, increments gone counter, paces via bucketPacing
400 or 403 with code: 50083"archived"Thread is archived - messages inside an archived thread cannot be deleted until the thread is unarchived2Queues msgID in pendingArchived[channelID] without marking it deleted; at the end of the page or channel batch, drainArchivedThreads calls PATCH /channels/{id} with {"archived": false}6, deletes the queued messages, marks them in state.Deleted, and calls PATCH /channels/{id} with {"archived": true}
400 or 403 with code: 50021"nondeletable"Cannot execute action on a system message (recipient pins, call notifications, boosts, thread-created notices)2Calls st.Mark(id) and st.MarkNondeletable(id) so the ID is persisted in state.json under both deleted and nondeletable, then skips it on all future passes
400 or 403 (any other code)"forbidden"Missing permissions or locked resourceMarks ID in state.Deleted for the current state, increments forbidden counter; if a whole page of marked messages still appears in search on a later pass, liveCatchup re-attempts non-50021 messages at most once per pass (retriedThisPass)
401 Unauthorized"auth" (*AuthError)User token rejected or rotatedSaves state.json immediately and parks the daemon (or exits 2 in purge)

Keyset pagination past stuck messages (advanceMaxID)

Section titled “Keyset pagination past stuck messages (advanceMaxID)”

Discord’s search endpoint returns 25 hits per page, ordered newest-first. When a scope contains more than 25 permanently undeletable messages (such as 50021 system messages, locked threads where PATCH /channels/{id} returns 403, or hits deferred by an attachment download failure), a naive loop that always queries from cutoffSF would fetch the same 25 stuck messages on every page and never reach older deletable messages behind them.

liveCatchup (cmd/discordctl/search.go) avoids this trap with keyset pagination:

  • Each scope starts with maxID = t.CutoffSF.
  • When a page has zero new deletable hits (all hits are filtered out, deferred, marked nondeletable, or already retried once this pass) or when a page’s work was entirely deferred by the archiver (!issuedDelete), advanceMaxID sets maxID to the minimum message snowflake on the page (minHitID(hits)). Because Discord’s max_id query parameter is exclusive, the next search query fetches messages strictly older than the oldest stuck message on the current page.
  • If drainArchivedThreads cannot unarchive a thread (SetThreadArchived returns "forbidden" or "gone"), the queued message IDs are left unmarked in state.json so a future pass can retry if permissions change, and are added to sweepDeferred for the remainder of the current pass so advanceMaxID steps past them instead of re-querying the same page indefinitely.

What operation are you running?Do you need different windowsper guild or channel?scheduled account-wide retentionAre you reading or buildingfrom an existing archive?inspecting archived datadiscordctl search (preview)then discordctl purge--guild / --channelimmediate one-off wipeof a guild or channeldiscordctl run --watchwith global RETENTION_DAYSand ARCHIVE_RECIPIENTSnodiscordctl run --watch+ config.toml / RETENTION_OVERRIDES(carves channels via SkipChannels)yesdiscordctl archivecat / blob / verify / datasetwith --identity on offline copyyes (no token needed)

The same decision paths as a numbered list:

  1. Scheduled account-wide retention with one cutoff: run discordctl run --watch with RETENTION_DAYS and ARCHIVE_RECIPIENTS set to your age public key.
  2. Scheduled retention with per-guild, per-channel, or DM exceptions: run discordctl run --watch with config.toml or RETENTION_OVERRIDES (guild:<id>:<days>, channel:<id>:<days>, kind:dm:<days>, kind:groupdm:<days>, kind:discoverable:<days>) and EXCLUDE_GUILDS / EXCLUDE_CHANNELS.
  3. Immediate targeted wipe of one server, channel, or phrase: preview matches with discordctl search --guild <id> --content <phrase>, then execute discordctl purge --guild <id> --content <phrase>, which archives every matched message before deleting it at a 0-day default cutoff.
  4. Reading or verifying archived messages and attachments: sync /data/archive to a machine holding the age private identity and run discordctl archive cat, discordctl archive blob, discordctl archive verify, or discordctl archive dataset offline without DISCORD_TOKEN.

Claim or behaviourStatusHow it was checked
Archive commit failure prevents any DELETE call for that page (liveCatchup) or channel (phaseExport)TestedTestArchiveCommitFailureZeroDeletes and TestExportPhaseArchiveCommitFailureNoDeletes in cmd/discordctl/archiver_test.go
Context messages from FetchAround and incoming DM messages never become delete targetsTestedTestArchiveInvariantOnlySearchHitsDeleted in cmd/discordctl/archiver_test.go; TestIncomingSweepClientCannotDelete in cmd/discordctl/incoming_test.go
Retry-exhausted anchor attachment defers the hit without deleting or marking it; failed context attachment records blob error and still deletes anchorTestedTestArchiveOwnAttachmentRetryExhaustedDefersHit, TestArchiveOwnAttachmentStoreFailureZeroDeletes, and TestArchiveContextAttachmentStoreFailureStillDeletes in cmd/discordctl/archiver_test.go
Partial CDN download stream is discarded on retry and only the clean attempt lands in .age blobTestedTestBug8RetryAfterPartialStreamStoresOnlyGoodBytes in cmd/discordctl/archiver_test.go; TestDownloaderNeverSendsAuthorization and TestDownloaderTooLargeOnStream in internal/discord/client_archive_test.go
Segments and blobs contain no plaintext on disk, enforce 0700/0600 modes, and reject non-numeric attachment IDsTestedTestSegmentNotPlaintext, TestBlobNotPlaintextAndModes, and TestPutBlobRejectsPathTraversal in internal/archive/archive_test.go
bucketPacing computes reset when remaining == 0 and reset / remaining when remaining > 0TestedTestBucketPacing and TestDelete429ReturnsRetryAfter in internal/discord/client_test.go
Error 50083 queues archived thread messages for SetThreadArchived(false) -> delete -> SetThreadArchived(true), and skips unmarked when unarchive returns 403TestedTestDeleteArchivedThreadCodeIsArchived in internal/discord/client_test.go; TestExportPhaseArchivedDrainSuccess and TestExportPhaseArchivedCannotUnarchive in cmd/discordctl/export_archived_test.go
Error 50021 on HTTP 400 or 403 marks the message nondeletable in state.json and skips it on subsequent passes and all-done page retriesTestedTestDelete400SystemMessageCodeIsNondeletable and TestDelete403SystemMessageCodeIsNondeletable in internal/discord/client_test.go; TestNondeletableNotReattemptedSecondPass and TestNondeletableMixedAllDonePage in cmd/discordctl/catchup_test.go
Server-channel overrides and exclusions carve the channel and its threads out of guild search targets, and defer *_THREAD rows in the export phaseTestedTestBuildRunTargets and TestExportChannelDays in cmd/discordctl/overrides_test.go; TestExportPhaseDefersThreadsUnderChannelExclude in cmd/discordctl/archiver_test.go
archive cat --since filters segment filenames by unixnano prefix before decryption so a newer ingest key can read post-rotation segmentsTestedTestOpenSegmentsSinceSkipsOldSegments and TestOpenSegmentsSinceUndecryptableInWindowErrors in internal/archive/reader_since_test.go; TestArchiveCatSincePrintsOnlyNewerRecords in cmd/discordctl/archive_cmd_test.go
minDeleteDelay = 0.3 s floor avoids account-level anti-abuse flags on sustained bulk deletesDesign-onlyEnforced in requireDeleteDelayFloor() (cmd/discordctl/config.go); Discord does not publish user-account anti-abuse thresholds

GotchaDetail
Dry-run state persistence (Bug15)in an early version, --dry-run called st.Mark(id) and persisted state.json at the end of the pass, causing the next real pass to skip every message the dry run had visited. State.SetDryRun(true) (internal/state/state.go) keeps Mark() in memory for single-pass deduplication while Save() touches only the /data/state/heartbeat file and leaves state.json and state.json.bak untouched.
Unarchived thread drain infinite loop (Bug20)when a thread is locked or the user lacks permission to unarchive it, SetThreadArchived(chID, false) returns "forbidden" and drainArchivedThreads leaves the message IDs unmarked in state.json. Without adding those IDs to sweepDeferred for the rest of the current sweep (cmd/discordctl/search.go), liveCatchup saw them as new work on the next iteration and re-queried the same keyset page forever.
Deferred-only page keyset stall (Bug19)when every new hit on a search page had its anchor attachment fail download retries, archivePage deferred all of them and the delete loop issued zero DELETE calls. Because the messages still existed on Discord, the next search query with the same max_id returned the identical page. Tracking issuedDelete and calling advanceMaxID whenever !issuedDelete advances the keyset bound past the deferred page so older messages behind it are still swept.
Newly created year/month directory durabilityos.MkdirAll creates segments/YYYY/MM, and writeFile fsyncs the segment file and MM/. On a crash immediately after a month rollover, the new YYYY/ or MM/ directory entry itself could be lost unless its parent directory is also synced; Writer.Commit (internal/archive/writer.go) explicitly calls syncDir on both filepath.Dir(segDir) and filepath.Dir(filepath.Dir(segDir)).
Key rotation with archive cat --sinceOpenSegments fails hard if any segment cannot be decrypted by the provided identity file. When adding a secondary age recipient (such as a dedicated ingest key for downstream indexing) to ARCHIVE_RECIPIENTS on an existing archive, pass --since <RFC3339> to discordctl archive cat; OpenSegmentsSince (internal/archive/reader.go) filters segment paths by their <unixnano> filename prefix before calling age.Decrypt.

  1. Discord, “Rate Limits,” Discord Developer Documentation. https://github.com/discord/discord-api-docs/blob/HEAD/developers/topics/rate-limits.mdx ↩ ↩2

  2. Discord, “Opcodes and Status Codes - JSON Error Codes,” Discord Developer Documentation. https://github.com/discord/discord-api-docs/blob/HEAD/developers/topics/opcodes-and-status-codes.mdx ↩ ↩2 ↩3 ↩4

  3. Discord, “API Reference - Snowflakes,” Discord Developer Documentation. https://github.com/discord/discord-api-docs/blob/HEAD/developers/reference.mdx ↩

  4. Filippo Valsorda, “age - simple, modern and secure file encryption,” GitHub. https://github.com/FiloSottile/age/blob/HEAD/README.md ↩

  5. Discord, “Message Resource,” Discord Developer Documentation. https://github.com/discord/discord-api-docs/blob/HEAD/developers/resources/message.mdx ↩

  6. Discord, “Channels Resource - Modify Channel,” Discord Developer Documentation. https://github.com/discord/discord-api-docs/blob/HEAD/developers/resources/channel.mdx ↩