Module routes 

HTTP handler functions for the stargazer operational API.

Each handler is an async fn that takes axum extractors (State, Query, Path) and returns either a JSON response or a StatusCode error. All database errors are logged at warn level and surfaced to the caller as 500 Internal Server Error with a generic body — the raw sqlx::Error is never leaked because it may contain connection strings or schema details that are useful to an attacker.

Response types

The handlers operate on database rows (ReflectorRow, ActivityRow, StreamRow) but serialize trimmed *View structs over the wire. The view structs intentionally omit columns that are operationally useless to the HTTP consumer (raw audio_mp3 blobs, stream ids internal to the capture pipeline, etc.) and rename fields to the JSON conventions the operator dashboards expect.

Time-window parsing

Query endpoints accept a since parameter of the form <n><unit> where n is a positive integer and unit is s, m, h, or d. The helper parse_since turns this into a DateTime<Utc> anchored at Utc::now(). A missing or unparseable value falls back to the endpoint-specific default (documented per handler).

Structs

ActivityQuery 🔒

Query parameters for the /api/reflectors/{callsign}/activity endpoint.

ActivityView 🔒

JSON view of one activity-log row.

ConnectedNodeView 🔒

JSON view of one connected-node row.

GlobalActivityQuery 🔒

Query parameters for the /api/activity endpoint.

HealthResponse 🔒

JSON response body for the /health endpoint.

MetricsResponse 🔒

JSON response body for the /metrics endpoint.

ReflectorQuery 🔒

Query parameters for the /api/reflectors endpoint.

ReflectorView 🔒

JSON view of one reflector row.

StreamQuery 🔒

Query parameters for the /api/streams endpoint.

StreamView 🔒

JSON view of one captured stream.

UploadQueueQuery 🔒

Query parameters for the /api/upload-queue endpoint.

Constants

DEFAULT_ACTIVITY_LIMIT 🔒

Default row cap for /api/activity when limit is missing.

DEFAULT_ACTIVITY_WINDOW 🔒

Default time window for /api/reflectors/{callsign}/activity.

DEFAULT_REFLECTOR_WINDOW 🔒

Default time window for /api/reflectors when since is missing.

DEFAULT_STREAM_LIMIT 🔒

Default row cap for /api/streams when limit is missing.

DEFAULT_STREAM_WINDOW 🔒

Default time window for /api/streams.

DEFAULT_UPLOAD_LIMIT 🔒

Default row cap for /api/upload-queue when limit is missing.

MAX_LIMIT 🔒

Maximum rows any query endpoint will return regardless of limit.

Functions

clamp_limit 🔒

Clamps a caller-provided row limit to the configured maximum.

health 🔒

GET /health — kubernetes liveness/readiness probe.

list_activity 🔒

GET /api/activity — global activity feed across all reflectors.

list_reflectors 🔒

GET /api/reflectors — list active reflectors with status.

list_streams 🔒

GET /api/streams — query captured streams with filters.

metrics 🔒

GET /metrics — tier statistics snapshot.

parse_duration_string 🔒

Parses a relative time string like "1h" or "30m" into a Duration.

parse_since 🔒

Turns a relative since string into an absolute DateTime<Utc>.

reflector_activity 🔒

GET /api/reflectors/{callsign}/activity — recent activity for one reflector.

reflector_nodes 🔒

GET /api/reflectors/{callsign}/nodes — nodes linked to a reflector.

tier3_connect 🔒

POST /api/tier3/connect — manually promote a reflector to Tier 3.

tier3_disconnect 🔒

DELETE /api/tier3/{callsign}/{module} — disconnect a Tier 3 session.

upload_queue 🔒

GET /api/upload-queue — pending and failed uploads.