worker/docs

Worker Implementation Documents

This directory is the implementation authority for the standalone RSMon worker. It converts the worker-related plans formerly kept in the RSMon control-plane repository into contracts tied to this repository's packages and tests.

These documents distinguish three states:

• Implemented: wired into cmd/rsmon-worker and covered by tests.
• Partial: code exists, but a named runtime path or acceptance criterion is missing.
• Planned: no production path exists yet. The document identifies the package, protocol, dependency, and tests required to implement it.

Plans do not override code. When a document and the current implementation disagree, update both in the same change or mark the discrepancy explicitly.

Implementation Index

Document	Scope	Current state
architecture.md	Process boundaries, ownership, runtime composition	Implemented with partial subsystems
control-plane-protocol.md	WebSocket frames, leases, config, compatibility APIs	Implemented
tasks-and-notifications.md	Normal checks and delegated notification execution	Implemented with provider gaps
web-console-and-observability.md	Local UI, auth, inventory view, host telemetry	Partial
inventory.md	Worker host discovery and control-plane inventory projection	Partial
private-workers.md	Customer worker isolation, credentials, onboarding	Partial
network-diagnostics.md	Confirmation checks and dedicated diagnostic tasks	Partial
critical-check-cluster.md	Raft-backed dispatchless critical checks	Scaffold only
implementation-roadmap.md	Ordered repository work packages and release gates	Active
source-plan-migration.md	Source-to-target conversion ledger and resolved conflicts	Complete mapping

Ownership Boundary

This repository owns:

• worker process startup, configuration, and graceful shutdown;
• the control-plane client and wire types;
• check and notification execution;
• local web console, local state, inventory collection, and host metrics;
• worker-to-worker transport and Raft state;
• Docker, Compose, systemd, and release-image packaging.

The RSMon control-plane repository owns:

• users, accounts, monitors, contacts, billing, and RBAC;
• PostgreSQL task production, selection, leasing, retry, and dead-letter state;
• worker registration and authorization policy;
• accepted-result application and VictoriaMetrics persistence;
• customer-facing fleet, inventory, diagnostics, and incident APIs.

The worker must not receive control-plane PostgreSQL, Valkey, or VictoriaMetrics credentials. Normal results, host telemetry, inventory, and diagnostics are reported over authenticated protocol messages for validation and persistence by the control plane.

Required Quality Gates

Run before merging worker changes:

make check
docker build -t rsmon-worker:test .
docker run --rm rsmon-worker:test --version
docker compose config

Features that alter protocol messages require compatibility tests in internal/wire and runner protocol tests in internal/distworker. Raft work requires deterministic FSM tests and a multi-node fault test. Security-sensitive features require negative tests for account scope, arbitrary target rejection, credential redaction, and unauthenticated access.