Bind address.

Bind port.

Used in generated CloudEvent source links.

Static asset root for homepage assets. The directory holds index.html, the homepage, and the files it links: logo.png, which is also the PNG favicon, and favicon.svg. Both icons are the documentation’s own. A custom directory needs all three files.

The homepage puts the Aviso client card before the Aviso server card. Each card links to its documentation and GitHub repository. A separate HTTP API reference section opens this server’s Swagger UI.

All four fields are optional strings. Omitting the object or any field keeps the corresponding default:

Set these under application.homepage in YAML. Environment overrides take priority over file values, using these exact keys:

AVISOSERVER_APPLICATION__HOMEPAGE__CLIENT_DOCUMENTATION_URL
AVISOSERVER_APPLICATION__HOMEPAGE__CLIENT_REPOSITORY_URL
AVISOSERVER_APPLICATION__HOMEPAGE__SERVER_DOCUMENTATION_URL
AVISOSERVER_APPLICATION__HOMEPAGE__SERVER_REPOSITORY_URL

Startup rejects URLs that cannot be parsed as absolute HTTP or HTTPS URLs with a host, or that contain a username or password. The error names the configuration field without printing its value. Links are HTML-escaped when rendered, including quotes and query-string ampersands.

One of trace, debug, info, warn, error. Unknown values fall back to info instead of failing startup. Used as the application-wide level when RUST_LOG is unset.

Kept for compatibility; output is OTel-aligned JSON.

Turns OTLP log export on. Startup fails when enabled without an endpoint.

Collector endpoint. A missing scheme defaults to http://. For protocol: http the OTLP path /v1/logs is appended when absent.

Transport. Collectors conventionally listen on 4317 for gRPC and 4318 for HTTP.

Set to true to enable authentication.

direct: forward credentials to auth-o-tron. trusted_proxy: validate forwarded JWT locally.

auth-o-tron base URL. Required when enabled=true and mode=direct.

Shared HMAC secret for JWT validation. Required when enabled=true. Not exposed via /api/v1/schema endpoints and redacted when auth settings are serialized or logged.

