13 KiB

Raw Permalink Blame History

ingress-api Specification

Purpose

Read access to ingress definitions: the ingresses list and its summary numbers, every query backed by an index.

Requirements

Requirement: Ingresses list endpoint

Edition: CE. GET /api/v1/ingresses SHALL list the ingress definitions of the activity range with the common query contract (from, to, tz, limit 1-100 default 25, opaque cursor), the filters status, inputType and q, the ranked sort keys createdAt (default), totalDuration, sessions and lastSession (order default desc), and the list envelope { items, nextCursor, prevCursor, total? } with total under the DASHBOARD_LIST_TOTAL_MAX_RANGE rule.

Scenario: Default list

GIVEN 30 ingresses created in the last 24 hours and 4 older ones that neither started a session in that range nor are publishing
WHEN the client requests GET /api/v1/ingresses with a valid token
THEN the response is 200 with the 25 most recently created ingresses of the last 24 hours, nextCursor set, prevCursor: null and total: 30

Scenario: Cursor walk

GIVEN 60 ingresses in range and limit=25
WHEN the client follows nextCursor twice and then prevCursor once
THEN the pages hold ingresses 1-25, 26-50, 51-60 and 26-50 with no gaps or duplicates, each page ordered by createdAt desc with _id desc as tie-breaker

Scenario: Ranked cursor walk

GIVEN 60 ingresses in the activity range, two of them publishing, and sort=totalDuration&limit=25
WHEN the client follows nextCursor twice
THEN the pages hold ingresses 1-25, 26-50 and 51-60 of the ranking at the first page's asOf, with no gaps or duplicates

Requirement: Ingress list item

Edition: CE. Each item of the ingresses list SHALL be the public projection of the ingress document: identity, definition facts, lifecycle and the aggregate session counters. schemaVersion, expiresAt, participantName, url and any stream key SHALL never be part of a list item.

Scenario: Fields of an item

WHEN an item is read
THEN it has ingressId, name?, inputType (rtmp | whip | url), roomName, participantIdentity, status (inactive | buffering | publishing | error | complete | deleted), enabled, reusable, createdAt, deletedAt?, sessions, totalDurationMs, lastSessionAt? and hasError, and no url, streamKey, participantName, schemaVersion or expiresAt

Scenario: Deleted ingress within retention

GIVEN an ingress deleted yesterday whose document has not expired
WHEN it is returned
THEN status is deleted and deletedAt is set

Scenario: Error flag

GIVEN a reusable ingress whose last session ended in error and which is now inactive
WHEN it is returned
THEN status is inactive and hasError is true

Requirement: Ingress status filter

Edition: CE. The ingresses list SHALL accept status as one of inactive, buffering, publishing, error, complete, deleted or all (default all) and reject any other value with 400 VALIDATION_ERROR.

Scenario: Publishing only

WHEN the client sends ?status=publishing
THEN every item has status: "publishing" and the activity range still applies

Scenario: Unknown status

WHEN the client sends ?status=active
THEN the response is 400 with code VALIDATION_ERROR and details.issues[0].path equal to ["status"]

Scenario: Old ingress publishing now

GIVEN an ingress created 30 days ago that is publishing now
WHEN the client sends ?status=publishing&from=now-1h&to=now
THEN the ingress is in items

Requirement: Input type filter

Edition: CE. The ingresses list SHALL accept inputType as exactly one of rtmp, whip or url, SHALL return every input type when the parameter is absent, and SHALL reject any other value with 400 VALIDATION_ERROR.

Scenario: WHIP only

GIVEN an RTMP, a WHIP and a URL ingress created in range
WHEN the client sends ?inputType=whip
THEN items holds only the WHIP ingress

Scenario: Unknown input type

WHEN the client sends ?inputType=srt
THEN the response is 400 with code VALIDATION_ERROR and details.issues[0].path equal to ["inputType"]

Requirement: Time range and sort key

