events-presenter is a lightweight Go service that listens for events from PostgreSQL and exposes them over HTTP, providing both:
- Server-Sent Events (SSE) for real-time notifications
- REST endpoints for querying event resources
- Health probes for Kubernetes deployments
It is designed to be cloud-native, resilient, and easy to deploy inside Kubernetes.
The service acts as a bridge between PostgreSQL and connected clients:
- Connects to PostgreSQL and waits until the database is ready.
- Subscribes to a PostgreSQL
LISTEN/NOTIFYchannel (events). - Pushes incoming notifications into an internal queue.
- Broadcasts events to connected SSE clients.
- Exposes HTTP endpoints for querying stored resources.
- Provides readiness and liveness probes.
- Supports graceful shutdown.
- Real-time event streaming via SSE
- PostgreSQL LISTEN/NOTIFY integration
- JWT-based authentication for protected endpoints
- Connection pool for efficient DB usage
- Internal worker queue for concurrent processing
- Kubernetes-ready health probes (no auth required)
- Graceful shutdown handling
- Structured logging support
- Configurable via environment variables
/notifications and /events require a JWT bearer token issued by the Krateo authn service.
Pass it in the Authorization header:
Authorization: Bearer <token>
Requests without a valid token receive 401 Unauthorized.
Health probe endpoints (/livez, /readyz) are exempt from authentication.
Server-Sent Events endpoint. Streams events to connected clients in real time.
Example:
curl -N http://localhost:8083/notifications \
--header "Authorization: Bearer <token>"Returns event-related resources from PostgreSQL.
curl http://localhost:8083/events \
--header "Authorization: Bearer <token>"curl --request POST http://localhost:8083/events \
--header "Authorization: Bearer <token>" \
--header "Content-Type: application/json" \
--data '{"cluster":"cluster-a","limit":100}'Detailed search and pagination examples are available in SEARCH.md.
Health probes do not require authentication and are intended for Kubernetes internal use only.
| Endpoint | Auth required | Purpose |
|---|---|---|
/livez |
No | Liveness probe – indicates the process is running |
/readyz |
No | Readiness probe – indicates the service is ready to accept traffic |
## Configuration
| Variable | Description | Default |
|---|---|---|
PORT |
HTTP server port | 8083 |
DEBUG |
Enable debug logging | false |
DB_USER |
Database username | — |
DB_PASS |
Database password | — |
DB_NAME |
Database name | — |
DB_HOST |
Database host | localhost |
DB_PORT |
Database port | 5432 |
DB_PARAMS |
Extra connection parameters | — |
DB_READY_TIMEOUT |
Max time to wait for DB readiness | 2m |
JWT_SIGN_KEY |
HMAC signing key for JWT validation | — |
AUTHN_NS |
Kubernetes namespace where user clientconfig secrets live | — |
OTEL_ENABLED |
Enable OpenTelemetry metrics | true |
OTEL_EXPORT_INTERVAL |
Metrics export interval | 30s |
The service builds a PostgreSQL connection string from these values.
The service is Kubernetes-friendly and supports:
- Readiness / liveness probes
- Graceful shutdown on SIGTERM
- Externalized configuration
- Secret-based credentials
Typical deployment flow:
- Deploy PostgreSQL.
- Configure environment variables (or Helm values).
- Expose via Service / Ingress.
- Optionally enable TLS with cert-manager.
On SIGINT or SIGTERM, the service:
- Marks itself as not ready.
- Stops accepting new HTTP connections.
- Shuts down the PostgreSQL listener.
- Drains workers.
- Terminates cleanly.
This prevents dropped connections and partial event delivery.
Continuously listens on the events channel and reconnects automatically if the connection drops.
Buffered worker queue with configurable concurrency to avoid blocking event ingestion.
Manages SSE clients and broadcasts events safely to all subscribers.
- Use connection pooling (already enabled).
- Store DB credentials in Kubernetes Secrets.
- Place the service behind an ingress with proper timeouts for SSE.
- Enable TLS.
- Monitor readiness probes during deployments.