pkg/

Package agentproto implements the protocol between service controllers and host agents (spec 02 §10, ADR-0005): the controller keeps every host's desired state in a Hub and serves it with HostAgentService; the agent's Client watches it (snapshot, then deltas with revisions), caches it on disk, applies it level-triggered and reports status.

Package apierr builds API errors in the qStack format (spec 02 §5.5): a gRPC status code plus google.rpc.ErrorInfo{reason: QS_*, domain: "qstack.cloud"} and, where relevant, BadRequest / QuotaFailure / RetryInfo details.

Package audit records audit trail events (spec 11 §3, REQ-OBS-010) and removes sensitive fields from requests in audit events and logs (REQ-SEC-005).

Package authz enforces IAM permissions in every public API (spec 03 §4, REQ-IAM-011, REQ-IAM-012).

Package clock is the only place allowed to read wall-clock time (enforced by the forbidigo linter).

Package config loads service configuration (spec 02 §14): a YAML file whose unknown keys are rejected, then QS_* environment overrides declared with `env` struct tags, then validation.

Package db is the PostgreSQL access layer shared by all services (spec 02 §7, ADR-0004): a pgx connection pool, transactions, optimistic locking, forward-only migrations and pool metrics.

Package events defines qStack events (spec 02 §8): the CloudEvents 1.0 envelope, NATS subjects and streams, a JetStream publisher and a consumer that processes every event exactly once against the consumer's database.

Package filter parses List filters (spec 02 §5.2, REQ-PLT-032):

Package grpcclient dials internal gRPC services (spec 01 §7, 02 §11): discovery by DNS (headless Service), client-side round_robin over healthy backends (gRPC health checking), a 5 s default timeout, retries only for UNAVAILABLE (at most 3, with gRPC's jittered backoff), and propagation of the caller context: x-request-id, x-qs-subject and traceparent.

Package idempotency makes mutating API calls safe to retry (spec 02 §5.4, REQ-PLT-050).

Package ids generates and parses resource IDs of the form `<prefix>-<ulid>` (spec 02 §3, REQ-PLT-020), e.g.

Package operation stores long-running operations (LRO, spec 02 §5.3) in the owner service's database (REQ-PLT-042).

Package outbox implements the transactional outbox (spec 02 §8, REQ-PLT-090): a change and its event are written in one transaction, and a relay running in the service's controller publishes the events to NATS JetStream and deletes them once acknowledged.

Package pagination implements List paging (spec 02 §5.2, REQ-PLT-031): page_size defaults to 100 and is capped at 1000; page_token is an opaque, HMAC-signed keyset cursor bound to the request parameters and valid for one hour.

Package protoopts reads qStack proto options declared in api/proto/qstack/api/annotations.proto: the IAM permission of an RPC and the sensitive marker of a field.

Package quota is the client of project quotas (spec 02 §12, 03 §5): a mutating method reserves the resources it is about to create for its operation, and the controller commits the reservation when the resource exists or releases it when the operation fails.

Package reconcile runs controllers (spec 02 §9): a Reconciler drives one resource at a time towards its desired state, fed by a deduplicating work queue with exponential backoff, by events and by periodic resync.

Package telemetry wires logging, metrics, tracing and health endpoints the same way in every qStack binary (spec 02 §13).

Package testenv provides real infrastructure for integration tests (build tag `integration`, spec 14 §1).

Package validate checks requests against their protovalidate rules (spec 02 §1) before the handler runs: a violation is INVALID_ARGUMENT / QS_INVALID_FIELD with one google.rpc.BadRequest field violation per rule.

Package version reports build metadata of qStack binaries.