ambiser
/
openvidu
mirror of https://github.com/OpenVidu/openvidu.git
9
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
openvidu/openvidu-dashboard/openspec/specs/overview-api/spec.md

8.1 KiB
Raw Blame History

overview-api Specification

Purpose

The overview endpoint: one cheap, index-backed response with the live counters, today's totals, recent rooms and stale hints that the Overview page and the live counter tiles poll.

Requirements

Requirement: Overview endpoint

Edition: CE. GET /api/v1/overview SHALL require a bearer token, accept only tz (IANA zone or UTC, default UTC) and answer 200 with generatedAt, live, today and recentRooms; an unknown tz SHALL be rejected with 400. The writer health, schema and migration are served by GET /api/v1/status.

Scenario: Default response

  • GIVEN a deployment with a running writer
  • WHEN the client requests GET /api/v1/overview with a valid token
  • THEN the response is 200 with generatedAt within one second of the server clock and the keys live, today and recentRooms, and no nodes key on CE

Scenario: Unknown timezone

  • WHEN the client requests GET /api/v1/overview?tz=Mars/Olympus
  • THEN the response is 400 with code VALIDATION_ERROR and details.issues[0].path equal to ["tz"]

Requirement: Live counters

Edition: CE. live SHALL carry rooms (status active), participants (status active, kind STANDARD), services (status active, every kind but STANDARD), participantsByKind (every kind, 0 when absent), publishers (active STANDARD with isPublisher), egresses (status starting, active or ending) and ingressSessions (status publishing).

Scenario: Mixed kinds

  • GIVEN 12 active rooms holding 85 active STANDARD, 2 SIP, 3 EGRESS and 2 AGENT participants, 54 STANDARD publishers and 1 INGRESS publisher, 3 egresses in status active, 1 in ending and 1 complete, and 1 publishing ingress session
  • WHEN the client requests the overview
  • THEN live is { rooms: 12, participants: 85, services: 7, participantsByKind: { STANDARD: 85, SIP: 2, INGRESS: 0, EGRESS: 3, AGENT: 2, CONNECTOR: 0, BRIDGE: 0 }, publishers: 54, egresses: 4, ingressSessions: 1, stale: … }

Scenario: Joining participants are not active

  • GIVEN a room with one active and one joining STANDARD participant
  • WHEN the client requests the overview
  • THEN live.participants is 1

Requirement: Stale hints

Edition: CE. live.stale SHALL carry rooms and participants, the number of active documents whose lastStatsAt is older than olderThanMs at generatedAt, and olderThanMs itself: the stale window max(90 s, 60 s + I + 15 s) of the batch interval I that GET /api/v1/status reports as writer.batchIntervalMs (the largest among the nodes seen in the last hour, 10 s when none reports one); documents without lastStatsAt SHALL NOT be counted.

Scenario: Stale room and participants

  • GIVEN nodes reporting batchIntervalMs: 10000, an active room whose lastStatsAt is 100 s old with two active participants with lastStatsAt 100 s old, and another active room with fresh stats
  • WHEN the client requests the overview
  • THEN live.stale is { rooms: 1, participants: 2, olderThanMs: 90000 }

Scenario: Signal-only participant

  • GIVEN an active participant that never published nor subscribed and has no lastStatsAt
  • WHEN the client requests the overview
  • THEN it is not counted in live.stale.participants

Scenario: Slow writer

  • GIVEN a node seen in the last hour with batchIntervalMs: 60000 and an active room with one active participant, both with lastStatsAt 100 s old
  • WHEN the client requests the overview
  • THEN live.stale is { rooms: 0, participants: 0, olderThanMs: 135000 }

Scenario: Nodes without a reported interval

  • GIVEN node documents without batchIntervalMs
  • WHEN the client requests the overview
  • THEN live.stale.olderThanMs is 90000

Scenario: Window at the default interval

  • GIVEN the default batch interval of 10 s
  • WHEN the overview is requested
  • THEN live.stale.olderThanMs is 90 000

