Skip to content

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):

  1. Config Normalization & Discovery (watch/config.py, watch/sources.py): load() resolves WebUI settings or RESOURCE_WATCH_CONFIG; Source.discover() returns a normalized Discovered snapshot. If the primary endpoint fails, Monitor._diagnose_entry_failure checks entry_urls and a non-expired last_good_snapshot for non-authoritative unknown=True context.
  2. Sanity Gates & Consensus (watch/probes.py): Mutation, version non-regression, trailing slash, and SSRF checks run before Semaphore(4) fetches manifest.json. check_manifest_consistency requires a strict majority before approving baseline entries for chunk checks.
  3. Separated Fast & Slow Cycles (watch/runner.py, watch/scheduler.py): Fast cycles (300s) step deterministically through Rotation triples and record 7-day coverage only for verified 206 MD5 chunks. Slow cycles (3600s) use Semaphore(2) under an independent lock to validate version_files, eligible hot packages (disabled when allow_heavy=False), and daily TLS expiry.
  4. Alert Convergence & Atomic State (watch/state.py, watch/store.py): Results carry suppression keys into AlertState's M-of-N window; pending notifications persist alongside coverage state in <state_dir>/watch-state.json.
  5. Per-Recipient Recheck & Official Ack (main.py): _flush_outbox checks _discard_stale before each session send. On qq_official / qq_official_webhook, successful submission records submitted and awaits an admin's /线路 通知 followed by /线路 确认 in that exact session.

Interactive Architecture Diagram ​

Host Integration, SSRF Guard & Delivery Topology (Pan / Zoom)
Open Fullscreen

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 ​

AreaResponsibilityAssociated Tests
main.pyAstrBot Star lifecycle, /线路 routing, persistent outbox, QQ official acktests/test_plugin_loading.py, tests/test_delivery.py, tests/test_qq_official.py
watch/config.py, sources.py, discovery.pyConfig precedence/clamping, endpoint/mirrors sources, JSON parserstests/test_config.py, tests/test_sources.py, tests/test_discovery.py
watch/http.py, probes.py, models.pyPublic IP resolution, redirect pinning, streaming digest, 10 probestests/test_probes.py, tests/test_network_regressions.py
watch/runner.py, scheduler.pyFast/slow orchestration, degraded fallback, 7-day Rotation & Tickertests/test_runner.py, tests/test_scheduler.py, tests/test_monitor_regressions.py
watch/state.py, store.pyAlertState windows, suppression tree, mute retention, JSON storetests/test_state.py, tests/test_state_regressions.py, tests/test_store.py
watch/commands.py, render.pyCommandGate, impact rendering, safe() & clamp() sanitizationtests/test_commands.py, tests/test_render.py
tools/check-no-endpoints.pyStatic endpoint, mirror, and credential leak guardrailtests/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.py

Key Architectural Decisions (ADRs) & Migration ​

  • ADR-1 (MD5 + Manifest chunk_size): Uses each manifest's declared chunk_size and 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 & Separate User-Agent): Refusing to fall back to a baked-in entrypoint prevents false green monitoring on unconfigured deployments; resource-watch/1.0 keeps CDN logs separable from real user downloads.

Configuration Migration Summary ​

Legacy / Example SyntaxCurrent Runtime ContractAction 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: 2Replace legacy array/shorthand keys when adapting config.example.json
Top-level entry_url + mirrors set togetherentry_url wins whenever non-emptyClear entry_url if switching to static mirrors mode