Architecture, Code Map & Decisions
One Real Run Walkthrough
Every scheduled tick or manual command follows five verifiable stages (for the full line-by-line engineering walkthrough, inspect repo-docs/walkthroughs/one-real-run.md):
- Config Normalization & Discovery (
watch/config.py,watch/sources.py):load()resolves WebUI settings orRESOURCE_WATCH_CONFIG;Source.discover()returns a normalizedDiscoveredsnapshot. If the primary endpoint fails,Monitor._diagnose_entry_failurechecksentry_urlsand a non-expiredlast_good_snapshotfor non-authoritativeunknown=Truecontext. - Sanity Gates & Consensus (
watch/probes.py): Mutation, version non-regression, trailing slash, and SSRF checks run beforeSemaphore(4)fetchesmanifest.json.check_manifest_consistencyrequires a strict majority before approving baseline entries for chunk checks. - Separated Fast & Slow Cycles (
watch/runner.py,watch/scheduler.py): Fast cycles (300s) step deterministically throughRotationtriples and record 7-day coverage only for verified 206 MD5 chunks. Slow cycles (3600s) useSemaphore(2)under an independent lock to validateversion_files, eligible hot packages (disabled whenallow_heavy=False), and daily TLS expiry. - Alert Convergence & Atomic State (
watch/state.py,watch/store.py): Results carry suppression keys intoAlertState'sM-of-Nwindow; pending notifications persist alongside coverage state in<state_dir>/watch-state.json. - Per-Recipient Recheck & Official Ack (
main.py):_flush_outboxchecks_discard_stalebefore each session send. Onqq_official/qq_official_webhook, successful submission recordssubmittedand awaits an admin's/线路 通知followed by/线路 确认in that exact session.
Interactive Architecture Diagram
Diagram note: The interactive topology summarizes host integration, SSRF/command guards, and alert channels; actual
watch/probes inspect distribution configs, manifests, HTTP Range slices, MD5 digests, and TLS certs rather than host CPU or memory.
Code Map & Verification Workflow
| Area | Responsibility | Associated Tests |
|---|---|---|
main.py | AstrBot Star lifecycle, /线路 routing, persistent outbox, QQ official ack | tests/test_plugin_loading.py, tests/test_delivery.py, tests/test_qq_official.py |
watch/config.py, sources.py, discovery.py | Config precedence/clamping, endpoint/mirrors sources, JSON parsers | tests/test_config.py, tests/test_sources.py, tests/test_discovery.py |
watch/http.py, probes.py, models.py | Public IP resolution, redirect pinning, streaming digest, 10 probes | tests/test_probes.py, tests/test_network_regressions.py |
watch/runner.py, scheduler.py | Fast/slow orchestration, degraded fallback, 7-day Rotation & Ticker | tests/test_runner.py, tests/test_scheduler.py, tests/test_monitor_regressions.py |
watch/state.py, store.py | AlertState windows, suppression tree, mute retention, JSON store | tests/test_state.py, tests/test_state_regressions.py, tests/test_store.py |
watch/commands.py, render.py | CommandGate, impact rendering, safe() & clamp() sanitization | tests/test_commands.py, tests/test_render.py |
tools/check-no-endpoints.py | Static endpoint, mirror, and credential leak guardrail | tests/test_guardrail_endpoints.py, tests/test_guardrail_regressions.py |
Run offline verification (252 unit tests total; 5 AiohttpBoundaryTest cases skip when system python3 lacks aiohttp):
sh
python3 -m unittest discover -s tests -t . -v
python3 tools/check-no-endpoints.py --verbose
python3 -m compileall -q tools watch main.pyKey Architectural Decisions (ADRs) & Migration
- ADR-1 (MD5 + Manifest
chunk_size): Uses each manifest's declaredchunk_sizeand 32-hex chunk MD5s instead of SHA-256 or a hardcoded 16 MiB slice so probe verdicts stay identical to the distribution client's own validation. - ADR-2 (Deterministic Rotation vs Random Sampling): Persistent
(mirror, file, chunk)cursor rotation keeps traffic bounded per cycle while giving/线路 覆盖率an auditable 7-day byte coverage metric. - ADR-3 (No Default
entry_url& SeparateUser-Agent): Refusing to fall back to a baked-in entrypoint prevents false green monitoring on unconfigured deployments;resource-watch/1.0keeps CDN logs separable from real user downloads.
Configuration Migration Summary
| Legacy / Example Syntax | Current Runtime Contract | Action Needed |
|---|---|---|
alert.fire_after: [2, 3], alert.recover_after: 2 (config.example.json) | alert.fire_after_failures: 2, alert.fire_window: 3, alert.recover_after_successes: 2 | Replace legacy array/shorthand keys when adapting config.example.json |
Top-level entry_url + mirrors set together | entry_url wins whenever non-empty | Clear entry_url if switching to static mirrors mode |