Requirement: Today's figures

Edition: CE. today SHALL carry tz, since (local midnight of tz in UTC), rooms, participantSessions, participantMinutes, egresses, ingressSessions and approximate, summed from the global hourly rollups whose bucket starts at or after the hour containing since; approximate is true when since is not on an hour boundary.

Scenario: Whole-hour zone

  • GIVEN tz=Europe/Madrid at 12:40 local time on 2026-10-13 and hourly global rollups since 22:00 UTC of the previous day summing rooms.created 143, participants.joined 1204, participants.minutes 18340, egress.started 21 and ingress.sessionsStarted 4
  • WHEN the client requests the overview
  • THEN today is { tz: "Europe/Madrid", since: "2026-10-12T22:00:00.000Z", rooms: 143, participantSessions: 1204, participantMinutes: 18340, egresses: 21, ingressSessions: 4, approximate: false }

Scenario: Half-hour zone

  • GIVEN tz=Asia/Kolkata
  • WHEN the client requests the overview
  • THEN today.since is 18:30 UTC of the previous day, the sum starts at the 18:00 UTC bucket and approximate is true

Scenario: No rollups yet

  • GIVEN an empty analytics_hourly collection
  • WHEN the client requests the overview
  • THEN every counter of today is 0 and approximate is false

Requirement: Recent rooms

Edition: CE. recentRooms SHALL list at most 10 rooms of any status ordered by createdAt descending, each with sid, name, status, createdAt, endedAt?, durationMs?, closedBy?, participants { active, sessions, unique } (unique: distinct STANDARD identities), nodeId?, lastStatsAt? and stale? (true for an active room whose lastStatsAt is older than the stale window at generatedAt), never internal id arrays, schemaVersion or expiresAt.

Scenario: Twelve rooms

  • GIVEN 12 rooms, the newest two active
  • WHEN the client requests the overview
  • THEN recentRooms has 10 items starting with the two active rooms, each with the listed fields and no participantSids

Scenario: Unique identities of a recent room

  • GIVEN a closed room with 7 STANDARD sessions of 4 identities and one EGRESS session
  • WHEN the client requests the overview
  • THEN its recentRooms item has participants: { active: 0, sessions: 7, unique: 4 }

Scenario: Stale recent room

  • GIVEN an active room whose lastStatsAt is 2 minutes before generatedAt and a writer batch interval of 10 s
  • WHEN the client requests the overview
  • THEN its recentRooms item has stale: true and an active room with stats 20 s old has no stale field

Scenario: Empty database

  • WHEN no room exists
  • THEN recentRooms is []

Requirement: Conditional overview

Edition: CE. The response SHALL carry a weak ETag derived from the body without generatedAt and Cache-Control: private, no-cache; a request whose If-None-Match matches SHALL answer 304 without a body.

Scenario: Quiet deployment

  • GIVEN a client holding the ETag of the last overview
  • WHEN it polls again 10 s later and no counter, room, rollup or node fact changed
  • THEN the response is 304 with the same ETag and an empty body

Scenario: Writer batch without changes on CE

  • GIVEN the same client on CE
  • WHEN a batch updated only nodes.lastSeenAt
  • THEN the response is 304

Requirement: Index-backed overview

Edition: CE. Every overview query SHALL use an index of the shared contract (rooms { status, createdAt }, participants { status, kind }, egresses { status, startedAt }, ingress_sessions { status }, analytics_hourly { scope, bucket }), examining at most each collection's active documents plus 20 rooms; nodes, bounded by the node count, is read whole for the stale window's batch interval; schema_meta is not read.

Scenario: Explain plans

  • GIVEN a database generated by the data generator at scenario M
  • WHEN each overview query is explained
  • THEN no plan on rooms, participants, egresses, ingress_sessions or analytics_hourly contains COLLSCAN, and totalDocsExamined of the room and participant aggregations equals the number of active documents