From 70a0b0488c5e8f2ac847dabddcafafe645e06368 Mon Sep 17 00:00:00 2001 From: juancarmore Date: Wed, 28 Oct 2026 17:04:02 +0100 Subject: [PATCH] openvidu-dashboard: archive graceful-shutdown-drain, keep only the specs --- .../graceful-shutdown-drain/.openspec.yaml | 2 - .../changes/graceful-shutdown-drain/design.md | 27 ------------- .../graceful-shutdown-drain/proposal.md | 39 ------------------- .../specs/server-analytics-writer/spec.md | 24 ------------ .../changes/graceful-shutdown-drain/tasks.md | 14 ------- .../specs/server-analytics-writer/spec.md | 16 +++++--- 6 files changed, 11 insertions(+), 111 deletions(-) delete mode 100644 openvidu-dashboard/openspec/changes/graceful-shutdown-drain/.openspec.yaml delete mode 100644 openvidu-dashboard/openspec/changes/graceful-shutdown-drain/design.md delete mode 100644 openvidu-dashboard/openspec/changes/graceful-shutdown-drain/proposal.md delete mode 100644 openvidu-dashboard/openspec/changes/graceful-shutdown-drain/specs/server-analytics-writer/spec.md delete mode 100644 openvidu-dashboard/openspec/changes/graceful-shutdown-drain/tasks.md diff --git a/openvidu-dashboard/openspec/changes/graceful-shutdown-drain/.openspec.yaml b/openvidu-dashboard/openspec/changes/graceful-shutdown-drain/.openspec.yaml deleted file mode 100644 index 97e364202..000000000 --- a/openvidu-dashboard/openspec/changes/graceful-shutdown-drain/.openspec.yaml +++ /dev/null @@ -1,2 +0,0 @@ -schema: spec-driven -created: 2026-10-27 diff --git a/openvidu-dashboard/openspec/changes/graceful-shutdown-drain/design.md b/openvidu-dashboard/openspec/changes/graceful-shutdown-drain/design.md deleted file mode 100644 index bc0df7fef..000000000 --- a/openvidu-dashboard/openspec/changes/graceful-shutdown-drain/design.md +++ /dev/null @@ -1,27 +0,0 @@ -# Design - -## Context - -- On the first `SIGINT`, `SIGTERM` or `SIGQUIT` the server calls `Stop(false)`: it drains the router and waits, every - 5 s, until it has no participants. A second signal calls `Stop(true)`, which does not wait; the server then closes - its rooms with `SERVER_SHUTDOWN` and `openvidu.Stop` flushes telemetry and the analytics queues for at most 5 s. -- `docker-compose down` sends one `SIGTERM` and kills the container after its stop grace period. - -## Goals / Non-Goals - -**Goals:** -- The spec says what a planned stop and a forced stop leave in the store. - -**Non-Goals:** -- Closing rooms on the first signal, which would cut the graceful drain of media nodes. - -## Decisions - -### Describe the drain - -The drain is the server's contract with clients and with the scale-in of media nodes; the analytics writer follows it. -The requirement now covers the drain, the second signal and the kill during the drain. - -### Data model - -- No change. diff --git a/openvidu-dashboard/openspec/changes/graceful-shutdown-drain/proposal.md b/openvidu-dashboard/openspec/changes/graceful-shutdown-drain/proposal.md deleted file mode 100644 index a3d023932..000000000 --- a/openvidu-dashboard/openspec/changes/graceful-shutdown-drain/proposal.md +++ /dev/null @@ -1,39 +0,0 @@ -# Proposal - -## Why - -The "Graceful shutdown" requirement says that on `SIGTERM` a node with active rooms closes them with `SERVER_SHUTDOWN` -and flushes their end. The server does not do that: the first `SIGTERM` drains it (no new participants, wait for the -present ones to leave) and only a second signal closes the rooms. A forced stop of a node (`docker-compose down`, which -kills it after its grace period) therefore ends while it drains, writes nothing more, and the reconciler closes its -sessions as for a crashed node. The integration test of that case expects leave events and fails. - -## What Changes - -- The requirement describes the drain: during it the participants that leave are written as usual; a second signal - closes the rooms with `SERVER_SHUTDOWN`; once the rooms are closed, the flush works as before. -- A node killed while it drains is left to the reconciler, as a crashed one. -- No server or writer behaviour changes. - -Scope excludes the following: -- The drain itself and the stop of media nodes in the deployments. - -Edition: CE and PRO (server). Repositories: the specs of the dashboard, and the end-to-end reconciler tests of the -deployments (forced media node stop). - -CHANGELOG: none. - -## Capabilities - -### New Capabilities - -None. - -### Modified Capabilities - -- `server-analytics-writer`: "Graceful shutdown" describes the drain and the forced stop. - -## Impact - -- Specs only, and the forced media node stop case of the end-to-end reconciler tests, which now expects the - reconciler to close the sessions of a node stopped by force. diff --git a/openvidu-dashboard/openspec/changes/graceful-shutdown-drain/specs/server-analytics-writer/spec.md b/openvidu-dashboard/openspec/changes/graceful-shutdown-drain/specs/server-analytics-writer/spec.md deleted file mode 100644 index 9dadf97ee..000000000 --- a/openvidu-dashboard/openspec/changes/graceful-shutdown-drain/specs/server-analytics-writer/spec.md +++ /dev/null @@ -1,24 +0,0 @@ -## MODIFIED Requirements - -### Requirement: Graceful shutdown -Edition: CE and PRO. On a first `SIGTERM` or `SIGINT` the server drains: it takes no new participants and waits for -the present ones to leave, whose leave events are written as usual; a second signal closes the rooms with -`SERVER_SHUTDOWN`. Once the rooms are closed the server SHALL flush the telemetry stats workers and operation queue -into the writer and write every queued event and stat before exiting, waiting at most 5 s; entries not written in that -window SHALL be counted as dropped. A node killed while it drains writes nothing more and its open sessions are left -to the reconciler. - -#### Scenario: Planned restart -- **GIVEN** a node with active rooms and participants -- **WHEN** it receives `SIGTERM` and then a second `SIGTERM` -- **THEN** the database holds the `ROOM_ENDED (ROOM_END_SERVER_SHUTDOWN)` and `PARTICIPANT_LEFT` events and the entities are `closed`/`left` with the final stats flushed - -#### Scenario: Killed while draining -- **GIVEN** a node with active participants that receives one `SIGTERM` -- **WHEN** it is killed before they leave, as `docker-compose down` does after its grace period -- **THEN** no end event of those sessions is written and the reconciler closes them as for a crashed node, with `closedBy: "reconciler"` - -#### Scenario: Database unavailable at shutdown -- **GIVEN** an unreachable database -- **WHEN** the node receives `SIGTERM` -- **THEN** the process exits within 5 s of the signal and logs the number of dropped entries diff --git a/openvidu-dashboard/openspec/changes/graceful-shutdown-drain/tasks.md b/openvidu-dashboard/openspec/changes/graceful-shutdown-drain/tasks.md deleted file mode 100644 index 60633474c..000000000 --- a/openvidu-dashboard/openspec/changes/graceful-shutdown-drain/tasks.md +++ /dev/null @@ -1,14 +0,0 @@ -# Tasks - -## 1. Tests - -- [x] 1.1 Make the forced media node stop case of the end-to-end reconciler tests expect the reconciler to close the - sessions of the node. Verify by running it on the deployment playground. - -## 2. Docs and CHANGELOG - -- [x] 2.1 No CHANGELOG line and no `AGENTS.md` change. Verify by reading the change against both. - -## 3. Integration check - -- [x] 3.1 Run the spec validation and the format check of the dashboard. Verify that they pass. diff --git a/openvidu-dashboard/openspec/specs/server-analytics-writer/spec.md b/openvidu-dashboard/openspec/specs/server-analytics-writer/spec.md index 58dbc503a..116c28293 100644 --- a/openvidu-dashboard/openspec/specs/server-analytics-writer/spec.md +++ b/openvidu-dashboard/openspec/specs/server-analytics-writer/spec.md @@ -290,16 +290,22 @@ the rest of the batch is applied. - **THEN** every other document is written, the rejected one is counted as a write error and the batch is not retried ### Requirement: Graceful shutdown -Edition: CE and PRO. On `SIGTERM` or `SIGINT`, after rooms are closed with `SERVER_SHUTDOWN`, the server -SHALL flush the telemetry stats workers and operation queue into the writer and write every queued event -and stat before exiting, waiting at most 5 s; entries not written in that window SHALL be counted as -dropped. +Edition: CE and PRO. On a first `SIGTERM` or `SIGINT` the server drains: it takes no new participants and waits for +the present ones to leave, whose leave events are written as usual; a second signal closes the rooms with +`SERVER_SHUTDOWN`. Once the rooms are closed the server SHALL flush the telemetry stats workers and operation queue +into the writer and write every queued event and stat before exiting, waiting at most 5 s; entries not written in that +window SHALL be counted as dropped. #### Scenario: Planned restart - **GIVEN** a node with active rooms and participants -- **WHEN** it receives `SIGTERM` +- **WHEN** it receives `SIGTERM` and then a second `SIGTERM` - **THEN** the database holds the `ROOM_ENDED (ROOM_END_SERVER_SHUTDOWN)` and `PARTICIPANT_LEFT` events and the entities are `closed`/`left` with the final stats flushed +#### Scenario: Killed while draining +- **GIVEN** a node with active participants that receives one `SIGTERM` +- **WHEN** it is killed before they leave, as `docker-compose down` does after its grace period +- **THEN** no end event of those sessions is written and the reconciler closes them as for a crashed node, with `closedBy: "reconciler"` + #### Scenario: Database unavailable at shutdown - **GIVEN** an unreachable database - **WHEN** the node receives `SIGTERM`