stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
daa6a4ae8ce372f398c450eeaaafcd079ca5ea46
git.stella-ops.org/src/StellaOps.Scanner.Storage/AGENTS.md
master daa6a4ae8c
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
Build Test Deploy / build-test (push) Has been cancelled
Details
Build Test Deploy / authority-container (push) Has been cancelled
Details
Build Test Deploy / docs (push) Has been cancelled
Details
Build Test Deploy / deploy (push) Has been cancelled
Details
up
2025-10-19 10:38:55 +03:00

2.7 KiB
Raw Blame History

AGENTS

Role

Provide durable catalog and artifact storage for the Scanner plane, spanning Mongo catalog collections and MinIO object storage. Expose repositories and services used by WebService and Worker components to persist job state, image metadata, and exported artefacts deterministically.

Scope

  • Mongo collections: artifacts, images, layers, links, jobs, lifecycle_rules, migrations.
  • Metadata documents: enforce majority write/read concerns, UTC timestamps, deterministic identifiers (SHA-256 digests, ULIDs for jobs).
  • Bootstrapper: create collections + indexes (unique digests, compound references, TTL on lifecycle rules, sparse lookup helpers) and run schema migrations.
  • Object storage (MinIO/S3): manage bucket layout (layers/, images/, indexes/, attest/), immutability policies, deterministic paths, and retention classes.
  • Services: coordinate dual-write between Mongo metadata and MinIO blobs, compute digests, manage reference counts, and expose typed repositories for WebService/Worker interactions.

Participants

  • Scanner.WebService binds configuration, runs bootstrapper during startup, and uses repositories to enqueue scans, look up catalog entries, and manage lifecycle policies.
  • Scanner.Worker writes job progress, uploads SBOM artefacts, and updates artefact reference counts.
  • Policy / Notify consumers resolve artefact metadata for reports via catalog APIs once exposed.

Interfaces & contracts

  • Options configured via ScannerStorageOptions (Mongo + object store). EnsureValid rejects incomplete/unsafe configuration.
  • Mongo access uses IMongoDatabase scoped with majority ReadConcern/WriteConcern and cancellation tokens.
  • Object store abstraction (IArtifactObjectStore) encapsulates MinIO (S3) operations with server-side checksum validation and optional object-lock retain-until.
  • Service APIs follow deterministic naming: digests normalized (sha256:<hex>), ULIDs sortable, timestamps ISO-8601 UTC.

In/Out of scope

In: persistence models, bootstrap/migrations, catalog repositories, object storage client, retention helpers, dual-write coordination, deterministic digests. Out: HTTP endpoints, queue processing, analyzer logic, SBOM composition, policy decisions, UI contracts.

Observability & security expectations

  • Emit structured logs for catalog/object-store writes including correlation IDs and digests.
  • Guard against double writes; idempotent operations keyed by digests.
  • Do not log credentials; redact connection strings. Honour cancellation tokens.
  • Metrics hooks (pending) must expose duration counters for Mongo and MinIO operations.

Tests

  • Integration tests with ephemeral Mongo/MinIO stubs covering bootstrapper indexes, TTL enforcement, dual-write coordination, digest determinism, and majority read/write concerns.