# Streaming service

A Streaming service is implemented using a Publish/Subscribe (Pub/Sub) pattern.

Available channels:

- vulnerability
- comment
- bundle
- sighting

Database-level listeners automatically publish new **sightings**, **comments**, and **bundles** to their respective Pub/Sub channels.
The various feeders push incoming vulnerabilities directly to the designated vulnerability channel.

## Configuration

The streaming service can be configured using the `config/stream.json` file. An example configuration is provided below.

```bash
{
    "register_listeners": true,
    "pubsub_bp": true,
    "global_subscription": false,
    "channels": [
        "vulnerability",
        "comment",
        "bundle",
        "sighting"
    ],
    "_notes": {
        "register_listeners": "Register the listeners for comments, bundles, and sightings.",
        "pubsub_bp": "Activate or deactivate the subscription Blueprint for specific clients.",
        "channels": "The list of channels exposed by the Pub/Sub Blueprint.",
        "global_subscription": "Activate or deactivate the global subscription mechanism for server-side processing of messages."
    }
}
```

### Listeners

When database-level listeners are enabled, all new comments, bundles, and sightings are automatically streamed to the Pub/Sub service.

### Internal streaming

When `global_subscription` is set to `True`, an internal subscription mechanism is provided
for the components of the application. The internal streaming service is executed in a dedicated thread.

### HTTP streaming

The subscription endpoint is gated on the global `stream:subscribe`
permission, which the built-in `admin` role holds. The channels carry rows
as they are inserted — a comment reaches the `comment` channel before any
moderation step has run — so the endpoint is deliberately not open to every
confirmed account. To let an automation account read the stream without
making it an administrator, create a global role carrying only
`stream:subscribe` and assign it to that account.

Operators should also be aware that a long-lived SSE connection needs the
reverse proxy configured for it: streaming enabled (`beresp.do_stream` in
Varnish), buffering off, and a first-byte timeout longer than the interval
between events. The endpoint emits an SSE comment line at least every 15
seconds so an idle channel still carries traffic.

Connection to the authenticated HTTP subscribing interface when (`pubsub_bp` is set to `True`):

```bash
$ curl -H "X-API-KEY: <YOUR-TOKEN>" http://127.0.0.1:10001/pubsub/subscribe/comment
```

[FediVuln](https://pypi.org/project/FediVuln) can also be used to subscribe to a channel:

```bash
$ FediVuln-Publish -t comment
```

A status will be pushed with the configured Mastodon account (see the documentation of FediVuln).