API v3alpha: AlertService

Parent: #5450

Summary

Define and implement the complete alert.v3alpha.AlertService for alert ingestion, alert and group queries, streamed ingestion, and stored-mutation watches.

The public proto should be reviewed first. Implementation may then land in phases as the shared contracts, transport controls, and mutation broker become available.

Proto PR

Define:

• Alert, alert status, gettable alert, and alert group messages.
• Shared matcher, state, receiver-label, pagination, validation, and partial-result fields.
• Stored-mutation event and snapshot-complete messages.
• PostAlerts.
• ListAlerts.
• ListAlertGroups.
• Client-streamed alert ingestion.
• WatchAlerts.
• WatchAlertGroups.

Document best-effort batch ingestion, partial acceptance, live-view pagination, initial snapshots, stored-mutation events, and node-local cursor semantics. Reserve removed or deferred field numbers deliberately.

Implementation phases

Unary ingestion and queries

• Convert directly between public proto and internal alert types.
• Validate/default timestamps and remove empty labels consistently with existing ingestion behavior.
• Return hexadecimal fingerprints and receiver metadata.
• Predict current silence and inhibition status at query time.
• Preserve existing best-effort batch semantics unless the alpha contract is explicitly revised.
• Make partial acceptance unambiguous without claiming exact accepted counts until the provider reports per-alert callback and store-limit outcomes.
• Implement OR across matcher sets and AND within a set, state filters, receiver-label filters, deterministic fingerprint ordering, and shared pagination.
• Query alert groups through the reload-safe dispatcher closure and return group key, group/route labels, receiver, muted metadata, and per-alert status.
• Document that mute/status output is a computed snapshot and can change without a stored mutation.
• Refactor receive metrics so v2 and Connect use distinct version labels without duplicate collector registration or changes to existing v2 series.

Streamed ingestion

Reuse unary validation and defaulting. Apply the shared request/message, admission, idle, lifetime, and cancellation policies. Return final accepted/failed summaries only to the precision the provider can report.

Watches

Implement initial snapshots, snapshot-complete markers, stored create/update/delete events, shared filters, and entered/updated/exited transitions through the mutation broker.

Do not emit events caused only by silence/inhibition reevaluation, elapsed alert end times, route/config reload, or time-interval state. Clients derive time-based state or reconnect for a fresh snapshot.

Acceptance criteria

• The alert.v3alpha proto and generated code land before handler implementation.
• Unary ingestion and queries use internal models and shared contracts.
• Partial-success behavior is documented and tested.
• Ordering and pagination are deterministic and token validation is consistent.
• Group and alert state reflects the current computed snapshot.
• Streamed ingestion is bounded and cancellation-safe.
• Watches provide atomic snapshots, snapshot-complete markers, stored mutations, overflow/resnapshot, and node-local cursors.
• Connect, gRPC-Web where supported, native gRPC, route-prefix, reload, and v2 coexistence coverage uses Ginkgo/Gomega.

Dependencies and related work

• Shared contracts and reload/error infrastructure: #5479.
• Connect request, stream, and observability hardening: #5478.
• Stored-mutation broker and domain feeds for watch methods: #5480.
• Related API v2 alert-group pagination proposal: #3297.