74 lines
2.3 KiB
Markdown
74 lines
2.3 KiB
Markdown
# RSS Service
|
|
|
|
Serves public feed endpoints for Noisebell.
|
|
|
|
This service does not store history. On each request it fetches the current state from `cache-service` and renders that one current state as RSS or Atom.
|
|
|
|
## States
|
|
|
|
- `open`: Noisebridge is open right now.
|
|
- `closed`: Noisebridge is closed right now.
|
|
- `offline`: the cache cannot currently confirm the Pi state.
|
|
|
|
## Feed behavior
|
|
|
|
- Feeds are current-state only, not historical archives.
|
|
- Each feed emits either one item or zero items.
|
|
- The item `guid` changes when the current status event changes, so feed readers can treat it as new.
|
|
- Filtered feeds omit the item when the current state does not match that feed.
|
|
|
|
## Endpoints
|
|
|
|
| Format | Purpose | Path |
|
|
|--------|---------|------|
|
|
| JSON | Current status passthrough | `/status` |
|
|
| RSS | All states | `/all/rss.xml` |
|
|
| Atom | All states | `/all/atom.xml` |
|
|
| RSS | Open + closed only | `/door/rss.xml` |
|
|
| Atom | Open + closed only | `/door/atom.xml` |
|
|
| RSS | Open only | `/open/rss.xml` |
|
|
| Atom | Open only | `/open/atom.xml` |
|
|
| HTTP | Health check | `/health` |
|
|
| HTTP | Redirect to docs | `/` |
|
|
|
|
Current aliases:
|
|
|
|
- `/rss.xml` currently serves the same feed as `/all/rss.xml`.
|
|
- `/atom.xml` currently serves the same feed as `/all/atom.xml`.
|
|
- `/` redirects to the repo README for this module.
|
|
|
|
## Feed text
|
|
|
|
Items use custom titles:
|
|
|
|
- `Noisebridge opened`
|
|
- `Noisebridge closed`
|
|
- `Noisebridge sensor went offline`
|
|
|
|
Descriptions include:
|
|
|
|
- the current state
|
|
- when that state began, if known
|
|
- when the cache last confirmed the state
|
|
|
|
## Caching and polling hints
|
|
|
|
- RSS includes `<ttl>1`, which suggests a 1-minute polling interval.
|
|
- HTTP responses include `Cache-Control: public, max-age=60`.
|
|
- HTTP responses also include `ETag` and `Last-Modified` so clients can revalidate cheaply.
|
|
|
|
## Atom vs RSS
|
|
|
|
RSS and Atom are both XML feed formats.
|
|
|
|
- RSS is older and very widely supported.
|
|
- Atom is newer and has a more regular structure.
|
|
- For this service they contain the same information in two different standard formats.
|
|
|
|
## Configuration
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `NOISEBELL_RSS_CACHE_URL` | required | Base URL of `cache-service` |
|
|
| `NOISEBELL_RSS_PORT` | `3002` | Listen port |
|
|
| `NOISEBELL_RSS_HTTP_TIMEOUT_SECS` | `10` | Timeout when requesting cache status |
|