openvidu/openvidu-dashboard/openspec/changes/writer-review-fixes/design.md

Design

Context

• Ingress state: IOInfoService.UpdateIngressState (pkg/service/ioservice_ingress.go) stores the state the ingress service sends and emits IngressStarted, IngressUpdated or IngressEnded with it. On a local deployment the buffering and publishing states arrive with an empty room_id, and only the ending state names the room (RM_rgFu9jsQne28), although the ingress participant joined that room 40 ms before the publishing state.
• Ingress projection: the writer's projection/ingress.go lifts roomSid from state.room_id, and adds the session to the room's internal.ingressSessionIds only when it is set.
• Ingress store: IOInfoService holds an IngressStore, which getIngressStore resolves to the *RedisStore, also the ObjectStore that loads rooms by name. Ingress needs Redis.
• Egress history: projection/egress.go adds { status, at } to statusHistory with $setUnion, which drops only identical entries: two active updates 13 ms apart, one per output, both stay.
• Browser vocabulary: projection/vocabulary.go maps an empty browser to other, through browserFamily().

Goals / Non-Goals

Goals:

• A publishing ingress session is linked to, and counted by, its room with no new projection path.
• The contract stays additive.

Non-Goals:

• Changing how the ingress service reports its state (upstream LiveKit ingress).

Decisions

D1. The server names the room of an ingress state

In an OPENVIDU block of UpdateIngressState, when req.State.RoomId is empty and the ingress has a room name, the server loads that room through the store and sets the room's SID on the state it emits. A missing or failing load leaves it empty, logged at debug. The block runs before the telemetry calls, so the webhook and the analytics event carry the same state, and the stored state is updated with it too.

The store is reached through a type assertion of s.is to the room loader that *RedisStore implements, so the wire graph is unchanged.

Rejected: linking the session in the writer when the ingress participant joins. That event has no resource_id, so the room could not count the session until it ends, and the room's counters would still miss a live ingress.

D2. One status history entry per egress status

The statusHistory update keeps, for the incoming status, the entry with the earliest at: it drops any stored entry of the same status whose at is later, adds the incoming entry when no entry of that status is left, sorts by at and keeps the last 50. Egress statuses only move forward, so a repeated status is never a new step.

Rejected: comparing with the last entry only, which depends on the order events arrive in.

D3. none in the browser vocabulary

browserFamily("") returns none, and BrowserFamily gains NONE: 'none', in the contract that the validator and the writer share.

Rejected: leaving other for both, which hides SDKs without a browser among unknown browsers.

Data model

Collection	Change
ingress_sessions	roomSid set from the first publishing state, instead of the ending one.
rooms	internal.ingressSessionIds, and the counters it feeds, set as soon as the session publishes.
egresses	statusHistory with one entry per status.
analytics_5min, analytics_hourly, analytics_daily	participants.byBrowser.none.

• No index change.
• No schema version bump: the v2 schema has not shipped.
• Legacy migration: the legacy events carry no ingress state of this kind and no output updates, so the mapping is unchanged. Legacy sessions without a browser stay under other.

Performance budget

One LoadRoom (a Redis HGET) per ingress state update without a room id: a handful per ingress session. The writer budgets are unchanged; the batch benchmark covers the egress update.

Risks / Trade-offs

• [The room is recreated under the same name while the ingress publishes] → The state names the room active at the time of the update, the one the ingress participant is in.
• [The webhooks of those state updates now carry room_id] → An addition, matching what the ending state already sends.

Migration Plan

Ships with the 3.10 server, and the dashboard typings ship with it through the contract. ui-review-fixes labels the new key.