Configuration Reference

This page documents runtime-relevant configuration fields and defaults.

Topic Wire Format

• Topic wire subjects always use . as separator.
• Per-schema topic.separator is no longer used.
• Token values are percent-encoded for reserved chars (., *, >, %) before writing to backend subjects.

See Topic Encoding for rules and examples.

application

logging

Runtime override via RUST_LOG

If the RUST_LOG environment variable is set, it takes priority over logging.level and gives the operator full EnvFilter directive syntax for runtime triage without a code change. Examples:

RUST_LOG=info,aviso_server=debug
RUST_LOG=warn,aviso_server::auth=trace
RUST_LOG=info,aviso_server::sse=debug,actix_web=warn

A malformed RUST_LOG value is reported on stderr at startup and the server falls back to logging.level. The most common parse failures are an empty target before = (for example RUST_LOG==warn) and a non-level value after = (for example RUST_LOG=info,aviso_server=verbose).

A missing comma like RUST_LOG=info aviso_server=debug does not trigger the fallback. EnvFilter parses the whole string as a single target name with a space, and the directive ends up matching nothing instead of failing loudly. If a RUST_LOG value looks correct but no logs appear, double-check the commas first.

RUST_LOG="" (empty string) is treated as if RUST_LOG were unset and falls back to logging.level. Without this guard EnvFilter::try_new("") silently succeeds with a filter that matches nothing and silences the entire process. This is a real failure mode under deployment systems that export unset variables as empty strings, such as the Kubernetes downward API or docker-compose’s ${VAR:-}.

When RUST_LOG is unset, the default filter combines logging.level with a small set of mute directives so that framework internals do not flood operational logs:

These mute directives are pinned by unit tests, only apply when RUST_LOG is unset, and only apply when the directive’s level is more restrictive than logging.level. With logging.level=warn or logging.level=error the directives are skipped entirely so they never raise the per-target ceiling above what the operator chose; with logging.level=info the two actix_*=warn directives narrow framework chatter while async_nats=info is skipped (it would be neutral); with logging.level=debug or logging.level=trace all three directives apply. Setting RUST_LOG opts out of all of them and gives the operator full directive control.

auth

Authentication is optional. When disabled (default), all API endpoints are publicly accessible only if schemas do not define stream auth rules. Startup fails if global auth is disabled while a schema sets auth.required=true or non-empty auth.read_roles/auth.write_roles.

When enabled:

• Admin endpoints always require a valid JWT and an admin role.
• Stream endpoints (notify, watch, replay) enforce authentication only when the target schema has auth.required: true.
• Schema endpoints (/api/v1/schema) are always public.
• In trusted_proxy mode, Aviso validates Authorization: Bearer <jwt> locally with jwt_secret.

Per-stream auth (notification_schema.<event_type>.auth)

See Authentication for detailed setup, client usage, and error responses.

ecpds

Optional ECPDS destination authorization. Only available when built with --features ecpds. When configured, streams can reference the "ecpds" plugin in their auth.plugins list to enforce destination-level access control on watch and replay requests.

See ECPDS Destination Authorization for setup and runtime behavior, and the ECPDS runbook for operational triage.

metrics

Optional Prometheus metrics endpoint. When enabled, a separate HTTP server serves /metrics on an internal port for scraping by Prometheus/ServiceMonitor. This keeps metrics isolated from the public API.

Exposed metrics:

A binary built with --features ecpds registers the following five metrics. The unlabelled counters and the gauge appear as Prometheus series at process startup. The two labelled counters (access_decisions_total, fetch_total) are pre-initialised at startup with every documented outcome value, so each outcome label appears as a series at zero before any ECPDS traffic; this lets alert rules of the form rate(metric{outcome="error"}[5m]) > 0 start evaluating on a known-zero baseline rather than on a missing series.

Process-level metrics (CPU, memory, open FDs) are automatically collected on Linux.

notification_backend

notification_backend.in_memory

See InMemory Backend for operational caveats.

notification_backend.jetstream

