diff --git a/clients/typescript/src/schema.d.ts b/clients/typescript/src/schema.d.ts index e5df5d26fe..bd161d1265 100644 --- a/clients/typescript/src/schema.d.ts +++ b/clients/typescript/src/schema.d.ts @@ -274,6 +274,22 @@ export interface paths { patch?: never; trace?: never; }; + "/api/control/locations/{location_id}/targets/{target}/attention-acknowledgements": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get: operations["listAttentionAcknowledgements"]; + put?: never; + post: operations["acknowledgeAttention"]; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; "/api/control/locations/{location_id}/targets/{target}/catalog": { parameters: { query?: never; @@ -1598,6 +1614,51 @@ export interface components { decision_id?: string | null; error: string; }; + /** @description A condition whose latest acknowledgement event marks it handled. */ + AttentionAcknowledgement: { + /** Format: date-time */ + acknowledged_at: string; + /** @description The person's name, or the audit actor when the person no longer exists. */ + acknowledged_by: string; + /** + * Format: uuid + * @description The acknowledging audit event, which a withdrawal can name. + */ + event_id: string; + key: string; + shape: unknown; + /** + * Format: date-time + * @description When the acknowledgement lapses even if the condition never changes; none without a time limit. + */ + until?: string | null; + }; + /** @description Marks an ongoing condition handled as it looks now, or withdraws that; an event ID applies once. */ + AttentionAcknowledgementRequest: { + acknowledged: boolean; + /** Format: uuid */ + event_id: string; + /** @description The condition's kind and subject, stable while it lasts, such as `stale_sources`. */ + key: string; + /** @description Why, when it isn't a person's own choice, such as a withdrawal once the condition cleared. */ + reason?: string | null; + /** @description What the condition looks like, as a JSON object of at most 8 KiB that later states are compared with. */ + shape: unknown; + /** + * Format: uuid + * @description For a withdrawal, the acknowledgement event it withdraws: it applies only while that is still the latest. + */ + withdraws?: string | null; + }; + /** @description A target's condition acknowledgements, and how long one lasts while its condition is unchanged. */ + AttentionAcknowledgements: { + acknowledgements: components["schemas"]["AttentionAcknowledgement"][]; + /** + * Format: int64 + * @description The server's `attention_snooze` in seconds; none when acknowledgements have no time limit. + */ + snooze_seconds?: number | null; + }; AuthenticationDenial: { error: string; /** Format: uuid */ @@ -4879,6 +4940,95 @@ export interface operations { }; }; }; + listAttentionAcknowledgements: { + parameters: { + query?: never; + header?: never; + path: { + location_id: string; + target: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Conditions marked handled within two snoozes, lapsed ones included, and the snooze */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["AttentionAcknowledgements"]; + }; + }; + /** @description Session rejected */ + 401: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + 403: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ApiErrorBody"]; + }; + }; + }; + }; + acknowledgeAttention: { + parameters: { + query?: never; + header: { + "x-sqb-csrf": string; + }; + path: { + location_id: string; + target: string; + }; + cookie?: never; + }; + requestBody: { + content: { + "application/json": components["schemas"]["AttentionAcknowledgementRequest"]; + }; + }; + responses: { + /** @description Whether the condition's acknowledgement changed */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["MutationResponse"]; + }; + }; + /** @description The key, shape or reason is invalid, or the event ID was reused */ + 400: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Session rejected */ + 401: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + 403: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ApiErrorBody"]; + }; + }; + }; + }; readPersonCatalog: { parameters: { query: { diff --git a/crates/sqlbuild-cli/src/native_commands/_helpers/command/decision.rs b/crates/sqlbuild-cli/src/native_commands/_helpers/command/decision.rs index a25c178e17..6b32a28178 100644 --- a/crates/sqlbuild-cli/src/native_commands/_helpers/command/decision.rs +++ b/crates/sqlbuild-cli/src/native_commands/_helpers/command/decision.rs @@ -5,6 +5,7 @@ use std::path::PathBuf; use chrono::{DateTime, Utc}; use serde_json::json; +use sqlbuild_orchestration::acknowledgements::models::AttentionSnooze; use sqlbuild_orchestration::api::models::{ApiAuthentication, HumanLogin, ServerFacts}; use sqlbuild_orchestration::credentials::models::{AuditRetention, CredentialScope}; use sqlbuild_orchestration::declarations::models::TriggerChange; @@ -335,6 +336,15 @@ pub(crate) fn control_api_settings( run_logs, state_history, pool_caps: Default::default(), + attention_snooze: match &config.server.attention_snooze { + Some(text) => AttentionSnooze::parse(text).map_err(|error| match error { + ControlError::Invalid(message) => { + ControlError::Invalid(format!("[server] {message}")) + } + other => other, + })?, + None => AttentionSnooze::default(), + }, }, )) } diff --git a/crates/sqlbuild-cli/src/server_config/models.rs b/crates/sqlbuild-cli/src/server_config/models.rs index 8c06fe4fed..7c3324439f 100644 --- a/crates/sqlbuild-cli/src/server_config/models.rs +++ b/crates/sqlbuild-cli/src/server_config/models.rs @@ -19,7 +19,7 @@ pub(crate) struct ServerConfig { pub(crate) launchers: Launchers, } -/// The listener, control database variable, password sign-in, default role and scheduler. +/// The listener, control database variable, password sign-in, default role, scheduler and attention snooze. #[derive(Debug, Default, serde::Deserialize)] #[serde(deny_unknown_fields)] pub(crate) struct ServerSection { @@ -29,6 +29,7 @@ pub(crate) struct ServerSection { pub(crate) password_origin: Option, pub(crate) default_role: Option, pub(crate) scheduler: Option, + pub(crate) attention_snooze: Option, } /// How long the server keeps statistics, audit records, snapshots, run logs and state history. diff --git a/crates/sqlbuild-cli/tests/native_commands/test_control.rs b/crates/sqlbuild-cli/tests/native_commands/test_control.rs index 45fed24373..f163a688d1 100644 --- a/crates/sqlbuild-cli/tests/native_commands/test_control.rs +++ b/crates/sqlbuild-cli/tests/native_commands/test_control.rs @@ -379,13 +379,13 @@ fn given_a_control_store_when_running_server_migrate_then_dry_run_lists_and_migr StoreMigrationCommandTestCase { description: "migrate an empty store", arguments: &["server", "migrate"], - expected_stdout: "The control store is empty: created schema version 2.\n", + expected_stdout: "The control store is empty: created schema version 3.\n", expected_store: true, }, StoreMigrationCommandTestCase { description: "dry run on a current store", arguments: &["server", "migrate", "--dry-run"], - expected_stdout: "The control store is at schema version 2: nothing to migrate.\n", + expected_stdout: "The control store is at schema version 3: nothing to migrate.\n", expected_store: true, }, ]; diff --git a/crates/sqlbuild-cli/tests/native_commands/test_proxy.rs b/crates/sqlbuild-cli/tests/native_commands/test_proxy.rs index ed853fbb51..bd99c87d57 100644 --- a/crates/sqlbuild-cli/tests/native_commands/test_proxy.rs +++ b/crates/sqlbuild-cli/tests/native_commands/test_proxy.rs @@ -191,6 +191,18 @@ fn given_invalid_or_conflicting_server_configuration_when_a_standalone_server_st arguments: &[], expected_error: "[retention] statistics_days must be between 1 and 65535", }, + ServerConfigurationTestCase { + description: "an attention snooze that isn't a duration names its key", + configuration: "[server]\nattention_snooze = \"a day\"\n", + arguments: &[], + expected_error: "[server] attention_snooze must be a duration such as \"24h\" or \"1d12h\", or \"0\" for no time limit", + }, + ServerConfigurationTestCase { + description: "an attention snooze in months is refused", + configuration: "[server]\nattention_snooze = \"1mo\"\n", + arguments: &[], + expected_error: "[server] attention_snooze can't use years or months", + }, ServerConfigurationTestCase { description: "the replaced trusted-proxy flag points to the file", configuration: "", diff --git a/crates/sqlbuild-orchestration/src/acknowledgements/_helpers/attention_state.rs b/crates/sqlbuild-orchestration/src/acknowledgements/_helpers/attention_state.rs new file mode 100644 index 0000000000..69394a37a0 --- /dev/null +++ b/crates/sqlbuild-orchestration/src/acknowledgements/_helpers/attention_state.rs @@ -0,0 +1,85 @@ +//! What is already stored for a condition when a person acknowledges it or withdraws that. + +use chrono::{DateTime, Utc}; +use serde_json::Value; +use uuid::Uuid; + +use crate::acknowledgements::constants::{ACKNOWLEDGED, WITHDRAWN}; +use crate::acknowledgements::models::PriorAttention; +use crate::acknowledgements::models::{ + AttentionAcknowledgementRequest, AttentionSnooze, StandingAttention, +}; +use crate::store::errors::ControlError; +use crate::store::main::query::query; +use crate::store::models::{ControlTransaction, Parameter}; + +/// The request's earlier application under its event ID, or else the condition's latest event. +pub(crate) async fn prior_attention( + transaction: ControlTransaction, + (location_id, target): (Uuid, &str), + (request, body): (&AttentionAcknowledgementRequest, &Value), +) -> Result<(ControlTransaction, PriorAttention), ControlError> { + let (transaction, retried) = query( + transaction, + "SELECT scope_json FROM sqb_security_audit WHERE event_id=$1", + vec![Parameter::Id(request.event_id)], + ) + .await?; + if let Some(previous) = retried.first() { + if previous["scope_json"].get("request") != Some(body) { + return Err(ControlError::Invalid( + "acknowledgement event ID already has different content".into(), + )); + } + return Ok((transaction, PriorAttention::Retried)); + } + let (transaction, latest) = query( + transaction, + &format!( + "SELECT event_id, action, occurred_at, scope_json FROM sqb_security_audit \ + WHERE action IN ('{ACKNOWLEDGED}','{WITHDRAWN}') AND scope_json ->> 'location_id'=$1 \ + AND scope_json ->> 'target'=$2 AND scope_json ->> 'key'=$3 ORDER BY storage_id DESC LIMIT 1" + ), + vec![ + Parameter::Text(location_id.to_string()), + Parameter::Text(target.into()), + Parameter::Text(request.key.clone()), + ], + ) + .await?; + let previous = latest.first(); + let at: Option> = previous + .map(|row| serde_json::from_value(row["occurred_at"].clone())) + .transpose() + .map_err(|error| ControlError::Schema(format!("acknowledgement time: {error}")))?; + let event_id: Option = previous + .map(|row| serde_json::from_value(row["event_id"].clone())) + .transpose() + .map_err(|error| ControlError::Schema(format!("acknowledgement event: {error}")))?; + let standing = StandingAttention { + event_id, + acknowledged: previous.is_some_and(|row| row["action"].as_str() == Some(ACKNOWLEDGED)), + shape: previous.map_or(Value::Null, |row| row["scope_json"]["shape"].clone()), + at, + }; + Ok((transaction, PriorAttention::Standing(standing))) +} + +/// Whether a request changes nothing: a held shape, or a withdrawal of nothing or of a superseded acknowledgement. +pub(crate) fn unchanged( + standing: &StandingAttention, + request: &AttentionAcknowledgementRequest, + (now, snooze): (DateTime, AttentionSnooze), +) -> bool { + if !request.acknowledged { + return !standing.acknowledged + || request + .withdraws + .is_some_and(|named| standing.event_id != Some(named)); + } + standing.acknowledged + && standing.shape == request.shape + && standing + .at + .is_some_and(|at| snooze.until(at).is_none_or(|until| now < until)) +} diff --git a/crates/sqlbuild-orchestration/src/acknowledgements/_helpers/latest_events.rs b/crates/sqlbuild-orchestration/src/acknowledgements/_helpers/latest_events.rs new file mode 100644 index 0000000000..4822cbf2a6 --- /dev/null +++ b/crates/sqlbuild-orchestration/src/acknowledgements/_helpers/latest_events.rs @@ -0,0 +1,85 @@ +//! An acknowledgement is its subject's latest acknowledging or withdrawing audit event. + +use std::collections::BTreeMap; + +use chrono::{DateTime, Utc}; +use uuid::Uuid; + +use crate::acknowledgements::models::{ + AcknowledgementEvents, AcknowledgementListing, LatestAcknowledgement, +}; +use crate::authorization::main::decisions::authorize_listing::authorize_listing; +use crate::credentials::models::AuditContext; +use crate::store::errors::ControlError; +use crate::store::main::{begin::begin, commit::commit, query::query}; +use crate::store::models::{ControlStore, Parameter, TransactionMode}; + +/// A target's acknowledgement events since `$1` with the actor's name, by subquery so the index serves it. +pub(crate) fn listing_sql(events: &AcknowledgementEvents) -> String { + format!( + "SELECT a.event_id, a.action, \ + COALESCE((SELECT p.name FROM sqb_principals p WHERE 'principal:' || CAST(p.principal_id AS TEXT)=a.actor), a.actor) AS actor, \ + a.occurred_at, a.scope_json FROM sqb_security_audit a \ + WHERE a.action IN ('{}', '{}') AND a.occurred_at >= $1 \ + AND a.scope_json ->> 'location_id'=$2 AND a.scope_json ->> 'target'=$3 ORDER BY a.storage_id", + events.acknowledged, events.withdrawn + ) +} + +/// Subjects whose latest event in the window acknowledges them, for a person who can list the runs. +pub(crate) async fn latest_acknowledgements( + store: &ControlStore, + (context, credentials): (&AuditContext, Uuid), + listing: AcknowledgementListing<'_>, +) -> Result, ControlError> { + let AcknowledgementListing { + location_id, + target, + default_role, + events, + window, + } = listing; + let (transaction, _) = authorize_listing( + begin(store, TransactionMode::Write).await?, + (context, credentials), + (location_id, target), + default_role, + ) + .await?; + let since = window.map_or(DateTime::UNIX_EPOCH, |window| transaction.now - window); + let (transaction, rows) = query( + transaction, + &listing_sql(events), + vec![ + Parameter::Time(since), + Parameter::Text(location_id.to_string()), + Parameter::Text(target.into()), + ], + ) + .await?; + commit(transaction).await?; + let mut latest: BTreeMap> = BTreeMap::new(); + for row in rows { + let scope = row["scope_json"].clone(); + let subject = scope[events.subject] + .as_str() + .ok_or_else(|| { + ControlError::Schema(format!("acknowledgement without its {}", events.subject)) + })? + .to_owned(); + let acknowledged_at: DateTime = serde_json::from_value(row["occurred_at"].clone()) + .map_err(|error| ControlError::Schema(format!("acknowledgement time: {error}")))?; + let event_id: Uuid = serde_json::from_value(row["event_id"].clone()) + .map_err(|error| ControlError::Schema(format!("acknowledgement event: {error}")))?; + let marked = + (row["action"].as_str() == Some(events.acknowledged)).then(|| LatestAcknowledgement { + event_id, + subject: subject.clone(), + acknowledged_by: row["actor"].as_str().unwrap_or_default().into(), + acknowledged_at, + scope, + }); + latest.insert(subject, marked); + } + Ok(latest.into_values().flatten().collect()) +} diff --git a/crates/sqlbuild-orchestration/src/acknowledgements/_helpers/mod.rs b/crates/sqlbuild-orchestration/src/acknowledgements/_helpers/mod.rs new file mode 100644 index 0000000000..97a6d76f61 --- /dev/null +++ b/crates/sqlbuild-orchestration/src/acknowledgements/_helpers/mod.rs @@ -0,0 +1,2 @@ +pub(crate) mod attention_state; +pub(crate) mod latest_events; diff --git a/crates/sqlbuild-orchestration/src/acknowledgements/constants.rs b/crates/sqlbuild-orchestration/src/acknowledgements/constants.rs new file mode 100644 index 0000000000..9297b45284 --- /dev/null +++ b/crates/sqlbuild-orchestration/src/acknowledgements/constants.rs @@ -0,0 +1,29 @@ +//! Limits and audit actions of acknowledgements. + +use crate::acknowledgements::models::AcknowledgementEvents; + +pub(crate) const MAX_KEY_CHARS: usize = 256; +pub(crate) const MAX_SHAPE_BYTES: usize = 8 * 1024; +pub(crate) const ACKNOWLEDGED: &str = "attention.acknowledged"; +pub(crate) const WITHDRAWN: &str = "attention.acknowledgement_withdrawn"; +pub(crate) const MAX_REASON_CHARS: usize = 200; +/// The `attention_snooze` that removes the time limit. +pub(crate) const NO_TIME_LIMIT: &str = "0"; +/// Seconds after which an acknowledged condition comes back unchanged, unless `attention_snooze` says otherwise. +pub(crate) const DEFAULT_ATTENTION_SNOOZE_SECONDS: i64 = 86_400; +/// The longest `attention_snooze` with a time limit; `"0"` removes the limit instead. +pub(crate) const MAX_ATTENTION_SNOOZE_DAYS: i64 = 365; +/// Snoozes a listing keeps a condition acknowledgement for, so a lapsed one says why it is back. +pub(crate) const ATTENTION_LISTING_SNOOZES: i32 = 2; +/// Days of listed run acknowledgements; the overview lists only a day of problems. +pub(crate) const RUN_LISTING_DAYS: i64 = 7; +pub(crate) const RUN_EVENTS: AcknowledgementEvents = AcknowledgementEvents { + acknowledged: "run.acknowledged", + withdrawn: "run.acknowledgement_withdrawn", + subject: "run_id", +}; +pub(crate) const ATTENTION_EVENTS: AcknowledgementEvents = AcknowledgementEvents { + acknowledged: ACKNOWLEDGED, + withdrawn: WITHDRAWN, + subject: "key", +}; diff --git a/crates/sqlbuild-orchestration/src/acknowledgements/main/acknowledge_person_attention.rs b/crates/sqlbuild-orchestration/src/acknowledgements/main/acknowledge_person_attention.rs new file mode 100644 index 0000000000..6a565d2add --- /dev/null +++ b/crates/sqlbuild-orchestration/src/acknowledgements/main/acknowledge_person_attention.rs @@ -0,0 +1,104 @@ +//! Anyone who can see a target's runs marks a condition handled as it looks now, as an audit event. + +use serde_json::json; +use uuid::Uuid; + +use crate::acknowledgements::_helpers::attention_state::{prior_attention, unchanged}; +use crate::acknowledgements::constants::{ + ACKNOWLEDGED, MAX_KEY_CHARS, MAX_REASON_CHARS, MAX_SHAPE_BYTES, WITHDRAWN, +}; +use crate::acknowledgements::models::PriorAttention; +use crate::acknowledgements::models::{AttentionAcknowledgementRequest, AttentionSnooze}; +use crate::authorization::main::decisions::authorize_listing::authorize_listing; +use crate::credentials::main::audit::append_audit::append_audit; +use crate::credentials::models::{AuditContext, DefaultRole}; +use crate::store::errors::ControlError; +use crate::store::main::{begin::begin, commit::commit}; +use crate::store::models::{Change, ControlStore, TransactionMode}; + +fn validate(request: &AttentionAcknowledgementRequest) -> Result<(), ControlError> { + let key = request.key.as_str(); + if key.trim().is_empty() + || key.chars().count() > MAX_KEY_CHARS + || key.chars().any(char::is_control) + { + return Err(ControlError::Invalid(format!( + "attention key must be 1 to {MAX_KEY_CHARS} characters without control characters" + ))); + } + if !request.shape.is_object() { + return Err(ControlError::Invalid( + "attention shape must be a JSON object".into(), + )); + } + if request.shape.to_string().len() > MAX_SHAPE_BYTES { + return Err(ControlError::Invalid(format!( + "attention shape must be at most {MAX_SHAPE_BYTES} bytes" + ))); + } + if request.acknowledged && request.withdraws.is_some() { + return Err(ControlError::Invalid( + "only a withdrawal can name the acknowledgement it withdraws".into(), + )); + } + if request + .reason + .as_ref() + .is_some_and(|reason| reason.trim().is_empty() || reason.chars().count() > MAX_REASON_CHARS) + { + return Err(ControlError::Invalid(format!( + "attention reason must be 1 to {MAX_REASON_CHARS} characters" + ))); + } + Ok(()) +} + +/// Whether the acknowledgement changed; the same shape again applies only once the last one lapsed. +pub async fn acknowledge_person_attention( + store: &ControlStore, + (context, credentials): (&AuditContext, Uuid), + (location_id, target, request): (Uuid, &str, &AttentionAcknowledgementRequest), + (default_role, snooze): (DefaultRole, AttentionSnooze), +) -> Result { + let (transaction, context) = authorize_listing( + begin(store, TransactionMode::Write).await?, + (context, credentials), + (location_id, target), + default_role, + ) + .await?; + validate(request)?; + let body = + serde_json::to_value(request).map_err(|error| ControlError::Invalid(error.to_string()))?; + let (transaction, prior) = + prior_attention(transaction, (location_id, target), (request, &body)).await?; + let PriorAttention::Standing(standing) = prior else { + commit(transaction).await?; + return Ok(false); + }; + if unchanged(&standing, request, (transaction.now, snooze)) { + commit(transaction).await?; + return Ok(false); + } + let action = if request.acknowledged { + ACKNOWLEDGED + } else { + WITHDRAWN + }; + let mut transaction = append_audit( + transaction, + &context, + (request.event_id, action), + ( + json!({"location_id": location_id, "target": target, "key": request.key, "shape": request.shape, "reason": request.reason, "request": body}), + json!({"acknowledged": standing.acknowledged, "shape": standing.shape}), + json!({"acknowledged": request.acknowledged, "shape": request.shape}), + ), + ) + .await?; + transaction + .changes + .insert(Change::Attention(location_id, target.into())); + commit(transaction).await?; + Ok(true) +} diff --git a/crates/sqlbuild-orchestration/src/acknowledgements/main/list_person_acknowledgements.rs b/crates/sqlbuild-orchestration/src/acknowledgements/main/list_person_acknowledgements.rs index 77948a3d3c..8e01c92ae5 100644 --- a/crates/sqlbuild-orchestration/src/acknowledgements/main/list_person_acknowledgements.rs +++ b/crates/sqlbuild-orchestration/src/acknowledgements/main/list_person_acknowledgements.rs @@ -1,59 +1,41 @@ //! A run's acknowledgement is its latest acknowledgement event, projected from the audit log. -use std::collections::BTreeMap; - -use chrono::{DateTime, Duration, Utc}; +use chrono::Duration; use uuid::Uuid; +use crate::acknowledgements::_helpers::latest_events::latest_acknowledgements; +use crate::acknowledgements::constants::{RUN_EVENTS, RUN_LISTING_DAYS}; +use crate::acknowledgements::models::AcknowledgementListing; use crate::acknowledgements::models::RunAcknowledgement; -use crate::authorization::main::decisions::authorize_listing::authorize_listing; use crate::credentials::models::{AuditContext, DefaultRole}; use crate::store::errors::ControlError; -use crate::store::main::{begin::begin, commit::commit, query::query}; -use crate::store::models::{ControlStore, Parameter, TransactionMode}; +use crate::store::models::ControlStore; /// Runs marked handled in the last week; the overview lists only a day of problems. pub async fn list_person_acknowledgements( store: &ControlStore, - (context, credentials): (&AuditContext, Uuid), + person: (&AuditContext, Uuid), (location_id, target): (Uuid, &str), default_role: DefaultRole, ) -> Result, ControlError> { - let (transaction, _) = authorize_listing( - begin(store, TransactionMode::Write).await?, - (context, credentials), - (location_id, target), + let listing = AcknowledgementListing { + location_id, + target, default_role, - ) - .await?; - let since = transaction.now - Duration::days(7); - let (transaction, rows) = query( - transaction, - "SELECT a.action, COALESCE(p.name, a.actor) AS actor, a.occurred_at, a.scope_json ->> 'run_id' AS run_id \ - FROM sqb_security_audit a LEFT JOIN sqb_principals p ON 'principal:' || CAST(p.principal_id AS TEXT)=a.actor \ - WHERE a.occurred_at >= $1 AND a.action IN ('run.acknowledged','run.acknowledgement_withdrawn') \ - AND a.scope_json ->> 'location_id'=$2 AND a.scope_json ->> 'target'=$3 ORDER BY a.storage_id", - vec![ - Parameter::Time(since), - Parameter::Text(location_id.to_string()), - Parameter::Text(target.into()), - ], - ) - .await?; - commit(transaction).await?; - let mut latest: BTreeMap> = BTreeMap::new(); - for row in rows { - let run_id: Uuid = serde_json::from_value(row["run_id"].clone()) - .map_err(|error| ControlError::Schema(format!("acknowledgement run: {error}")))?; - let acknowledged_at: DateTime = serde_json::from_value(row["occurred_at"].clone()) - .map_err(|error| ControlError::Schema(format!("acknowledgement time: {error}")))?; - let marked = - (row["action"].as_str() == Some("run.acknowledged")).then(|| RunAcknowledgement { - run_id, - acknowledged_by: row["actor"].as_str().unwrap_or_default().into(), - acknowledged_at, - }); - latest.insert(run_id, marked); - } - Ok(latest.into_values().flatten().collect()) + events: &RUN_EVENTS, + window: Some(Duration::days(RUN_LISTING_DAYS)), + }; + latest_acknowledgements(store, person, listing) + .await? + .into_iter() + .map(|ack| { + Ok(RunAcknowledgement { + run_id: ack.subject.parse().map_err(|error| { + ControlError::Schema(format!("acknowledgement run: {error}")) + })?, + acknowledged_by: ack.acknowledged_by, + acknowledged_at: ack.acknowledged_at, + }) + }) + .collect() } diff --git a/crates/sqlbuild-orchestration/src/acknowledgements/main/list_person_attention_acknowledgements.rs b/crates/sqlbuild-orchestration/src/acknowledgements/main/list_person_attention_acknowledgements.rs new file mode 100644 index 0000000000..00f775ff02 --- /dev/null +++ b/crates/sqlbuild-orchestration/src/acknowledgements/main/list_person_attention_acknowledgements.rs @@ -0,0 +1,45 @@ +//! A condition's acknowledgement is its latest acknowledgement event, projected from the audit log. + +use uuid::Uuid; + +use crate::acknowledgements::_helpers::latest_events::latest_acknowledgements; +use crate::acknowledgements::constants::ATTENTION_EVENTS; +use crate::acknowledgements::models::{ + AcknowledgementListing, AttentionAcknowledgement, AttentionAcknowledgements, AttentionSnooze, +}; +use crate::credentials::models::{AuditContext, DefaultRole}; +use crate::store::errors::ControlError; +use crate::store::models::ControlStore; + +/// Conditions acknowledged within two snoozes, lapsed ones included with their `until`. +pub async fn list_person_attention_acknowledgements( + store: &ControlStore, + person: (&AuditContext, Uuid), + (location_id, target): (Uuid, &str), + (default_role, snooze): (DefaultRole, AttentionSnooze), +) -> Result { + let listing = AcknowledgementListing { + location_id, + target, + default_role, + events: &ATTENTION_EVENTS, + window: snooze.listing_window(), + }; + let acknowledgements: Vec = + latest_acknowledgements(store, person, listing) + .await? + .into_iter() + .map(|ack| AttentionAcknowledgement { + event_id: ack.event_id, + shape: ack.scope["shape"].clone(), + key: ack.subject, + acknowledged_by: ack.acknowledged_by, + acknowledged_at: ack.acknowledged_at, + until: snooze.until(ack.acknowledged_at), + }) + .collect(); + Ok(AttentionAcknowledgements { + snooze_seconds: snooze.seconds(), + acknowledgements, + }) +} diff --git a/crates/sqlbuild-orchestration/src/acknowledgements/main/mod.rs b/crates/sqlbuild-orchestration/src/acknowledgements/main/mod.rs index 7078a48559..1641de4de1 100644 --- a/crates/sqlbuild-orchestration/src/acknowledgements/main/mod.rs +++ b/crates/sqlbuild-orchestration/src/acknowledgements/main/mod.rs @@ -1,2 +1,4 @@ +pub mod acknowledge_person_attention; pub mod acknowledge_person_run; pub mod list_person_acknowledgements; +pub mod list_person_attention_acknowledgements; diff --git a/crates/sqlbuild-orchestration/src/acknowledgements/mod.rs b/crates/sqlbuild-orchestration/src/acknowledgements/mod.rs index 4fe9f2045f..febad71399 100644 --- a/crates/sqlbuild-orchestration/src/acknowledgements/mod.rs +++ b/crates/sqlbuild-orchestration/src/acknowledgements/mod.rs @@ -1,4 +1,7 @@ -//! People mark problem runs handled for everyone who can see them; the audit log holds every change. +//! People mark problem runs and ongoing attention conditions handled, as audit events. + +pub(crate) mod _helpers; +pub(crate) mod constants; pub mod main; pub mod models; diff --git a/crates/sqlbuild-orchestration/src/acknowledgements/models.rs b/crates/sqlbuild-orchestration/src/acknowledgements/models.rs index 3f6c3b108f..729f935645 100644 --- a/crates/sqlbuild-orchestration/src/acknowledgements/models.rs +++ b/crates/sqlbuild-orchestration/src/acknowledgements/models.rs @@ -1,9 +1,17 @@ //! Acknowledgements of problem runs, kept as audit events. -use chrono::{DateTime, Utc}; +use chrono::{DateTime, Duration, Utc}; use serde::{Deserialize, Serialize}; +use serde_json::Value; use uuid::Uuid; +use crate::acknowledgements::constants::{ + ATTENTION_LISTING_SNOOZES, DEFAULT_ATTENTION_SNOOZE_SECONDS, MAX_ATTENTION_SNOOZE_DAYS, + NO_TIME_LIMIT, +}; +use crate::credentials::models::DefaultRole; +use crate::store::errors::ControlError; + /// Marks a run as handled for everyone who can see it, or withdraws the mark; retried with the same event ID it applies once. #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, utoipa::ToSchema)] #[serde(deny_unknown_fields)] @@ -21,3 +29,156 @@ pub struct RunAcknowledgement { pub acknowledged_by: String, pub acknowledged_at: DateTime, } + +/// Marks an ongoing condition handled as it looks now, or withdraws that; an event ID applies once. +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, utoipa::ToSchema)] +#[serde(deny_unknown_fields)] +pub struct AttentionAcknowledgementRequest { + pub event_id: Uuid, + /// The condition's kind and subject, stable while it lasts, such as `stale_sources`. + pub key: String, + /// What the condition looks like, as a JSON object of at most 8 KiB that later states are compared with. + pub shape: serde_json::Value, + pub acknowledged: bool, + /// Why, when it isn't a person's own choice, such as a withdrawal once the condition cleared. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub reason: Option, + /// For a withdrawal, the acknowledgement event it withdraws: it applies only while that is still the latest. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub withdraws: Option, +} + +/// A condition whose latest acknowledgement event marks it handled. +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, utoipa::ToSchema)] +pub struct AttentionAcknowledgement { + /// The acknowledging audit event, which a withdrawal can name. + pub event_id: Uuid, + pub key: String, + pub shape: serde_json::Value, + /// The person's name, or the audit actor when the person no longer exists. + pub acknowledged_by: String, + pub acknowledged_at: DateTime, + /// When the acknowledgement lapses even if the condition never changes; none without a time limit. + pub until: Option>, +} + +/// A target's condition acknowledgements, and how long one lasts while its condition is unchanged. +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, utoipa::ToSchema)] +pub struct AttentionAcknowledgements { + /// The server's `attention_snooze` in seconds; none when acknowledgements have no time limit. + pub snooze_seconds: Option, + pub acknowledgements: Vec, +} + +/// How long an acknowledged condition stays hidden while it doesn't change; `None` for no time limit. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct AttentionSnooze(Option); + +impl AttentionSnooze { + /// A duration in the project's format, such as `24h` or `1d12h`, or `0` for no time limit. + pub fn parse(text: &str) -> Result { + let invalid = || { + ControlError::Invalid(format!( + "attention_snooze must be a duration such as \"24h\" or \"1d12h\", or \"0\" for no time limit, not {text:?}" + )) + }; + if text.trim() == NO_TIME_LIMIT { + return Ok(Self(None)); + } + let digits = sqlbuild_cursor::algebra::main::parse_duration::parse_duration(text) + .ok_or_else(invalid)?; + let amount = |digits: &str| digits.parse::().map_err(|_| invalid()); + if amount(&digits.years)? != 0 || amount(&digits.months)? != 0 { + return Err(ControlError::Invalid(format!( + "attention_snooze can't use years or months, which vary in length: {text:?}" + ))); + } + let seconds = [ + (digits.days, 86_400), + (digits.hours, 3_600), + (digits.minutes, 60), + (digits.seconds, 1), + ] + .into_iter() + .try_fold(0_i64, |total, (digits, unit)| { + amount(&digits)? + .checked_mul(unit) + .and_then(|part| total.checked_add(part)) + .ok_or_else(invalid) + })?; + if seconds > MAX_ATTENTION_SNOOZE_DAYS * 86_400 { + return Err(ControlError::Invalid(format!( + "attention_snooze can be at most {MAX_ATTENTION_SNOOZE_DAYS} days, or \"0\" for no time limit: {text:?}" + ))); + } + Duration::try_seconds(seconds) + .map(|snooze| Self(Some(snooze))) + .ok_or_else(invalid) + } + + /// The snooze in seconds; none without a time limit. + pub fn seconds(self) -> Option { + self.0.map(|snooze| snooze.num_seconds()) + } + + /// When an acknowledgement made `at` lapses unchanged; none without a time limit. + pub(crate) fn until(self, at: DateTime) -> Option> { + self.0.map(|snooze| at + snooze) + } + + /// How far back a listing reads; without a time limit, every acknowledgement the audit log keeps. + pub(crate) fn listing_window(self) -> Option { + self.0.map(|snooze| snooze * ATTENTION_LISTING_SNOOZES) + } +} + +impl Default for AttentionSnooze { + fn default() -> Self { + Self(Some(Duration::seconds(DEFAULT_ATTENTION_SNOOZE_SECONDS))) + } +} + +/// The audit actions of one kind of acknowledgement, and the scope field naming its subject. +#[derive(Debug)] +pub(crate) struct AcknowledgementEvents { + pub(crate) acknowledged: &'static str, + pub(crate) withdrawn: &'static str, + pub(crate) subject: &'static str, +} + +/// Which target's acknowledgements of one kind to list, over how long. +#[derive(Debug)] +pub(crate) struct AcknowledgementListing<'a> { + pub(crate) location_id: Uuid, + pub(crate) target: &'a str, + pub(crate) default_role: DefaultRole, + pub(crate) events: &'a AcknowledgementEvents, + /// None to read every event the audit log keeps. + pub(crate) window: Option, +} + +/// A subject's standing acknowledgement: who made it, when, and the event's scope. +#[derive(Debug)] +pub(crate) struct LatestAcknowledgement { + pub(crate) event_id: Uuid, + pub(crate) subject: String, + pub(crate) acknowledged_by: String, + pub(crate) acknowledged_at: DateTime, + pub(crate) scope: Value, +} + +/// A condition's acknowledgement as stored before a request: the request's own retry, or the standing state. +#[derive(Debug)] +pub(crate) enum PriorAttention { + Retried, + Standing(StandingAttention), +} + +/// A condition's latest acknowledgement event, if any: whether it acknowledges, with which shape, when. +#[derive(Debug)] +pub(crate) struct StandingAttention { + pub(crate) event_id: Option, + pub(crate) acknowledged: bool, + pub(crate) shape: Value, + pub(crate) at: Option>, +} diff --git a/crates/sqlbuild-orchestration/src/api/_helpers/authentication/password_sessions.rs b/crates/sqlbuild-orchestration/src/api/_helpers/authentication/password_sessions.rs index f1e5d9fe70..49825311d1 100644 --- a/crates/sqlbuild-orchestration/src/api/_helpers/authentication/password_sessions.rs +++ b/crates/sqlbuild-orchestration/src/api/_helpers/authentication/password_sessions.rs @@ -147,6 +147,11 @@ pub(crate) fn person_routes() -> Router { get(crate::api::_helpers::resources::person_operations::acknowledgements) .post(crate::api::_helpers::resources::person_operations::acknowledge), ) + .route( + "/api/control/locations/{location_id}/targets/{target}/attention-acknowledgements", + get(crate::api::_helpers::resources::person_operations::attention_acknowledgements) + .post(crate::api::_helpers::resources::person_operations::acknowledge_attention), + ) .route( "/api/control/locations/{location_id}/targets/{target}/runs/{run_id}/nodes", get(crate::api::_helpers::resources::person_reads::run_nodes), diff --git a/crates/sqlbuild-orchestration/src/api/_helpers/resources/person_operations.rs b/crates/sqlbuild-orchestration/src/api/_helpers/resources/person_operations.rs index 8cf1037ddb..7c1e391039 100644 --- a/crates/sqlbuild-orchestration/src/api/_helpers/resources/person_operations.rs +++ b/crates/sqlbuild-orchestration/src/api/_helpers/resources/person_operations.rs @@ -6,11 +6,16 @@ use axum::extract::{Path, Query, State}; use axum::{Extension, Json}; use uuid::Uuid; +use crate::acknowledgements::main::acknowledge_person_attention::acknowledge_person_attention; use crate::acknowledgements::main::acknowledge_person_run::acknowledge_person_run; use crate::acknowledgements::main::list_person_acknowledgements::list_person_acknowledgements; -use crate::acknowledgements::models::{AcknowledgementRequest, RunAcknowledgement}; +use crate::acknowledgements::main::list_person_attention_acknowledgements::list_person_attention_acknowledgements; +use crate::acknowledgements::models::{ + AcknowledgementRequest, AttentionAcknowledgementRequest, AttentionAcknowledgements, + RunAcknowledgement, +}; use crate::api::errors::ApiError; -use crate::api::models::{MutationResponse, RunsQuery}; +use crate::api::models::{MutationResponse, RunsQuery, ServerFacts}; use crate::credentials::models::AuthenticatedPerson; use crate::credentials::models::{AuditContext, DefaultRole}; use crate::declarations::main::change_person_trigger::change_person_trigger; @@ -211,6 +216,56 @@ pub(crate) async fn acknowledgements( )) } +#[utoipa::path(post, path = "/api/control/locations/{location_id}/targets/{target}/attention-acknowledgements", operation_id = "acknowledgeAttention", + params(("location_id" = Uuid, Path), ("target" = String, Path), ("x-sqb-csrf" = String, Header)), + request_body = AttentionAcknowledgementRequest, + responses((status = 200, body = MutationResponse, description = "Whether the condition's acknowledgement changed"), + (status = 400, description = "The key, shape or reason is invalid, or the event ID was reused"), + (status = 401, description = "Session rejected"), + (status = 403, body = crate::api::models::ApiErrorBody)), security(("session" = []), ("cliSession" = [])))] +pub(crate) async fn acknowledge_attention( + (State(store), Extension(context)): (State, Extension), + (Path((location_id, target)), Extension(default_role), Extension(facts)): ( + Path<(Uuid, String)>, + Extension, + Extension, + ), + Extension(AuthenticatedPerson(principal, _)): Extension, + Json(request): Json, +) -> Result, ApiError> { + Ok(Json(MutationResponse { + applied: acknowledge_person_attention( + &store, + (&context, principal), + (location_id, &target, &request), + (default_role, facts.attention_snooze), + ) + .await?, + })) +} + +#[utoipa::path(get, path = "/api/control/locations/{location_id}/targets/{target}/attention-acknowledgements", operation_id = "listAttentionAcknowledgements", + params(("location_id" = Uuid, Path), ("target" = String, Path)), + responses((status = 200, body = AttentionAcknowledgements, description = "Conditions marked handled within two snoozes, lapsed ones included, and the snooze"), + (status = 401, description = "Session rejected"), + (status = 403, body = crate::api::models::ApiErrorBody)), security(("session" = []), ("cliSession" = [])))] +pub(crate) async fn attention_acknowledgements( + (State(store), Extension(context)): (State, Extension), + (Extension(default_role), Extension(facts)): (Extension, Extension), + Path((location_id, target)): Path<(Uuid, String)>, + Extension(AuthenticatedPerson(principal, _)): Extension, +) -> Result, ApiError> { + Ok(Json( + list_person_attention_acknowledgements( + &store, + (&context, principal), + (location_id, &target), + (default_role, facts.attention_snooze), + ) + .await?, + )) +} + #[utoipa::path(post, path = "/api/control/triggers", operation_id = "changeTrigger", params(("x-sqb-csrf" = String, Header)), request_body = TriggerChangeRequest, responses((status = 200, body = MutationResponse), (status = 401, description = "Session rejected"), diff --git a/crates/sqlbuild-orchestration/src/api/models.rs b/crates/sqlbuild-orchestration/src/api/models.rs index 31c54c5e53..bcb7ad0313 100644 --- a/crates/sqlbuild-orchestration/src/api/models.rs +++ b/crates/sqlbuild-orchestration/src/api/models.rs @@ -29,6 +29,8 @@ use crate::api::_helpers::resources::{ person_operations::recent_runs, person_operations::acknowledge, person_operations::acknowledgements, + person_operations::acknowledge_attention, + person_operations::attention_acknowledgements, person_reads::run_nodes, person_reads::nodes, person_reads::node_states, @@ -615,6 +617,8 @@ pub struct ServerFacts { pub state_history: crate::warehouse_metadata::models::StateHistoryRetention, /// Each launcher's `pool_caps`; empty where this server runs no launcher. pub pool_caps: crate::declarations::models::ServerPoolCaps, + /// How long an acknowledged attention condition stays hidden while unchanged. + pub attention_snooze: crate::acknowledgements::models::AttentionSnooze, } /// The server's version, storage, sign-in and retention, for administrators. diff --git a/crates/sqlbuild-orchestration/src/store/_helpers/changes.rs b/crates/sqlbuild-orchestration/src/store/_helpers/changes.rs index cd23dd0052..ea0e96e385 100644 --- a/crates/sqlbuild-orchestration/src/store/_helpers/changes.rs +++ b/crates/sqlbuild-orchestration/src/store/_helpers/changes.rs @@ -43,12 +43,12 @@ pub(crate) async fn resolve_changes( continue; } let scope = match &change { - Change::Snapshot(location_id, target) | Change::NodeStatus(location_id, target) => { - ChangedScope { - location_id: *location_id, - target: target.clone(), - } - } + Change::Snapshot(location_id, target) + | Change::NodeStatus(location_id, target) + | Change::Attention(location_id, target) => ChangedScope { + location_id: *location_id, + target: target.clone(), + }, Change::Run(id) | Change::Trigger(id) => { let sql = if matches!(change, Change::Run(_)) { "SELECT location_id, target FROM sqb_runs WHERE run_id=$1" @@ -73,6 +73,7 @@ pub(crate) async fn resolve_changes( Change::Trigger(_) => vec![ChangeTopic::Ticks], Change::Snapshot(..) => vec![ChangeTopic::Snapshot, ChangeTopic::NodeStatus], Change::NodeStatus(..) => vec![ChangeTopic::NodeStatus], + Change::Attention(..) => vec![ChangeTopic::Runs], Change::Credentials => continue, }; for topic in topics { diff --git a/crates/sqlbuild-orchestration/src/store/indexes.sql b/crates/sqlbuild-orchestration/src/store/indexes.sql index 811e4e24f6..9086da0ec7 100644 --- a/crates/sqlbuild-orchestration/src/store/indexes.sql +++ b/crates/sqlbuild-orchestration/src/store/indexes.sql @@ -12,3 +12,4 @@ CREATE INDEX IF NOT EXISTS sqb_warehouse_catalog_received ON sqb_warehouse_catal CREATE INDEX IF NOT EXISTS sqb_warehouse_fingerprints_received ON sqb_warehouse_fingerprints(location_id, target, received_at); CREATE INDEX IF NOT EXISTS sqb_warehouse_consumption_received ON sqb_warehouse_consumption(location_id, target, received_at); CREATE INDEX IF NOT EXISTS sqb_warehouse_observations_received ON sqb_warehouse_observations(location_id, target, received_at); +CREATE INDEX IF NOT EXISTS sqb_security_audit_attention ON sqb_security_audit((scope_json ->> 'location_id'), (scope_json ->> 'target'), (scope_json ->> 'key'), storage_id) WHERE action IN ('attention.acknowledged', 'attention.acknowledgement_withdrawn'); diff --git a/crates/sqlbuild-orchestration/src/store/models.rs b/crates/sqlbuild-orchestration/src/store/models.rs index 874305b955..d5f0ee80ba 100644 --- a/crates/sqlbuild-orchestration/src/store/models.rs +++ b/crates/sqlbuild-orchestration/src/store/models.rs @@ -98,6 +98,8 @@ pub(crate) enum Change { Trigger(Uuid), Snapshot(Uuid, String), NodeStatus(Uuid, String), + /// A condition was acknowledged or withdrawn; the Overview reloads on the runs topic. + Attention(Uuid, String), Credentials, } diff --git a/crates/sqlbuild-orchestration/src/store_migrations/_helpers/migration.rs b/crates/sqlbuild-orchestration/src/store_migrations/_helpers/migration.rs index 7fb2d6e2bf..de16a20674 100644 --- a/crates/sqlbuild-orchestration/src/store_migrations/_helpers/migration.rs +++ b/crates/sqlbuild-orchestration/src/store_migrations/_helpers/migration.rs @@ -14,11 +14,18 @@ use crate::store_migrations::models::{StoreMigration, StoreMigrationPlan}; use crate::store::constants::{INDEXES, SCHEMA}; /// The migrations after the baseline, in order: entry `i` includes `store_migrations/sql/{NNNN}_{name}.{sqlite,postgres}.sql` and brings a store to version `NNNN = BASELINE_VERSION + i + 1`. -pub(crate) const MIGRATIONS: &[StoreMigration] = &[StoreMigration { - name: "large_project_server", - sqlite: include_str!("../sql/0002_large_project_server.sqlite.sql"), - postgres: include_str!("../sql/0002_large_project_server.postgres.sql"), -}]; +pub(crate) const MIGRATIONS: &[StoreMigration] = &[ + StoreMigration { + name: "large_project_server", + sqlite: include_str!("../sql/0002_large_project_server.sqlite.sql"), + postgres: include_str!("../sql/0002_large_project_server.postgres.sql"), + }, + StoreMigration { + name: "attention_acknowledgement_index", + sqlite: include_str!("../sql/0003_attention_acknowledgement_index.sqlite.sql"), + postgres: include_str!("../sql/0003_attention_acknowledgement_index.postgres.sql"), + }, +]; /// The schema version a store created by this build has. pub(crate) fn current_version(migrations: &[StoreMigration]) -> i64 { diff --git a/crates/sqlbuild-orchestration/src/store_migrations/sql/0003_attention_acknowledgement_index.postgres.sql b/crates/sqlbuild-orchestration/src/store_migrations/sql/0003_attention_acknowledgement_index.postgres.sql new file mode 100644 index 0000000000..1fbb50e081 --- /dev/null +++ b/crates/sqlbuild-orchestration/src/store_migrations/sql/0003_attention_acknowledgement_index.postgres.sql @@ -0,0 +1,4 @@ +-- The index the Overview's attention acknowledgement listing reads: each item's latest +-- acknowledgement or withdrawal. IF NOT EXISTS skips an index an operator pre-built. +-- On a large audit log, pre-build it with CREATE INDEX CONCURRENTLY IF NOT EXISTS to keep sign-ins flowing. +CREATE INDEX IF NOT EXISTS sqb_security_audit_attention ON sqb_security_audit((scope_json ->> 'location_id'), (scope_json ->> 'target'), (scope_json ->> 'key'), storage_id) WHERE action IN ('attention.acknowledged', 'attention.acknowledgement_withdrawn'); diff --git a/crates/sqlbuild-orchestration/src/store_migrations/sql/0003_attention_acknowledgement_index.sqlite.sql b/crates/sqlbuild-orchestration/src/store_migrations/sql/0003_attention_acknowledgement_index.sqlite.sql new file mode 100644 index 0000000000..5b7611b8f9 --- /dev/null +++ b/crates/sqlbuild-orchestration/src/store_migrations/sql/0003_attention_acknowledgement_index.sqlite.sql @@ -0,0 +1,3 @@ +-- The index the Overview's attention acknowledgement listing reads: each item's latest +-- acknowledgement or withdrawal. IF NOT EXISTS skips an index an operator pre-built. +CREATE INDEX IF NOT EXISTS sqb_security_audit_attention ON sqb_security_audit((scope_json ->> 'location_id'), (scope_json ->> 'target'), (scope_json ->> 'key'), storage_id) WHERE action IN ('attention.acknowledged', 'attention.acknowledgement_withdrawn'); diff --git a/crates/sqlbuild-orchestration/tests/api/helpers.rs b/crates/sqlbuild-orchestration/tests/api/helpers.rs index 2e3ce11dab..7a71ae6f0b 100644 --- a/crates/sqlbuild-orchestration/tests/api/helpers.rs +++ b/crates/sqlbuild-orchestration/tests/api/helpers.rs @@ -13,6 +13,14 @@ pub(crate) async fn start_api(store: &ControlStore) -> TestApi { pub(crate) async fn start_api_with_authentication( store: &ControlStore, authentication: ApiAuthentication, +) -> TestApi { + start_api_with_facts(store, authentication, Default::default()).await +} + +pub(crate) async fn start_api_with_facts( + store: &ControlStore, + authentication: ApiAuthentication, + facts: crate::api::models::ServerFacts, ) -> TestApi { let listener = tokio::net::TcpListener::bind("127.0.0.1:0") .await @@ -26,7 +34,7 @@ pub(crate) async fn start_api_with_authentication( ( authentication, (Vec::new(), std::sync::Arc::new(ExactKeyPlanner)), - Default::default(), + facts, ), (|| {}, async { let _ = signal.await; diff --git a/crates/sqlbuild-orchestration/tests/api/test_attention_acknowledgements.rs b/crates/sqlbuild-orchestration/tests/api/test_attention_acknowledgements.rs new file mode 100644 index 0000000000..01be4cfd20 --- /dev/null +++ b/crates/sqlbuild-orchestration/tests/api/test_attention_acknowledgements.rs @@ -0,0 +1,672 @@ +//! A person marks an ongoing condition handled as it looks now, until it changes or is withdrawn. + +use serde_json::{Value, json}; +use uuid::Uuid; + +use crate::acknowledgements::_helpers::latest_events::listing_sql; +use crate::acknowledgements::constants::ATTENTION_EVENTS; +use crate::acknowledgements::models::AttentionSnooze; +use crate::api::models::ServerFacts; +use crate::api::models::{ApiAuthentication, HumanLogin}; +use crate::api::tests::denials_helpers::person_send; +use crate::api::tests::helpers::{start_api_with_authentication, start_api_with_facts, stop_api}; +use crate::api::tests::test_types::{ + AttentionAcknowledgementTestCase, AttentionSnoozeTestCase, AutomaticWithdrawalTestCase, + ListingPlanTestCase, NamedWithdrawalTestCase, SnoozeParseTestCase, +}; +use crate::credentials::tests::location_helpers::create_location; +use crate::credentials::tests::role_helpers::role_fixture; +use crate::store::main::migrate_store::migrate_store; +use crate::store::main::{begin::begin, commit::commit, query::query}; +use crate::store::models::{Parameter, TransactionMode}; +use crate::store::tests::store_helpers::{close_test_store, open_test_store, run}; +use crate::store::tests::store_test_types::Backend; + +#[test] +fn given_an_ongoing_condition_when_a_person_acknowledges_it_then_everyone_reads_its_shape_until_it_changes_or_is_withdrawn() + { + let test_cases = [ + AttentionAcknowledgementTestCase { + description: "SQLite", + backend: Backend::Sqlite, + expected_statuses: [200, 200, 400, 200, 400, 400, 400], + expected_applied: [true, false, false, true, true, true, false], + expected_acknowledged_by: "orders-admin", + expected_snooze_hours: 24, + expected_keys: ( + &["event:tick_overdue:segments_hourly", "stale_sources"], + &["event:tick_overdue:segments_hourly"], + ), + }, + AttentionAcknowledgementTestCase { + description: "PostgreSQL", + backend: Backend::Postgres, + expected_statuses: [200, 200, 400, 200, 400, 400, 400], + expected_applied: [true, false, false, true, true, true, false], + expected_acknowledged_by: "orders-admin", + expected_snooze_hours: 24, + expected_keys: ( + &["event:tick_overdue:segments_hourly", "stale_sources"], + &["event:tick_overdue:segments_hourly"], + ), + }, + ]; + for test_case in test_cases { + run(async { + let Some(fixture) = open_test_store(test_case.backend).await else { + return; + }; + let store = &fixture.store; + migrate_store(store).await.expect("migrate"); + let roles = role_fixture(store).await; + let inventory = create_location(store, "inventory", "orders-admin") + .await + .expect("location"); + let api = start_api_with_authentication( + store, + ApiAuthentication { + login: HumanLogin::Password("https://control.example.com".into()), + ..ApiAuthentication::default() + }, + ) + .await; + let client = reqwest::Client::new(); + let administrator = ( + roles.administrator.bearer.as_str(), + roles.administrator.csrf.as_str(), + ); + let url = |target: &str| { + format!( + "{}/api/control/locations/{inventory}/targets/{target}/attention-acknowledgements", + api.url + ) + }; + let send = |target: &str, body: Option| { + let url = url(target); + let client = client.clone(); + async move { + let response = + person_send(&client, (&url, administrator.0, administrator.1), body).await; + let status = response.status().as_u16(); + ( + status, + response.json::().await.unwrap_or(Value::Null), + ) + } + }; + let request = |key: &str, shape: Value, acknowledged: bool| json!({"event_id": Uuid::now_v7(), "key": key, "shape": shape, "acknowledged": acknowledged}); + let keys = |listed: &Value| { + listed["acknowledgements"] + .as_array() + .map(|all| all.iter().map(|a| a["key"].clone()).collect::>()) + .unwrap_or_default() + }; + let one_source = json!({"members": ["raw__payments:warn"]}); + let acknowledge = request("stale_sources", one_source.clone(), true); + let mut conflicting = acknowledge.clone(); + conflicting["shape"] = json!({"members": []}); + + let first = send("development", Some(acknowledge.clone())).await; + let retried = send("development", Some(acknowledge)).await; + let reused = send("development", Some(conflicting)).await; + let again = send( + "development", + Some(request("stale_sources", one_source, true)), + ) + .await; + let empty_key = send("development", Some(request("", json!({}), true))).await; + let array_shape = send( + "development", + Some(request("stale_sources", json!(["x"]), true)), + ) + .await; + let large_shape = send( + "development", + Some(request( + "stale_sources", + json!({"members": vec!["x".repeat(64); 200]}), + true, + )), + ) + .await; + let listed = send("development", None).await.1; + let listed = listed["acknowledgements"].clone(); + let at: chrono::DateTime = + serde_json::from_value(listed[0]["acknowledged_at"].clone()).expect("time"); + let until: chrono::DateTime = + serde_json::from_value(listed[0]["until"].clone()).expect("until"); + let worse = send( + "development", + Some(request( + "stale_sources", + json!({"members": ["raw__payments:warn", "raw__refunds:error"]}), + true, + )), + ) + .await; + let other = send( + "development", + Some(request( + "event:tick_overdue:segments_hourly", + json!({"code": "tick_overdue"}), + true, + )), + ) + .await; + let changed = send("development", None).await.1; + let withdrawn = send( + "development", + Some(request("stale_sources", json!({}), false)), + ) + .await; + let withdrawn_again = send( + "development", + Some(request("stale_sources", json!({}), false)), + ) + .await; + let remaining = send("development", None).await.1; + let elsewhere = send("production", None).await.1["acknowledgements"].clone(); + assert_eq!( + ( + [ + first.0, + retried.0, + reused.0, + again.0, + empty_key.0, + array_shape.0, + large_shape.0 + ], + [ + &first.1["applied"], + &retried.1["applied"], + &again.1["applied"], + &worse.1["applied"], + &other.1["applied"], + &withdrawn.1["applied"], + &withdrawn_again.1["applied"], + ], + &listed[0]["acknowledged_by"], + (until - at).num_hours(), + (keys(&changed), keys(&remaining)), + elsewhere, + ), + ( + test_case.expected_statuses, + test_case.expected_applied.map(Value::Bool).each_ref(), + &json!(test_case.expected_acknowledged_by), + test_case.expected_snooze_hours, + ( + test_case.expected_keys.0.iter().map(|k| json!(k)).collect(), + test_case.expected_keys.1.iter().map(|k| json!(k)).collect(), + ), + json!([]), + ), + "{}", + test_case.description + ); + stop_api(api).await; + close_test_store(fixture).await; + }); + } +} + +#[test] +fn given_a_configured_snooze_when_a_condition_is_acknowledged_then_it_lapses_unchanged_only_after_that_long() + { + let test_cases = [ + AttentionSnoozeTestCase { + description: "the default, 24 hours", + snooze: AttentionSnooze::default(), + expected_snooze_seconds: json!(86_400), + expected_until_seconds: Some(86_400), + expected_same_shape_applies_after_a_wait: false, + }, + AttentionSnoozeTestCase { + description: "one second", + snooze: AttentionSnooze::parse("1s").expect("one second"), + expected_snooze_seconds: json!(1), + expected_until_seconds: Some(1), + expected_same_shape_applies_after_a_wait: true, + }, + AttentionSnoozeTestCase { + description: "no time limit", + snooze: AttentionSnooze::parse("0").expect("no limit"), + expected_snooze_seconds: Value::Null, + expected_until_seconds: None, + expected_same_shape_applies_after_a_wait: false, + }, + ]; + for test_case in test_cases { + run(async { + let Some(fixture) = open_test_store(Backend::Sqlite).await else { + return; + }; + let store = &fixture.store; + migrate_store(store).await.expect("migrate"); + let roles = role_fixture(store).await; + let inventory = create_location(store, "inventory", "orders-admin") + .await + .expect("location"); + let api = start_api_with_facts( + store, + ApiAuthentication { + login: HumanLogin::Password("https://control.example.com".into()), + ..ApiAuthentication::default() + }, + ServerFacts { + attention_snooze: test_case.snooze, + ..ServerFacts::default() + }, + ) + .await; + let client = reqwest::Client::new(); + let url = format!( + "{}/api/control/locations/{inventory}/targets/development/attention-acknowledgements", + api.url + ); + let administrator = ( + url.as_str(), + roles.administrator.bearer.as_str(), + roles.administrator.csrf.as_str(), + ); + let acknowledge = || json!({"event_id": Uuid::now_v7(), "key": "stale_models", "shape": {"counts": {"changed": 2}}, "acknowledged": true}); + person_send(&client, administrator, Some(acknowledge())).await; + let listed: Value = person_send(&client, administrator, None) + .await + .json() + .await + .expect("listing"); + tokio::time::sleep(std::time::Duration::from_millis(1_100)).await; + let again: Value = person_send(&client, administrator, Some(acknowledge())) + .await + .json() + .await + .expect("again"); + let ack = &listed["acknowledgements"][0]; + let until_seconds = ack["until"].as_str().map(|until| { + let at: chrono::DateTime = + serde_json::from_value(ack["acknowledged_at"].clone()).expect("time"); + let until: chrono::DateTime = until.parse().expect("until"); + (until - at).num_seconds() + }); + assert_eq!( + (&listed["snooze_seconds"], until_seconds, &again["applied"]), + ( + &test_case.expected_snooze_seconds, + test_case.expected_until_seconds, + &json!(test_case.expected_same_shape_applies_after_a_wait) + ), + "{}", + test_case.description + ); + stop_api(api).await; + close_test_store(fixture).await; + }); + } +} + +#[test] +fn given_a_snooze_setting_when_it_is_parsed_then_durations_and_zero_are_accepted_and_the_rest_rejected() + { + let test_cases = [ + SnoozeParseTestCase { + description: "hours", + text: "24h", + expected_seconds: Ok(Some(86_400)), + }, + SnoozeParseTestCase { + description: "days and hours", + text: "1d12h", + expected_seconds: Ok(Some(129_600)), + }, + SnoozeParseTestCase { + description: "minutes", + text: "90m", + expected_seconds: Ok(Some(5_400)), + }, + SnoozeParseTestCase { + description: "no time limit", + text: "0", + expected_seconds: Ok(None), + }, + SnoozeParseTestCase { + description: "no unit", + text: "24", + expected_seconds: Err("attention_snooze must be a duration"), + }, + SnoozeParseTestCase { + description: "a word", + text: "a day", + expected_seconds: Err("attention_snooze must be a duration"), + }, + SnoozeParseTestCase { + description: "a year", + text: "365d", + expected_seconds: Ok(Some(31_536_000)), + }, + SnoozeParseTestCase { + description: "longer than a year", + text: "366d", + expected_seconds: Err("attention_snooze can be at most 365 days"), + }, + SnoozeParseTestCase { + description: "months", + text: "1mo", + expected_seconds: Err("can't use years or months"), + }, + SnoozeParseTestCase { + description: "too long", + text: "99999999999999999999d", + expected_seconds: Err("attention_snooze must be a duration"), + }, + ]; + for test_case in test_cases { + let expected_error = test_case.expected_seconds.err(); + let outcome = AttentionSnooze::parse(test_case.text) + .map(AttentionSnooze::seconds) + .map_err(|error| { + expected_error.is_some_and(|expected| error.to_string().contains(expected)) + }); + assert_eq!( + outcome, + test_case.expected_seconds.map_err(|_| true), + "{}", + test_case.description + ); + } +} + +#[test] +fn given_a_cleared_condition_when_viewers_withdraw_it_automatically_then_it_is_withdrawn_once_with_the_reason() + { + let test_cases = [ + AutomaticWithdrawalTestCase { + description: "SQLite", + backend: Backend::Sqlite, + expected_applied: [true, false], + expected_reason: "automatic: the condition cleared", + expected_withdrawals: 1, + }, + AutomaticWithdrawalTestCase { + description: "PostgreSQL", + backend: Backend::Postgres, + expected_applied: [true, false], + expected_reason: "automatic: the condition cleared", + expected_withdrawals: 1, + }, + ]; + for test_case in test_cases { + run(async { + let Some(fixture) = open_test_store(test_case.backend).await else { + return; + }; + let store = &fixture.store; + migrate_store(store).await.expect("migrate"); + let roles = role_fixture(store).await; + let inventory = create_location(store, "inventory", "orders-admin") + .await + .expect("location"); + let api = start_api_with_authentication( + store, + ApiAuthentication { + login: HumanLogin::Password("https://control.example.com".into()), + ..ApiAuthentication::default() + }, + ) + .await; + let client = reqwest::Client::new(); + let url = format!( + "{}/api/control/locations/{inventory}/targets/development/attention-acknowledgements", + api.url + ); + let administrator = ( + url.as_str(), + roles.administrator.bearer.as_str(), + roles.administrator.csrf.as_str(), + ); + let shape = json!({"counts": {"changed": 2}}); + person_send( + &client, + administrator, + Some(json!({"event_id": Uuid::now_v7(), "key": "stale_models", "shape": shape, "acknowledged": true})), + ) + .await; + let withdrawal = json!({"event_id": Uuid::now_v7(), "key": "stale_models", "shape": shape, "acknowledged": false, "reason": test_case.expected_reason}); + let mut applied = Vec::new(); + for _viewer in 0..2 { + let response: Value = person_send(&client, administrator, Some(withdrawal.clone())) + .await + .json() + .await + .expect("withdrawal"); + applied.push(response["applied"].clone()); + } + let listed: Value = person_send(&client, administrator, None) + .await + .json() + .await + .expect("listing"); + let audit: Value = person_send( + &client, + ( + &format!("{}/api/control/audit?limit=50", api.url), + administrator.1, + administrator.2, + ), + None, + ) + .await + .json() + .await + .expect("audit"); + let withdrawals: Vec = audit + .as_array() + .or_else(|| audit["events"].as_array()) + .into_iter() + .flatten() + .filter(|event| event["action"] == "attention.acknowledgement_withdrawn") + .map(|event| event["scope_json"]["reason"].clone()) + .collect(); + assert_eq!( + (applied, listed["acknowledgements"].clone(), withdrawals), + ( + test_case.expected_applied.map(Value::Bool).to_vec(), + json!([]), + vec![json!(test_case.expected_reason); test_case.expected_withdrawals] + ), + "{}", + test_case.description + ); + stop_api(api).await; + close_test_store(fixture).await; + }); + } +} + +#[test] +fn given_a_withdrawal_naming_an_acknowledgement_when_a_newer_one_stands_then_it_changes_nothing() { + let test_cases = [ + NamedWithdrawalTestCase { + description: "SQLite", + backend: Backend::Sqlite, + expected_statuses: [200, 200, 200, 400, 200], + expected_applied: [false, true], + expected_standing_after_stale: "re-acknowledged", + }, + NamedWithdrawalTestCase { + description: "PostgreSQL", + backend: Backend::Postgres, + expected_statuses: [200, 200, 200, 400, 200], + expected_applied: [false, true], + expected_standing_after_stale: "re-acknowledged", + }, + ]; + for test_case in test_cases { + run(async { + let Some(fixture) = open_test_store(test_case.backend).await else { + return; + }; + let store = &fixture.store; + migrate_store(store).await.expect("migrate"); + let roles = role_fixture(store).await; + let inventory = create_location(store, "inventory", "orders-admin") + .await + .expect("location"); + let api = start_api_with_authentication( + store, + ApiAuthentication { + login: HumanLogin::Password("https://control.example.com".into()), + ..ApiAuthentication::default() + }, + ) + .await; + let client = reqwest::Client::new(); + let url = format!( + "{}/api/control/locations/{inventory}/targets/development/attention-acknowledgements", + api.url + ); + let administrator = ( + url.as_str(), + roles.administrator.bearer.as_str(), + roles.administrator.csrf.as_str(), + ); + let send = |body: Value| { + let client = client.clone(); + async move { + let response = person_send(&client, administrator, Some(body)).await; + let status = response.status().as_u16(); + ( + status, + response.json::().await.unwrap_or(Value::Null), + ) + } + }; + let first = Uuid::now_v7(); + let again = Uuid::now_v7(); + let acknowledged = send(json!({"event_id": first, "key": "stale_models", "shape": {"counts": {"changed": 2}}, "acknowledged": true})).await; + let reacknowledged = send(json!({"event_id": again, "key": "stale_models", "shape": {"counts": {"changed": 3}}, "acknowledged": true, "reason": "re-acknowledged"})).await; + let stale = send(json!({"event_id": Uuid::now_v7(), "key": "stale_models", "shape": {}, "acknowledged": false, "reason": "automatic: the condition cleared", "withdraws": first})).await; + let named_acknowledgement = send(json!({"event_id": Uuid::now_v7(), "key": "stale_models", "shape": {}, "acknowledged": true, "withdraws": first})).await; + let listed: Value = person_send(&client, administrator, None) + .await + .json() + .await + .expect("listing"); + let current = send(json!({"event_id": Uuid::now_v7(), "key": "stale_models", "shape": {}, "acknowledged": false, "reason": "automatic: the condition cleared", "withdraws": again})).await; + assert_eq!( + ( + [ + acknowledged.0, + reacknowledged.0, + stale.0, + named_acknowledgement.0, + current.0 + ], + [&stale.1["applied"], ¤t.1["applied"]], + ( + &listed["acknowledgements"][0]["event_id"], + &listed["acknowledgements"][0]["shape"]["counts"]["changed"] + ), + ), + ( + test_case.expected_statuses, + test_case.expected_applied.map(Value::Bool).each_ref(), + (&json!(again), &json!(3)), + ), + "{}: {}", + test_case.description, + test_case.expected_standing_after_stale + ); + stop_api(api).await; + close_test_store(fixture).await; + }); + } +} + +#[test] +fn given_a_large_audit_log_when_listing_condition_acknowledgements_then_the_attention_index_serves_the_read() + { + let test_cases = [ + ListingPlanTestCase { + description: "SQLite", + backend: Backend::Sqlite, + explain: "EXPLAIN QUERY PLAN ", + expected_index: "sqb_security_audit_attention", + expected_full_scans: &["SCAN a", "SCAN sqb_security_audit"], + }, + ListingPlanTestCase { + description: "PostgreSQL", + backend: Backend::Postgres, + explain: "EXPLAIN ", + expected_index: "sqb_security_audit_attention", + expected_full_scans: &["Seq Scan on sqb_security_audit"], + }, + ]; + for test_case in test_cases { + run(async { + let Some(fixture) = open_test_store(test_case.backend).await else { + return; + }; + let store = &fixture.store; + migrate_store(store).await.expect("migrate"); + let mut transaction = begin(store, TransactionMode::Write).await.expect("begin"); + let location = Uuid::now_v7(); + for index in 0..2_000_i64 { + let action = + ["run.requested", ATTENTION_EVENTS.acknowledged][usize::from(index % 400 == 0)]; + (transaction, _) = query( + transaction, + "INSERT INTO sqb_security_audit (event_id, occurred_at, actor, action, granting_role, request_id, ip_address, scope_json, before_json, after_json, storage_id) \ + VALUES ($1, $2, 'principal:someone', $3, 'admin', $4, NULL, $5, $6, $6, $7)", + vec![ + Parameter::Id(Uuid::now_v7()), + Parameter::Time(chrono::Utc::now()), + Parameter::Text(action.into()), + Parameter::Id(Uuid::now_v7()), + Parameter::Json(json!({"location_id": location, "target": "development", "key": "stale_models", "shape": {}})), + Parameter::Json(json!({})), + Parameter::Integer(index + 1), + ], + ) + .await + .expect("audit event"); + } + (transaction, _) = query(transaction, "ANALYZE", vec![]) + .await + .expect("statistics"); + let (transaction, plan) = query( + transaction, + &format!("{}{}", test_case.explain, listing_sql(&ATTENTION_EVENTS)), + vec![ + Parameter::Time(chrono::DateTime::UNIX_EPOCH), + Parameter::Text(location.to_string()), + Parameter::Text("development".into()), + ], + ) + .await + .expect("plan"); + commit(transaction).await.expect("commit"); + let plan: Vec = plan + .iter() + .filter_map(|row| row.get("detail").or_else(|| row.get("QUERY PLAN"))) + .filter_map(|line| line.as_str().map(str::to_owned)) + .collect(); + let text = plan.join("\n"); + assert_eq!( + ( + text.contains(test_case.expected_index), + test_case + .expected_full_scans + .iter() + .filter(|scan| text.contains(*scan)) + .count() + ), + (true, 0), + "{}: {text}", + test_case.description + ); + close_test_store(fixture).await; + }); + } +} diff --git a/crates/sqlbuild-orchestration/tests/api/test_contracts.rs b/crates/sqlbuild-orchestration/tests/api/test_contracts.rs index ea45183fa8..c72ebecf8f 100644 --- a/crates/sqlbuild-orchestration/tests/api/test_contracts.rs +++ b/crates/sqlbuild-orchestration/tests/api/test_contracts.rs @@ -40,6 +40,8 @@ mod statistics_helpers; mod statistics_retention; #[path = "test_acknowledgements.rs"] mod test_acknowledgements; +#[path = "test_attention_acknowledgements.rs"] +mod test_attention_acknowledgements; #[path = "test_catalog_reads.rs"] mod test_catalog_reads; #[path = "test_changes.rs"] diff --git a/crates/sqlbuild-orchestration/tests/api/test_types.rs b/crates/sqlbuild-orchestration/tests/api/test_types.rs index 72c8c81ca1..feca6abd72 100644 --- a/crates/sqlbuild-orchestration/tests/api/test_types.rs +++ b/crates/sqlbuild-orchestration/tests/api/test_types.rs @@ -340,6 +340,63 @@ pub(crate) struct AcknowledgementTestCase { pub(crate) expected_acknowledged_by: &'static str, } +pub(crate) struct AttentionAcknowledgementTestCase { + pub(crate) description: &'static str, + pub(crate) backend: Backend, + /// Statuses of: acknowledge, retry, reused event ID, same shape again, empty key, array shape, large shape. + pub(crate) expected_statuses: [u16; 7], + /// Whether each of acknowledge, retry, same shape, worse shape, other key, withdraw, again applied. + pub(crate) expected_applied: [bool; 7], + pub(crate) expected_acknowledged_by: &'static str, + pub(crate) expected_snooze_hours: i64, + /// Listed keys after the worse shape and another condition, then after withdrawing the first. + pub(crate) expected_keys: (&'static [&'static str], &'static [&'static str]), +} + +pub(crate) struct AttentionSnoozeTestCase { + pub(crate) description: &'static str, + pub(crate) snooze: crate::acknowledgements::models::AttentionSnooze, + pub(crate) expected_snooze_seconds: serde_json::Value, + pub(crate) expected_until_seconds: Option, + pub(crate) expected_same_shape_applies_after_a_wait: bool, +} + +pub(crate) struct SnoozeParseTestCase { + pub(crate) description: &'static str, + pub(crate) text: &'static str, + /// The snooze in seconds (none for no time limit), or part of the error message. + pub(crate) expected_seconds: Result, &'static str>, +} + +pub(crate) struct AutomaticWithdrawalTestCase { + pub(crate) description: &'static str, + pub(crate) backend: Backend, + /// Whether the first and the second viewer's identical withdrawal applied. + pub(crate) expected_applied: [bool; 2], + pub(crate) expected_reason: &'static str, + pub(crate) expected_withdrawals: usize, +} + +pub(crate) struct NamedWithdrawalTestCase { + pub(crate) description: &'static str, + pub(crate) backend: Backend, + /// Statuses of: acknowledge, re-acknowledge, stale withdrawal, acknowledge naming one, current withdrawal. + pub(crate) expected_statuses: [u16; 5], + /// Whether the withdrawal naming the first and then the second acknowledgement applied. + pub(crate) expected_applied: [bool; 2], + pub(crate) expected_standing_after_stale: &'static str, +} + +pub(crate) struct ListingPlanTestCase { + pub(crate) description: &'static str, + pub(crate) backend: Backend, + /// How the backend shows a plan. + pub(crate) explain: &'static str, + pub(crate) expected_index: &'static str, + /// Plan lines that would mean the whole audit log is read. + pub(crate) expected_full_scans: &'static [&'static str], +} + pub(crate) struct ProvidersTestCase { pub(crate) description: &'static str, pub(crate) backend: Backend, diff --git a/crates/sqlbuild-orchestration/tests/store/schema/test_store_migrations.rs b/crates/sqlbuild-orchestration/tests/store/schema/test_store_migrations.rs index 7b434b617c..041225eeed 100644 --- a/crates/sqlbuild-orchestration/tests/store/schema/test_store_migrations.rs +++ b/crates/sqlbuild-orchestration/tests/store/schema/test_store_migrations.rs @@ -37,6 +37,10 @@ const SQLITE_CHECKSUMS: &[(i64, &str)] = &[ 2, "4d4e3aa56b3a39d8550f691ae12fe463187b4f4cdeacc66ca94803701cab5e0a", ), + ( + 3, + "734163e22863ff86fbcf1329540736f279806d4ce5ea04f6d6ecb1703b3468c8", + ), ]; const POSTGRES_CHECKSUMS: &[(i64, &str)] = &[ ( @@ -47,6 +51,10 @@ const POSTGRES_CHECKSUMS: &[(i64, &str)] = &[ 2, "99e13d88687d6e590e47149200a0d1cb03c0ff285a95339da40b76cba99e2a21", ), + ( + 3, + "b1250935a5adf1d4691836a2125bb57360c1ff0a2a296a77e4d11bf6a80a99d9", + ), ]; /// A version 1 store mid-run: a child run holding a concurrency slot, a jobs document and an audit result. const VERSION_1_LIVE_WORK: &str = "ALTER TABLE sqb_schema_version ADD COLUMN version BIGINT; \ @@ -170,13 +178,13 @@ fn given_a_version_1_store_with_live_work_when_migrating_then_rows_default_and_r description: "SQLite store", dialect: &SQLITE_STORE, foreign_key_check: "SELECT \"table\" || ' ' || parent AS item FROM pragma_foreign_key_check", - expected_version: 2, + expected_version: current_version(MIGRATIONS), }, LiveWorkUpgradeTestCase { description: "PostgreSQL store", dialect: &POSTGRES_STORE, foreign_key_check: "SELECT 'enforced' AS item WHERE FALSE", - expected_version: 2, + expected_version: current_version(MIGRATIONS), }, ]; for test_case in test_cases { diff --git a/src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/server.md b/src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/server.md index 3c958c3dc7..2e46bc706b 100644 --- a/src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/server.md +++ b/src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/server.md @@ -12,6 +12,7 @@ Online: https://sqlbuild.com/docs/cli/server/ - Serve over HTTPS - Sign in through a reverse proxy - Receive platform events +- Acknowledge attention items - Back up the control database - Upgrade - Set retention @@ -65,7 +66,7 @@ executable = "/usr/local/bin/sqb" | Section | Keys | | --- | --- | -| `[server]` | `host` (default `127.0.0.1`), `port` (`8000`), `database_env` (`SQLBUILD_CONTROL_DATABASE_URL`), `password_origin`, `default_role` (`none`), `scheduler` (`true`) | +| `[server]` | `host` (default `127.0.0.1`), `port` (`8000`), `database_env` (`SQLBUILD_CONTROL_DATABASE_URL`), `password_origin`, `default_role` (`none`), `scheduler` (`true`), `attention_snooze` (`"24h"`); see [Acknowledge attention items](#acknowledge-attention-items) | | `[retention]` | `statistics_days`, `audit_days`, `snapshot_count`, `run_log_days`, `run_log_count`, `state_history_versions`; see [Set retention](#set-retention) | | `[oidc]` | `origin`, `issuer`, `client_id`, `identities`, and optionally `client_secret_env`, `certificate_authority`, `groups_claim` and `group_roles` | | `[trusted_proxy]` | `origin`, and optionally `trusted_peers` (`127.0.0.1` and `::1`), `allowed_hosts`, `username_header` (`X-SQB-User`), `display_name_header`, `email_header`, `unknown_users` (`provision_viewer`), `proxy_logout_url` and `identities`; see [Sign in through a reverse proxy](#sign-in-through-a-reverse-proxy) | @@ -257,6 +258,33 @@ characters, and `null` when the worker reported none. It can quote warehouse dat webhook like other run evidence. `run_failed` events appear only in the webhook, not in the server's platform history. +## Acknowledge attention items + +Anyone who can see a target's runs can acknowledge an item on its Overview's attention list. That +hides the item for everyone viewing the target, and records who did it in the audit log: + +- A problem run stays acknowledged until someone undoes it. +- An ongoing condition, such as nodes out of date or a late schedule, stays acknowledged until it + gets worse, or until `attention_snooze` has passed: + +```toml +[server] +attention_snooze = "12h" +``` + +`attention_snooze` takes a duration in days, hours, minutes and seconds, such as `"24h"` (the +default), `"90m"` or `"1d12h"`. `"0"` removes the time limit, so an acknowledged condition stays +hidden until it gets worse or clears. Years and months aren't accepted. + +When the Overview finds that an acknowledged condition has cleared, it withdraws the +acknowledgement, so the condition shows again if it comes back. The audit log records that +withdrawal as automatic. Acknowledgements are audit records, so `audit_days` also limits how long +one without a time limit lasts. + +The Overview withdraws an acknowledgement of nodes out of date only once the target's warehouse sync +has reported and settled. On a target without sync history, or where you may not read its sync +status, it isn't withdrawn automatically and lapses only after `attention_snooze`. + ## Back up the control database With no `SQLBUILD_CONTROL_DATABASE_URL`, the server keeps its control database in one SQLite file. @@ -320,6 +348,18 @@ server can't read what they wrote. the control server is older than this worker and refused its run report; upgrade the server before its workers ``` +Some migrations add an index, which the server builds when it migrates. On PostgreSQL that build +locks its table against writes, so on a large table those writes wait until it is built. Migration +`0003` indexes acknowledgements in the audit log, so on a large audit log it holds up audit writes, +including sign-ins. To avoid that, build the index yourself before you upgrade, without blocking +writes: + +```sql +CREATE INDEX CONCURRENTLY IF NOT EXISTS sqb_security_audit_attention ON sqb_security_audit((scope_json ->> 'location_id'), (scope_json ->> 'target'), (scope_json ->> 'key'), storage_id) WHERE action IN ('attention.acknowledged', 'attention.acknowledgement_withdrawn'); +``` + +The migration then finds the index already there and skips it. + ## Set retention Set how much history the server keeps in the `[retention]` section of `server.toml`: diff --git a/ui/e2e/attention-ack.spec.ts b/ui/e2e/attention-ack.spec.ts new file mode 100644 index 0000000000..e8978c232e --- /dev/null +++ b/ui/e2e/attention-ack.spec.ts @@ -0,0 +1,40 @@ +import { expect, test } from '@playwright/test'; + +// The Overview's attention list: every item can be acknowledged. A run is hidden for good; an ongoing +// condition until it changes. Both move to "Acknowledged (N)", where anyone can undo them. +test.use({ viewport: { width: 1600, height: 1000 } }); + +test('acknowledging a condition moves it under Acknowledged until it changes, and Undo brings it back', async ({ page }) => { + await page.goto('/?mock'); + const issues = page.locator('section.health .issues'); + const row = issues.locator('.issue', { hasText: 'past the freshness threshold' }); + await expect(row).toBeVisible({ timeout: 20_000 }); + + const ack = row.getByRole('button', { name: 'Acknowledge' }); + await expect(ack).toHaveText('Ack'); + await expect(ack).toHaveAttribute('title', /until it changes/); + await ack.click(); + await expect(row).toHaveCount(0); + + const handled = page.locator('section.health .handled'); + await expect(handled.getByRole('button', { name: /^Acknowledged \(1\)$/ })).toBeVisible(); + await handled.getByRole('button', { name: /^Acknowledged/ }).click(); + const acknowledged = handled.locator('.issue', { hasText: 'past the freshness threshold' }); + await expect(acknowledged).toContainText('Acknowledged by you'); + await expect(acknowledged).toContainText('hidden until it changes'); + + await acknowledged.getByRole('button', { name: 'Undo' }).click(); + await expect(issues.locator('.issue', { hasText: 'past the freshness threshold' })).toBeVisible(); + await expect(handled).toHaveCount(0); +}); + +test('a run is acknowledged for good', async ({ page }) => { + await page.goto('/?mock'); + const row = page.locator('section.health .issues .issue', { hasText: 'core_build partial' }); + await expect(row).toBeVisible({ timeout: 20_000 }); + await expect(row.getByRole('button', { name: 'Acknowledge' })).toHaveAttribute('title', /^Hide this from the attention list for everyone viewing this target\./); + await row.getByRole('button', { name: 'Acknowledge' }).click(); + const handled = page.locator('section.health .handled'); + await handled.getByRole('button', { name: /^Acknowledged/ }).click(); + await expect(handled.locator('.issue', { hasText: 'core_build partial' })).toContainText('for good'); +}); diff --git a/ui/e2e/attention-auto-withdraw.spec.ts b/ui/e2e/attention-auto-withdraw.spec.ts new file mode 100644 index 0000000000..0192e64018 --- /dev/null +++ b/ui/e2e/attention-auto-withdraw.spec.ts @@ -0,0 +1,158 @@ +import { expect, test, type Page } from '@playwright/test'; +import { FakeControl, type TargetName } from './support/fake-control'; + +// The real Overview and its server client, against a control server faked by the test: an acknowledged +// condition that clears is withdrawn once, naming that acknowledgement, and never on a read that can't +// show it cleared: another target's, one taken during a sync, a failed one, or one already superseded. +test.use({ viewport: { width: 1600, height: 1000 } }); + +const health = (page: Page) => page.locator('section.health'); +const item = (page: Page, text: string | RegExp) => health(page).locator('.issues .issue', { hasText: text }); +/** How long the page has, once a read is answered, to judge it and send what it would; the absence of a + * request can't be awaited, so this is the one fixed wait. */ +const GRACE_MS = 750; + +/** Waits until `count` Overview reads of `target` have been answered, then gives the page its grace. */ +async function afterReads(page: Page, server: FakeControl, count: number, target: TargetName = 'shop') { + await expect.poll(() => server.reads[target].answered, { timeout: 20_000 }).toBeGreaterThanOrEqual(count); + await page.waitForTimeout(GRACE_MS); +} + +async function acknowledge(page: Page, text: string | RegExp) { + await expect(item(page, text)).toBeVisible({ timeout: 20_000 }); + await item(page, text).getByRole('button', { name: 'Acknowledge' }).click(); + await expect(item(page, text)).toHaveCount(0); +} + +test('a cleared condition is withdrawn once, naming its acknowledgement, and comes back as new', async ({ page }) => { + const server = new FakeControl({ shop: { changed: ['orders', 'order_items', 'customers'] } }); + await server.install(page); + await page.goto('/'); + await acknowledge(page, '3 nodes out of date'); + const [ack] = server.targets.shop.acks; + expect(ack.key).toBe('stale_models'); + + server.targets.shop.changed = []; + await page.reload(); + await expect.poll(() => server.withdrawals().length, { timeout: 15_000 }).toBe(1); + const [withdrawal] = server.withdrawals(); + expect(withdrawal).toMatchObject({ target: 'shop', body: { key: 'stale_models', acknowledged: false, withdraws: ack.event_id, reason: 'automatic: the condition cleared' } }); + expect(server.targets.shop.acks).toEqual([]); + + server.targets.shop.changed = ['orders']; + const before = server.reads.shop.answered; + await page.reload(); + await expect(item(page, '1 node out of date').getByRole('button', { name: 'Acknowledge' })).toBeVisible({ timeout: 20_000 }); + await expect(health(page).getByRole('button', { name: /^Acknowledged/ })).toHaveCount(0); + await afterReads(page, server, before + 1); + expect(server.withdrawals()).toHaveLength(1); +}); + +test('a first read made before the sync status arrives is taken again once it does, and then withdraws', async ({ page }) => { + const server = new FakeControl({ shop: { changed: ['orders', 'order_items'] } }); + await server.install(page); + await page.goto('/'); + await acknowledge(page, '2 nodes out of date'); + server.targets.shop.changed = []; + server.targets.shop.healthDelayMs = 3_000; + const before = server.reads.shop.answered; + await page.reload(); + await expect(item(page, 'out of date')).toHaveCount(0, { timeout: 20_000 }); + // Nothing else prompts a read: the page reads again by itself once it knows node state has settled. + await expect.poll(() => server.withdrawals().length, { timeout: 15_000 }).toBe(1); + await afterReads(page, server, before + 2); + expect(server.withdrawals()).toHaveLength(1); +}); + +test('a read taken during a sync is never judged, even once the sync has settled', async ({ page }) => { + const server = new FakeControl({ shop: { changed: ['orders', 'order_items'] } }); + await server.install(page); + await page.goto('/'); + await acknowledge(page, '2 nodes out of date'); + server.targets.shop.changed = []; + server.targets.shop.sync = 'running'; + const before = server.reads.shop.answered; + await page.reload(); + await expect(item(page, 'out of date')).toHaveCount(0, { timeout: 20_000 }); + await afterReads(page, server, before + 1); + expect(server.withdrawals()).toEqual([]); + + // The sync settles, and the nodes are out of date again. The read after it is slow: in that gap the + // read taken during the sync, which saw them cleared, is still the latest, and must not be judged. + server.targets.shop.sync = 'settled'; + server.targets.shop.changed = ['orders']; + server.targets.shop.readDelayMs = 2_000; + const settledFrom = server.reads.shop.started; + server.notify('all'); + await expect.poll(() => server.reads.shop.started, { timeout: 15_000 }).toBeGreaterThan(settledFrom); + // Back, and smaller than when acknowledged, so it shows as acknowledged still. + await expect(health(page).getByRole('button', { name: /^Acknowledged \(1\)$/ })).toBeVisible({ timeout: 20_000 }); + await afterReads(page, server, server.reads.shop.started); + expect(server.withdrawals()).toEqual([]); +}); + +test('a failed read withdraws nothing, even after a withdrawal that failed', async ({ page }) => { + const server = new FakeControl({ shop: { changed: ['orders', 'order_items'] } }); + await server.install(page); + await page.goto('/'); + await acknowledge(page, '2 nodes out of date'); + server.targets.shop.changed = []; + server.targets.shop.failWithdrawals = true; + await page.reload(); + await expect.poll(() => server.withdrawals().length, { timeout: 15_000 }).toBe(1); + expect(server.withdrawals()[0].status).toBe(500); + + // The next read fails: what is still shown is not judged again. + server.targets.shop.failReads = true; + const before = server.reads.shop.answered; + server.notify('runs'); + await expect(page.locator('.error-note')).toBeVisible({ timeout: 15_000 }); + await afterReads(page, server, before + 1); + expect(server.withdrawals()).toHaveLength(1); +}); + +test('switching target while a withdrawal is held back sends nothing to the new target', async ({ page }) => { + const server = new FakeControl({ shop: { changed: ['orders', 'order_items'] }, returns: { changed: ['refunds'] } }); + await server.install(page); + await page.goto('/'); + await acknowledge(page, '2 nodes out of date'); + // The withdrawal on shop fails, so it is held back, not marked as sent. + server.targets.shop.changed = []; + server.targets.shop.failWithdrawals = true; + await page.reload(); + await expect.poll(() => server.withdrawals('shop').length, { timeout: 15_000 }).toBe(1); + + // returns holds an acknowledgement under the same key; its read is slow, so shop's data stays shown. + server.targets.returns.acks = [{ event_id: '0190d1a0-0000-7000-8000-0000000000a2', key: 'stale_models', shape: { counts: { changed: 1, behind: 0 } }, acknowledged_at: new Date().toISOString() }]; + server.targets.returns.readDelayMs = 2_000; + await page.getByRole('button', { name: 'Switch location' }).click(); + await page.getByRole('menuitemradio', { name: /returns/ }).click(); + await expect(page.getByRole('button', { name: 'Switch location' })).toContainText('returns'); + await expect.poll(() => server.reads.returns.started, { timeout: 15_000 }).toBeGreaterThan(0); + await afterReads(page, server, 1, 'returns'); + expect(server.withdrawals('returns')).toEqual([]); + expect(server.withdrawals('shop')).toHaveLength(1); +}); + +test('a slow read that saw a condition clear withdraws nothing once a newer read shows it back', async ({ page }) => { + const server = new FakeControl({ shop: { failedRun: true } }); + server.stopScheduler(); + await server.install(page); + await page.goto('/'); + await acknowledge(page, /scheduler/i); + + // The next read sees the scheduler back, and is answered slowly. + for (const t of Object.values(server.targets)) t.schedulerLeader = true; + server.targets.shop.readDelayMs = 2_000; + const slow = server.reads.shop.started + 1; + server.notify('runs'); + await expect.poll(() => server.reads.shop.started, { timeout: 15_000 }).toBeGreaterThanOrEqual(slow); + // Meanwhile it stops again, and acknowledging the failed run reads the Overview again at once, + // overtaking the slow read, which then arrives with the condition cleared. + server.stopScheduler(); + server.targets.shop.readDelayMs = 0; + await item(page, /failed/).getByRole('button', { name: 'Acknowledge' }).click(); + await afterReads(page, server, slow + 1); + expect(server.writes.filter((w) => w.path === '/acknowledgements')).toHaveLength(1); + expect(server.withdrawals()).toEqual([]); +}); diff --git a/ui/e2e/budgets.spec.ts b/ui/e2e/budgets.spec.ts index b65bfb4a9c..20647f7d48 100644 --- a/ui/e2e/budgets.spec.ts +++ b/ui/e2e/budgets.spec.ts @@ -249,6 +249,102 @@ test('Plan: switching sections and showing more on a large changed build', async ); }); +/** + * Runs in the page before the app. While `__sqbHoldReads(true)`, the mock client's replies (each a + * `readMs` timer) are held, and run when holding stops, so a test can see the page before a read lands. + */ +function holdReads(readMs: number) { + const realSetTimeout = window.setTimeout.bind(window); + let holding = false; + let next = 2e9; + const held: (() => void)[] = []; + window.setTimeout = ((handler: TimerHandler, ms?: number, ...args: unknown[]) => { + if (!holding || ms !== readMs || typeof handler !== 'function') return realSetTimeout(handler, ms, ...args); + held.push(() => handler(...args)); + return ++next; + }) as typeof window.setTimeout; + (window as unknown as { __sqbHoldReads: (on: boolean) => void }).__sqbHoldReads = (on) => { + holding = on; + if (on) return; + for (const run of held.splice(0)) run(); + }; +} + +const holdMockReads = (page: Page, on: boolean) => page.evaluate((o) => (window as unknown as { __sqbHoldReads: (on: boolean) => void }).__sqbHoldReads(o), on); + +const FOLDER_ROW = '[data-testid="folder-tree"] tbody tr[data-path], [data-testid="folder-tree"] tbody tr.leaf'; +const ISSUE = 'section.health .issues .issue'; + +test('Overview and folder view on a 10,000-node project', async ({ page }) => { + test.setTimeout(300_000); + // The mock client's reply latency (`latencyMs`). + await page.addInitScript(holdReads, 120); + const cdp = await open(page, '/?mock&huge&still', ISSUE); + const quiet = async () => { + await page.waitForLoadState('networkidle'); + await frames(page, 4); + }; + judge( + '10K open the folder view', + await cost(page, cdp, FOLDER_ROW, async () => { + await page.getByTestId('all-folders').click(); + await page.locator(FOLDER_ROW).nth(19).waitFor(); + }), + BUDGETS['10K open the folder view'] + ); + judge( + '10K expand all', + await cost(page, cdp, FOLDER_ROW, async () => { + await page.getByRole('button', { name: 'Expand all' }).click(); + await page.locator('[data-testid="folder-tree"] tbody tr.leaf, [data-testid="folder-more"]').first().waitFor(); + }), + BUDGETS['10K expand all'] + ); + await page.getByRole('button', { name: 'Collapse all' }).click(); + await quiet(); + judge( + '10K open one folder', + await cost(page, cdp, FOLDER_ROW, async () => { + await page.getByTestId('folder-toggle').first().click(); + await page.locator('[data-testid="folder-toggle"][aria-expanded="true"]').first().waitFor(); + }), + BUDGETS['10K open one folder'] + ); + await page.getByRole('button', { name: 'Expand all' }).click(); + await quiet(); + const tree = (await page.getByTestId('folder-tree').locator('tbody').boundingBox())!; + judge( + '10K opened tree scroll', + await cost(page, cdp, FOLDER_ROW, () => wheel(page, { x: tree.x + tree.width / 2, y: Math.min(tree.y + 200, 800) }, 20, (i) => (i < 10 ? 400 : -400))), + BUDGETS['10K opened tree scroll'] + ); + judge( + '10K back to the Overview', + await cost(page, cdp, ISSUE, async () => { + await page.locator('nav a', { hasText: 'Overview' }).first().click(); + await page.locator(ISSUE).first().waitFor(); + }), + BUDGETS['10K back to the Overview'] + ); + const stale = page.locator(ISSUE, { hasText: 'out of date' }); + let listedWhileReading = -1; + judge( + '10K acknowledge nodes out of date', + await cost(page, cdp, ISSUE, async () => { + // The Overview's read that follows is held: the item must leave the list without waiting for it. + await holdMockReads(page, true); + await stale.getByRole('button', { name: 'Acknowledge' }).click(); + await frames(page, 4); + listedWhileReading = await stale.count(); + await holdMockReads(page, false); + await page.waitForFunction(() => ![...document.querySelectorAll('section.health .issues .issue')].some((e) => e.textContent?.includes('out of date'))); + }), + BUDGETS['10K acknowledge nodes out of date'] + ); + console.info(`BUDGET 10K acknowledged item still listed while the Overview reads again: ${listedWhileReading}`); + expect.soft(listedWhileReading, 'an acknowledged item leaves the list at once, not after the Overview is read again').toBe(0); +}); + // Measured on 10 runs each at 1× and 6× CPU (Chrome throttling), with the breakdown traced from the // mutation records (`BUDGET_TRACE=1`). The graph's settle timer is held while a gesture is counted and // run once at its end, so DOM changes and reads are the same on every run and get 2 of headroom. @@ -285,5 +381,27 @@ const BUDGETS: Record = { 'Plan section unchanged': { layouts: 4, styles: 8, mutations: 117, nodes: 2500, drawn: 50, reads: 1 }, 'Plan section changed': { layouts: 3, styles: 7, mutations: 113, nodes: 2850, drawn: 50, reads: 0 }, // Show more reads the next page once and adds its 50 rows. Measured layouts 2, styles 8–9, mutations 54. - 'Plan show more': { layouts: 4, styles: 12, mutations: 56, nodes: 3400, drawn: 100, reads: 1 } + 'Plan show more': { layouts: 4, styles: 12, mutations: 56, nodes: 3400, drawn: 100, reads: 1 }, + // The 10,000-node project (`?huge`), measured the same way: DOM changes, nodes, rows and reads the + // same in every run but one (141 against 140 DOM changes going back to the Overview at 6×). The folder + // tree windows its rows like any long list; drawing every folder or node instead adds thousands of rows. + // Opening the folder view reads the selection vocabulary once and draws 40 rows: 320 cell class writes, + // 40 rows' label and wrap classes, the rest the tab switch. Measured layouts 3, styles 12–17. + '10K open the folder view': { layouts: 5, styles: 24, mutations: 456, nodes: 7300, drawn: 44, reads: 1 }, + // Expand all swaps the window's rows for the expanded tree's (316 row insertions and removals) and + // rewrites their cells' classes. Measured layouts 1, styles 11–16. + '10K expand all': { layouts: 3, styles: 23, mutations: 577, nodes: 5700, drawn: 28, reads: 0 }, + // Opening one folder inserts its 20 subfolder rows and rewrites the window's cell classes (440). + // Measured layouts 1–2, styles 9–15. + '10K open one folder': { layouts: 5, styles: 23, mutations: 469, nodes: 7500, drawn: 48, reads: 0 }, + // 20 wheel steps of 400 px over the expanded tree: like the Checks list, each step swaps rows in and out + // of the window (2,142) and rewrites the recycled cells' classes (6,579), one layout per step. + // Measured layouts 20, styles 45–53, mutations 8,800. + '10K opened tree scroll': { layouts: 22, styles: 63, mutations: 8802, nodes: 5700, drawn: 28, reads: 0 }, + // Reads the Overview, its timeline and the cost summary once each, and draws the attention card's 9 + // items and the timeline. Measured layouts 3–4, styles 22–31, mutations 140–141. + '10K back to the Overview': { layouts: 7, styles: 42, mutations: 143, nodes: 4600, drawn: 12, reads: 3 }, + // The acknowledgement and the Overview's read that follows it; the item leaves the list at once (the + // test holds that read back to check), so 6 DOM changes. Measured layouts 1, styles 6–7. + '10K acknowledge nodes out of date': { layouts: 3, styles: 10, mutations: 8, nodes: 4700, drawn: 11, reads: 2 } }; diff --git a/ui/e2e/folder-tree.spec.ts b/ui/e2e/folder-tree.spec.ts new file mode 100644 index 0000000000..83fe5fbbe2 --- /dev/null +++ b/ui/e2e/folder-tree.spec.ts @@ -0,0 +1,94 @@ +import { expect, test, type Page } from '@playwright/test'; + +// The catalog's folders as a tree: clicking anywhere on a folder's label opens or closes it, except on +// its name, which, like each count, opens those nodes in the list instead. +test.use({ viewport: { width: 1600, height: 1000 } }); + +const open = async (page: Page) => { + await page.goto('/catalog?mock&large&view=folders'); + const tree = page.getByTestId('folder-tree'); + await expect(tree.locator('tr[data-path]').first()).toBeVisible({ timeout: 20_000 }); + return tree; +}; +/** The first top-level folder with subfolders. */ +const parentRow = (page: Page) => page.getByTestId('folder-tree').locator('tr[aria-level="1"]', { has: page.getByTestId('folder-toggle') }).first(); + +test('a click anywhere on a folder’s label, but its name, opens and closes it', async ({ page }) => { + await open(page); + const row = parentRow(page); + const path = await row.getAttribute('data-path'); + const toggle = row.getByTestId('folder-toggle'); + const children = page.locator(`tr[data-path^="${path}/"]`); + await expect(toggle).toHaveAttribute('aria-expanded', 'false'); + await expect(children).toHaveCount(0); + + // Empty space at the right of the label. + const label = row.getByTestId('folder-label'); + const box = (await label.boundingBox())!; + await page.mouse.click(box.x + box.width - 12, box.y + box.height / 2); + await expect(toggle).toHaveAttribute('aria-expanded', 'true'); + expect(await children.count()).toBeGreaterThan(0); + expect(await label.evaluate((td) => getComputedStyle(td).cursor)).toBe('pointer'); + + // The folder icon. + await label.locator('svg').nth(1).click(); + await expect(toggle).toHaveAttribute('aria-expanded', 'false'); + // The "N subfolders" text. + await label.locator('small').click(); + await expect(toggle).toHaveAttribute('aria-expanded', 'true'); + + // The chevron is a button that the keyboard works too. + await toggle.focus(); + await page.keyboard.press('Enter'); + await expect(toggle).toHaveAttribute('aria-expanded', 'false'); + await page.keyboard.press('Space'); + await expect(toggle).toHaveAttribute('aria-expanded', 'true'); +}); + +test('selecting text on a label does not open or close the folder', async ({ page }) => { + await open(page); + const row = parentRow(page); + const small = row.getByTestId('folder-label').locator('small'); + const box = (await small.boundingBox())!; + await page.mouse.move(box.x + 1, box.y + box.height / 2); + await page.mouse.down(); + await page.mouse.move(box.x + box.width - 1, box.y + box.height / 2, { steps: 5 }); + await page.mouse.up(); + expect(await page.evaluate(() => window.getSelection()?.toString().length ?? 0)).toBeGreaterThan(0); + await expect(row.getByTestId('folder-toggle')).toHaveAttribute('aria-expanded', 'false'); +}); + +test('a folder’s name opens its nodes in the list, without opening or closing it', async ({ page }) => { + await open(page); + const row = parentRow(page); + const path = (await row.getAttribute('data-path'))!; + // Watch the toggle: the tree goes away once the list opens, so a toggle would only show as a change. + await row.getByTestId('folder-toggle').evaluate((button) => { + const w = window as unknown as { toggled: number }; + w.toggled = 0; + new MutationObserver(() => (w.toggled += 1)).observe(button, { attributes: true, attributeFilter: ['aria-expanded'] }); + }); + // Opened in a new tab, the tree stays, so a toggle would show directly. + const [tab] = await Promise.all([page.context().waitForEvent('page'), row.getByTestId('folder-name').click({ modifiers: ['Control'] })]); + await tab.close(); + await expect(row.getByTestId('folder-toggle')).toHaveAttribute('aria-expanded', 'false'); + await row.getByTestId('folder-name').click(); + await expect(page.getByTestId('folder-tree')).toHaveCount(0); + expect(await page.evaluate(() => (window as unknown as { toggled: number }).toggled)).toBe(0); + await expect(page).not.toHaveURL(/view=folders/); + // The selection is evaluated a moment later; then the list holds just the folder's nodes. + await expect(page.getByText(/^\d+ of \d+ nodes$/)).toHaveText(/^(\d+) of (?!\1 )\d+ nodes$/); + const shown = (await page.locator('table.catalog tbody tr .cell-name a').allInnerTexts()).map((s) => s.trim()); + expect(shown.length).toBeGreaterThan(0); + expect(shown.filter((name) => !name.startsWith(path.split('/')[0])), path).toEqual([]); +}); + +test('a folder’s count opens just those nodes', async ({ page }) => { + const tree = await open(page); + const count = tree.getByTestId('folder-count-changed').first(); + const n = Number(await count.innerText()); + await count.click(); + await expect(page.getByTestId('folder-tree')).toHaveCount(0); + await expect(page.getByText(new RegExp(`^${n} of \\d+ nodes$`))).toBeVisible(); + await expect(page.locator('table.catalog tbody tr')).toHaveCount(n); +}); diff --git a/ui/e2e/perf.spec.ts b/ui/e2e/perf.spec.ts index 3a84d448ff..be907dd949 100644 --- a/ui/e2e/perf.spec.ts +++ b/ui/e2e/perf.spec.ts @@ -187,3 +187,63 @@ test('the plan page switches sections and shows more quickly on a slow computer' console.info(`plan page, CPU slowed 6×: ${steps.join('; ')}`); expect(over, `steps over ${PLAN_STEP_MS} ms`).toEqual([]); }); + +// The Overview and the catalog's folder view on a project of about 10,000 nodes (`?mock&huge`), on a slow +// computer: the pages open within the list budget, opening folders shows their rows within a second, the +// whole opened tree scrolls at the frame budget, and acknowledging an item takes it off the list as fast. +test('the Overview and the folder view stay quick on a 10,000-node project', async ({ page }) => { + test.setTimeout(240_000); + await page.setViewportSize({ width: 1600, height: 1000 }); + await page.goto('/?mock&huge'); + await page.locator('section.health .issue').first().waitFor({ timeout: 60_000 }); + await settle(page); + const cdp = await page.context().newCDPSession(page); + await cdp.send('Emulation.setCPUThrottlingRate', { rate: 6 }); + const timed = async (act: () => Promise, done: () => Promise) => { + const start = Date.now(); + await act(); + await expect.poll(done, { timeout: 20_000, intervals: [10] }).toBe(true); + return Date.now() - start; + }; + const results: string[] = []; + const over: string[] = []; + const judge = (step: string, ms: number, budget: number) => { + results.push(`${step} ${ms} ms`); + if (ms > budget) over.push(`${step}: ${ms} ms > ${budget}`); + }; + const rows = page.getByTestId('folder-tree').locator('tbody tr[data-path], tbody tr.leaf'); + + judge('open the folder view', await timed(() => page.getByTestId('all-folders').click(), async () => (await rows.count()) >= 20), 2000); + await settle(page); + judge('expand all', await timed(() => page.getByRole('button', { name: 'Expand all' }).click(), async () => (await page.getByTestId('folder-more').count()) > 0 || (await page.locator('tbody tr.leaf').count()) > 0), 1000); + await page.getByRole('button', { name: 'Collapse all' }).click(); + await settle(page); + const toggle = page.getByTestId('folder-toggle').first(); + judge('open one folder', await timed(() => toggle.click(), async () => (await toggle.getAttribute('aria-expanded')) === 'true'), 1000); + await page.getByRole('button', { name: 'Expand all' }).click(); + await settle(page); + const box = (await page.getByTestId('folder-tree').locator('tbody').boundingBox())!; + await page.mouse.move(box.x + box.width / 2, Math.min(box.y + 200, 900)); + const scroll = async () => { + for (let i = 0; i < 20; i++) { + await page.mouse.wheel(0, i < 10 ? 400 : -400); + await page.waitForTimeout(30); + } + }; + // PERF.md sets no budget for scrolling a list; the opened tree is reported beside the node list of the + // same project, which the shared table windows the same way, so a tree row that costs more shows. + const tree = await medianRun(page, scroll); + await page.getByRole('tab', { name: 'Nodes', exact: true }).click(); + await page.locator('table.catalog tbody tr').first().waitFor(); + await settle(page); + const list = await medianRun(page, scroll); + results.push(`scroll the opened tree: p90 ${Math.round(tree.p90)} ms, max ${Math.round(tree.max)} ms (node list: p90 ${Math.round(list.p90)} ms, max ${Math.round(list.max)} ms)`); + + judge('back to the Overview', await timed(() => page.locator('nav a', { hasText: 'Overview' }).first().click(), async () => (await page.locator('section.health .issue').count()) > 0), 2000); + await settle(page); + const stale = page.locator('section.health .issues .issue', { hasText: 'out of date' }); + judge('acknowledge nodes out of date', await timed(() => stale.getByRole('button', { name: 'Acknowledge' }).click(), async () => (await stale.count()) === 0), 1000); + + console.info(`10,000 nodes, CPU slowed 6×: ${results.join('; ')}`); + expect(over, 'steps over budget').toEqual([]); +}); diff --git a/ui/e2e/support/fake-control.ts b/ui/e2e/support/fake-control.ts new file mode 100644 index 0000000000..358becdbe9 --- /dev/null +++ b/ui/e2e/support/fake-control.ts @@ -0,0 +1,201 @@ +// A control server faked inside a browser test, so the real page and its server client run against +// state the test changes as it goes. Lives only in the tests: the app has no hook for it, it answers +// the page's requests through Playwright's routing. Two targets, `shop` and `returns`. + +import type { Page, Route } from '@playwright/test'; + +export const LOCATIONS = { shop: '0190d1a0-0000-7000-8000-000000000001', returns: '0190d1a0-0000-7000-8000-000000000002' } as const; +export type TargetName = keyof typeof LOCATIONS; +const SNAPSHOT = '0190d1a0-0000-7000-8000-0000000000aa'; +const ACTIONS = ['view', 'view.sql', 'view.evidence', 'job.run', 'run.cancel', 'run.rerun', 'run.adhoc', 'audit.view']; + +type Ack = { event_id: string; key: string; shape: unknown; acknowledged_at: string }; +/** One request the page wrote: an acknowledgement, a withdrawal or a run's acknowledgement. */ +export type Write = { target: TargetName; path: string; body: Record; status: number }; + +/** What one target holds; tests change it between reads. */ +export type TargetState = { + /** Models whose definition changed since their last build: "N nodes out of date". */ + changed: string[]; + /** The warehouse sync: done, still going, or failed. */ + sync: 'settled' | 'running' | 'failed'; + /** Whether the scheduler has a leader; without one, every viewer sees it stopped. */ + schedulerLeader: boolean; + acks: Ack[]; + /** A failed run on the attention list, to acknowledge. */ + failedRun: boolean; + /** Delays the answers to this target's Overview reads. */ + readDelayMs: number; + /** Refuses this target's Overview reads with a server error. */ + failReads: boolean; + /** Refuses withdrawals of condition acknowledgements with a server error. */ + failWithdrawals: boolean; + /** Delays the sync status, so it arrives after the page's first read has begun. */ + healthDelayMs: number; +}; + +const MODELS = ['orders', 'order_items', 'customers', 'payments', 'refunds']; + +const json = (route: Route, body: unknown, status = 200) => route.fulfill({ status, contentType: 'application/json', body: JSON.stringify(body) }); +const later = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)); + +export class FakeControl { + readonly targets: Record; + readonly writes: Write[] = []; + /** Overview reads per target, counted by their acknowledgement listing: begun, and answered. */ + readonly reads: Record = { shop: { started: 0, answered: 0 }, returns: { started: 0, answered: 0 } }; + #notices: string[] = []; + #states: Record = { shop: { seen: '', version: 0 }, returns: { seen: '', version: 0 } }; + #lease = new Date(Date.now() - 60_000).toISOString(); + + constructor(overrides: Partial>> = {}) { + const base = (): TargetState => ({ changed: [], sync: 'settled', schedulerLeader: true, acks: [], failedRun: false, readDelayMs: 0, failReads: false, failWithdrawals: false, healthDelayMs: 0 }); + this.targets = { shop: { ...base(), ...overrides.shop }, returns: { ...base(), ...overrides.returns } }; + } + + /** Withdrawals of condition acknowledgements the page sent, in order. */ + withdrawals(target?: TargetName): Write[] { + return this.writes.filter((w) => w.path.endsWith('/attention-acknowledgements') && w.body.acknowledged === false && (!target || w.target === target)); + } + + /** Tells the page something changed, as the server's change feed does, so it reads again. */ + notify(topic: 'runs' | 'all' = 'runs') { + this.#notices.push(topic); + } + + /** A new scheduler outage: the lease that ran out is a new one. */ + stopScheduler() { + this.#lease = new Date().toISOString(); + for (const t of Object.values(this.targets)) t.schedulerLeader = false; + } + + async install(page: Page) { + // The first location is the one the page opens on. + await page.addInitScript(() => localStorage.clear()); + await page.route('**/api/**', (route) => this.#answer(route)); + } + + async #answer(route: Route) { + const request = route.request(); + const url = new URL(request.url()); + const path = url.pathname; + if (path === '/api/control/bootstrap') { + return json(route, { + login_mode: 'disabled', + access: { + principal_id: '0190d1a0-0000-7000-8000-0000000000bb', + name: 'tester', + actions: ACTIONS, + locations: (Object.keys(LOCATIONS) as TargetName[]).map((name) => ({ location_id: LOCATIONS[name], name, target: 'dev', actions: ACTIONS })) + } + }); + } + if (path === '/api/control/platform/problems') { + // Answered as things stood when the request arrived, however long the reply takes. + const answer = { scheduler_leader: Object.values(this.targets).every((t) => t.schedulerLeader), scheduler_lease_expires_at: this.#lease, broken_locations: [], overdue_ticks: [], low_calendars: [] }; + const delay = Math.max(...Object.values(this.targets).map((t) => t.readDelayMs)); + if (delay) await later(delay); + return json(route, answer); + } + const scoped = /^\/api\/control\/locations\/([^/]+)\/targets\/dev\/(.+)$/.exec(path); + const name = scoped && (Object.keys(LOCATIONS) as TargetName[]).find((n) => LOCATIONS[n] === scoped[1]); + if (!scoped || !name) return json(route, { error: 'not found' }, 404); + const target = this.targets[name]; + const rest = scoped[2]; + if (rest === 'changes') { + const events = this.#notices.splice(0).map((topic) => `event: changed\ndata: ${JSON.stringify({ topic })}\n\n`); + return route.fulfill({ status: 200, contentType: 'text/event-stream', body: `retry: 200\n\n${events.join('')}` }); + } + if (request.method() === 'POST') return this.#write(route, name, rest, request.postDataJSON() as Record); + if (rest === 'health') { + if (target.healthDelayMs) await later(target.healthDelayMs); + return json(route, this.#health(target)); + } + if (rest === 'nodes') return json(route, MODELS.map((m) => ({ ...this.#node(target, m), node_key: `model:${m}`, kind: 'model', name: m, path: `models/shop/${m}.sql`, materialization: 'table', description: null, tags: [], dependencies: [], relation: { database: null, schema: 'dev', name: m }, column_count: 3, snapshot_id: SNAPSHOT }))); + if (rest === 'node-states') { + // A new version whenever the states differ, as the server numbers them, so the page takes them. + const states = Object.fromEntries(MODELS.map((m) => [`model:${m}`, this.#node(target, m)])); + const seen = JSON.stringify(states); + if (seen !== this.#states[name].seen) this.#states[name] = { seen, version: this.#states[name].version + 1 }; + return json(route, { snapshot_id: SNAPSHOT, version: this.#states[name].version, states }); + } + if (rest.startsWith('snapshots')) return json(route, [{ snapshot_id: SNAPSHOT, generation: 1, git_revision: null, git_dirty: false, git_author: null, environment_hash: 'e'.repeat(64), sqb_version: '0.0.0', published_at: '2026-11-01T00:00:00Z', changes: [], connection: null }]); + if (rest === 'jobs' || rest === 'triggers' || rest === 'checks' || rest === 'acknowledgements') return json(route, []); + if (rest.startsWith('cost')) return json(route, { since: '2026-11-01T00:00:00Z', credits: 0, usd: null, runs: 0, incomplete_runs: 0, by_job: [], by_warehouse_size: [], by_node: [] }); + // The Overview's own reads: answered as things stood when the request arrived, then slowed or + // refused as the test asks. + const reading = rest === 'attention-acknowledgements'; + if (reading) this.reads[name].started += 1; + const failed = target.failReads; + const answer = rest.startsWith('runs') + ? target.failedRun ? [this.#failedRun(name)] : [] + : reading + ? { snooze_seconds: 86_400, acknowledgements: target.acks.map((a) => ({ ...a, acknowledged_by: 'tester', until: new Date(Date.parse(a.acknowledged_at) + 86_400_000).toISOString() })) } + : null; + if (target.readDelayMs) await later(target.readDelayMs); + const reply = failed ? json(route, { error: 'the control store is unavailable' }, 500) : answer === null ? json(route, { error: 'not found' }, 404) : json(route, answer); + await reply; + if (reading) this.reads[name].answered += 1; + return; + } + + #write(route: Route, name: TargetName, rest: string, body: Record) { + const target = this.targets[name]; + const record = (status: number) => this.writes.push({ target: name, path: rest.startsWith('/') ? rest : `/${rest}`, body, status }); + if (rest !== 'attention-acknowledgements') { + record(200); + return json(route, { applied: true }); + } + if (!body.acknowledged && target.failWithdrawals) { + record(500); + return json(route, { error: 'the control store is unavailable' }, 500); + } + record(200); + const latest = target.acks.find((a) => a.key === body.key); + if (body.acknowledged) { + target.acks = [...target.acks.filter((a) => a.key !== body.key), { event_id: String(body.event_id), key: String(body.key), shape: body.shape, acknowledged_at: new Date().toISOString() }]; + return json(route, { applied: true }); + } + // As the server: a withdrawal naming an acknowledgement applies only while that one is the latest. + const applies = !!latest && (body.withdraws === undefined || body.withdraws === latest.event_id); + if (applies) target.acks = target.acks.filter((a) => a.key !== body.key); + return json(route, { applied: applies }); + } + + #node(target: TargetState, model: string) { + const builtAt = '2026-11-01T00:00:00Z'; + return { + last_build: { observed_at: builtAt, run_id: 'build-1', version_hash: 'f'.repeat(64) }, + last_outcome: { status: 'success', at: builtAt, run_id: '0190d1a0-0000-7000-8000-0000000000cc' }, + definition_changed: target.changed.includes(model), + checks: { total: 0, passing: 0, warning: 0, failing: 0 } + }; + } + + #health(target: TargetState) { + const at = new Date().toISOString(); + const health = { + kind: 'warehouse_sync', + generation: 1, + location: { database: null, schema: 'dev' }, + table: 'catalog', + failure: target.sync === 'failed' ? 'read' : null, + records_sent: 5, + elapsed_millis: 10, + progress: { position: target.sync === 'running' ? 1 : 2, kinds: 2, rows: 5, elapsed_millis: 20, completed: target.sync !== 'running' } + }; + return [{ received_at: at, report: { event_id: '0190d1a0-0000-7000-8000-0000000000dd', session_id: '0190d1a0-0000-7000-8000-0000000000ee', target: 'dev', health } }]; + } + + #failedRun(name: TargetName) { + const at = new Date(Date.now() - 600_000).toISOString(); + const id = '0190d1a0-0000-7000-8000-0000000000f1'; + return { + run_id: id, location_id: LOCATIONS[name], target: 'dev', snapshot_id: SNAPSHOT, snapshot_generation: 1, git_revision: null, git_dirty: false, sqb_version: '0.0.0', image_id: null, + job_key: null, kind: 'adhoc', origin: 'manual', parent_run_id: null, root_run_id: id, trigger_id: null, trigger_name: null, tick_id: null, rerun_of_run_id: null, + requested_by: 'principal:tester', requester_name: 'tester', priority: 0, rewrite_history: false, status: 'failed', status_reason: 'a node failed', + queued_at: at, launched_at: at, started_at: at, ended_at: at, cancel_requested_at: null, selection_json: ['model:orders'], node_counts_json: { failed: 1 }, + ignored_audit_failures: 0, last_event_storage_id: 1, narrowing: null + }; + } +} diff --git a/ui/src/lib/api/client.ts b/ui/src/lib/api/client.ts index eda383756c..1ad1115920 100644 --- a/ui/src/lib/api/client.ts +++ b/ui/src/lib/api/client.ts @@ -34,6 +34,8 @@ import type { IgnoredAuditFailure, RunCostRow, CostSummary, + AutomaticWithdrawal, + ConditionShape, NodeBuildCost, NodeStates, Snapshot, @@ -129,6 +131,9 @@ export interface ApiClient extends PlatformApi { timeline(scope: Scope, window: { since: string; until: string }): Promise; /** Marks a run handled for everyone who can see it, or withdraws the mark; recorded in the audit log. */ acknowledgeRun(scope: Scope, runId: string, acknowledged: boolean): Promise; + /** Acknowledge an ongoing condition as it looks now (`shape`), until it changes, or withdraw that. */ + /** `automatic` withdraws one acknowledgement, which the server applies only while it is still the latest. */ + acknowledgeCondition(scope: Scope, key: string, shape: ConditionShape, acknowledged: boolean, automatic?: AutomaticWithdrawal): Promise; /** Writes a `cancel_requested` fact; the scheduler then signals the worker. */ cancelRun(scope: Scope, runId: string): Promise; /** `nodes` is required for `selected` and ignored otherwise. */ diff --git a/ui/src/lib/api/http-client.test.ts b/ui/src/lib/api/http-client.test.ts index bbbb9f87c1..de0997249a 100644 --- a/ui/src/lib/api/http-client.test.ts +++ b/ui/src/lib/api/http-client.test.ts @@ -407,6 +407,7 @@ describe('overview', () => { const path = new URL(request.url).pathname; if (path.endsWith('/nodes') && nodesStatus !== 200) return Response.json({ error: 'refused' }, { status: nodesStatus }); if (path.endsWith('/platform/problems')) return Response.json({ scheduler_leader: 'server-1', scheduler_lease_expires_at: null, broken_locations: [], overdue_ticks: [] }); + if (path.endsWith('/attention-acknowledgements')) return Response.json({ snooze_seconds: 86_400, acknowledgements: [] }); return Response.json([]); }) ); diff --git a/ui/src/lib/api/http-client.ts b/ui/src/lib/api/http-client.ts index 9b700e1400..3568a3b147 100644 --- a/ui/src/lib/api/http-client.ts +++ b/ui/src/lib/api/http-client.ts @@ -21,7 +21,7 @@ import { toSelectionEvaluation, toSelectionVocabulary } from './http-selection'; import type { ChangeSubscription, ChangedChannel, ChangedSignal, ConnectionState } from './signals'; import type { AuthMode, Bootstrap, Capability, Location, NavCounts, PlatformEvent, Scope, Snapshot, WarehouseSync } from './types'; import type { Account, AuditEntry, AuditQuery, ConnectionTest, LocationDetail, ServerSettings, WarehouseConnection, LocationSummary, PlatformEventQuery, PlatformEventRecord, PlatformHealth, MaintenanceHistory, ProviderConnection, RoleAssignment, RoleAssignmentRequest, RoleDefinition, RoleDetail } from './types/platform'; -import type { Acknowledgement, CatalogNode, CatalogNodeDetail, Check, CheckDetail, CheckEvidence, CheckSql, NodeStates, NodeStatusDelta, Overview, SnapshotChange, ColumnLineage } from './types/build'; +import type { Acknowledgement, CatalogNode, CatalogNodeDetail, Check, CheckDetail, CheckEvidence, CheckSql, NodeStates, NodeStatusDelta, Overview, SnapshotChange, ColumnLineage, AttentionAcknowledgement, ConditionShape, AutomaticWithdrawal } from './types/build'; import type { AdhocRunCheck, AdhocRunRequest, BulkRunResult, SelectionEvaluation, SelectionRequest, SelectionVocabulary, PlanDiff, PlanPage, PlanPageSection, PlanResult, QueueEntry, Timeline, Job, JobDetail, JobLaunchOptions, RerunMode, SnapshotNode, Run, RunDetail, RunListQuery, RunRowPage, RunRowQuery, RunTabCounts, Trigger, TriggerDetail, TriggerState, RunEventPage, RunNodeError, RunOutputLine, RunStatement, IgnoredAuditFailure, RunCostRow, CostSummary, NodeBuildCost, StatementSql } from './types/operate'; import { newRequestId } from '$lib/browser/request-id'; @@ -51,6 +51,7 @@ const SUPPORTED: ReadonlySet = new Set([ 'listRunOutput', 'getRunNodeError', 'acknowledgeRun', + 'acknowledgeCondition', 'cancelRun', 'cancelMatchingRuns', 'rerunRun', @@ -509,6 +510,15 @@ export function createHttpClient({ baseUrl = '', onUnauthorized, fetch: answer, if (response.status === 401) onUnauthorized(); if (!response.ok) throw new ApiError(errorText(error, response), response.status); }, + async acknowledgeCondition(scope: Scope, key: string, shape: ConditionShape, acknowledged: boolean, automatic?: AutomaticWithdrawal): Promise { + const { locationId, target } = parseLocationKey(scope.locationId); + const { error, response } = await http.POST('/api/control/locations/{location_id}/targets/{target}/attention-acknowledgements', { + body: { event_id: automatic?.eventId ?? newRequestId(), key, shape, acknowledged, ...(automatic ? { reason: automatic.reason, withdraws: automatic.withdraws } : {}) }, + params: { path: { location_id: locationId, target }, header: { 'x-sqb-csrf': csrfToken(document.cookie) } } + }); + if (response.status === 401) onUnauthorized(); + if (!response.ok) throw new ApiError(errorText(error, response), response.status); + }, async rerunRun(scope: Scope, runId: string, mode: Exclude): Promise { const source = await requireRun(scope, runId); const body = { run_id: newRequestId(), source_run_id: runId, from_failure: mode === 'from_failure', priority: source.priority, reason: 'Rerun from the web UI' }; @@ -856,7 +866,8 @@ export function createHttpClient({ baseUrl = '', onUnauthorized, fetch: answer, listing ?? implemented.listCatalogNodes(scope), implemented.listSnapshotChanges(scope, { limit: 100 }), implemented.listPlatformEvents(), - acknowledgementsOf(scope) + acknowledgementsOf(scope), + attentionAcknowledgementsOf(scope) ]); // Every listing needs view on all of the target, so a partial viewer gets no counts at all. const read = await reads.catch((error: unknown) => { @@ -864,8 +875,8 @@ export function createHttpClient({ baseUrl = '', onUnauthorized, fetch: answer, throw error; }); if (!read) return null; - const [runs, checks, nodes, changes, events, acknowledgements] = read; - return overviewOf({ runs, checks, nodes, changes, events, acknowledgements, now: Date.now() }); + const [runs, checks, nodes, changes, events, acknowledgements, conditions] = read; + return overviewOf({ runs, checks, nodes, changes, events, acknowledgements, conditions, now: Date.now(), scopeKey: scope.locationId }); }, listChecks: async (scope: Scope): Promise => (await checkResults(scope)).map(toCheck), getCheck: async (scope: Scope, id: string): Promise => checkDetailOf(await checkResults(scope, id)), @@ -1132,6 +1143,21 @@ export function createHttpClient({ baseUrl = '', onUnauthorized, fetch: answer, return new Map(data.map((a) => [a.run_id, { by: a.acknowledged_by, at: a.acknowledged_at }])); } + /** Conditions marked handled within two snoozes, lapsed ones included, and the snooze; none from a server or recording without them. */ + async function attentionAcknowledgementsOf(scope: Scope): Promise<{ snoozeSeconds: number | null | undefined; acknowledgements: AttentionAcknowledgement[] }> { + const { locationId, target } = parseLocationKey(scope.locationId); + const { data, error, response } = await http.GET('/api/control/locations/{location_id}/targets/{target}/attention-acknowledgements', { + params: { path: { location_id: locationId, target } } + }); + if (response.status === 401) onUnauthorized(); + if (response.status === 404) return { snoozeSeconds: undefined, acknowledgements: [] }; + if (!data) throw new ApiError(errorText(error, response), response.status); + return { + snoozeSeconds: data.snooze_seconds ?? null, + acknowledgements: data.acknowledgements.map((a) => ({ eventId: a.event_id, key: a.key, shape: a.shape as ConditionShape, by: a.acknowledged_by, at: a.acknowledged_at, until: a.until ?? null })) + }; + } + /** Triggers with their latest tick and the newest listed run each started. */ async function triggersOf(scope: Scope): Promise { const [wires, runs] = await Promise.all([listedTriggers(scope), recentRuns(scope)]); diff --git a/ui/src/lib/api/http-overview.test.ts b/ui/src/lib/api/http-overview.test.ts index 83f0766e05..57ad0bd910 100644 --- a/ui/src/lib/api/http-overview.test.ts +++ b/ui/src/lib/api/http-overview.test.ts @@ -52,6 +52,7 @@ describe('overview from live reads', () => { changes: [change(1, [['added', 'model:orders'], ['added', 'seed:regions'], ['removed', 'model:old']]), change(24 * 8, [['added', 'model:totals']])], events: [event('scheduler', true), event('cleared', false)], acknowledgements: new Map([['orders-new', { by: 'ada', at: hoursAgo(1) }]]), + conditions: { snoozeSeconds: 86_400, acknowledgements: [] }, scopeKey: 'loc-1:dev', now }); @@ -95,12 +96,14 @@ describe('overview from live reads', () => { it('counts each stale node once, and leaves late sources unknown', () => { expect(overview.metrics.stale).toEqual({ nodes: 2, changed: 1, behind: 2, sources: null }); - expect(overview.attention.find((i) => i.kind === 'stale_models')).toEqual({ kind: 'stale_models', changed: ['model:orders'], behind: ['model:orders', 'model:events'] }); + expect(overview.attention.find((i) => i.kind === 'stale_models')).toMatchObject({ kind: 'stale_models', changed: ['model:orders'], behind: ['model:orders', 'model:events'] }); + // An ongoing condition, which can be acknowledged until it changes; no acknowledgement is listed. + expect(overview.attention.find((i) => i.kind === 'stale_models')).toMatchObject({ condition: { key: 'stale_models', shape: { counts: { changed: 1, behind: 2 } }, acknowledged: null, lapsed: null } }); }); it('leaves parts without a server read empty instead of zero', () => { expect(overview.metrics.cost).toBeNull(); - const unknown = overviewOf({ runs: [], checks: [], nodes: [{ ...node('model:a', 'table', 'models/a.sql'), stale: null }], changes: [], events: [], acknowledgements: new Map(), now }); + const unknown = overviewOf({ runs: [], checks: [], nodes: [{ ...node('model:a', 'table', 'models/a.sql'), stale: null }], changes: [], events: [], acknowledgements: new Map(), conditions: { snoozeSeconds: 86_400, acknowledgements: [] }, scopeKey: 'loc-1:dev', now }); expect(unknown.groups).toBeNull(); }); }); diff --git a/ui/src/lib/api/http-overview.ts b/ui/src/lib/api/http-overview.ts index 56f25a02c4..053b4d6906 100644 --- a/ui/src/lib/api/http-overview.ts +++ b/ui/src/lib/api/http-overview.ts @@ -1,7 +1,8 @@ import { topFolder } from '$lib/lineage/catalog-graph'; import { recentDeploys } from '$lib/build-area/overview-panels'; +import { clearedAcknowledgements, visibleEventKey, withConditions } from '$lib/build-area/attention-conditions'; import { checkCountsOf } from './http-catalog'; -import type { Acknowledgement, AttentionItem, AttentionRun, CatalogNode, Check, GroupStatus, Overview, PlatformEvent, Run, SnapshotChange } from './types'; +import type { Acknowledgement, AttentionAcknowledgement, AttentionItem, AttentionRun, CatalogNode, Check, GroupStatus, Overview, PlatformEvent, Run, SnapshotChange } from './types'; const DAY = 24 * 60 * 60 * 1000; const MODEL_KINDS = new Set(['view', 'table', 'incremental']); @@ -18,6 +19,10 @@ export type OverviewInputs = { events: PlatformEvent[]; /** Problem runs marked handled, by run ID. */ acknowledgements: Map; + /** The location key (`:`) the read was for. */ + scopeKey: string; + /** Conditions' latest acknowledgements, and the server's snooze (undefined from a server without it). */ + conditions: { snoozeSeconds: number | null | undefined; acknowledgements: AttentionAcknowledgement[] }; now: number; }; @@ -65,7 +70,7 @@ export function groupStatusOf(nodes: CatalogNode[]): GroupStatus[] { * does not check source freshness, so late sources stay unknown. Groups are top-level folders, and * group status is null when the server reports no build state. There is no cost read, so the page hides cost. */ -export function overviewOf({ runs, checks, nodes, changes, events, acknowledgements, now }: OverviewInputs): Overview { +export function overviewOf({ runs, checks, nodes, changes, events, acknowledgements, conditions, now, scopeKey }: OverviewInputs): Overview { const acknowledged = (r: Run) => acknowledgements.get(r.id) ?? null; const topLevel = runs.filter((r) => !r.parentRunId); const recent = topLevel.filter((r) => Date.parse(r.queuedAt) >= now - DAY); @@ -103,7 +108,13 @@ export function overviewOf({ runs, checks, nodes, changes, events, acknowledgeme stale: { nodes: staleNodes, changed: changed.length, behind: behind.length, sources: null }, cost: null }, - attention, + attention: withConditions(attention, conditions.acknowledgements, now), + attentionSnoozeSeconds: conditions.snoozeSeconds, + // Nodes out of date are seen only with build state; late sources aren't checked here. Every viewer + // sees the scheduler, but other problems only for targets they may view, so only this target's count. + clearedAcknowledgements: clearedAcknowledgements(attention, conditions.acknowledgements, (key) => + key === 'stale_models' ? nodes.some((n) => n.stale !== null) : visibleEventKey(key, scopeKey) + ), groups: nodes.some((n) => n.stale !== null) ? groupStatusOf(nodes) : null, recentChanges: recentDeploys(changes), latestRun: latest ? { id: latest.id, status: latest.status, endedAt: latest.endedAt } : null diff --git a/ui/src/lib/api/http-problems.ts b/ui/src/lib/api/http-problems.ts index 4c24b27d0d..3e1a431e01 100644 --- a/ui/src/lib/api/http-problems.ts +++ b/ui/src/lib/api/http-problems.ts @@ -16,6 +16,8 @@ export function toPlatformEvents(problems: Wire['PlatformProblems'], now: number kind: 'scheduler_no_leader', severity: 'critical', occurredAt: problems.scheduler_lease_expires_at ?? new Date(now).toISOString(), + // The lease that ran out tells one leaderless outage from the next. + occurrence: problems.scheduler_lease_expires_at ?? undefined, active: true, locationId: null, subject: null, @@ -28,6 +30,8 @@ export function toPlatformEvents(problems: Wire['PlatformProblems'], now: number kind: 'location_broken', severity: 'critical', occurredAt: location.last_seen_at, + // Its last check-in tells one outage from the next. + occurrence: location.last_seen_at, active: true, locationId: keyOf(location.location_id, location.target), subject: placeOf(location.location_name, location.target), @@ -47,6 +51,7 @@ export function toPlatformEvents(problems: Wire['PlatformProblems'], now: number kind: 'tick_overdue', severity: 'warning', occurredAt: oldest.scheduled_for, + members: [...new Set(ticks.map((t) => t.trigger_id))].sort(), active: true, locationId: key, subject: place, @@ -68,6 +73,7 @@ export function toPlatformEvents(problems: Wire['PlatformProblems'], now: number kind: 'calendar_horizon_low', severity: 'warning', occurredAt: ends(soonest), + members: [...new Set(calendars.map((c) => c.trigger_id))].sort(), active: true, locationId: key, subject: place, diff --git a/ui/src/lib/api/index.ts b/ui/src/lib/api/index.ts index ac21520d39..b08cbfc48d 100644 --- a/ui/src/lib/api/index.ts +++ b/ui/src/lib/api/index.ts @@ -2,6 +2,7 @@ import type { ApiClient } from './client'; import { createHttpClient } from './http-client'; import { MockApiClient, type MockOptions } from './mock/mock-client'; import { largeProject } from './mock/large-project'; +import { hugeProject } from './mock/huge-project'; import { awkward } from './mock/awkward'; import { replayFetch, type Recording } from './replay'; import { LocalChangeBus } from './signals'; @@ -36,8 +37,9 @@ async function loadRecording(): Promise { * The client the app uses: the server, or the mock with `?mock` or `VITE_SQB_MOCK=1`. * With the mock, `?as=`, `?events=none|all` and `?live=reconnecting|offline` * adjust it for demos, `?awkward` stretches every list to thousands of rows with very long - * names, for the layout test, `?large` swaps in a catalog the size of a real project, and `?still` - * keeps runs from advancing on their own. + * names, for the layout test, `?large` swaps in a catalog the size of a real project, `?huge` one + * of about 10,000 nodes in nested folders, for the Overview's and the folder view's performance budgets, + * and `?still` keeps runs from advancing on their own. */ export function createClient(search: URLSearchParams, onUnauthorized: () => void = () => {}): ApiClient { if (DEMO) return createHttpClient({ onUnauthorized, fetch: replayFetch(loadRecording), changes: new LocalChangeBus() }); @@ -51,7 +53,7 @@ export function createClient(search: URLSearchParams, onUnauthorized: () => void connection: LIVE.find((l) => l === live), still: search.has('still') }); - const sized = search.has('large') ? largeProject(mock) : mock; + const sized = search.has('huge') ? hugeProject(mock) : search.has('large') ? largeProject(mock) : mock; return countedReads(search.has('awkward') ? awkward(sized) : sized); } diff --git a/ui/src/lib/api/mock/build.ts b/ui/src/lib/api/mock/build.ts index d34e2c7725..b0d7040d99 100644 --- a/ui/src/lib/api/mock/build.ts +++ b/ui/src/lib/api/mock/build.ts @@ -5,6 +5,7 @@ import { ApiError } from '../client'; import { groupStatusOf, problemRunsOf } from '../http-overview'; +import { clearedAcknowledgements, withConditions } from '$lib/build-area/attention-conditions'; import { recentDeploys } from '$lib/build-area/overview-panels'; import type { AttentionItem, @@ -301,7 +302,10 @@ export class MockBuild { // The mock holds one day of costed runs; the server's baseline is the rolling average of the same window. cost: cost === null ? null : { last24h: round(cost), baseline: round(cost * 0.78), baselineDays: 7, unit: 'credits' } }, - attention, + attention: withConditions(attention, this.#ctx.operate.conditionAcknowledgements(), now), + attentionSnoozeSeconds: 86_400, + // The mock holds every condition, so it sees them all. + clearedAcknowledgements: clearedAcknowledgements(attention, this.#ctx.operate.conditionAcknowledgements(), () => true), groups: groupStatusOf(nodes), recentChanges: recentDeploys(this.#changes(scope)), latestRun: latest ? { id: latest.id, status: latest.status, endedAt: latest.endedAt } : null diff --git a/ui/src/lib/api/mock/huge-project.ts b/ui/src/lib/api/mock/huge-project.ts new file mode 100644 index 0000000000..dd8a70e41d --- /dev/null +++ b/ui/src/lib/api/mock/huge-project.ts @@ -0,0 +1,78 @@ +// A project of about 10,000 nodes, for the performance budgets of the Overview and the catalog's folder +// view: 40 top-level folders, each with five subfolders, some of those with their own, and most folders +// with something changed, behind or failed. Turned on with `?mock&huge`. Pure apart from wrapping the +// client it is given. + +import type { ApiClient } from '../client'; +import { groupStatusOf } from '../http-overview'; +import { withConditions } from '$lib/build-area/attention-conditions'; +import type { AttentionAcknowledgement, AttentionItem, CatalogNode, Overview, StaleReason } from '../types'; + +const FOLDERS = [ + 'analytics', 'billing', 'catalog_data', 'customers', 'exports', 'finance', 'forecasting', 'fulfilment', 'inventory', 'marketing', + 'orders', 'partners', 'payments', 'pricing', 'reference', 'regions', 'returns', 'sales', 'shipping', 'support', + 'suppliers', 'subscriptions', 'reviews', 'warehouses', 'logistics', 'promotions', 'loyalty', 'accounts', 'invoices', 'refunds', + 'tax', 'audit', 'search', 'sessions', 'devices', 'campaigns', 'channels', 'carriers', 'stores', 'staff' +]; +const SUBFOLDERS = ['staging', 'intermediate/cleaned', 'intermediate/joined', 'marts', 'reports']; +const NOUNS = ['events', 'daily_totals', 'snapshot', 'latest', 'history', 'summary', 'mapped', 'enriched', 'keys', 'lookup', 'rollup', 'changes']; +const PER_FOLDER = 50; + +const since = '2026-11-01T00:00:00Z'; +const changed: StaleReason = { reason: 'changed', change: 'definition', detail: 'Its definition changed since its last build', since }; +const behind: StaleReason = { reason: 'behind', upstream: [], detail: 'Upstream data is newer than its last build', since }; + +/** The huge project's nodes, copies of `template`; deterministic. */ +export function hugeProjectNodes(template: CatalogNode): CatalogNode[] { + const nodes: CatalogNode[] = []; + FOLDERS.forEach((folder, f) => + SUBFOLDERS.forEach((sub, s) => { + for (let i = 0; i < PER_FOLDER; i++) { + const key = `${folder}__${sub.replace('/', '__')}__${NOUNS[i % NOUNS.length]}_${i}`; + const healthy = f % 3 === 2; + const stale: StaleReason[] = []; + if (!healthy && (i + s + f) % 9 === 0) stale.push(behind); + if (!healthy && (i * 7 + f) % 23 === 1) stale.push(changed); + nodes.push({ + ...template, + key, + kind: 'table', + group: null, + path: `models/${folder}/${sub}/${key}.sql`, + upstream: [], + description: `${folder} ${sub.replace('/', ' ')} ${NOUNS[i % NOUNS.length]}`, + stale, + lastOutcome: !healthy && i === 3 && s === f % 5 ? 'failed' : 'success' + }); + } + }) + ); + return nodes; +} + +/** The client with its catalog, and the Overview built from it, replaced by the huge project. */ +export function hugeProject(client: ApiClient): ApiClient { + let held: Promise | null = null; + const project = (scope: Parameters[0]) => + (held ??= client.listCatalogNodes(scope).then((real) => hugeProjectNodes(real.find((n) => n.kind === 'table' && n.lastBuild) ?? real[0]))); + return new Proxy(client, { + get(target, prop, receiver) { + if (prop === 'listCatalogNodes') return project; + if (prop === 'overview') { + return async (...args: Parameters): Promise => { + const [base, nodes] = await Promise.all([target.overview(...args), project(args[0])]); + if (!base) return base; + const keys = (test: (s: StaleReason) => boolean) => nodes.filter((n) => n.stale?.some(test)).map((n) => n.key); + // The nodes out of date are the huge project's, so their condition is worked out again for them. + const held = 'mockConditionAcknowledgements' in target ? (target as { mockConditionAcknowledgements(): AttentionAcknowledgement[] }).mockConditionAcknowledgements() : []; + const attention = base.attention.map((item): AttentionItem => + item.kind === 'stale_models' ? withConditions([{ kind: 'stale_models', changed: keys((s) => s.reason !== 'behind'), behind: keys((s) => s.reason === 'behind') }], held, Date.now())[0] : item + ); + return { ...base, attention, groups: groupStatusOf(nodes) }; + }; + } + const value = Reflect.get(target, prop, receiver); + return typeof value === 'function' ? value.bind(target) : value; + } + }); +} diff --git a/ui/src/lib/api/mock/large-project.ts b/ui/src/lib/api/mock/large-project.ts index 835face93c..d4fa7a7c74 100644 --- a/ui/src/lib/api/mock/large-project.ts +++ b/ui/src/lib/api/mock/large-project.ts @@ -77,6 +77,17 @@ export function largeProject(client: ApiClient): ApiClient { return planModelDiff(doc, model); }; } + // Folder links select `path:`, which the large project answers from its own nodes. + if (prop === 'evaluateSelection') { + return async (...[scope, request]: Parameters) => { + const paths = request.select.split(/\s+/).filter((t) => t.startsWith('path:')).map((t) => t.slice(5).replace(/\/$/, '')); + if (!paths.length || request.select.split(/\s+/).some((t) => t && !t.startsWith('path:')) || request.exclude.trim()) return target.evaluateSelection(scope, request); + const real = await target.listCatalogNodes(scope); + const template = real.find((n) => n.kind === 'table') ?? real[0]; + const keys = largeProjectNodes(template).filter((n) => paths.some((p) => n.path.startsWith(`${p}/`))).map((n) => n.key).sort(); + return { snapshotId: null, count: keys.length, keys, nextOffset: null, error: null }; + }; + } if (prop !== 'listCatalogNodes') return typeof value === 'function' ? value.bind(target) : value; return async (...args: Parameters) => { const real = await target.listCatalogNodes(...args); diff --git a/ui/src/lib/api/mock/mock-client.ts b/ui/src/lib/api/mock/mock-client.ts index 2a95b83540..0b1881a4ec 100644 --- a/ui/src/lib/api/mock/mock-client.ts +++ b/ui/src/lib/api/mock/mock-client.ts @@ -5,6 +5,9 @@ import { LocalChangeBus, type ConnectionState } from '../signals'; import { stateOf } from '../node-states'; import type { AdhocRunCheck, + AttentionAcknowledgement, + AutomaticWithdrawal, + ConditionShape, SelectionEvaluation, SelectionRequest, SelectionVocabulary, @@ -318,6 +321,16 @@ export class MockApiClient implements ApiClient { this.#operate.acknowledgeRun(runId, acknowledged, 'you'); } + /** The conditions' acknowledgements the mock holds, for wrappers that replace a condition, such as the huge project. */ + mockConditionAcknowledgements(): AttentionAcknowledgement[] { + return this.#operate.conditionAcknowledgements(); + } + + async acknowledgeCondition(scope: Scope, key: string, shape: ConditionShape, acknowledged: boolean, automatic?: AutomaticWithdrawal): Promise { + this.#location(scope); + this.#operate.acknowledgeCondition(key, shape, acknowledged, 'you', automatic?.withdraws); + } + async rerunRun(scope: Scope, runId: string, mode: Exclude): Promise { this.#location(scope); return this.#operate.rerunRun(scope, runId, mode); diff --git a/ui/src/lib/api/mock/operate-store.ts b/ui/src/lib/api/mock/operate-store.ts index 542cfb6100..f8780ead55 100644 --- a/ui/src/lib/api/mock/operate-store.ts +++ b/ui/src/lib/api/mock/operate-store.ts @@ -9,6 +9,8 @@ import type { LocalChangeBus } from '../signals'; import { memberLinks, pairKey } from '$lib/lineage/member-graph'; import type { Acknowledgement, + AttentionAcknowledgement, + ConditionShape, CatalogNode, WaitReason, AdhocPermission, @@ -57,6 +59,7 @@ import type { TriggerState, TriggerStateEvent } from '../types'; +import { newRequestId } from '$lib/browser/request-id'; import { serverLimitOf, IMAGE_ID, @@ -846,9 +849,25 @@ export class MockOperate { /** Problem runs marked handled, by run ID. */ #acknowledgements = new Map(); + #conditionAcks = new Map(); acknowledgement(runId: string): Acknowledgement | null { return this.#acknowledgements.get(runId) ?? null; } + /** Conditions' latest acknowledgements, as the server lists them. */ + conditionAcknowledgements(): AttentionAcknowledgement[] { + return [...this.#conditionAcks.values()]; + } + /** As the server: holds for 24 hours, and acknowledging the same shape again while it holds changes nothing. */ + acknowledgeCondition(key: string, shape: ConditionShape, acknowledged: boolean, by: string, withdraws?: string): void { + if (!acknowledged) { + if (withdraws === undefined || this.#conditionAcks.get(key)?.eventId === withdraws) this.#conditionAcks.delete(key); + return; + } + const held = this.#conditionAcks.get(key); + const now = Date.now(); + if (held && JSON.stringify(held.shape) === JSON.stringify(shape) && (held.until === null || now < Date.parse(held.until))) return; + this.#conditionAcks.set(key, { eventId: newRequestId(), key, shape, by, at: new Date(now).toISOString(), until: new Date(now + 86_400_000).toISOString() }); + } acknowledgeRun(runId: string, acknowledged: boolean, by: string): void { if (acknowledged) this.#acknowledgements.set(runId, { by, at: new Date().toISOString() }); else this.#acknowledgements.delete(runId); diff --git a/ui/src/lib/api/types.ts b/ui/src/lib/api/types.ts index 9aef3bcd9b..097c4954d1 100644 --- a/ui/src/lib/api/types.ts +++ b/ui/src/lib/api/types.ts @@ -138,6 +138,13 @@ export type PlatformEvent = { locationId: string | null; subject: string | null; message: string; + /** What a grouped event holds, such as the IDs of a location's late schedules; a new one makes it worse. */ + members?: string[]; + /** + * Tells one occurrence of an ongoing problem from the next when `id` is fixed per problem, such as a + * stopped scheduler's expired lease or a broken location's last check-in. + */ + occurrence?: string; }; // ---- navigation ---- diff --git a/ui/src/lib/api/types/build.ts b/ui/src/lib/api/types/build.ts index 43a32d1a54..a9e7da26be 100644 --- a/ui/src/lib/api/types/build.ts +++ b/ui/src/lib/api/types/build.ts @@ -374,14 +374,39 @@ export type AttentionRun = Pick; + /** Members that make it worse when a new one appears, such as `:`. */ + members?: string[]; + /** Severity, least first; a higher one is worse. */ + severity?: number; + /** Which occurrence it is: a different one means it resolved and came back. */ + occurrence?: string; +}; +/** A condition's latest acknowledgement, as the server lists it; `until` is when it lapses even unchanged, null without a time limit. */ +export type AttentionAcknowledgement = { eventId: string; key: string; shape: ConditionShape; by: string; at: Iso; until: Iso | null }; +/** A withdrawal the Overview makes itself: its event ID, why, and the acknowledgement event it withdraws. */ +export type AutomaticWithdrawal = { eventId: string; reason: string; withdraws: string }; +/** An ongoing condition on the attention list, acknowledged until it changes. */ +export type AttentionCondition = { + /** Its kind and subject, stable while it lasts, such as `stale_sources`. */ + key: string; + shape: ConditionShape; + /** Holds until the condition gets worse, resolves and comes back, or `until` passes (null: no time limit). */ + acknowledged: (Acknowledgement & { until: Iso | null }) | null; + /** Why an acknowledgement no longer holds, while the condition is back on the list. */ + lapsed: { reason: string; by: string; at: Iso } | null; +}; export type AttentionItem = | { kind: 'run_problem'; run: AttentionRun; acknowledged: Acknowledgement | null } | { kind: 'run_unresponsive'; run: AttentionRun; lastHeartbeatAt: Iso | null; acknowledged: Acknowledgement | null } - | { kind: 'stale_models'; changed: string[]; behind: string[] } - | { kind: 'stale_sources'; sources: ({ key: string } & SourceFreshness)[] } - | { kind: 'platform_event'; event: PlatformEvent } - | { kind: 'queue_blocked'; runId: string; jobKey: string | null; queuedAt: Iso; waits: QueueWait[] } - | { kind: 'calendar_low'; triggerId: string; triggerName: string; detail: string }; + | { kind: 'stale_models'; changed: string[]; behind: string[]; condition?: AttentionCondition } + | { kind: 'stale_sources'; sources: ({ key: string } & SourceFreshness)[]; condition?: AttentionCondition } + | { kind: 'platform_event'; event: PlatformEvent; condition?: AttentionCondition } + | { kind: 'queue_blocked'; runId: string; jobKey: string | null; queuedAt: Iso; waits: QueueWait[]; condition?: AttentionCondition } + | { kind: 'calendar_low'; triggerId: string; triggerName: string; detail: string; condition?: AttentionCondition }; export type OverviewMetrics = { models: { total: number; addedThisWeek: number; removedThisWeek: number }; @@ -404,4 +429,13 @@ export type Overview = { /** Newest first, up to the fourth deploy that changed something, with the deploys without changes between. */ recentChanges: SnapshotChange[]; latestRun: (Pick & { status: RunStatus }) | null; + /** Set by the page that read it, to tell this read from data remembered or shown from another. */ + readId?: string; + /** How long an acknowledged condition stays hidden unchanged, in seconds; null without a time limit, absent when unknown. */ + attentionSnoozeSeconds?: number | null; + /** + * Acknowledged conditions this read could see and found gone. Only conditions it reads in full + * are judged, so a condition it can't see (such as late sources, unchecked here) is never listed. + */ + clearedAcknowledgements?: AttentionAcknowledgement[]; }; diff --git a/ui/src/lib/build-area/attention-conditions.test.ts b/ui/src/lib/build-area/attention-conditions.test.ts new file mode 100644 index 0000000000..47c0e661a2 --- /dev/null +++ b/ui/src/lib/build-area/attention-conditions.test.ts @@ -0,0 +1,224 @@ +import { describe, expect, it } from 'vitest'; +import type { AttentionAcknowledgement, AttentionItem, CatalogNode, PlatformEvent, StaleReason } from '$lib/api'; +import { overviewOf } from '$lib/api/http-overview'; +import { acknowledgementOf, clearedWithdrawalId, conditionOf, judgedRead, snoozeWords, withConditions, withdrawalsDue } from './attention-conditions'; +import { toPlatformEvents } from '$lib/api/http-problems'; + +const now = Date.parse('2026-11-18T12:00:00Z'); +const iso = (hoursFromNow: number) => new Date(now + hoursFromNow * 3_600_000).toISOString(); +const event = (extra: Partial = {}): PlatformEvent => ({ + id: 'ev-1', + kind: 'tick_overdue', + severity: 'warning', + occurredAt: iso(-1), + active: true, + locationId: 'loc-1', + subject: 'segments_hourly', + message: 'The segments_hourly schedule should have started a run 12 minutes ago.', + ...extra +}); +const stale = (changed: number, behind: number): AttentionItem => ({ + kind: 'stale_models', + changed: Array.from({ length: changed }, (_, i) => `model:c${i}`), + behind: Array.from({ length: behind }, (_, i) => `model:b${i}`) +}); +const source = (key: string, status: 'warn' | 'error') => ({ key, status, loadedAt: iso(-2), checkedAt: iso(0), warnAfterSeconds: 1800, errorAfterSeconds: 7200 }); +/** The acknowledgement of `item` as it looks now, made `hoursAgo` ago. */ +const acknowledged = (item: AttentionItem, hoursAgo = 1): AttentionAcknowledgement => { + const { key, shape } = conditionOf(item)!; + return { eventId: `ack-${key}-${hoursAgo}`, key, shape, by: 'ada', at: iso(-hoursAgo), until: iso(24 - hoursAgo) }; +}; +const stateOf = (item: AttentionItem, acks: AttentionAcknowledgement[], at = now) => { + const [shown] = withConditions([item], acks, at); + const condition = 'condition' in shown ? shown.condition : undefined; + return { acknowledged: !!acknowledgementOf(shown), lapsed: condition?.lapsed?.reason ?? null }; +}; + +describe('acknowledging a condition until it changes', () => { + it('keys a condition by its kind and subject, and leaves runs to their own acknowledgement', () => { + expect(conditionOf(stale(2, 3))).toEqual({ key: 'stale_models', noun: 'node', shape: { counts: { changed: 2, behind: 3 } } }); + expect(conditionOf({ kind: 'platform_event', event: event() })?.key).toBe('event:tick_overdue:loc-1:segments_hourly'); + expect(conditionOf({ kind: 'run_problem', run: { id: 'r' } as never, acknowledged: null })).toBeNull(); + }); + + it('holds while the condition is the same or better', () => { + const ack = acknowledged(stale(2, 3)); + expect(stateOf(stale(2, 3), [ack])).toEqual({ acknowledged: true, lapsed: null }); + expect(stateOf(stale(1, 0), [ack])).toEqual({ acknowledged: true, lapsed: null }); + }); + + it('comes back, saying why, when it gets worse', () => { + expect(stateOf(stale(2, 5), [acknowledged(stale(2, 3))])).toEqual({ acknowledged: false, lapsed: '2 more nodes behind since it was acknowledged' }); + const sources: AttentionItem = { kind: 'stale_sources', sources: [source('raw__orders', 'warn')] }; + const escalated: AttentionItem = { kind: 'stale_sources', sources: [source('raw__orders', 'error')] }; + expect(stateOf(escalated, [acknowledged(sources)]).lapsed).toBe('1 more source past their error threshold since it was acknowledged'); + expect(stateOf({ kind: 'platform_event', event: event({ severity: 'critical' }) }, [acknowledged({ kind: 'platform_event', event: event() })]).lapsed).toBe('it became more severe'); + }); + + it('ignores a changed message, which can hold relative times', () => { + const before: AttentionItem = { kind: 'platform_event', event: event() }; + const later: AttentionItem = { kind: 'platform_event', event: event({ message: 'The segments_hourly schedule should have started a run 40 minutes ago.' }) }; + expect(stateOf(later, [acknowledged(before)])).toEqual({ acknowledged: true, lapsed: null }); + }); + + it('comes back when it resolved and recurred, or after 24 hours', () => { + const before: AttentionItem = { kind: 'platform_event', event: event() }; + expect(stateOf({ kind: 'platform_event', event: event({ id: 'ev-2' }) }, [acknowledged(before)]).lapsed).toBe('it resolved and came back'); + expect(stateOf(stale(2, 3), [acknowledged(stale(2, 3), 25)]).lapsed).toBe('the time it was acknowledged for ended'); + }); + + it('keeps large shapes small: many sources compare by their counts', () => { + const many: AttentionItem = { kind: 'stale_sources', sources: Array.from({ length: 80 }, (_, i) => source(`raw__s${i}`, 'warn')) }; + expect(conditionOf(many)?.shape).toEqual({ counts: { warn: 80, error: 0 } }); + expect(JSON.stringify(conditionOf(stale(10_000, 10_000))!.shape).length).toBeLessThan(100); + }); +}); + +describe('server problems, whose event IDs are fixed per problem', () => { + type Problems = Parameters[0]; + const place = { location_id: '0190a000-0000-7000-8000-000000000001', location_name: 'shop', target: 'prod' }; + const tick = (trigger: string) => ({ ...place, trigger_id: trigger, name: trigger, scheduled_for: iso(-1) }); + const problems = (over: Partial): Problems => ({ scheduler_leader: true, scheduler_lease_expires_at: null, broken_locations: [], overdue_ticks: [], low_calendars: [], ...over }) as Problems; + const item = (over: Partial): AttentionItem => ({ kind: 'platform_event', event: toPlatformEvents(problems(over), now)[0] }); + + it('comes back when another schedule is late, though the event ID stays the same', () => { + const one = item({ overdue_ticks: [tick('t-hourly')] }); + const two = item({ overdue_ticks: [tick('t-hourly'), tick('t-daily')] }); + expect((one as { event: PlatformEvent }).event.id).toBe((two as { event: PlatformEvent }).event.id); + expect(stateOf(one, [acknowledged(one)])).toEqual({ acknowledged: true, lapsed: null }); + expect(stateOf(two, [acknowledged(one)]).lapsed).toBe('1 more schedule late since it was acknowledged'); + // The same schedules late again, at a later time: still the same condition. + expect(stateOf(item({ overdue_ticks: [{ ...tick('t-hourly'), scheduled_for: iso(0) }] }), [acknowledged(one)]).acknowledged).toBe(true); + }); + + it('comes back when another calendar runs low', () => { + const cal = (trigger: string) => ({ ...place, trigger_id: trigger, name: trigger, horizon_end: iso(5), refresh_at: iso(1) }); + const one = item({ low_calendars: [cal('c-1')] }); + expect(stateOf(item({ low_calendars: [cal('c-1'), cal('c-2')] }), [acknowledged(one)]).lapsed).toBe('1 more calendar running out of dates since it was acknowledged'); + }); + + it('tells one scheduler or location outage from the next', () => { + const outage = item({ scheduler_leader: false, scheduler_lease_expires_at: iso(-3) }); + expect(stateOf(item({ scheduler_leader: false, scheduler_lease_expires_at: iso(-3) }), [acknowledged(outage)]).acknowledged).toBe(true); + expect(stateOf(item({ scheduler_leader: false, scheduler_lease_expires_at: iso(-1) }), [acknowledged(outage)]).lapsed).toBe('it resolved and came back'); + const broken = (seen: number) => item({ broken_locations: [{ ...place, last_seen_at: iso(seen) }] as Problems['broken_locations'] }); + expect(stateOf(broken(-2), [acknowledged(broken(-2))]).acknowledged).toBe(true); + expect(stateOf(broken(-1), [acknowledged(broken(-2))]).lapsed).toBe('it resolved and came back'); + }); +}); + +describe('the server’s limits', () => { + it('cuts a long key between characters, never inside one', () => { + const key = conditionOf({ kind: 'platform_event', event: event({ subject: '🦆'.repeat(300) }) })!.key; + expect(Array.from(key).length).toBeLessThanOrEqual(256); + expect(key).not.toMatch(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(? { + const long = (name: string) => conditionOf({ kind: 'platform_event', event: event({ subject: `${name.repeat(300)} · prod` }) })!.key; + expect(long('a').length).toBeLessThanOrEqual(256); + expect(long('a')).not.toBe(long('b')); + expect(conditionOf({ kind: 'platform_event', event: event() })!.key).toBe('event:tick_overdue:loc-1:segments_hourly'); + }); + + it('keeps shapes under 8 KiB, comparing by counts when members would not fit', () => { + const sources: AttentionItem = { kind: 'stale_sources', sources: Array.from({ length: 50 }, (_, i) => source(`raw__${'x'.repeat(240)}_${i}`, 'warn')) }; + const shape = conditionOf(sources)!.shape; + expect(shape).toEqual({ counts: { warn: 50, error: 0 } }); + expect(JSON.stringify(shape).length).toBeLessThan(8192); + }); +}); + +describe('acknowledgements of conditions that cleared', () => { + const ack = (key: string, shape = {}): AttentionAcknowledgement => ({ eventId: `ack-${key}`, key, shape, by: 'ada', at: iso(-2), until: iso(22) }); + const built = (stale: StaleReason[] | null): CatalogNode => ({ key: 'model:orders', kind: 'table', path: 'models/orders.sql', group: null, upstream: [], stale, lastOutcome: 'success', lastBuild: { builtAt: iso(-1) } }) as unknown as CatalogNode; + const changed: StaleReason = { reason: 'changed', change: 'definition', detail: '', since: iso(-3) }; + const read = (nodes: CatalogNode[], acks: AttentionAcknowledgement[]) => + overviewOf({ runs: [], checks: [], nodes, changes: [], events: [], acknowledgements: new Map(), conditions: { snoozeSeconds: 86_400, acknowledgements: acks }, now, scopeKey: 'loc-1:dev' }); + + it('lists one whose condition the read can see and no longer finds', () => { + const nodesOutOfDate = ack('stale_models', { counts: { changed: 2, behind: 0 } }); + expect(read([built([])], [nodesOutOfDate]).clearedAcknowledgements).toEqual([nodesOutOfDate]); + expect(read([built([changed])], [nodesOutOfDate]).clearedAcknowledgements).toEqual([]); + }); + + it('never lists one the read cannot see: unknown build state, or late sources, which it does not check', () => { + expect(read([built(null)], [ack('stale_models')]).clearedAcknowledgements).toEqual([]); + expect(read([built([])], [ack('stale_sources')]).clearedAcknowledgements).toEqual([]); + expect(read([built([])], [ack('event:tick_overdue:loc-1:dev:shop · dev')]).clearedAcknowledgements).toEqual([ack('event:tick_overdue:loc-1:dev:shop · dev')]); + }); + + it('judges another target’s problems never, as a viewer may not be allowed to see them; the scheduler always', () => { + // The server lists a broken location, late schedules and low calendars only to people who may view + // that target, so their absence from this read says nothing about them. + const elsewhere = [ack('event:location_broken:loc-2:prod:billing · prod'), ack('event:tick_overdue:loc-1:prod:shop · prod'), ack('event:calendar_horizon_low:loc-2:dev:billing · dev')]; + expect(read([built([])], elsewhere).clearedAcknowledgements).toEqual([]); + expect(read([built([])], [ack('event:scheduler_no_leader::')]).clearedAcknowledgements).toEqual([ack('event:scheduler_no_leader::')]); + expect(read([built([])], [ack('event:location_broken:loc-1:dev:shop · dev')]).clearedAcknowledgements).toHaveLength(1); + }); + + it('judges only the page’s own latest read, for the target now selected, shown and not failed', () => { + // The page shows its data through a proxy, so the shown read is a copy carrying the read's ID. + const a = { ...read([built([])], [ack('stale_models')]), readId: 'read-a' }; + const b = { ...read([built([])], []), readId: 'read-b' }; + const readA = { overview: a, readId: 'read-a', scopeKey: 'loc-1:dev', nodesSettled: true }; + expect(judgedRead(readA, { shown: { ...a }, scopeKey: 'loc-1:dev', failed: false })).toBe(readA); + expect(judgedRead(readA, { shown: a, scopeKey: 'loc-1:dev', failed: false })).toBe(readA); + // Switched to target B: A's data is still shown until B's read lands, and A's withdrawal waits on it. + expect(judgedRead(readA, { shown: a, scopeKey: 'loc-2:dev', failed: false })).toBeNull(); + // Back on A, its remembered data shows before a fresh read: never judged. + expect(judgedRead({ overview: b, readId: 'read-b', scopeKey: 'loc-2:dev', nodesSettled: true }, { shown: a, scopeKey: 'loc-1:dev', failed: false })).toBeNull(); + // Remembered from an earlier visit: a read of the same target, but not this page's latest. + expect(judgedRead({ ...readA, readId: 'read-a2' }, { shown: a, scopeKey: 'loc-1:dev', failed: false })).toBeNull(); + expect(judgedRead(readA, { shown: a, scopeKey: 'loc-1:dev', failed: true })).toBeNull(); + expect(judgedRead(null, { shown: a, scopeKey: 'loc-1:dev', failed: false })).toBeNull(); + }); + + it('judges nodes out of date only from a read that began after node state settled', () => { + const a = { ...read([built([])], [ack('stale_models'), ack('event:scheduler_no_leader::')]), readId: 'read-a' }; + // Read during a sync: even once the sync has finished, that read's nodes are not judged; a new read is needed. + const duringSync = judgedRead({ overview: a, readId: 'read-a', scopeKey: 'loc-1:dev', nodesSettled: false }, { shown: a, scopeKey: 'loc-1:dev', failed: false })!; + expect(withdrawalsDue(duringSync.overview.clearedAcknowledgements, { failed: false, syncing: !duringSync.nodesSettled }).map((x) => x.key)).toEqual(['event:scheduler_no_leader::']); + const afterSync = judgedRead({ overview: a, readId: 'read-a', scopeKey: 'loc-1:dev', nodesSettled: true }, { shown: a, scopeKey: 'loc-1:dev', failed: false })!; + expect(withdrawalsDue(afterSync.overview.clearedAcknowledgements, { failed: false, syncing: !afterSync.nodesSettled }).map((x) => x.key)).toEqual(['stale_models', 'event:scheduler_no_leader::']); + }); + + it('withdraws nothing after a failed read, and nodes out of date only once node state has settled', () => { + const cleared = [ack('stale_models'), ack('event:location_broken:loc-1:')]; + expect(withdrawalsDue(cleared, { failed: true, syncing: false })).toEqual([]); + expect(withdrawalsDue(cleared, { failed: false, syncing: true }).map((a) => a.key)).toEqual(['event:location_broken:loc-1:']); + expect(withdrawalsDue(cleared, { failed: false, syncing: false })).toEqual(cleared); + }); + + it('withdraws each acknowledgement with one event ID every viewer agrees on, derived from that acknowledgement', () => { + const id = clearedWithdrawalId(ack('stale_models')); + expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-8[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/); + expect(clearedWithdrawalId(ack('stale_models'))).toBe(id); + expect(clearedWithdrawalId({ ...ack('stale_models'), eventId: 'a-later-acknowledgement' })).not.toBe(id); + }); + + it('shows a condition that comes back after it was withdrawn as new, even with a smaller count', () => { + const before = stale(5, 0); + const withdrawnThenBack = stale(2, 0); + // While acknowledged, a smaller count stays hidden. + expect(stateOf(withdrawnThenBack, [acknowledged(before)])).toEqual({ acknowledged: true, lapsed: null }); + // Once the cleared condition's acknowledgement is withdrawn, the listing no longer holds it. + expect(stateOf(withdrawnThenBack, [])).toEqual({ acknowledged: false, lapsed: null }); + }); +}); + +describe('the configured snooze', () => { + it('never lapses on time without a time limit', () => { + const ack = { ...acknowledged(stale(2, 3), 1000), until: null }; + expect(stateOf(stale(2, 3), [ack])).toEqual({ acknowledged: true, lapsed: null }); + expect(stateOf(stale(2, 4), [ack]).lapsed).toBe('1 more node behind since it was acknowledged'); + }); + + it('lapses after the configured time', () => { + expect(stateOf(stale(2, 3), [{ ...acknowledged(stale(2, 3), 2), until: iso(-1) }]).lapsed).toBe('the time it was acknowledged for ended'); + }); + + it('is worded in plain units', () => { + expect([86_400, 5_400, 129_600, 1, 172_800].map(snoozeWords)).toEqual(['1 day', '1 hour and 30 minutes', '1 day and 12 hours', '1 second', '2 days']); + }); +}); diff --git a/ui/src/lib/build-area/attention-conditions.ts b/ui/src/lib/build-area/attention-conditions.ts new file mode 100644 index 0000000000..0a62bc39dc --- /dev/null +++ b/ui/src/lib/build-area/attention-conditions.ts @@ -0,0 +1,187 @@ +// Ongoing conditions on the Overview's attention list, and whether an acknowledgement still holds. +// A run is acknowledged for good; a condition only until it changes: it gets worse, it resolves and +// comes back, or the acknowledgement's 24 hours end. The server stores each acknowledgement with the +// condition's shape when it was acknowledged; this module says what a condition's shape is and what +// counts as worse. Shapes hold kinds, subjects, severities and counts, never message text, which can +// hold relative times ("12 minutes ago"). Pure. + +import type { AttentionAcknowledgement, AttentionCondition, AttentionItem, ConditionShape } from '$lib/api'; +import { plural } from '$lib/format/plural'; + +/** Members kept in a shape; beyond this a condition is compared by its counts only, to keep the stored shape small. */ +const MAX_MEMBERS = 50; +const SEVERITY: Record = { info: 0, warning: 1, critical: 2, warn: 1, error: 2 }; + +/** A condition's key and shape, and what its members are called; null for runs, which are acknowledged for good. */ +export function conditionOf(item: AttentionItem): { key: string; shape: ConditionShape; noun: string } | null { + switch (item.kind) { + case 'stale_models': + return { key: 'stale_models', noun: 'node', shape: { counts: { changed: new Set(item.changed).size, behind: new Set(item.behind).size } } }; + case 'stale_sources': { + const members = item.sources.map((s) => `${s.key}:${s.status}`).sort(); + const counts = { warn: item.sources.filter((s) => s.status === 'warn').length, error: item.sources.filter((s) => s.status === 'error').length }; + return { key: 'stale_sources', noun: 'source', shape: bounded({ counts, members }) }; + } + case 'platform_event': { + const e = item.event; + const severity = SEVERITY[e.severity] ?? 0; + const key = boundedKey(`event:${e.kind}:${e.locationId ?? ''}:${e.subject ?? ''}`); + // A grouped event (late schedules, low calendars) gets worse as it holds more; its ID is fixed. + if (e.members) return { key, noun: NOUNS[e.kind] ?? 'event', shape: bounded({ severity, counts: { [e.kind]: e.members.length }, members: e.members }) }; + // A fixed ID (a stopped scheduler, a broken location) comes with what tells its occurrences apart. + return { key, noun: 'event', shape: { severity, ...(e.occurrence ?? e.id ? { occurrence: e.occurrence ?? e.id } : {}) } }; + } + case 'queue_blocked': + return { key: `queue:${item.runId}`, noun: 'wait', shape: { members: [...new Set(item.waits.map((w) => w.kind))].sort() } }; + case 'calendar_low': + return { key: `calendar:${item.triggerId}`, noun: 'warning', shape: {} }; + case 'run_problem': + case 'run_unresponsive': + return null; + } +} + +const COUNT_LABEL: Record = { changed: 'changed', behind: 'behind', warn: 'late', error: 'past their error threshold', tick_overdue: 'late', calendar_horizon_low: 'running out of dates' }; +const NOUNS: Record = { tick_overdue: 'schedule', calendar_horizon_low: 'calendar' }; + +/** The server keeps keys to 256 characters; a longer one is cut, with a hash of the whole to keep it distinct. */ +export const MAX_KEY_CHARS = 256; +export function boundedKey(key: string): string { + // The server counts characters (code points), so a key is measured and cut by them, never mid-pair. + const points = Array.from(key); + if (points.length <= MAX_KEY_CHARS) return key; + // FNV-1a, 32 bits, twice with different seeds: deterministic and enough to tell keys of one target apart. + const fnv = (seed: number) => { + let h = seed; + for (let i = 0; i < key.length; i++) h = Math.imul(h ^ key.charCodeAt(i), 0x01000193) >>> 0; + return h.toString(16).padStart(8, '0'); + }; + return `${points.slice(0, MAX_KEY_CHARS - 18).join('')}#${fnv(0x811c9dc5)}${fnv(0x050c5d1f)}`; +} + +/** The server keeps shapes to 8 KiB; members are left out beyond MAX_MEMBERS or this many bytes, comparing by counts. */ +const MAX_SHAPE_BYTES = 6 * 1024; +function bounded(shape: ConditionShape): ConditionShape { + if (!shape.members) return shape; + const fits = shape.members.length <= MAX_MEMBERS && new TextEncoder().encode(JSON.stringify(shape)).length <= MAX_SHAPE_BYTES; + if (fits) return shape; + const { members: _, ...rest } = shape; + return rest; +} + +/** Why an acknowledgement no longer holds at `now`, or null while it does. */ +export function lapseOf(stored: ConditionShape, current: ConditionShape, until: string | null, now: number, noun: string): string | null { + if (stored.occurrence !== undefined && current.occurrence !== undefined && stored.occurrence !== current.occurrence) return 'it resolved and came back'; + if ((current.severity ?? 0) > (stored.severity ?? 0)) return 'it became more severe'; + for (const [name, count] of Object.entries(current.counts ?? {})) { + const more = count - (stored.counts?.[name] ?? 0); + if (more > 0) return `${plural(more, `more ${noun}`)} ${COUNT_LABEL[name] ?? name} since it was acknowledged`; + } + if (stored.members && current.members) { + const added = current.members.filter((m) => !stored.members!.includes(m)).length; + if (added) return `${plural(added, `new ${noun}`)} since it was acknowledged`; + } + if (until !== null && now >= Date.parse(until)) return 'the time it was acknowledged for ended'; + return null; +} + +/** A snooze in words, such as `24 hours` or `1 day and 12 hours`. */ +export function snoozeWords(seconds: number): string { + const parts = [ + [Math.floor(seconds / 86_400), 'day'], + [Math.floor((seconds % 86_400) / 3_600), 'hour'], + [Math.floor((seconds % 3_600) / 60), 'minute'], + [seconds % 60, 'second'] + ] as const; + const words = parts.filter(([n]) => n > 0).map(([n, unit]) => plural(n, unit)); + return words.length > 1 ? `${words.slice(0, -1).join(', ')} and ${words.at(-1)}` : (words[0] ?? '0 seconds'); +} + +/** + * Acknowledged conditions that `items` no longer hold, among those this read can `see`; a condition it + * can't see is never judged gone. Runs are acknowledged for good and have no condition, so never appear. + */ +export function clearedAcknowledgements(items: readonly AttentionItem[], acknowledgements: readonly AttentionAcknowledgement[], see: (key: string) => boolean): AttentionAcknowledgement[] { + const present = new Set(items.flatMap((item) => conditionOf(item)?.key ?? [])); + return acknowledgements.filter((a) => see(a.key) && !present.has(a.key)); +} + +/** + * The cleared acknowledgements to withdraw now: none after a failed read, and nodes out of date only once + * node state has settled (no sync running, the last one succeeded), when their absence can be trusted. + */ +export function withdrawalsDue(cleared: readonly AttentionAcknowledgement[] | undefined, read: { failed: boolean; syncing: boolean }): AttentionAcknowledgement[] { + if (read.failed) return []; + return (cleared ?? []).filter((a) => a.key !== 'stale_models' || !read.syncing); +} + +/** + * An Overview read as the page made it: its own ID (the page holds data in a proxy, so the read is told + * apart by ID, not identity), for which scope, and whether node state had settled when it began. + */ +export type JudgedRead = { overview: T; readId: string; scopeKey: string; nodesSettled: boolean }; + +/** + * The read whose cleared acknowledgements may be withdrawn, or null: only the page's own latest read, while + * it is what is shown, for the scope now selected, and not after a failed reload. Shown data that came from + * elsewhere (remembered from an earlier visit, or still the previous target's) is never judged. + */ +export function judgedRead(read: JudgedRead | null, now: { shown: { readId?: string } | null; scopeKey: string | null; failed: boolean }): JudgedRead | null { + if (!read || now.failed || now.shown?.readId !== read.readId || now.scopeKey !== read.scopeKey) return null; + return read; +} + +/** What the audit log says of a withdrawal made because the condition cleared. */ +export const CLEARED_REASON = 'automatic: the condition cleared'; + +/** + * Whether an event's condition is one every viewer of `scopeKey` (a `:` key) sees in full: + * the server-wide scheduler, which everyone sees, or this target's own problems. Others' problems are + * listed only to people who may view their target, so their absence here says nothing. + */ +export function visibleEventKey(key: string, scopeKey: string): boolean { + if (key === boundedKey('event:scheduler_no_leader::')) return true; + return ['location_broken', 'tick_overdue', 'calendar_horizon_low'].some((kind) => key.startsWith(`event:${kind}:${scopeKey}:`)); +} + +/** + * The event ID of withdrawing `ack` because its condition cleared: the same for every viewer, so the + * server applies it once however many Overviews notice. A new acknowledgement gets a new one. + */ +export function clearedWithdrawalId(ack: Pick): string { + const text = `${ack.eventId}\ncleared`; + // FNV-1a, 32 bits, with four seeds: 128 deterministic bits, shaped as a UUID (version 8, variant 10). + const hash = (seed: number) => { + let h = seed; + for (let i = 0; i < text.length; i++) h = Math.imul(h ^ text.charCodeAt(i), 0x01000193) >>> 0; + return h.toString(16).padStart(8, '0'); + }; + const hex = [0x811c9dc5, 0x050c5d1f, 0x2d358dcc, 0x7a1f3e91].map(hash).join(''); + const variant = ((parseInt(hex[16], 16) & 0x3) | 0x8).toString(16); + return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-8${hex.slice(13, 16)}-${variant}${hex.slice(17, 20)}-${hex.slice(20, 32)}`; +} + +/** The items with their conditions, each acknowledged while its acknowledgement holds and otherwise saying why it lapsed. */ +export function withConditions(items: AttentionItem[], acknowledgements: readonly AttentionAcknowledgement[], now: number): AttentionItem[] { + const byKey = new Map(acknowledgements.map((a) => [a.key, a])); + return items.map((item) => { + const found = conditionOf(item); + if (!found) return item; + const ack = byKey.get(found.key); + const reason = ack ? lapseOf(ack.shape, found.shape, ack.until, now, found.noun) : null; + const condition: AttentionCondition = { + key: found.key, + shape: found.shape, + acknowledged: ack && !reason ? { by: ack.by, at: ack.at, until: ack.until } : null, + lapsed: ack && reason ? { reason, by: ack.by, at: ack.at } : null + }; + return { ...item, condition } as AttentionItem; + }); +} + +/** Whether an item is acknowledged now: a run by its own mark, a condition while its acknowledgement holds. */ +/** `until` is absent for a run, acknowledged for good, and null for a condition without a time limit. */ +export function acknowledgementOf(item: AttentionItem): { by: string; at: string; until?: string | null } | null { + if ('acknowledged' in item) return item.acknowledged; + return ('condition' in item && item.condition?.acknowledged) || null; +} diff --git a/ui/src/lib/build-area/attention.test.ts b/ui/src/lib/build-area/attention.test.ts index e4de69c642..7927b80561 100644 --- a/ui/src/lib/build-area/attention.test.ts +++ b/ui/src/lib/build-area/attention.test.ts @@ -30,6 +30,16 @@ describe('overview alerts', () => { ]); }); + it('keeps an overdue schedule as its own alert when its outage is acknowledged, so it isn’t hidden with it', () => { + const broken = event('broken', 'location_broken', 'shop'); + const acknowledged = { ...broken, condition: { key: 'event:location_broken:shop:', shape: {}, acknowledged: { by: 'ada', at: ago(1), until: ago(-600) }, lapsed: null } } as AttentionItem; + const views = attentionViews([acknowledged, event('late-shop', 'tick_overdue', 'shop', { message: 'hourly is late' })], now); + expect(views.map(({ view }) => [view.key, view.consequences.length])).toEqual([ + ['event:broken', 0], + ['event:late-shop', 0] + ]); + }); + it('keeps an overdue schedule as its own alert when nothing explains it', () => { const views = attentionViews([event('late', 'tick_overdue', 'shop'), event('broken', 'location_broken', 'marketing')], now); expect(views.map(({ view }) => view.key)).toEqual(['event:late', 'event:broken']); diff --git a/ui/src/lib/build-area/attention.ts b/ui/src/lib/build-area/attention.ts index 5bd97bc743..38dc82c461 100644 --- a/ui/src/lib/build-area/attention.ts +++ b/ui/src/lib/build-area/attention.ts @@ -174,7 +174,8 @@ const waitRun = (wait: QueueWait): string | null => ('runId' in wait ? wait.runI */ function causeOf(item: AttentionItem, items: AttentionItem[]): string | null { if (item.kind === 'platform_event' && item.event.kind === 'tick_overdue') { - const events = items.flatMap((i) => (i.kind === 'platform_event' ? [i.event] : [])); + // An acknowledged cause has left the list, so what follows from it stands on its own. + const events = items.flatMap((i) => (i.kind === 'platform_event' && !i.condition?.acknowledged ? [i.event] : [])); const location = events.find((e) => e.kind === 'location_broken' && e.locationId === item.event.locationId); const scheduler = events.find((e) => e.kind === 'scheduler_no_leader'); const cause = location ?? scheduler; diff --git a/ui/src/lib/build-area/folder-tree.test.ts b/ui/src/lib/build-area/folder-tree.test.ts new file mode 100644 index 0000000000..71c752c71a --- /dev/null +++ b/ui/src/lib/build-area/folder-tree.test.ts @@ -0,0 +1,91 @@ +import { describe, expect, it } from 'vitest'; +import type { CatalogNode, StaleReason } from '$lib/api'; +import { folderPaths, folderTree, visibleTreeRows, type TreeRow } from './folder-tree'; + +const behind = [{ reason: 'behind', upstream: [], detail: '', since: '2026-11-18T00:00:00Z' }] as StaleReason[]; +const node = (key: string, path: string, extra: Partial = {}): CatalogNode => + ({ key, kind: 'table', path, group: null, upstream: [], stale: [], lastOutcome: 'success', lastBuild: { builtAt: '2026-11-18T00:00:00Z' }, ...extra }) as CatalogNode; + +const nodes = [ + node('card_events', 'models/payments/providers/card/card_events.sql', { stale: behind }), + node('card_daily', 'models/payments/providers/card/card_daily.sql'), + node('bank_events', 'models/payments/providers/bank/bank_events.sql'), + node('settled', 'models/payments/settlement/settled.sql', { lastOutcome: 'failed' }), + node('payments_summary', 'models/payments/payments_summary.sql'), + node('orders', 'models/orders/marts/orders.sql'), + node('raw_orders', 'sources/shop.yml', { kind: 'source' }) +]; +const label = (r: TreeRow) => (r.kind === 'folder' ? `${' '.repeat(r.folder.depth)}${r.folder.group}${r.expandable ? (r.expanded ? ' v' : ' >') : ''}` : r.kind === 'node' ? `${' '.repeat(r.depth)}· ${r.node.key}` : `${' '.repeat(r.folder.depth + 1)}+${r.hidden} more`); +const rows = (opts: Partial[1]> = {}) => + visibleTreeRows(folderTree(nodes), { expanded: new Set(), sort: 'urgency', reverse: false, attentionOnly: false, listNodes: false, ...opts }).map(label); + +describe('the catalog folder tree', () => { + it('selects a folder by path only when that selects exactly what it counts, and only under models/ or python/', () => { + const tree = folderTree([ + node('orders', 'models/shop/orders/orders.sql'), + // A source declared in the folder: a path would select it, though the folder doesn't count it. + node('raw_returns', 'models/shop/returns/sources.yml', { kind: 'source' }), + node('returns', 'models/shop/returns/returns.sql'), + // A node of a declared group whose file sits in the folder. + node('loyalty', 'models/shop/customers/loyalty.sql', { group: 'crm' }), + node('customers', 'models/shop/customers/customers.sql'), + node('codes', 'seeds/lookups/codes.csv', { kind: 'seed' }), + node('score', 'python/ml/score.py', { kind: 'asset' }) + ]); + const selection = (path: string) => { + const find = (fs: ReturnType): ReturnType[number] | undefined => fs.flatMap((f) => (f.path === path ? [f] : [find(f.children)].filter((x) => !!x)))[0]; + return find(tree)?.selection; + }; + expect(selection('shop/orders')).toBe('path:models/shop/orders'); + expect(selection('shop/returns')).toBe('returns'); + expect(selection('shop/customers')).toBe('customers'); + expect(selection('shop')).toBe('orders returns customers'); + // `path:seeds/…` is rejected: path selectors start at models/ or python/. + expect([selection('seeds'), selection('seeds/lookups')]).toEqual(['codes', 'codes']); + expect(selection('python/ml')).toBe('path:python/ml'); + }); + + it('counts each folder with its subfolders, and selects exactly its nodes', () => { + const [payments, orders] = folderTree(nodes); + expect([payments.path, payments.total, payments.current, payments.behind, payments.failed]).toEqual(['payments', 5, 3, 1, 1]); + expect(payments.selection).toBe('path:models/payments'); + expect(payments.children.map((c) => [c.path, c.total, c.selection])).toEqual([ + ['payments/providers', 3, 'path:models/payments/providers'], + ['payments/settlement', 1, 'path:models/payments/settlement'] + ]); + expect(payments.members.map((n) => n.key)).toEqual(['payments_summary']); + expect(orders.total).toBe(1); + expect(folderPaths(folderTree(nodes))).toEqual(['payments', 'payments/providers', 'payments/providers/card', 'payments/providers/bank', 'payments/settlement', 'orders', 'orders/marts']); + }); + + it('expands in place, most urgent first within each level', () => { + expect(rows()).toEqual(['payments >', 'orders >']); + expect(rows({ expanded: new Set(['payments', 'payments/providers']) })).toEqual(['payments v', ' settlement', ' providers v', ' card', ' bank', 'orders >']); + expect(rows({ expanded: new Set(['payments']), sort: 'group' })).toEqual(['orders >', 'payments v', ' providers >', ' settlement']); + }); + + it('lists a folder’s own nodes after its subfolders when asked, capped with a row for the rest', () => { + expect(rows({ expanded: new Set(['payments', 'payments/providers/card']), listNodes: true, nodeLimit: 1 })).toEqual(['payments v', ' settlement >', ' providers >', ' · payments_summary', 'orders >']); + expect(rows({ expanded: new Set(['payments', 'payments/providers', 'payments/providers/card']), listNodes: true, nodeLimit: 1 })).toEqual([ + 'payments v', + ' settlement >', + ' providers v', + ' card v', + ' · card_events', + ' +1 more', + ' bank >', + ' · payments_summary', + 'orders >' + ]); + }); + + it('leaves out fully current folders and nodes when showing only what needs attention', () => { + expect(rows({ attentionOnly: true, expanded: new Set(['payments', 'payments/providers', 'payments/providers/card']), listNodes: true })).toEqual([ + 'payments v', + ' settlement >', + ' providers v', + ' card v', + ' · card_events' + ]); + }); +}); diff --git a/ui/src/lib/build-area/folder-tree.ts b/ui/src/lib/build-area/folder-tree.ts new file mode 100644 index 0000000000..1e562ee5b9 --- /dev/null +++ b/ui/src/lib/build-area/folder-tree.ts @@ -0,0 +1,126 @@ +// The catalog's folders as a tree, each folder with where its nodes stand (its subfolders' included), +// a catalog selection for exactly its nodes, and the nodes sitting in it directly. One pass. Pure. + +import type { CatalogNode, GroupStatus } from '$lib/api'; +import { shortName } from '$lib/build-area/labels'; +import { folderOf } from '$lib/lineage/catalog-graph'; +import { canSelectByPath, inexactDirs } from '$lib/selection/folders'; +import { needsAttention } from './overview-panels'; +import { sortFolders } from './overview-panels'; + +export type FolderNode = GroupStatus & { + /** From the project's top, such as `payments/providers`; `group` is its last part. */ + path: string; + depth: number; + children: FolderNode[]; + /** Nodes in this folder itself, not in a subfolder. */ + members: CatalogNode[]; + /** A catalog selection of every node in it, subfolders included. */ + selection: string; +}; + +const dirOf = (path: string) => (path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : ''); + +export type FolderSort = 'urgency' | 'group' | 'current' | 'changed' | 'behind' | 'failed'; + +/** Folders sorted by a column: most urgent first, names A to Z, or counts largest first; `reverse` turns it round. */ +export function sortFolderRows(rows: readonly T[], by: FolderSort, reverse = false): T[] { + const urgent = sortFolders(rows) as T[]; + if (by === 'urgency') return reverse ? urgent.reverse() : urgent; + const rank = new Map(urgent.map((r, i) => [r, i])); + const sign = reverse ? -1 : 1; + return [...rows].sort((a, b) => (by === 'group' ? sign * a.group.localeCompare(b.group) : sign * (b[by] - a[by]) || rank.get(a)! - rank.get(b)!)); +} + +/** The top-level folders, each holding its subfolders, unsorted. Sources are left out, as on the Overview. */ +export function folderTree(nodes: readonly CatalogNode[]): FolderNode[] { + const byPath = new Map(); + const top: FolderNode[] = []; + for (const n of nodes) { + if (n.kind === 'source') continue; + const folder = folderOf(n); + const dir = dirOf(n.path); + // The file-system folder the catalog folder starts at, such as `models/`; null when the folder is a declared group. + const root = dir === folder || dir.endsWith(`/${folder}`) ? dir.slice(0, dir.length - folder.length) : null; + const parts = folder.split('/'); + const stale = n.stale ?? []; + const isChanged = stale.some((s) => s.reason !== 'behind'); + const isBehind = stale.some((s) => s.reason === 'behind'); + const isFailed = n.lastOutcome === 'failed'; + const isCurrent = !stale.length && !isFailed && !!n.lastBuild; + let parent: FolderNode | null = null; + for (let i = 0; i < parts.length; i++) { + const path = parts.slice(0, i + 1).join('/'); + let f = byPath.get(path); + if (!f) { + f = { group: parts[i], path, depth: i, total: 0, current: 0, changed: 0, behind: 0, failed: 0, children: [], members: [], selection: '', root, keys: [] }; + byPath.set(path, f); + (parent ? parent.children : top).push(f); + } + if (f.root !== root) f.root = null; + f.total += 1; + f.current += Number(isCurrent); + f.changed += Number(isChanged); + f.behind += Number(isBehind); + f.failed += Number(isFailed); + f.keys.push(shortName(n.key)); + if (i === parts.length - 1) f.members.push(n); + parent = f; + } + } + // `path:` selects every node under the folder's directory, so it stands for the folder only when that is + // exactly what the folder counts: under a root a path selector accepts, and with no source, and no node + // of another folder, in it. Otherwise the folder's nodes are selected by name. + const dirOfFolder = new Map(); + for (const f of byPath.values()) if (f.root !== null && canSelectByPath(`${f.root}${f.path}`)) dirOfFolder.set(`${f.root}${f.path}`, f.path); + const inside = (n: CatalogNode, path: string) => n.kind !== 'source' && (folderOf(n) === path || folderOf(n).startsWith(`${path}/`)); + const inexact = inexactDirs(nodes, new Set(dirOfFolder.keys()), (n, dir) => inside(n, dirOfFolder.get(dir)!)); + for (const f of byPath.values()) { + const dir = f.root !== null ? `${f.root}${f.path}` : null; + f.selection = dir && dirOfFolder.has(dir) && !inexact.has(dir) ? `path:${dir}` : [...new Set(f.keys)].join(' '); + delete (f as { root?: unknown }).root; + delete (f as { keys?: unknown }).keys; + } + return top; +} + +/** Every folder path in the tree, for Expand all. */ +export function folderPaths(tree: readonly FolderNode[]): string[] { + return tree.flatMap((f) => [f.path, ...folderPaths(f.children)]); +} + +export type TreeRow = + | { kind: 'folder'; folder: FolderNode; expandable: boolean; expanded: boolean } + | { kind: 'node'; node: CatalogNode; depth: number } + | { kind: 'more'; folder: FolderNode; hidden: number }; + +const nodeNeedsAttention = (n: CatalogNode) => n.lastOutcome === 'failed' || !!n.stale?.length; + +/** + * The rows on screen: folders sorted within each level, an expanded folder's subfolders under it and, + * with `listNodes`, its own nodes after them, up to `nodeLimit` and then a row for the rest. With + * `attentionOnly`, fully current folders and nodes are left out. + */ +export function visibleTreeRows( + tree: readonly FolderNode[], + options: { expanded: ReadonlySet; sort: FolderSort; reverse: boolean; attentionOnly: boolean; listNodes: boolean; nodeLimit?: number } +): TreeRow[] { + const { expanded, sort, reverse, attentionOnly, listNodes, nodeLimit = 20 } = options; + const rows: TreeRow[] = []; + const walk = (level: readonly FolderNode[]) => { + for (const folder of sortFolderRows(attentionOnly ? level.filter(needsAttention) : level, sort, reverse)) { + const members = attentionOnly ? folder.members.filter(nodeNeedsAttention) : folder.members; + const expandable = folder.children.some((c) => !attentionOnly || needsAttention(c)) || (listNodes && members.length > 0); + const open = expandable && expanded.has(folder.path); + rows.push({ kind: 'folder', folder, expandable, expanded: open }); + if (!open) continue; + walk(folder.children); + if (!listNodes) continue; + const shown = [...members].sort((a, b) => Number(nodeNeedsAttention(b)) - Number(nodeNeedsAttention(a)) || shortName(a.key).localeCompare(shortName(b.key))); + for (const node of shown.slice(0, nodeLimit)) rows.push({ kind: 'node', node, depth: folder.depth + 1 }); + if (shown.length > nodeLimit) rows.push({ kind: 'more', folder, hidden: shown.length - nodeLimit }); + } + }; + walk(tree); + return rows; +} diff --git a/ui/src/lib/build-area/overview-panels.test.ts b/ui/src/lib/build-area/overview-panels.test.ts index 944fb8553d..29e7255cc6 100644 --- a/ui/src/lib/build-area/overview-panels.test.ts +++ b/ui/src/lib/build-area/overview-panels.test.ts @@ -1,6 +1,6 @@ import { describe, expect, it } from 'vitest'; import type { GroupStatus, SnapshotChange } from '$lib/api'; -import { quietDeployLine, recentDeployRows, recentDeploys, sortFolders, visibleFolders } from './overview-panels'; +import { quietDeployLine, recentDeployRows, recentDeploys, sortFolders, cappedFolders } from './overview-panels'; const HOUR = 60 * 60 * 1000; const now = Date.parse('2026-11-16T12:00:00Z'); @@ -69,16 +69,14 @@ describe('build status by folder', () => { expect(sorted.map((g) => g.group)).toEqual(['returns', 'billing', 'inventory', 'alpha', 'customers', 'orders']); }); - it('shows eight folders, plus any beyond that need attention, until expanded', () => { + it('shows at most eight folders, most urgent first, however many need attention', () => { const calm = Array.from({ length: 12 }, (_, i) => folder(`calm_${String(i).padStart(2, '0')}`, 20 - i)); const attention = Array.from({ length: 10 }, (_, i) => folder(`busy_${i}`, 1, 0, 0, 1)); - expect(visibleFolders(calm, false)).toMatchObject({ hidden: 4 }); - expect(visibleFolders(calm, false).rows.map((g) => g.group)).toEqual(calm.slice(0, 8).map((g) => g.group)); - const mixed = visibleFolders([...calm, ...attention], false); - expect(mixed.rows).toHaveLength(10); + expect(cappedFolders(calm).rows.map((g) => g.group)).toEqual(calm.slice(0, 8).map((g) => g.group)); + const mixed = cappedFolders([...calm, ...attention]); + expect(mixed.rows).toHaveLength(8); expect(mixed.rows.every((g) => g.behind)).toBe(true); - expect(mixed.hidden).toBe(12); - expect(visibleFolders([...calm, ...attention], true)).toMatchObject({ hidden: 0 }); - expect(visibleFolders([...calm, ...attention], true).rows).toHaveLength(22); + expect([mixed.total, mixed.attention]).toEqual([22, 10]); + expect(cappedFolders(calm.slice(0, 3))).toMatchObject({ total: 3, attention: 0 }); }); }); diff --git a/ui/src/lib/build-area/overview-panels.ts b/ui/src/lib/build-area/overview-panels.ts index e18de01a36..cb54545890 100644 --- a/ui/src/lib/build-area/overview-panels.ts +++ b/ui/src/lib/build-area/overview-panels.ts @@ -6,7 +6,7 @@ import { plural } from '$lib/format/plural'; /** Deploys that changed something the Recent changes panel shows. */ export const RECENT_DEPLOYS = 4; -/** Folders the Build status panel shows before "Show all"; folders that need attention always show. */ +/** Folders the Overview's Build status card shows at most; the catalog's folder view lists them all. */ export const FOLDER_ROWS = 8; /** Whether a deploy changed any definition: a node, a job or trigger, a role or the environment. */ @@ -74,12 +74,9 @@ export function sortFolders(groups: readonly GroupStatus[]): GroupStatus[] { } /** - * The folder rows to show, sorted: the first `limit`, plus every folder beyond that needs attention, - * or all of them when expanded. `hidden` counts the rest, for "Show all N folders". + * The Overview card's folders: at most `limit`, most urgent first, however many need attention (the + * catalog's folder view lists them all), with how many there are and how many need attention. */ -export function visibleFolders(groups: readonly GroupStatus[], expanded: boolean, limit = FOLDER_ROWS): { rows: GroupStatus[]; hidden: number } { - const sorted = sortFolders(groups); - if (expanded) return { rows: sorted, hidden: 0 }; - const rows = sorted.filter((g, i) => i < limit || needsAttention(g)); - return { rows, hidden: sorted.length - rows.length }; +export function cappedFolders(groups: readonly GroupStatus[], limit = FOLDER_ROWS): { rows: GroupStatus[]; total: number; attention: number } { + return { rows: sortFolders(groups).slice(0, limit), total: groups.length, attention: groups.filter(needsAttention).length }; } diff --git a/ui/src/lib/components/build-area/folder-tree.svelte b/ui/src/lib/components/build-area/folder-tree.svelte new file mode 100644 index 0000000000..c8383f829f --- /dev/null +++ b/ui/src/lib/components/build-area/folder-tree.svelte @@ -0,0 +1,205 @@ + + +
+
+ {tree.length} folders · 0}>{needing} need attention + + + {#if sort !== 'urgency' || reverse}{/if} + + +
+ + {#snippet head(c)} + {#if c.id !== 'bar'} + + {/if} + {/snippet} + {#snippet row(r)} + {#if r.kind === 'folder'} + {@const f = r.folder} + + labelClick(e, r)} data-testid="folder-label"> +
+ {#if r.expandable} + + {:else} + + {/if} + {#if r.expanded}{:else}{/if} + open(e, f.selection)} title="Open {f.path} in the catalog" data-testid="folder-name">{f.group} + {#if !r.expanded && f.children.length}{f.children.length} subfolders{/if} +
+ + + + + + + + + {f.current}/{f.total} + {#each COUNTS as c (c.id)} + {@const n = f[c.id]} + {#if n} open(e, f.selection, c.id)} style:color={c.tone} title="Open its {n} {c.id} nodes in the catalog" data-testid="folder-count-{c.id}">{n}{:else}—{/if} + {/each} + + {:else if r.kind === 'node'} + {@const n = r.node} + {@const Glyph = nodeIcon[nodeIconKey(n)] ?? nodeIcon.table} + {@const state = nodeState(n)} + + +
+ + {#if linksNodes}{shortName(n.key)}{:else}{shortName(n.key)}{/if} +
+ + {state.label} + + + + + + {:else} + + + + + + + + + + + {/if} + {/snippet} +
+
+ + diff --git a/ui/src/lib/selection/folders.test.ts b/ui/src/lib/selection/folders.test.ts index d388e3a419..6a08c9aebc 100644 --- a/ui/src/lib/selection/folders.test.ts +++ b/ui/src/lib/selection/folders.test.ts @@ -12,7 +12,8 @@ describe('folder selections', () => { node('model:stg_a', 'models/staging/shop/stg_a.sql'), node('model:stg_b', 'models/staging/crm/stg_b.sql') ]); - expect(out.get('marts')).toBe('path:models/marts'); + // A source in the folder isn't counted, so its path would select more: the nodes are named instead. + expect(out.get('marts')).toBe('orders'); expect(out.get('staging')).toBe('path:models/staging'); }); @@ -22,6 +23,11 @@ describe('folder selections', () => { expect(out.get('models')).toBe('top'); }); + it('names the nodes of a folder outside models/ and python/, which a path selector rejects', () => { + const out = folderSelections([node('seed:codes', 'seeds/lookups/codes.csv', 'seed'), node('seed:regions', 'seeds/lookups/regions.csv', 'seed')]); + expect(out.get('seeds')).toBe('codes regions'); + }); + it('names the nodes when another group shares the folder', () => { const out = folderSelections([node('model:orders', 'models/marts/orders.sql'), node('model:legacy', 'models/marts/legacy.sql', 'table', 'archive')]); expect(out.get('marts')).toBe('orders'); diff --git a/ui/src/lib/selection/folders.ts b/ui/src/lib/selection/folders.ts index d5d089abde..ac3306f1d6 100644 --- a/ui/src/lib/selection/folders.ts +++ b/ui/src/lib/selection/folders.ts @@ -7,6 +7,27 @@ import { topFolder } from '$lib/lineage/catalog-graph'; const dirOf = (path: string) => (path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : ''); +/** The project folders a `path:` selector can start at; any other, such as `seeds/`, is an error (S012). */ +const PATH_ROOTS = ['models', 'python']; +export const canSelectByPath = (dir: string) => PATH_ROOTS.some((root) => dir.startsWith(`${root}/`)); + +/** + * Of `dirs`, those a `path:` selector would over-select: a node sits somewhere under one but doesn't + * `belong` to it, such as another group's node, or a source declared in a .yml file there. One pass + * over the nodes, plus one per folder depth. + */ +export function inexactDirs(nodes: readonly CatalogNode[], dirs: ReadonlySet, belongs: (n: CatalogNode, dir: string) => boolean): Set { + const inexact = new Set(); + for (const n of nodes) { + const parts = dirOf(n.path).split('/'); + for (let i = 1; i <= parts.length; i++) { + const dir = parts.slice(0, i).join('/'); + if (dirs.has(dir) && !belongs(n, dir)) inexact.add(dir); + } + } + return inexact; +} + /** The longest folder every one of `dirs` is in, or `''`. */ function commonDir(dirs: string[]): string { let common = dirs[0]?.split('/') ?? []; @@ -36,25 +57,20 @@ export function folderSelections(nodes: readonly CatalogNode[]): Map(); for (const [g, list] of groups) { const dir = commonDir(list.map((n) => dirOf(n.path))); - // A bare root such as `models` holds every model; it never stands for one group. - if (!dir.includes('/') || groupAt.has(dir)) continue; + // A bare root such as `models` holds every model; it never stands for one group. Nor can a folder + // outside the roots a path selector accepts. + if (!canSelectByPath(dir) || groupAt.has(dir)) continue; folderOf.set(g, dir); groupAt.set(dir, g); } // A folder is exact only when no other group's node sits anywhere under it. - const inexact = new Set(); - for (const n of nodes) { - const own = topFolder(n); - const parts = dirOf(n.path).split('/'); - for (let i = 1; i <= parts.length; i++) { - const g = groupAt.get(parts.slice(0, i).join('/')); - if (g !== undefined && g !== own) inexact.add(g); - } - } + // Sources are left out of the folders' counts, so one under a folder makes a path select more than counted. + const inexact = inexactDirs(nodes, new Set(groupAt.keys()), (n, dir) => n.kind !== 'source' && groupAt.get(dir) === topFolder(n)); const out = new Map(); for (const [g, list] of groups) { const dir = folderOf.get(g); - out.set(g, dir && !inexact.has(g) ? `path:${dir}` : [...new Set(list.map((n) => shortName(n.key)))].join(' ')); + const counted = list.filter((n) => n.kind !== 'source'); + out.set(g, dir && !inexact.has(dir) ? `path:${dir}` : [...new Set((counted.length ? counted : list).map((n) => shortName(n.key)))].join(' ')); } return out; } diff --git a/ui/src/lib/state/catalog-feed.ts b/ui/src/lib/state/catalog-feed.ts index 1a6b6a9a75..91175b836d 100644 --- a/ui/src/lib/state/catalog-feed.ts +++ b/ui/src/lib/state/catalog-feed.ts @@ -6,7 +6,8 @@ import { applyNodeStates, deltaAction } from '$lib/api/node-states'; const SIGNAL_PAUSE_MS = 300; /** `changedBuild` comes with the node states; null until they are read, or when the server has none. */ -export type CatalogView = { nodes: CatalogNode[] | undefined; error: string | null; loading: boolean; changedBuild: ChangedBuild | null }; +/** `scopeKey` is the location key the view holds nodes for, so a reader can tell them from another target's. */ +export type CatalogView = { nodes: CatalogNode[] | undefined; error: string | null; loading: boolean; changedBuild: ChangedBuild | null; scopeKey?: string | null }; const message = (reason: unknown) => (reason instanceof Error ? reason.message : String(reason)); @@ -98,7 +99,7 @@ export class CatalogFeed { } #set(view: Partial) { - this.#view = { ...this.#view, ...view }; + this.#view = { ...this.#view, ...view, scopeKey: this.#scope?.locationId ?? null }; this.publish(this.#view); } diff --git a/ui/src/routes/+page.svelte b/ui/src/routes/+page.svelte index af09f5686c..1dd3e79701 100644 --- a/ui/src/routes/+page.svelte +++ b/ui/src/routes/+page.svelte @@ -1,4 +1,6 @@ @@ -158,6 +236,10 @@
{view.title}

{view.detail}

+ {#if conditionFor(item)?.lapsed} + {@const lapsed = conditionFor(item)!.lapsed!} +

Back on the list: {lapsed.reason} (acknowledged by {lapsed.by} {formatAgo(lapsed.at, app.now)}).

+ {/if} {#if view.consequences.length}
    {#each view.consequences as c, i (i)}
  • {c.text}
  • {/each} @@ -166,9 +248,10 @@
{view.since} - {#if 'acknowledged' in item && canAcknowledge} - {/if} @@ -187,21 +270,21 @@ {/if} {#if handled.length}
- (showHandled = !showHandled)} class="h-[34px] pr-3.5 pl-[17px] text-[12px]">Acknowledged · {handled.length} + (showHandled = !showHandled)} class="h-[34px] pr-3.5 pl-[17px] text-[12px]">Acknowledged ({handled.length}) {#if showHandled}
{#each handled as { item, view } (view.key)} - {@const ack = acknowledgementOf(item)} + {@const ack = acknowledgementOf(item) ?? { by: 'you', at: new Date(app.now).toISOString(), until: 'acknowledged' in item ? undefined : snoozeSeconds === null ? null : new Date(app.now + snoozeSeconds * 1000).toISOString() }}
{view.title} -

{ack ? `Acknowledged by ${ack.by} · ${formatAgo(ack.at, app.now)}` : ''}

+

{ack ? `Acknowledged by ${ack.by} · ${formatAgo(ack.at, app.now)} · ${handledLabel(ack.until)}` : ''}

{view.since} - {#if 'acknowledged' in item && canAcknowledge} - + {#if canAck(item)} + {/if} {view.action} → @@ -272,8 +355,8 @@ {:else}
{#if overview.data === undefined && !overview.error}{:else}Nothing deployed yet.{/if}
{/each} - {#if collapsedHidden} - + {#if folders.total > folders.rows.length} + All {folders.total} folders ({folders.attention} need attention) → {/if}
{/if} @@ -344,6 +427,13 @@ .issue-actions { justify-content: flex-end; gap: 10px; } .issue-actions a { color: var(--primary); font-weight: 500; white-space: nowrap; } .handled { border-top: 1px solid var(--inner-line); } + .all-folders { align-self: flex-start; margin: 6px 16px 4px; color: var(--primary); font-size: 12px; font-weight: 500; } + .all-folders:hover { text-decoration: underline; } + .lapsed { margin: 4px 0 0; color: var(--sb-warning); font-size: 12px; } + /* Ack: muted text with a bell, always visible; on row hover it gains a border and full colour. */ + .issue :global(.ack) { height: 24px; padding: 0 8px; border: 1px solid transparent; color: var(--muted-foreground); font-size: 12px; font-weight: 500; } + .issue:hover :global(.ack), .issue :global(.ack:focus-visible) { border-color: var(--border); background: var(--sb-hover); color: var(--foreground); } + .issue :global(.ack:hover) { border-color: var(--muted-foreground); } .issue.muted .issue-title { color: var(--muted-foreground); font-weight: 500; } .ack-error { margin: 0; padding: 8px 17px; border-top: 1px solid var(--inner-line); color: var(--sb-error); font-size: 12px; } .issue-icon { display: grid; width: 22px; height: 22px; place-items: center; border-radius: 2px; } diff --git a/ui/src/routes/catalog/+page.svelte b/ui/src/routes/catalog/+page.svelte index 942ac55509..dcf94d62ee 100644 --- a/ui/src/routes/catalog/+page.svelte +++ b/ui/src/routes/catalog/+page.svelte @@ -25,6 +25,7 @@ import { folderOf } from '$lib/lineage/catalog-graph'; import { app } from '$lib/state/app.svelte'; import { useCatalogNodes } from '$lib/state/catalog.svelte'; + import FolderTree from '$lib/components/build-area/folder-tree.svelte'; import DataTable from '$lib/components/list/data-table.svelte'; import type { TableColumn } from '$lib/components/list/table-columns'; import { formatAgo, formatStamp } from '$lib/format/time'; @@ -40,7 +41,25 @@ const params = page.url.searchParams; let query = $state(params.get('q') ?? ''); let kindFilter = $state<'all' | KindTab>(parseKindTab(params.get('kind')) ?? 'all'); - let statusFilter = $state(params.get('stale') ? ['stale'] : []); + const STATUS_FILTERS: StatusFilter[] = ['stale', 'changed', 'behind', 'failed', 'warn']; + // `?status=` comes from links such as a folder's failed count; `?stale=1` from older ones. + let statusFilter = $state([...(params.get('stale') ? ['stale' as const] : []), ...STATUS_FILTERS.filter((s) => params.getAll('status').includes(s))]); + // The nodes grouped by folder, as a tree, or listed; kept in `?view=`. + let byFolder = $state(params.get('view') === 'folders'); + async function showFolders(on: boolean) { + byFolder = on; + const url = new URL(page.url); + if (on) url.searchParams.set('view', 'folders'); + else url.searchParams.delete('view'); + await goto(url, { replaceState: true, noScroll: true, keepFocus: true }); + } + /** Opens a folder's nodes, or its nodes of one status, in the list. The view leaves the URL first, so the + * selection bar then writes its selection onto that URL, after it, not at the same time. */ + async function openFolder(select: string, status: string | null) { + statusFilter = status ? [status as StatusFilter] : []; + await showFolders(false); + selection.select = select; + } // What `sqb build -s … --exclude …` selects, kept in the URL; Status only changes the view. const selection = createSelection({ url: true, replaces: ['group'] }); // Older links name top-level folders with `?group=`: once the nodes are known, each becomes its selection. @@ -140,6 +159,7 @@ : []} > {#snippet filters()} + {#if showBuildState} showFolders(v === 'folders')} />{/if} {#if picked.size}{/if} +{#if byFolder && showBuildState} + +{:else} n.key} rowHeight={ROW_H} resource={catalog} empty={all.length ? 'No nodes match the filter.' : 'Nothing deployed yet.'}> {#snippet row(n)} {@const Glyph = nodeIcon[nodeIconKey(n)] ?? nodeIcon.table} @@ -188,6 +211,7 @@ {/snippet} +{/if}