API v3alpha: SilenceService

[siavashs]

Parent: #5450

Summary

Define and implement the complete silence.v3alpha.SilenceService for unary CRUD/list operations and stored-mutation watches.

The public proto should be reviewed first. Implementation may then land in phases, with v2-incompatible writes protected by a narrowly scoped capability flag.

Proto PR

Define:

• Silence, SilenceStatus, and GettableSilence.
• Matcher-set, annotation, state-filter, pagination, validation, and required-feature fields using common.v3alpha.
• Create, Update, Get, List, Delete/Expire, and WatchSilences RPCs.
• Stored-mutation events and snapshot-complete messages.

Represent multiple alert matcher sets directly. Do not expose receiver matcher sets as functional public fields until validation, matching, history comparison, v2 conversion, and runtime silencing implement them consistently.

Document replacement IDs, explicit expiration, live-view pagination, current-state calculation, feature gating, and node-local watch cursors.

Implementation phases

Unary CRUD and listing

• Convert directly between the public proto and silencepb; do not reuse the v2 converter, which cannot represent multiple matcher sets.
• Split create and update semantics at the RPC boundary while preserving store behavior where history-changing updates expire the old ID and create a replacement ID.
• Return the resulting ID explicitly.
• Validate matcher sets, timestamps, IDs, and annotations before calling the store.
• Map missing IDs to NotFound, invalid definitions to InvalidArgument, limits to ResourceExhausted, disabled capabilities to FailedPrecondition, and unexpected failures to Internal.
• Implement definition and state filters, deterministic state/time/ID ordering, and shared pagination.
• Resolve the exact-ends_at boundary mismatch between CurrentState and internal query behavior.

Multi-matcher-set capability

Add a disabled-by-default --enable-feature capability flag for creating or updating silences with multiple matcher sets.

When disabled:

• Compatible single-set CRUD/list operations remain available.
• Multi-set writes return FailedPrecondition with structured details naming the required feature.
• Requests are not flattened or silently reinterpreted.

When enabled:

• Accept multi-set resources while API v2 remains mounted.
• Document and test that API v2 cannot faithfully represent these resources and may fail to read them.

WatchSilences

Emit an initial snapshot and snapshot-complete marker followed by stored created, updated, explicitly expired, replaced, HA-merged, and purged mutations.

Do not emit timer-driven activation or expiration events. Clients derive state from starts_at/ends_at and reconnect when they need a new computed snapshot.

Apply definition/state filters to snapshots and before/after mutations. Define read/watch behavior for already stored or HA-merged multi-set resources independently from the write capability gate.

Acceptance criteria

• The silence.v3alpha proto and generated code land before handler implementation.
• Unary operations convert directly to/from internal silence protobufs.
• Create/update replacement and resulting-ID semantics are explicit.
• Filtering, state boundaries, ordering, and pagination are deterministic.
• Multi-set writes are disabled by default and return structured FailedPrecondition details.
• Enabling multi-set writes does not disable v2, and the v2 limitation is documented and tested.
• WatchSilences covers local, HA, replacement, explicit expiry, and GC mutations with overflow/resnapshot semantics.
• Ginkgo/Gomega coverage includes CRUD, feature states, annotations, OR matcher sets, HA reads, watches, transports, and route prefixes.

Dependencies and related work

• Shared contracts and capability infrastructure: API v3alpha: add shared contracts and reusable infrastructure #5479.
• Connect request, stream, and observability hardening: API v3alpha: harden the ConnectRPC foundation #5478.
• Stored-mutation broker and silence feed: API v3alpha: build stored-mutation watch infrastructure #5480.
• Internal multi-matcher silence model: Multi-Matcher Silence Model #4946.

[siavashs]

The generated browser consumer and complete Silence UI are tracked in #5491 under parent #5451.

Before the silence.v3alpha proto freezes, please resolve the existing UI's active/pending/expired tab counts. Fetching every paginated Silence solely to calculate counts is unbounded. The preferred contract is bounded state counts/facets on ListSilences; otherwise the UI roadmap requires an explicit maintainer-approved parity exception.