ITWorx Pulse release export
bd774932d5
Public source validation / validate (push) Failing after 3m8s
96 lines
2.4 KiB
Markdown
96 lines
2.4 KiB
Markdown
# Backend and worker standards
|
|
|
|
## Domain boundaries
|
|
|
|
Core packages define:
|
|
- entities and reconciliation;
|
|
- metrics query model;
|
|
- dashboard validation/versioning;
|
|
- events;
|
|
- alert state machine;
|
|
- incidents;
|
|
- authorization policies.
|
|
|
|
Adapters implement:
|
|
- PostgreSQL;
|
|
- Prometheus;
|
|
- Unraid;
|
|
- Docker/constrained collector;
|
|
- OIDC;
|
|
- probes;
|
|
- notifications.
|
|
|
|
Domain packages must not import HTTP handlers or concrete adapters.
|
|
|
|
## HTTP
|
|
|
|
- Route groups map to modules.
|
|
- Middleware order is explicit.
|
|
- Request body, query and path validation.
|
|
- Body size limits.
|
|
- Timeouts and cancellation.
|
|
- Stable error mapping.
|
|
- Structured request log with redaction.
|
|
- Health/live and readiness separated.
|
|
- No mutation route for host/Docker/storage.
|
|
|
|
## Worker
|
|
|
|
- Jobs have stable keys and schedules.
|
|
- Database lock/lease prevents duplicate execution.
|
|
- Work is idempotent.
|
|
- Retries are bounded with jitter.
|
|
- Poison/repeated failures become visible system status.
|
|
- Shutdown waits for bounded graceful completion.
|
|
- Job result counts and duration recorded.
|
|
|
|
## Prometheus adapter
|
|
|
|
- Server-side only.
|
|
- Timeout and concurrency semaphore.
|
|
- Semantic templates only by default.
|
|
- Parse upstream warnings and staleness.
|
|
- Protect metadata/label endpoints.
|
|
- Normalize errors to stable codes.
|
|
- Instrument query duration/series/points/cache.
|
|
|
|
## Inventory reconciliation
|
|
|
|
- Stable source alias mapping.
|
|
- Snapshot can be repeated safely.
|
|
- Missing item becomes tombstoned after source-specific policy, not immediately deleted.
|
|
- User overrides remain separate.
|
|
- Relation source/confidence retained.
|
|
- Changes create deduplicated events.
|
|
- Source failure does not tombstone all entities.
|
|
|
|
## Alerts
|
|
|
|
- Deterministic state machine.
|
|
- Evaluation transaction/locking.
|
|
- Clock abstracted in tests.
|
|
- Unknown data explicit.
|
|
- Rule versions immutable.
|
|
- Notification side effects use outbox/idempotency pattern or equivalent.
|
|
- Acknowledgement does not mutate underlying firing condition.
|
|
|
|
## Database
|
|
|
|
- Context-aware queries.
|
|
- Parameterized SQL.
|
|
- Transaction boundaries documented.
|
|
- Pool limits.
|
|
- Repository methods return domain types/errors.
|
|
- Integration tests against real PostgreSQL.
|
|
- No production reliance on SQLite semantics.
|
|
|
|
## Agent
|
|
|
|
- Read-only capability list.
|
|
- No generic command execution endpoint.
|
|
- Authenticated/mutually trusted channel if remote.
|
|
- Bounded payloads.
|
|
- Version/capability negotiation.
|
|
- Local cache only where safe.
|
|
- Every elevated mount/capability justified and tested.
|