Realm-scoped roles for admin endpoints (/api/v1/admin/*). Must contain at least one realm with non-empty roles when enabled=true.

Timeout for auth-o-tron requests (milliseconds). Must be > 0.

Must be explicitly set whenever an auth block is present. When true, the stream requires authentication.

Realm-scoped roles for read access (watch/replay). When omitted, any authenticated user can read. Use ["*"] as the role list to grant realm-wide access.

Realm-scoped roles for write access (notify). When omitted, only users matching global admin_roles can write. Use ["*"] as the role list to grant realm-wide access.

Optional list of authorization plugins to run after role-based checks. Currently supported: "ecpds" (requires --features ecpds build). On a build without the required feature, startup fails with a clear error pointing at the offending stream. (Silent skip would widen access.) Empty plugins: [] is rejected; omit the field instead. Plugins only run when auth.required is true.

Service account username used for HTTP Basic Auth to ECPDS.

Service account password used for HTTP Basic Auth to ECPDS. It is redacted in configuration debug output. The schema discovery API does not expose the top-level ecpds settings.

Use HTTPS to protect credentials and destination lookups. HTTP is accepted only for local testing with 127.0.0.1, [::1], or localhost; other HTTP addresses fail startup validation.

servers is a list of base URL strings, without query strings or fragments. Path prefixes such as https://proxy.example/ecpds-api/ are supported. Aviso appends /ecpds/v1/destination/list?id=<username> to each base URL.

Set match_key to an ordinary identifier such as destination, declared in the schema with required: true. The name must not contain whitespace, /, or NUL. When the schema defines a topic, include this field in topic.key_order so delivery is filtered by the authorized destination.

Spatial identifiers cannot be match keys: PolygonHandler, PointCloudHandler, and the field name polygon are not allowed. Spatial matching does not enforce access to an exact destination value.

Selects a JSON field from each ECPDS destination record. Records missing that field are skipped. To investigate missing destinations, set RUST_LOG=info,aviso_ecpds=debug and look for auth.ecpds.fetch.skipped_record events.

How long to cache a user’s destination list before fetching it again. Use a whole number of seconds.

Maximum number of users in the destination cache. Use a whole number. The cache uses TinyLFU eviction when it needs to make room.

Maximum time for the whole ECPDS request, from DNS lookup through reading the response body. Use a whole number of seconds.

Maximum time to establish the connection, including TCP and TLS. This counts toward the total request timeout; it is not extra time. Use a whole number of seconds.

Controls what happens when an ECPDS server is unavailable:

• strict: every configured server must respond successfully. If any fails, the destination lookup fails with HTTP 503.
• any_success: combine destinations from the servers that respond successfully. The lookup fails if none succeeds.

In both modes, Aviso combines the returned destination lists. With any_success, destinations known only to an unavailable server may be missing. See Partial outage policy for the trade-off.

Enable the metrics endpoint.

Bind address for the metrics server. Defaults to loopback to avoid public exposure.

Required when enabled=true. Must differ from application.port.

Constant 1 with the server version as a label; join on it in dashboards to annotate deploys.

HTTP requests on the main server by matched route pattern (e.g. /api/v1/schema/{event_type}). Reserved label values: unrouted requests (404 scans) collapse into route="unmatched", requests failing with a service-level error (no route information available) record route="error", and non-standard HTTP methods collapse into method="other". The label is named route (not endpoint) to avoid colliding with the Prometheus Operator target label endpoint.

Request duration until response headers are ready. For the SSE routes (/api/v1/watch, /api/v1/replay) this is stream setup latency, not connection lifetime; see aviso_sse_connection_duration_seconds.

HTTP requests currently being processed, by method. Labelled by method only because the matched route pattern is not known until routing completes (after the request is already in flight). Distinguishes “slow because busy” from “slow because a downstream/backend stalled”.

Notification-backend operations at the trait boundary. operation ∈ {publish, get_batch, wipe_stream, wipe_all, delete_message}; outcome ∈ {ok, error}. subscribe_to_topic is excluded (its work happens lazily as the stream is polled).

Caller-observed backend operation latency (same labels as aviso_backend_operations_total). This is the metric to watch when notification throughput plateaus while pods are underused: it isolates backend (NATS/JetStream) latency from app CPU.

Total notification requests. status ∈ {success, error, rejected}; requests failing before schema validation record event_type="unknown".

Currently active SSE connections. route ∈ {/api/v1/watch, /api/v1/replay}.

Total SSE connections opened.

Distinct users with active SSE connections.

Notification events delivered to SSE clients. Heartbeats, control events, and close frames are not counted.

Error events emitted into SSE streams after the response started (typed stream errors and notification rendering failures); these are invisible to aviso_http_requests_total because the stream already returned 200.

SSE connection lifetime, observed when the connection closes (buckets 1s-24h). Long-lived open connections appear in aviso_sse_connections_active, not here, until they close.

Authentication attempts. mode ∈ {direct, trusted_proxy}; outcome ∈ {success, unauthorized, forbidden, service_unavailable}.

ECPDS destination cache hits (requests served from cache without an upstream call).

ECPDS destination cache misses (requests not served from cache). Includes coalesced waiters that did not trigger an upstream call themselves; aviso_ecpds_fetch_total is the right metric for “actual upstream calls”.

Number of usernames in the ECPDS destination cache, sampled from moka after eviction passes. Expired entries are pruned by moka asynchronously, so this gauge can briefly include not-yet-pruned expired entries until the next pending-tasks run.

Access decisions. outcome ∈ {allow, deny_destination, deny_match_key_missing, unavailable, admin_bypass, error}.

Upstream fetch outcomes (recorded once per access check whose request actually ran the upstream call; coalesced waiters do not contribute). outcome ∈ {success, http_401, http_403, http_4xx, http_5xx, invalid_response, unreachable}.

NATS connection URL.

Token auth; NATS_TOKEN env fallback.

NATS connection timeout for each startup connect attempt (> 0).

Startup connect attempts before backend init fails (> 0).

Stream message cap.

Stream size cap in bytes.

Default stream max age (s, m, h, d, w; for example 30d).

file or memory (parsed as typed enum at config load).

Omitting this setting requests file. Existing streams must use the requested type: a mismatch fails stream setup before any mutable settings change. The error names the stream and its current and requested types. Aviso does not delete or recreate streams, so messages remain intact. Use the current type or arrange a separate migration.

Stream replicas.

limits/interest. workqueue fails startup because independent watch/replay consumers are not supported.

old/new (parsed as typed enum at config load).

Mapped to NATS max_reconnects; unset and 0 both mean unlimited. A positive value makes the client give up permanently once exhausted.

Subscription creation uses a bounded retry loop: unset means five attempts, 0 means one attempt, and a positive value sets the attempt limit. Startup connection attempts are controlled separately by retry_attempts.

Reconnect delay and startup connect retry backoff (> 0).

Retry attempts for transient publish channel closed failures (> 0).

Base backoff in milliseconds for publish retries (> 0).

When unset, the effective value is true if notification_schema is non-empty, false otherwise. Set to true to force strict rejection even with no schema (deny-all “drain” mode). Set to false to preserve the legacy permissive generic fallback even with a declared schema; a startup warning is emitted in that case.

Duration literal (s, m, h, d, w).

Must be > 0.

Size literal (K, Ki, M, Mi, G, Gi, T, Ti).

Backend support is capability-gated.

Backend support is capability-gated.

SSE heartbeat period.

Maximum live watch duration.

Historical backend fetch batch size, independent of the request-wide delivery cap. Filtering can leave a batch with no notifications to deliver; replay keeps advancing through history.

Maximum historical notifications delivered per replay or replaying watch request, across all batches and after identifier constraints, spatial filters and successful CloudEvent rendering. Both backends enforce the same cap. Live-only watches are unaffected. A schema can override this default with notification_schema.<event_type>.max_historical_notifications, outside storage_policy. Omitting the schema field inherits the global value.

The value must be a positive integer; zero and unlimited are rejected. The server emits notification_replay_limit_reached only when it finds a renderable notification beyond the cap. Exactly filling the quota is not truncation. A truncated request closes without replay_completed or a transition to live delivery. See Historical Replay Limits.

Delay between historical replay batches.

Live stream CloudEvent conversion concurrency.