aviso-server 0.4.1

Notification service for data-driven workflows with live and replay APIs.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

<div align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ecmwf/logos/cde127b2c872e88474570a681e56b14cdecf4f03/logos/aviso/aviso_text_dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/ecmwf/logos/cde127b2c872e88474570a681e56b14cdecf4f03/logos/aviso/aviso_text_light.svg">
    <img alt="Aviso Logo" src="https://raw.githubusercontent.com/ecmwf/logos/cde127b2c872e88474570a681e56b14cdecf4f03/logos/aviso/aviso_text_light.svg">
  </picture>
</div>

<p align="center">
  <a href="https://crates.io/crates/aviso-server">
    <img src="https://img.shields.io/crates/v/aviso-server.svg" alt="Crates.io Badge">
  </a>
  <a href="https://sites.ecmwf.int/docs/aviso-server/main/">
    <img src="https://img.shields.io/badge/docs-online-blue" alt="Docs Badge">
  </a>
  <a href="https://github.com/ecmwf/codex/raw/refs/heads/main/ESEE">
    <img src="https://github.com/ecmwf/codex/raw/refs/heads/main/ESEE/foundation_badge.svg" alt="Foundation Badge">
  </a>
  <a href="https://github.com/ecmwf/codex/raw/refs/heads/main/Project%20Maturity">
    <img src="https://github.com/ecmwf/codex/raw/refs/heads/main/Project%20Maturity/emerging_badge.svg" alt="Maturity Badge">
  </a>
</p>

> [!IMPORTANT]  
> This software is **Emerging** and subject to ECMWF's guidelines on [Software Maturity](https://github.com/ecmwf/codex/raw/refs/heads/main/Project%20Maturity).

## Overview

Aviso Server is a notification service for data-driven workflows.

It helps you answer questions like:
- "What just arrived?"
- "Give me updates for this exact subset of data."
- "Replay everything I missed since yesterday."

Producers publish notifications once, and consumers can either follow live updates or replay history using the same filter model. Aviso keeps this predictable by validating identifiers against schema rules and streaming notifications in a consistent event format.
For regional use cases, Aviso also supports spatial filtering so clients can subscribe to notifications relevant to a specific area or point.

## Key Features

- Publish notifications through a simple HTTP API
- Watch live updates over SSE with connection and replay controls
- Replay historical notifications by sequence or timestamp
- Filter by exact identifier values or constraints (for supported field types)
- Use spatial filters for polygon/point use cases
- Run with either in-memory storage (local/dev) or JetStream (durable environments)

## Quick Start

### Run locally (in-memory backend)

```bash
cargo run
```

### Run tests

```bash
cargo test --workspace
```

JetStream integration tests are opt-in:

```bash
AVISO_RUN_NATS_TESTS=1 cargo test --workspace
```

## Build Docs Locally

```bash
cargo install mdbook
mdbook build docs
mdbook serve docs --open
```

## Authentication (Optional)

Aviso Server supports authentication via [auth-o-tron](https://github.com/ecmwf/auth-o-tron) as an external authentication service.

### Quick Start with Auth

1. Start auth-o-tron using Docker:
```bash
./scripts/auth-o-tron-docker.sh
```

By default this uses `scripts/example_auth_config.yaml`.
Use a custom config if needed:

```bash
AUTH_O_TRON_CONFIG_FILE=/path/to/auth-config.yaml ./scripts/auth-o-tron-docker.sh
```

2. Configure auth in `configuration/config.yaml`:
```yaml
auth:
  enabled: true
  auth_o_tron_url: "http://localhost:8080"
  jwt_secret: "your-shared-secret" # must match auth-o-tron jwt.secret
  admin_roles:
    your-realm: ["admin", "superuser"]
  timeout_ms: 5000
```

3. Run aviso-server with auth enabled

### Per-Stream Authentication

You can configure authentication requirements per stream in your notification schema:

```yaml
notification_schema:
  # Authenticated stream - any valid user
  public_stream:
    # ... other config
    auth:
      required: true  # Any authenticated user allowed

  # Separate read/write access
  restricted_stream:
    # ... other config
    auth:
      required: true
      read_roles:
        your-realm: ["*"]
      write_roles:
        your-realm: ["admin", "operator"]
```

### Admin Endpoints

Admin endpoints (`/api/v1/admin/*`) require users to have one of the configured `admin_roles`.

### Disabling Auth

To disable authentication completely:
```yaml
auth:
  enabled: false
```

Or omit the `auth` section entirely from your configuration.