From d12cab6bc59f6e958addd86aad70a6595091de9b Mon Sep 17 00:00:00 2001 From: juancarmore Date: Wed, 28 Oct 2026 17:04:02 +0100 Subject: [PATCH] openvidu-dashboard: archive analytics-requires-mongodb, keep only the specs --- .../analytics-requires-mongodb/.openspec.yaml | 2 - .../analytics-requires-mongodb/design.md | 50 ------------------- .../analytics-requires-mongodb/proposal.md | 49 ------------------ .../specs/deployment-compatibility/spec.md | 16 ------ .../specs/server-analytics-writer/spec.md | 17 ------- .../analytics-requires-mongodb/tasks.md | 19 ------- .../specs/deployment-compatibility/spec.md | 2 +- .../specs/server-analytics-writer/spec.md | 16 ++++++ 8 files changed, 17 insertions(+), 154 deletions(-) delete mode 100644 openvidu-dashboard/openspec/changes/analytics-requires-mongodb/.openspec.yaml delete mode 100644 openvidu-dashboard/openspec/changes/analytics-requires-mongodb/design.md delete mode 100644 openvidu-dashboard/openspec/changes/analytics-requires-mongodb/proposal.md delete mode 100644 openvidu-dashboard/openspec/changes/analytics-requires-mongodb/specs/deployment-compatibility/spec.md delete mode 100644 openvidu-dashboard/openspec/changes/analytics-requires-mongodb/specs/server-analytics-writer/spec.md delete mode 100644 openvidu-dashboard/openspec/changes/analytics-requires-mongodb/tasks.md diff --git a/openvidu-dashboard/openspec/changes/analytics-requires-mongodb/.openspec.yaml b/openvidu-dashboard/openspec/changes/analytics-requires-mongodb/.openspec.yaml deleted file mode 100644 index 97e364202..000000000 --- a/openvidu-dashboard/openspec/changes/analytics-requires-mongodb/.openspec.yaml +++ /dev/null @@ -1,2 +0,0 @@ -schema: spec-driven -created: 2026-10-27 diff --git a/openvidu-dashboard/openspec/changes/analytics-requires-mongodb/design.md b/openvidu-dashboard/openspec/changes/analytics-requires-mongodb/design.md deleted file mode 100644 index 867faea73..000000000 --- a/openvidu-dashboard/openspec/changes/analytics-requires-mongodb/design.md +++ /dev/null @@ -1,50 +0,0 @@ -# Design - -## Context - -- `openvidu.Start` calls `analytics.InitializeAnalytics`, which connects, pings, renames the legacy events collection, - initializes collections, validators and indexes, and prepares the writer, the reconciler and the migration. Any error - stops the server ("An error means the server must not start"). -- Measured against Amazon DocumentDB 5.0.0 and 8.0.0: updates with an aggregation pipeline fail with "Wrong type for - parameter u", time-series collections, partial indexes with `$in`, `validationAction: warn`, `$facet`, - `$setWindowFields`, `$percentile` and `$median` are not supported, and collections cannot be created inside - transactions. - -## Goals / Non-Goals - -**Goals:** -- An OpenVidu server configured with a DocumentDB URI starts and serves media, with analytics off and a log that says - why. - -**Non-Goals:** -- Writing analytics to DocumentDB. -- Changing how other startup failures behave (unreachable MongoDB, a newer schema, a bad configuration). - -## Decisions - -### Probe the capability, not the vendor - -The writer asks the database to explain an update with an aggregation pipeline on `schema_meta`. MongoDB plans it -without writing; a database without pipeline updates rejects it. Only the rejection of the pipeline form disables -analytics; any other error of the probe, such as a lost connection, is returned as before and stops the server. - -Alternative rejected: recognising DocumentDB by host name or `buildInfo`. Host names can be aliased and the build -information is not a contract; the capability is what the writer needs. - -Alternative rejected: probing with a real update. It writes a document that the contract validators do not expect. - -### Disabled, not degraded - -Without pipeline updates no entity can be projected, so there is nothing useful to keep: no collections, indexes, -reconciler or migration. The server keeps `analyticsEnabled` false, as when `openvidu.analytics.enabled` is false. - -### Data model - -- No collection, field, index or schema-version change; nothing is written to an unsupported database. -- Migration from legacy events: not run on an unsupported database; legacy collections stay as they are. -- Performance: one explain at startup. - -## Risks / Trade-offs - -- [A future MongoDB-compatible service accepts the explain but not the update] → Initialization would then fail as - today and stop the server; the log names the failing step. diff --git a/openvidu-dashboard/openspec/changes/analytics-requires-mongodb/proposal.md b/openvidu-dashboard/openspec/changes/analytics-requires-mongodb/proposal.md deleted file mode 100644 index bf1a2d0a4..000000000 --- a/openvidu-dashboard/openspec/changes/analytics-requires-mongodb/proposal.md +++ /dev/null @@ -1,49 +0,0 @@ -# Proposal - -## Why - -The writer updates every entity with an aggregation pipeline, creates `track_stats` as a time-series collection when it -can, uses partial indexes with `$in` and validators with `validationAction: warn`. Amazon DocumentDB (5.0 and 8.0) -supports none of the first, third and fourth, so database initialization fails and the server refuses to start: -`failed to start analytics: ... Feature not supported: validationAction:warn`. Deployments that use DocumentDB as their -external database would lose the whole OpenVidu server on upgrade, not only analytics. - -## What Changes - -- Before initializing the database, the writer checks that it runs updates with an aggregation pipeline, without - writing. A database that does not (Amazon DocumentDB) disables analytics: the server logs an error that names the - reason and that analytics and the dashboard need MongoDB, then starts and runs without analytics. It writes nothing - to that database. -- Every other analytics startup failure still stops the server. -- The dashboard's private CA variable is no longer described as a way to use Amazon DocumentDB. - -Scope excludes the following: -- A write path for databases without pipeline updates. -- The dashboard against such a database, which reports an uninitialized writer schema as it already does. -- The public documentation of external databases, updated with the release documentation. - -Edition: CE and PRO (writer). Repositories: openvidu-livekit (`openvidu/analytics`, `openvidu/openvidu.go`) and the -dashboard (specs, CHANGELOG). - -CHANGELOG lines: -- `openvidu-dashboard/CHANGELOG.md`, Upgrade notes: analytics and the dashboard require MongoDB; on Amazon DocumentDB the - server starts with analytics disabled. The `DATABASE_TLS_CA_FILE` line no longer names DocumentDB. -- openvidu-livekit `CHANGELOG-openvidu.md`, Changed: the same behaviour of the server. - -## Capabilities - -### New Capabilities - -None. - -### Modified Capabilities - -- `server-analytics-writer`: a database without pipeline updates disables analytics instead of stopping the server. -- `deployment-compatibility`: the private CA requirement names no DocumentDB. - -## Impact - -- Writer: `InitializeAnalytics` probes the database after the connection check; `openvidu.Start` treats the - unsupported database as analytics disabled. Unit tests of the probe classification and an integration test against - MongoDB. -- Dashboard: specs and CHANGELOG only. diff --git a/openvidu-dashboard/openspec/changes/analytics-requires-mongodb/specs/deployment-compatibility/spec.md b/openvidu-dashboard/openspec/changes/analytics-requires-mongodb/specs/deployment-compatibility/spec.md deleted file mode 100644 index 3b2b4a139..000000000 --- a/openvidu-dashboard/openspec/changes/analytics-requires-mongodb/specs/deployment-compatibility/spec.md +++ /dev/null @@ -1,16 +0,0 @@ -## MODIFIED Requirements - -### Requirement: TLS certificate authority for external MongoDB -Both editions. When `DATABASE_TLS_CA_FILE` is set, the dashboard SHALL connect with TLS and trust the PEM -bundle at that path (for MongoDB services whose certificates a private CA signs). - -#### Scenario: Private CA accepted -- **GIVEN** a MongoDB server presenting a certificate signed by a private CA and `DATABASE_TLS_CA_FILE` - pointing to that CA -- **WHEN** the dashboard starts -- **THEN** the connection succeeds - -#### Scenario: Unreadable CA file -- **GIVEN** `DATABASE_TLS_CA_FILE` pointing to a missing or unreadable file -- **WHEN** the dashboard starts -- **THEN** it logs the path and exits with code 1 diff --git a/openvidu-dashboard/openspec/changes/analytics-requires-mongodb/specs/server-analytics-writer/spec.md b/openvidu-dashboard/openspec/changes/analytics-requires-mongodb/specs/server-analytics-writer/spec.md deleted file mode 100644 index 43ebe2139..000000000 --- a/openvidu-dashboard/openspec/changes/analytics-requires-mongodb/specs/server-analytics-writer/spec.md +++ /dev/null @@ -1,17 +0,0 @@ -## ADDED Requirements - -### Requirement: Database without pipeline updates -Edition: CE and PRO. Before initializing the database, the writer SHALL check, without writing, that it runs updates -with an aggregation pipeline. When it does not, the server SHALL log an error naming the reason and that analytics and -the dashboard require MongoDB, write nothing to that database and start without analytics; any other analytics startup -failure SHALL still stop the server. - -#### Scenario: Amazon DocumentDB as external database -- **GIVEN** `openvidu.analytics.enabled: true` and `mongo_url` pointing to an Amazon DocumentDB cluster -- **WHEN** the server starts -- **THEN** it logs an error saying that the database does not support updates with aggregation pipelines and that analytics and the dashboard require MongoDB, accepts participants, and no analytics collection is created in the cluster - -#### Scenario: Unreachable MongoDB -- **GIVEN** `mongo_url` pointing to a MongoDB that does not answer -- **WHEN** the server starts -- **THEN** it refuses to start, as before diff --git a/openvidu-dashboard/openspec/changes/analytics-requires-mongodb/tasks.md b/openvidu-dashboard/openspec/changes/analytics-requires-mongodb/tasks.md deleted file mode 100644 index 2dabda862..000000000 --- a/openvidu-dashboard/openspec/changes/analytics-requires-mongodb/tasks.md +++ /dev/null @@ -1,19 +0,0 @@ -# Tasks - -## 1. Writer (openvidu-livekit) - -- [x] 1.1 Add the pipeline update probe (an explain on `schema_meta`) and the unsupported database error to - `openvidu/analytics`, run it after the connection check, and make `openvidu.Start` log it and start without - analytics. Verify with unit tests of the error classification, an integration test against MongoDB and the lint - of the fork. -- [x] 1.2 Start the server image against an Amazon DocumentDB cluster. Verify that it logs the error, serves a room - and creates no collection in the cluster. - -## 2. Docs and CHANGELOG - -- [x] 2.1 Add the upgrade note and correct the `DATABASE_TLS_CA_FILE` line of `openvidu-dashboard/CHANGELOG.md`, and add - the Changed line of `CHANGELOG-openvidu.md`. Verify by reading both against the change. - -## 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/deployment-compatibility/spec.md b/openvidu-dashboard/openspec/specs/deployment-compatibility/spec.md index 1c7ae4ee4..d01b5efa3 100644 --- a/openvidu-dashboard/openspec/specs/deployment-compatibility/spec.md +++ b/openvidu-dashboard/openspec/specs/deployment-compatibility/spec.md @@ -90,7 +90,7 @@ that MongoDB is disabled and exit with code 0 before connecting to anything; uns ### Requirement: TLS certificate authority for external MongoDB Both editions. When `DATABASE_TLS_CA_FILE` is set, the dashboard SHALL connect with TLS and trust the PEM -bundle at that path (for services such as Amazon DocumentDB). +bundle at that path (for MongoDB services whose certificates a private CA signs). #### Scenario: Private CA accepted - **GIVEN** a MongoDB server presenting a certificate signed by a private CA and `DATABASE_TLS_CA_FILE` diff --git a/openvidu-dashboard/openspec/specs/server-analytics-writer/spec.md b/openvidu-dashboard/openspec/specs/server-analytics-writer/spec.md index a0d52cf38..58dbc503a 100644 --- a/openvidu-dashboard/openspec/specs/server-analytics-writer/spec.md +++ b/openvidu-dashboard/openspec/specs/server-analytics-writer/spec.md @@ -519,3 +519,19 @@ allow-list and its redactions, including strings that start with `$` and map key - **GIVEN** `store_metadata: true`, a room `$room` with metadata `$$ROOT`, a participant `$$ROOT` named `$name` with metadata `$metadata` and attributes `{ "$role": "$host", "team.name": "$blue" }`, and an egress of the room that fails with error `$error` - **WHEN** their events are projected - **THEN** the room has `name: "$room"`, `config.metadata: "$$ROOT"` and one unique identity, the participant has `identity: "$$ROOT"`, `name: "$name"`, `metadata: "$metadata"` and those attributes, and the egress has `error: "$error"` + +### Requirement: Database without pipeline updates +Edition: CE and PRO. Before initializing the database, the writer SHALL check, without writing, that it runs updates +with an aggregation pipeline. When it does not, the server SHALL log an error naming the reason and that analytics and +the dashboard require MongoDB, write nothing to that database and start without analytics; any other analytics startup +failure SHALL still stop the server. + +#### Scenario: Amazon DocumentDB as external database +- **GIVEN** `openvidu.analytics.enabled: true` and `mongo_url` pointing to an Amazon DocumentDB cluster +- **WHEN** the server starts +- **THEN** it logs an error saying that the database does not support updates with aggregation pipelines and that analytics and the dashboard require MongoDB, accepts participants, and no analytics collection is created in the cluster + +#### Scenario: Unreachable MongoDB +- **GIVEN** `mongo_url` pointing to a MongoDB that does not answer +- **WHEN** the server starts +- **THEN** it refuses to start, as before