Edition: CE. The ingresses list SHALL apply from/to as an activity range, the union of the ingresses created in it (createdAt_id), those with lastSessionAt in it (lastSessionAt_id) and those publishing now (status: publishing) with createdAt ≤ to (status_createdAt). It SHALL accept sort only as createdAt, totalDuration, sessions or lastSession (else 400 VALIDATION_ERROR) and order as asc or desc (default desc).

Scenario: Oldest first

WHEN the client sends ?order=asc
THEN items are ordered by createdAt asc with _id asc as tie-breaker

Scenario: Unsupported sort key

WHEN the client sends ?sort=lastSessionAt
THEN the response is 400 with code VALIDATION_ERROR and details.issues[0].path equal to ["sort"]

Scenario: Used in the range

GIVEN an inactive ingress created 20 days ago whose last session started 2 hours ago
WHEN the client sends ?from=now-24h&to=now
THEN the ingress is in items

Scenario: Publishing for days

GIVEN an ingress created 30 days ago whose session started 3 days ago and is publishing now
WHEN the client sends ?from=now-1h&to=now
THEN the ingress is in items

Scenario: Idle in the range

GIVEN an inactive ingress created 30 days ago whose last session started 10 days ago
WHEN the client sends ?from=now-24h&to=now
THEN the ingress is not in items

Scenario: Created after the range

GIVEN an ingress created today that is publishing now
WHEN the client sends a range that ended yesterday
THEN the ingress is not in items

Scenario: Listed once

GIVEN an ingress created 1 hour ago whose only session started 50 minutes ago and is publishing now
WHEN the client sends ?from=now-24h&to=now
THEN the ingress appears once in items and counts once in total

Requirement: Name prefix search and id lookup

Edition: CE. The ingresses list SHALL treat q as a case-insensitive prefix over the ingress name when it has at least two characters, combined with the activity range, status and inputType, SHALL reject a one-character q with 400, and SHALL treat a value matching ^IN_[A-Za-z0-9]+$ as an exact id lookup that ignores from, to, status, inputType and sort and returns at most one item.

Scenario: Prefix search

GIVEN ingresses named Cam-1, cam-2 and my-cam created in range
WHEN the client sends ?q=CA
THEN items holds Cam-1 and cam-2 ordered by createdAt desc, and not my-cam

Scenario: One character

WHEN the client sends ?q=c
THEN the response is 400 with code VALIDATION_ERROR, details.issues[0].path equal to ["q"] and a message stating the two-character minimum

Scenario: Exact id outside the range

GIVEN a deleted ingress IN_ab12cd created 40 days ago
WHEN the client sends ?q=IN_ab12cd&from=now-24h&status=publishing
THEN the response is 200 with that single ingress in items, total: 1 and both cursors null

Scenario: Prefix of an ingress used in the range

GIVEN an ingress named Studio created 20 days ago whose last session started 1 hour ago
WHEN the client sends ?q=stu&from=now-24h&to=now
THEN the ingress is in items

Requirement: Ingresses summary endpoint

Edition: CE. GET /api/v1/ingresses/summary SHALL accept from, to and tz and answer 200 with { publishingNow, ingressesInRange, byInputType, sessionsInRange, totalDurationMs, approximate }, where ingressesInRange and byInputType count the ingresses the list selects for the range, the two session numbers are hour-aligned sums of the global hourly rollups and approximate is true when the range bounds are not on hour boundaries.

Scenario: Numbers of a range

GIVEN 2 ingresses publishing now and created in the last 24 hours, 3 more created in the last 24 hours (5 in all: 3 RTMP, 2 WHIP), 12 sessions started and 6 hours of sessions ended in the hourly buckets of that range
WHEN the client requests GET /api/v1/ingresses/summary?from=now-24h&to=now
THEN the response is { publishingNow: 2, ingressesInRange: 5, byInputType: { rtmp: 3, whip: 2, url: 0 }, sessionsInRange: 12, totalDurationMs: 21600000, approximate: true }