See JetStream Backend for detailed behavior.

notification_schema_strict

Controls how the server treats event_type values that are not declared in notification_schema.

In strict mode, POST /api/v1/notification, POST /api/v1/watch, and POST /api/v1/replay reject any event_type not present in notification_schema with 400 UNKNOWN_EVENT_TYPE. The error body is:

{
  "code": "UNKNOWN_EVENT_TYPE",
  "error": "unknown_event_type",
  "message": "unknown event type 'X'",
  "configured_event_types": ["dissemination", "mars", "test_polygon"],
  "request_id": "<uuid>"
}

configured_event_types is sorted for stable diffing in client tooling.

The same flag also bounds Prometheus / tracing label cardinality. Whenever effective strict mode is off (either notification_schema_strict is explicitly false, or it is unset with an empty/absent notification_schema so the startup default resolves to non-strict), a request whose event_type is not in the schema reaches the generic-fallback path and has its recorded event_type label collapsed to the literal "generic" instead of being persisted as user-controlled input.

notification_schema.<event_type>.payload

Schema-level payload contract for notify requests.

Behavior details and edge cases are documented in Payload Contract.

notification_schema.<event_type>.storage_policy

Optional per-schema storage settings validated at startup against selected backend capabilities.

Field behavior:

• retention_time overrides backend-level retention for the schema stream.
• max_messages overrides backend-level message cap for the schema stream.
• max_size overrides backend-level byte cap for the schema stream.
• allow_duplicates = false maps to one message per subject (latest kept); true removes this cap.
• compression = true enables stream compression when backend supports it.

Startup behavior:

• Invalid retention_time/max_size format fails startup.
• Unsupported fields for selected backend fail startup.
• Validation happens before backend initialization.
• With in_memory, all storage_policy fields are currently unsupported (startup fails if provided).

Runtime application behavior:

• storage_policy is applied on stream create and reconciled for existing JetStream streams when those streams are accessed by Aviso.
• Aviso-managed stream subject binding is also reconciled to the expected <base>.> pattern.
• Mutable fields (retention/limits/compression/duplicates/replicas) are updated when drift is detected.
• Recreate stream(s) only when you need historical data physically rewritten with new settings.

Example:

notification_backend:
  kind: jetstream
  jetstream:
    nats_url: "nats://localhost:4222"
    publish_retry_attempts: 5
    publish_retry_base_delay_ms: 150

notification_schema:
  dissemination:
    topic:
      base: "diss"
      key_order: ["destination", "target", "class", "expver", "domain", "date", "time", "stream", "step"]
    storage_policy:
      retention_time: "7d"
      max_messages: 2000000
      max_size: "10Gi"
      allow_duplicates: true
      compression: true

watch_endpoint

Custom config file path

Set AVISOSERVER_CONFIG_FILE to use a specific config file instead of the default search cascade:

AVISOSERVER_CONFIG_FILE=/path/to/config.yaml cargo run

When set, only this file is loaded as a file source (startup fails if it does not exist). The default locations (./configuration/config.yaml, /etc/aviso_server/config.yaml, $HOME/.aviso_server/config.yaml) are skipped. AVISOSERVER_* field-level overrides still apply on top.

Environment override examples

AVISOSERVER_APPLICATION__HOST=0.0.0.0
AVISOSERVER_APPLICATION__PORT=8000
AVISOSERVER_NOTIFICATION_BACKEND__KIND=jetstream
AVISOSERVER_NOTIFICATION_BACKEND__JETSTREAM__NATS_URL=nats://localhost:4222
AVISOSERVER_NOTIFICATION_BACKEND__JETSTREAM__TOKEN=secret
AVISOSERVER_WATCH_ENDPOINT__REPLAY_BATCH_SIZE=200
AVISOSERVER_AUTH__ENABLED=true
AVISOSERVER_AUTH__JWT_SECRET=secret
AVISOSERVER_METRICS__ENABLED=true
AVISOSERVER_METRICS__PORT=9090