Scenario: Hour-aligned range

WHEN the client requests ?from=2026-10-13T00:00:00Z&to=2026-10-13T12:00:00Z
THEN sessionsInRange and totalDurationMs are the sums of ingress.sessionsStarted and ingress.durationMs of the twelve global hourly buckets and approximate is false

Scenario: Publishing count ignores the range

GIVEN an ingress created 30 days ago that is publishing now
WHEN the client requests the summary with from=now-1h
THEN publishingNow counts it and ingressesInRange counts it too, as the list shows it

Scenario: Reused ingress counted by activity

GIVEN an idle ingress created 30 days ago whose last session started 2 hours ago
WHEN the client requests the summary with from=now-24h
THEN ingressesInRange counts it and publishingNow does not

Scenario: Ingresses selected for the range

WHEN the client requests the summary of a range
THEN ingressesInRange and byInputType count the ingresses created in the range, those with a session started in it and those publishing now and created before to

Requirement: Index-backed ingress queries

Edition: CE and PRO. Every query of this capability SHALL run on an index of the shared contract (dashboard-ce/typings/contract/indexes.ts), or on _id for the hourly rollups the long-range summary reads: no winning plan contains a COLLSCAN, and totalDocsExamined is bounded by the page size plus the documented residual filters, and for the list by the ingresses of the three branches of the activity range.

Scenario: Explain plans on the generated database

GIVEN a database generated by the data generator at scenario M
WHEN the list (every filter combination and sort) and summary queries are explained
THEN each winning plan uses an index of the shared contract and none contains COLLSCAN

Scenario: Activity range over 30 days

GIVEN a database generated at scenario M for 30 days
WHEN the list is explained with each sort key over 30 days for createdAt and over 7 days for the others
THEN the three branches use createdAt_id, lastSessionAt_id and status_createdAt, totalDocsExamined is at most the ingresses the branches select, and the p95 of a page is within 200 ms

Requirement: Ranked ingress sorts

Edition: CE. Every ingress sort SHALL rank in memory as api-conventions defines: createdAt ranks createdAt over any range; totalDuration ranks totalDurationMs plus asOf − lastSessionAt while publishing, sessions ranks sessions and lastSession ranks lastSessionAt, these three accepted when the range is within DASHBOARD_LIST_TOTAL_MAX_RANGE and answered 400 with code SORT_RANGE_TOO_WIDE beyond it.

Scenario: Total duration with a running session

GIVEN in the activity range: an inactive ingress with totalDurationMs of 3 hours, an inactive ingress with 20 minutes, and an ingress publishing with totalDurationMs of 1 hour whose last session started 90 minutes before asOf
WHEN the client sends GET /api/v1/ingresses?sort=totalDuration
THEN items holds the 3-hour ingress, the publishing ingress (2 h 30 min at asOf) and the 20-minute ingress, in that order

Scenario: Most used first

GIVEN ingresses in the activity range with sessions 12, 1 and 5
WHEN the client sends ?sort=sessions&order=desc
THEN items holds the ingresses with 12, 5 and 1 sessions, in that order

Scenario: Latest session first

GIVEN ingresses in the activity range whose last sessions started 2 hours, 10 minutes and 6 hours ago
WHEN the client sends ?sort=lastSession
THEN items holds them in the order 10 minutes, 2 hours and 6 hours ago

Scenario: Creation order over any range

WHEN the client sends ?sort=createdAt&from=now-90d&to=now
THEN the response is 200 with the ingresses of the activity range newest first

Scenario: Metric sort beyond the limit

GIVEN the default DASHBOARD_LIST_TOTAL_MAX_RANGE of 7 days
WHEN the client sends ?sort=sessions&from=now-30d&to=now
THEN the response is 400 with code SORT_RANGE_TOO_WIDE

13 KiB Raw Permalink Blame History Unescape Escape