From 982c4e4a34f0b2a4a48872e4585225bcc2dac604 Mon Sep 17 00:00:00 2001 From: Alexey <247128645+axkurcom@users.noreply.github.com> Date: Sat, 7 Nov 2026 08:05:22 +0300 Subject: [PATCH] API: expose observability settings and fix cross-generation cache races --- src/api/config_edit.rs | 61 ++- .../config_edit/api_observability_tests.rs | 508 ++++++++++++++++++ src/api/config_edit/preparation.rs | 90 +++- src/api/config_edit/tests.rs | 11 +- src/api/config_store.rs | 17 +- src/api/discovery/http_tests.rs | 1 + src/api/discovery/schema.rs | 20 +- src/api/discovery/schema/tests.rs | 12 +- src/api/handler.rs | 1 + src/api/mod.rs | 6 + src/api/observability_cache_tests.rs | 206 +++++++ src/api/runtime_edge.rs | 8 +- src/api/runtime_stats.rs | 3 + src/api/users/period_tests.rs | 1 + tools/generate_api_openapi.py | 31 +- tools/telemt_api.py | 30 +- tools/telemt_api_cli.py | 14 +- tools/tests/test_telemt_api.py | 24 +- tools/tests/test_telemt_api_cli.py | 32 ++ 19 files changed, 1024 insertions(+), 52 deletions(-) create mode 100644 src/api/config_edit/api_observability_tests.rs create mode 100644 src/api/observability_cache_tests.rs diff --git a/src/api/config_edit.rs b/src/api/config_edit.rs index 1da9f00..c950acb 100644 --- a/src/api/config_edit.rs +++ b/src/api/config_edit.rs @@ -8,9 +8,9 @@ use toml::Value as Toml; use super::ApiShared; use super::config_store::{ - EDITABLE_NETWORK_FIELDS, EDITABLE_SECTIONS, EDITABLE_SERVER_FIELDS, compute_snapshot_revision, - is_editable_section, load_config_snapshot, render_server_listeners, render_top_level_section, - resolve_single_source_owner, upsert_dns_overrides, upsert_toml_table, + EDITABLE_NETWORK_FIELDS, EDITABLE_SECTIONS, EDITABLE_SERVER_API_FIELDS, EDITABLE_SERVER_FIELDS, + compute_snapshot_revision, is_editable_section, load_config_snapshot, render_server_listeners, + render_top_level_section, resolve_single_source_owner, upsert_dns_overrides, upsert_toml_table, }; #[cfg(test)] use super::config_store::{write_atomic, write_atomic_if_unchanged}; @@ -25,6 +25,8 @@ use serde::Serialize; use std::path::{Path, PathBuf}; use std::sync::Arc; +#[cfg(test)] +mod api_observability_tests; mod diagnostics; mod preflight; mod preparation; @@ -250,7 +252,23 @@ fn filter_server_for_read(server: &Toml) -> Option { } } } - out.insert((*field).to_string(), value.clone()); + if *field == "api" { + if let Some(api) = value.as_table() { + out.insert( + "api".to_owned(), + Toml::Table( + api.iter() + .filter(|(key, _)| { + EDITABLE_SERVER_API_FIELDS.contains(&key.as_str()) + }) + .map(|(key, value)| (key.clone(), value.clone())) + .collect(), + ), + ); + } + } else { + out.insert((*field).to_string(), value.clone()); + } } } if out.is_empty() { @@ -261,20 +279,15 @@ fn filter_server_for_read(server: &Toml) -> Option { } /// Reject any `[server]` patch keys outside [`EDITABLE_SERVER_FIELDS`]. -fn validate_server_patch(server: &Toml) -> Result<(), ApiFailure> { - let Some(table) = server.as_table() else { +fn validate_server_patch(server: &Json) -> Result<(), ApiFailure> { + let Some(table) = server.as_object() else { return Err(ApiFailure::new( hyper::StatusCode::BAD_REQUEST, "section_not_editable", "server patch must be a JSON object", )); }; - if table.is_empty() { - return Err(ApiFailure::bad_request( - "empty server patch: provide at least one editable field \ - (currently: listeners)", - )); - } + // Validate original keys before null removal, including forbidden siblings. for key in table.keys() { if !EDITABLE_SERVER_FIELDS.contains(&key.as_str()) { return Err(ApiFailure::new( @@ -288,6 +301,30 @@ fn validate_server_patch(server: &Toml) -> Result<(), ApiFailure> { )); } } + if let Some(api) = table.get("api").filter(|api| !api.is_null()) { + let fields = api + .as_object() + .ok_or_else(|| ApiFailure::bad_request("server.api patch must be a JSON object"))?; + for key in fields.keys() { + if !EDITABLE_SERVER_API_FIELDS.contains(&key.as_str()) { + return Err(ApiFailure::new( + hyper::StatusCode::BAD_REQUEST, + "field_not_editable", + format!("server.api.{key} is not editable via the config API"), + )); + } + } + } + let has_listeners = table.get("listeners").is_some_and(|value| !value.is_null()); + let has_api_fields = table + .get("api") + .and_then(Json::as_object) + .is_some_and(|fields| fields.values().any(|value| !value.is_null())); + if !has_listeners && !has_api_fields { + return Err(ApiFailure::bad_request( + "empty server patch: provide listeners or an editable server.api field", + )); + } Ok(()) } diff --git a/src/api/config_edit/api_observability_tests.rs b/src/api/config_edit/api_observability_tests.rs new file mode 100644 index 0000000..6f7621c --- /dev/null +++ b/src/api/config_edit/api_observability_tests.rs @@ -0,0 +1,508 @@ +use super::*; +use crate::api::discovery::http_tests::Fixture; +use crate::config::hot_reload::spawn_config_watcher; +use crate::maestro::{generation::test_runtime_generation, reload::ReloadControl}; +use serde_json::json; +use std::time::Duration; +use tokio::sync::watch; +use tokio_util::sync::CancellationToken; + +const API: &str = "[server.api] # keep API perimeter\nenabled=true\nlisten='127.0.0.1:9092'\nread_only=false\nauth_header='Bearer discovery-test' # keep secret\nwhitelist=['127.0.0.1/32']\ngray_action='api'\nrequest_body_limit_bytes=4096\nruntime_edge_events_capacity=64\nminimal_runtime_enabled=false\nruntime_edge_enabled=false\n"; + +fn patch(fields: Json) -> Json { + json!({"server": {"api": fields}}) +} + +#[tokio::test] +async fn get_exposes_exactly_five_settings_and_defaults_without_api_secrets() { + for source in ["", API] { + let (path, _directory) = tests::temp_config(source); + let (managed, _) = read_managed_config(&path).await.unwrap(); + let fields = managed["server"]["api"].as_table().unwrap(); + let config = ProxyConfig::load(&path).unwrap(); + let typed = toml::Value::try_from(&config.server.api).unwrap(); + assert_eq!(fields.len(), 5); + for (key, value) in fields { + assert!(EDITABLE_SERVER_API_FIELDS.contains(&key.as_str())); + assert_eq!(*value, typed[key]); + } + assert!(!managed.to_string().contains("discovery-test")); + } +} + +#[tokio::test] +async fn every_forbidden_api_sibling_and_alias_is_rejected_even_when_null() { + let (path, _directory) = tests::temp_config(API); + let original = std::fs::read(&path).unwrap(); + let api = serde_json::to_value(ProxyConfig::default().server.api).unwrap(); + for (key, value) in api.as_object().unwrap() { + if EDITABLE_SERVER_API_FIELDS.contains(&key.as_str()) { + continue; + } + for value in [value.clone(), Json::Null] { + let error = apply_patch_to_path( + &path, + &patch(json!({key: value, "runtime_edge_enabled": true})), + None, + ) + .await + .unwrap_err(); + assert_eq!(error.code, "field_not_editable", "{key}: {error:?}"); + assert_eq!(std::fs::read(&path).unwrap(), original); + } + } + for body in [ + patch(json!({"typo": null, "runtime_edge_enabled": true})), + json!({"server": {"admin_api": null, "api": {"runtime_edge_enabled": true}}}), + json!({"server": {"port": null, "api": {"runtime_edge_enabled": true}}}), + ] { + assert_eq!( + apply_patch_to_path(&path, &body, None) + .await + .unwrap_err() + .code, + "field_not_editable" + ); + assert_eq!(std::fs::read(&path).unwrap(), original); + } +} + +#[tokio::test] +async fn observability_bounds_and_types_are_checked_before_persistence() { + let (path, _directory) = tests::temp_config(API); + for (key, good, bad) in [ + ( + "minimal_runtime_cache_ttl_ms", + vec![json!(0), json!(60_000)], + vec![json!(-1), json!(60_001), json!(1.5), json!(false)], + ), + ( + "runtime_edge_cache_ttl_ms", + vec![json!(0), json!(60_000)], + vec![json!(-1), json!(60_001), json!("0")], + ), + ( + "runtime_edge_top_n", + vec![json!(1), json!(1000)], + vec![json!(0), json!(1001), json!(-1), json!([])], + ), + ( + "minimal_runtime_enabled", + vec![json!(true), json!(false)], + vec![json!(0), json!("true")], + ), + ( + "runtime_edge_enabled", + vec![json!(true), json!(false)], + vec![json!(1), json!({})], + ), + ] { + for value in good { + apply_patch_to_path(&path, &patch(json!({key: value})), None) + .await + .unwrap(); + assert_eq!( + serde_json::to_value(ProxyConfig::load(&path).unwrap().server.api).unwrap()[key], + value + ); + } + let original = std::fs::read(&path).unwrap(); + for value in bad { + let error = apply_patch_to_path(&path, &patch(json!({key: value})), None) + .await + .unwrap_err(); + assert_eq!( + error.status, + hyper::StatusCode::BAD_REQUEST, + "{key}: {error:?}" + ); + assert_eq!(std::fs::read(&path).unwrap(), original); + } + } + let original = std::fs::read(&path).unwrap(); + for value in [ + json!(null), + json!({}), + json!([]), + json!(false), + json!({"runtime_edge_top_n": null}), + ] { + assert!( + apply_patch_to_path(&path, &patch(value), None) + .await + .is_err() + ); + assert_eq!(std::fs::read(&path).unwrap(), original); + } +} + +#[tokio::test] +async fn sparse_observability_patch_preserves_perimeter_listeners_and_comments() { + let source = format!("{API}\n[[server.listeners]]\nip='127.0.0.1'\nport=443\n"); + let (path, _directory) = tests::temp_config(&source); + let before = ProxyConfig::load(&path).unwrap(); + let mut response = apply_patch_to_path( + &path, + &patch(json!({ + "minimal_runtime_enabled": true, "minimal_runtime_cache_ttl_ms": 0, + "runtime_edge_enabled": true, "runtime_edge_cache_ttl_ms": 60_000, + "runtime_edge_top_n": 1, + })), + None, + ) + .await + .unwrap(); + let after = ProxyConfig::load(&path).unwrap(); + reconcile_runtime_effect(&mut response, &before, &after).unwrap(); + assert!(response.restart_required); + assert!(response.runtime_reload_required); + assert!(!response.process_restart_required); + assert!(response.deferred_process_fields.is_empty()); + assert_eq!(response.changed_paths.len(), 5); + let mut restored = after.clone(); + for field in EDITABLE_SERVER_API_FIELDS { + let mut api = serde_json::to_value(&restored.server.api).unwrap(); + api[*field] = serde_json::to_value(&before.server.api).unwrap()[*field].clone(); + restored.server.api = serde_json::from_value(api).unwrap(); + } + assert_eq!( + serde_json::to_value(restored).unwrap(), + serde_json::to_value(&before).unwrap() + ); + let written = std::fs::read_to_string(&path).unwrap(); + for line in source.lines().filter(|line| { + !line.starts_with("minimal_runtime_enabled=") && !line.starts_with("runtime_edge_enabled=") + }) { + assert!(written.contains(line), "{line}: {written}"); + } + let response = apply_patch_to_path( + &path, + &patch(json!({"runtime_edge_top_n": 2, "runtime_edge_enabled": null})), + None, + ) + .await + .unwrap(); + assert_eq!(response.changed_paths, ["server.api.runtime_edge_top_n"]); + assert!( + ProxyConfig::load(&path) + .unwrap() + .server + .api + .runtime_edge_enabled + ); +} + +#[tokio::test] +async fn precise_api_edits_preserve_inline_dotted_quoted_and_legacy_source_shapes() { + for source in [ + "server = { api = { auth_header = 'secret', runtime_edge_top_n = 10 } }\n", + "server.api.auth_header = 'secret'\nserver.api.runtime_edge_top_n = 10\n", + "['server'.'api']\nauth_header='secret'\nruntime_edge_top_n=10 # retain\n", + "[server.admin_api]\nauth_header='secret'\nruntime_edge_top_n=10 # retain\n", + ] { + let (path, _directory) = tests::temp_config(source); + let before = ProxyConfig::load(&path).unwrap(); + apply_patch_to_path( + &path, + &patch(json!({"runtime_edge_top_n": 3, "minimal_runtime_cache_ttl_ms": 0})), + None, + ) + .await + .unwrap(); + let after = ProxyConfig::load(&path).unwrap(); + assert_eq!(after.server.api.auth_header, before.server.api.auth_header); + assert_eq!(after.server.api.runtime_edge_top_n, 3); + assert_eq!(after.server.api.minimal_runtime_cache_ttl_ms, 0); + let written = std::fs::read_to_string(&path).unwrap(); + if source.contains("admin_api") { + assert!(written.contains("[server.admin_api]")); + assert!(!written.contains("[server.api]")); + } + if source.contains("# retain") { + assert!(written.contains("# retain")); + } + } +} + +#[tokio::test] +async fn included_api_owner_is_updated_and_multiple_owners_are_rejected_atomically() { + let directory = tempfile::tempdir().unwrap(); + let root = directory.path().join("config.toml"); + let included = directory.path().join("api.toml"); + let root_text = "include=\"api.toml\"\n[general]\nlog_level='normal'\n[server]\nport=443\n"; + std::fs::write(&root, root_text).unwrap(); + std::fs::write(&included, API).unwrap(); + apply_patch_to_path(&root, &patch(json!({"runtime_edge_top_n": 3})), None) + .await + .unwrap(); + assert_eq!(std::fs::read_to_string(&root).unwrap(), root_text); + assert_eq!( + ProxyConfig::load(&root) + .unwrap() + .server + .api + .runtime_edge_top_n, + 3 + ); + for (root_text, included_text, body) in [ + ( + root_text.to_owned(), + std::fs::read_to_string(&included).unwrap(), + json!({"server":{"api":{"runtime_edge_top_n": 4}}, "general":{"log_level":"debug"}}), + ), + ( + "include=\"api.toml\"\nserver.api.minimal_runtime_enabled=false\n".to_owned(), + "server.api.runtime_edge_enabled=false\n".to_owned(), + patch(json!({"minimal_runtime_enabled":true,"runtime_edge_enabled":true})), + ), + ( + "include=\"api.toml\"\nserver.api.minimal_runtime_enabled=false\n".to_owned(), + "server.api.runtime_edge_enabled=false\n".to_owned(), + patch(json!({"runtime_edge_top_n":3})), + ), + ] { + std::fs::write(&root, &root_text).unwrap(); + std::fs::write(&included, &included_text).unwrap(); + let error = apply_patch_to_path(&root, &body, None).await.unwrap_err(); + assert_eq!(error.code, "config_patch_not_atomic", "{error:?}"); + assert_eq!(std::fs::read_to_string(&root).unwrap(), root_text); + assert_eq!(std::fs::read_to_string(&included).unwrap(), included_text); + } +} + +#[tokio::test] +async fn http_preview_watcher_and_reload_keep_diagnostics_pending_until_activation() { + let mut fixture = Fixture::new(false); + std::fs::write( + &fixture.shared.config_path, + format!("[general]\nlog_level='normal'\n{API}"), + ) + .unwrap(); + let config = Arc::new(ProxyConfig::load(&fixture.shared.config_path).unwrap()); + let (control, mut commands) = ReloadControl::channel(1); + Arc::get_mut(&mut fixture.shared).unwrap().reload_control = control; + let cancellation = CancellationToken::new(); + let _cancel_on_drop = cancellation.clone().drop_guard(); + let (activation, activated) = watch::channel(false); + let (mut receiver, _log_receiver, watcher) = spawn_config_watcher( + fixture.shared.config_path.clone(), + config.clone(), + None, + None, + cancellation.clone(), + None, + Some(activated), + Some(fixture.shared.mutation_lock.clone()), + None, + ); + let mut runtime = test_runtime_generation(1, (*config).clone()); + Arc::get_mut(&mut runtime).unwrap().config_rx = receiver.clone(); + fixture.shared.active_runtime.store(runtime); + let task = tokio::spawn(watcher); + let body = json!({"general": {"log_level": "debug"}, "server": {"api": { + "minimal_runtime_enabled":true, "runtime_edge_enabled":true, + "minimal_runtime_cache_ttl_ms":0, "runtime_edge_cache_ttl_ms":0, "runtime_edge_top_n":1, + }}}); + let original = std::fs::read(&fixture.shared.config_path).unwrap(); + let preview = fixture + .request_body("POST", "/v1/config/validate", true, Some(&body), &[]) + .await; + assert_eq!(preview.0, 200, "{}", preview.2); + let data = &preview.2["data"]; + assert_eq!(data["apply"]["watcher_paths"], json!(["general.log_level"])); + assert_eq!( + data["apply"]["generation_paths"].as_array().unwrap().len(), + 5 + ); + assert_eq!(data["apply"]["process_restart_paths"], json!([])); + assert_eq!( + std::fs::read(&fixture.shared.config_path).unwrap(), + original + ); + assert_eq!( + fixture + .request_body("PATCH", "/v1/config", false, Some(&body), &[]) + .await + .0, + 401 + ); + let response = fixture + .request_body( + "PATCH", + "/v1/config", + true, + Some(&body), + &[ + ("If-Match", data["base_revision"].as_str().unwrap()), + ( + "If-Runtime-Match", + data["runtime"]["runtime_match"].as_str().unwrap(), + ), + ], + ) + .await; + assert_eq!(response.0, 200, "{}", response.2); + assert_eq!(response.2["data"]["runtime_reload_required"], true); + assert_eq!(response.2["data"]["process_restart_required"], false); + activation.send_replace(true); + tokio::time::timeout( + Duration::from_secs(5), + receiver.wait_for(|cfg| cfg.general.log_level == crate::config::LogLevel::Debug), + ) + .await + .unwrap() + .unwrap(); + assert_eq!(receiver.borrow().server.api, config.server.api); + assert_diagnostics(&fixture, false).await; + + // Even an unchanged desired patch can explicitly request the pending reload. + let accepted = fixture + .request_body( + "PATCH", + "/v1/config?reload=instant", + true, + Some(&patch(body["server"]["api"].clone())), + &[], + ) + .await; + assert_eq!(accepted.0, 202, "{}", accepted.2); + let command = tokio::time::timeout(Duration::from_secs(5), commands.recv()) + .await + .unwrap() + .unwrap(); + assert_diagnostics(&fixture, false).await; + let resolved = resolve_reload_config(&config, &command.config).unwrap(); + assert_eq!( + resolved.effective.server.api.listen, + config.server.api.listen + ); + assert_eq!( + resolved.effective.server.api.runtime_edge_events_capacity, + 64 + ); + fixture + .shared + .active_runtime + .store(test_runtime_generation(2, resolved.effective)); + assert_diagnostics(&fixture, true).await; + assert_eq!( + fixture + .request("GET", "/v1/runtime/events/recent", true) + .await + .2["data"]["data"]["capacity"], + 64 + ); + fixture + .shared + .reload_control + .fail(command.reload_id, "fixture completed") + .await; + let disabled = patch(json!({"minimal_runtime_enabled": false, "runtime_edge_enabled": false})); + let accepted = fixture + .request_body( + "PATCH", + "/v1/config?reload=drain&timeout_secs=30", + true, + Some(&disabled), + &[], + ) + .await; + assert_eq!(accepted.0, 202, "{}", accepted.2); + assert_diagnostics(&fixture, true).await; + let command = commands.recv().await.unwrap(); + fixture + .shared + .active_runtime + .store(test_runtime_generation(3, (*command.config).clone())); + assert_diagnostics(&fixture, false).await; + assert_eq!(fixture.request("GET", "/v1/health", true).await.0, 200); + cancellation.cancel(); + tokio::time::timeout(Duration::from_secs(5), task) + .await + .unwrap() + .unwrap(); +} + +async fn assert_diagnostics(fixture: &Fixture, enabled: bool) { + for path in [ + "/v1/stats/minimal/all", + "/v1/runtime/connections/summary", + "/v1/runtime/events/recent", + ] { + let (status, _, body) = fixture.request("GET", path, true).await; + assert_eq!(status, 200, "{body}"); + assert_eq!(body["data"]["enabled"], enabled, "{body}"); + if !enabled { + assert_eq!(body["data"]["reason"], "feature_disabled"); + } + } + let (_, _, caps) = fixture.request("GET", "/v1/capabilities", true).await; + for path in ["/v1/stats/minimal/all", "/v1/runtime/connections/summary"] { + let operation = caps["data"]["operations"] + .as_array() + .unwrap() + .iter() + .find(|op| op["path"] == path) + .unwrap(); + assert_eq!(operation["enabled"], enabled); + } +} + +#[tokio::test] +async fn observability_patch_obeys_read_only_and_source_revision_fences() { + let fixture = Fixture::new(false); + let body = patch(json!({"runtime_edge_enabled": true})); + let original = std::fs::read(&fixture.shared.config_path).unwrap(); + let preview = fixture + .request_body("POST", "/v1/config/validate", true, Some(&body), &[]) + .await; + assert_eq!(preview.0, 200, "{}", preview.2); + let rejected = fixture + .request_body("PATCH", "/v1/config", true, Some(&body), &[]) + .await; + assert_eq!(rejected.0, 403); + assert_eq!(rejected.2["error"]["code"], "read_only"); + assert_eq!( + std::fs::read(&fixture.shared.config_path).unwrap(), + original + ); + let prepared = prepare_patch_to_path(&fixture.shared.config_path, &body, None) + .await + .unwrap(); + let external = "# external source change\n"; + std::fs::write(&fixture.shared.config_path, external).unwrap(); + let conflict = write_atomic_if_unchanged( + prepared.config_path, + prepared.expected_revision, + prepared.owner_path, + prepared.expected_owner_contents, + prepared.owner_contents, + ) + .await + .unwrap_err(); + assert_eq!(conflict.code, "revision_conflict"); + assert_eq!( + std::fs::read_to_string(&fixture.shared.config_path).unwrap(), + external + ); +} + +#[tokio::test] +async fn listeners_and_observability_in_one_owner_preserve_each_other() { + let (path, _directory) = tests::temp_config(API); + apply_patch_to_path( + &path, + &json!({"server": { + "listeners": [{"ip": "127.0.0.1", "port": 8443}], + "api": {"runtime_edge_enabled": true}, + }}), + None, + ) + .await + .unwrap(); + let config = ProxyConfig::load(&path).unwrap(); + assert_eq!(config.server.listeners.len(), 1); + assert_eq!(config.server.listeners[0].port, Some(8443)); + assert!(config.server.api.runtime_edge_enabled); + assert_eq!(config.server.api.auth_header, "Bearer discovery-test"); +} diff --git a/src/api/config_edit/preparation.rs b/src/api/config_edit/preparation.rs index b672460..4e9980a 100644 --- a/src/api/config_edit/preparation.rs +++ b/src/api/config_edit/preparation.rs @@ -1,5 +1,6 @@ //! One source-preserving candidate pipeline shared by preview and commit. use super::*; +use crate::api::config_store::{FieldEdit, prepare_field_edits}; use crate::config::{LoadedConfig, ParsedConfigSource}; use tokio::sync::OwnedSemaphorePermit; @@ -82,7 +83,7 @@ fn parse_patch( "access.* is managed via the users API, not editable here", )); } - for (key, value) in patch_table { + for key in patch_table.keys() { if !is_editable_section(key.as_str()) { return Err(ApiFailure::new( hyper::StatusCode::BAD_REQUEST, @@ -91,7 +92,7 @@ fn parse_patch( )); } if key == "server" { - validate_server_patch(value)?; + validate_server_patch(&patch_json["server"])?; } else if key == "network" { validate_network_patch(&patch_json["network"])?; } @@ -127,30 +128,59 @@ fn parse_patch( .validate() .map_err(|error| diagnostics::validation_error("constraint_violation", "$", error))?; + let api_edits = api_field_edits(&loaded, &patch_toml)?; + let api_source = prepare_field_edits(&loaded, config_path, &api_edits) + .map_err(diagnostics::source_conflict)?; + let patch_listeners = patch_toml + .get("server") + .is_some_and(|server| server.get("listeners").is_some()); let ownership_targets: Vec<&str> = touched .iter() - .map(|section| { + .filter_map(|section| { if section == "server" { - "server.listeners" + patch_listeners.then_some("server.listeners") } else if section == "network" { - "network.dns_overrides" + Some("network.dns_overrides") } else { - section.as_str() + Some(section.as_str()) } }) .collect(); - let owner_path = resolve_single_source_owner(&loaded, config_path, &ownership_targets) - .map_err(diagnostics::source_conflict)?; + let section_owner = if ownership_targets.is_empty() { + None + } else { + Some( + resolve_single_source_owner(&loaded, config_path, &ownership_targets) + .map_err(diagnostics::source_conflict)?, + ) + }; + if let (Some(owner), Some(api)) = (§ion_owner, &api_source) { + if *owner != api.owner_path { + return Err(ApiFailure::new( + hyper::StatusCode::CONFLICT, + "config_patch_not_atomic", + "Mutation requires one independently writable config source", + )); + } + } + let owner_path = section_owner + .or_else(|| api_source.as_ref().map(|source| source.owner_path.clone())) + .ok_or_else(|| ApiFailure::bad_request("empty patch: no editable fields"))?; let mut owner_contents = loaded .source_contents .get(&owner_path) .cloned() .ok_or_else(|| ApiFailure::internal("config source owner is missing from snapshot"))?; let expected_owner_contents = owner_contents.clone(); + if let Some(api) = api_source { + owner_contents = api.owner_contents; + } for section in &touched { if *section == "server" { - let rendered = render_server_listeners(&requested_cfg)?; - owner_contents = upsert_toml_table(&owner_contents, "server.listeners", &rendered); + if patch_listeners { + let rendered = render_server_listeners(&requested_cfg)?; + owner_contents = upsert_toml_table(&owner_contents, "server.listeners", &rendered); + } } else if *section == "network" { owner_contents = upsert_dns_overrides(&owner_contents, &requested_cfg.network.dns_overrides)?; @@ -164,7 +194,7 @@ fn parse_patch( overrides.insert(owner_path.clone(), owner_contents.clone()); let candidate = ProxyConfig::parse_source_with_overrides(config_path, &overrides) .map_err(|error| diagnostics::validation_error("constraint_violation", "$", error))?; - if touched.iter().any(|section| section == "server") + if patch_listeners && serde_json::to_value(&candidate.config.server.listeners).ok() != serde_json::to_value(&requested_cfg.server.listeners).ok() { @@ -191,6 +221,44 @@ fn parse_patch( )) } +fn api_field_edits( + loaded: &ParsedConfigSource, + patch: &Toml, +) -> Result, ApiFailure> { + let Some(fields) = patch + .get("server") + .and_then(|server| server.get("api")) + .and_then(Toml::as_table) + else { + return Ok(Vec::new()); + }; + if fields.is_empty() { + return Ok(Vec::new()); + } + // PATCH uses canonical paths, while an authored legacy table keeps its name. + let mut table_name = "api"; + for source in loaded.source_contents.values() { + let document: Toml = toml::from_str(source).map_err(|_| { + ApiFailure::new( + hyper::StatusCode::CONFLICT, + "config_patch_not_atomic", + "Mutation requires one independently writable config source", + ) + })?; + if document + .get("server") + .and_then(|server| server.get("admin_api")) + .is_some() + { + table_name = "admin_api"; + } + } + Ok(fields + .iter() + .map(|(field, value)| FieldEdit::new(&["server", table_name, field], Some(value.clone()))) + .collect()) +} + fn finish( source: PatchSource, candidate: LoadedConfig, diff --git a/src/api/config_edit/tests.rs b/src/api/config_edit/tests.rs index 556ca51..0b0e407 100644 --- a/src/api/config_edit/tests.rs +++ b/src/api/config_edit/tests.rs @@ -228,8 +228,7 @@ async fn invalid_web_patch_does_not_modify_the_source() { #[tokio::test] async fn read_managed_config_returns_only_editable_sections() { - // Server identity and network siblings must not leak. Listeners-only server - // is returned via the nested allowlist (covered in a dedicated test). + // Server identity and network siblings must not leak through nested allowlists. let (path, _d) = temp_config(concat!( "[censorship]\ntls_domain = \"a\"\n", "[server]\nport = 443\n[server.api]\nauth_header = \"SECRET\"\n", @@ -241,7 +240,8 @@ async fn read_managed_config_returns_only_editable_sections() { assert!(table.contains_key("censorship")); let server = table["server"].as_table().unwrap(); assert!(server.contains_key("listeners")); - assert!(!server.contains_key("api")); + assert_eq!(server["api"].as_table().unwrap().len(), 5); + assert!(server["api"].get("auth_header").is_none()); assert!(!server.contains_key("port")); assert_eq!( serde_json::to_value(&table["network"]).unwrap(), @@ -251,7 +251,7 @@ async fn read_managed_config_returns_only_editable_sections() { } #[tokio::test] -async fn read_managed_config_returns_server_listeners_only() { +async fn read_managed_config_returns_server_listeners_and_api_observability() { let (path, _d) = temp_config(concat!( "[censorship]\ntls_domain = \"a\"\n", "[server]\nport = 443\n", @@ -266,7 +266,8 @@ async fn read_managed_config_returns_server_listeners_only() { .as_table() .unwrap(); assert!(server.contains_key("listeners")); - assert!(!server.contains_key("api")); + assert_eq!(server["api"].as_table().unwrap().len(), 5); + assert!(server["api"].get("auth_header").is_none()); assert!(!server.contains_key("port")); let listeners = server["listeners"].as_array().unwrap(); assert_eq!(listeners.len(), 1); diff --git a/src/api/config_store.rs b/src/api/config_store.rs index 14ee747..0451d9f 100644 --- a/src/api/config_store.rs +++ b/src/api/config_store.rs @@ -326,9 +326,9 @@ pub(super) async fn save_config_to_disk( /// located or replaced safely, so it is edited via `general`. /// /// `server` is partially editable: only the nested fields listed in -/// [`EDITABLE_SERVER_FIELDS`] (currently `listeners`) may appear in GET/PATCH. -/// Secrets and bind identity (`api`/`admin_api`, `port`, unix sockets, …) stay -/// blocked. `network` is also partial: only [`EDITABLE_NETWORK_FIELDS`] are +/// [`EDITABLE_SERVER_FIELDS`] may appear in GET/PATCH; `api` is further restricted +/// to [`EDITABLE_SERVER_API_FIELDS`]. Secrets and bind identity stay blocked. +/// `network` is also partial: only [`EDITABLE_NETWORK_FIELDS`] are /// exposed, retaining the boundary around per-node identity and routing policy. pub(super) const EDITABLE_SECTIONS: &[&str] = &[ "general", @@ -343,7 +343,16 @@ pub(super) const EDITABLE_SECTIONS: &[&str] = &[ /// /// Arrays (e.g. `listeners`) replace wholesale on PATCH, matching the existing /// merge semantics for non-table values. -pub(super) const EDITABLE_SERVER_FIELDS: &[&str] = &["listeners"]; +pub(super) const EDITABLE_SERVER_FIELDS: &[&str] = &["listeners", "api"]; + +/// Diagnostics settings applied by explicit generation reload, not the watcher. +pub(super) const EDITABLE_SERVER_API_FIELDS: &[&str] = &[ + "minimal_runtime_enabled", + "minimal_runtime_cache_ttl_ms", + "runtime_edge_enabled", + "runtime_edge_cache_ttl_ms", + "runtime_edge_top_n", +]; /// Only the generation resolver's overrides may be read/patched under `network`. pub(super) const EDITABLE_NETWORK_FIELDS: &[&str] = &["dns_overrides"]; diff --git a/src/api/discovery/http_tests.rs b/src/api/discovery/http_tests.rs index 57ae903..34a3088 100644 --- a/src/api/discovery/http_tests.rs +++ b/src/api/discovery/http_tests.rs @@ -38,6 +38,7 @@ impl Fixture { }]; let runtime = test_runtime_generation(1, config.clone()); let shared = ApiShared { + runtime_generation: runtime.id, stats: runtime.stats.clone(), ip_tracker: runtime.ip_tracker.clone(), me_pool: runtime.me_pool_runtime.clone(), diff --git a/src/api/discovery/schema.rs b/src/api/discovery/schema.rs index ad1789c..5ce8908 100644 --- a/src/api/discovery/schema.rs +++ b/src/api/discovery/schema.rs @@ -6,7 +6,7 @@ use serde::{Deserialize, Serialize}; use serde_json::Value; use super::super::config_store::{ - EDITABLE_NETWORK_FIELDS, EDITABLE_SECTIONS, EDITABLE_SERVER_FIELDS, + EDITABLE_NETWORK_FIELDS, EDITABLE_SECTIONS, EDITABLE_SERVER_API_FIELDS, EDITABLE_SERVER_FIELDS, }; use super::super::model::ApiFailure; use super::SCHEMA_VERSION; @@ -204,13 +204,19 @@ fn field_api(path: &str) -> FieldApi { || path .strip_prefix("network.") .is_some_and(|field| EDITABLE_NETWORK_FIELDS.contains(&field)) + || path + .strip_prefix("server.api.") + .is_some_and(|field| EDITABLE_SERVER_API_FIELDS.contains(&field)) || (top == "server" - && EDITABLE_SERVER_FIELDS.iter().any(|field| { - let prefix = format!("server.{field}"); - path == prefix - || path.starts_with(&format!("{prefix}[")) - || path.starts_with(&format!("{prefix}.")) - })); + && EDITABLE_SERVER_FIELDS + .iter() + .filter(|field| **field != "api") + .any(|field| { + let prefix = format!("server.{field}"); + path == prefix + || path.starts_with(&format!("{prefix}[")) + || path.starts_with(&format!("{prefix}.")) + })); let policy_field = path.strip_prefix("access.").and_then(|path| { let field = path.split('.').next()?; crate::api::access_policy::FIELDS diff --git a/src/api/discovery/schema/tests.rs b/src/api/discovery/schema/tests.rs index 909ffcf..cdfdcb8 100644 --- a/src/api/discovery/schema/tests.rs +++ b/src/api/discovery/schema/tests.rs @@ -133,11 +133,13 @@ fn api_ownership_aliases_and_null_contracts_match_existing_surfaces() { let schema = config_schema().unwrap(); assert!(field(schema, "web.vhosts[].base_path").api.config_write); assert!(field(schema, "server.listeners[].port").api.config_write); - assert!( - !field(schema, "server.api.runtime_edge_enabled") - .api - .config_write - ); + for entry in &schema.fields { + if let Some(key) = entry.spec.path.strip_prefix("server.api.") { + let editable = EDITABLE_SERVER_API_FIELDS.contains(&key); + assert_eq!(entry.api.config_read, editable, "{key}"); + assert_eq!(entry.api.config_write, editable, "{key}"); + } + } assert!(field(schema, "network.dns_overrides").api.config_read); assert!(field(schema, "network.dns_overrides").api.config_write); assert_eq!( diff --git a/src/api/handler.rs b/src/api/handler.rs index 213d6b0..f060549 100644 --- a/src/api/handler.rs +++ b/src/api/handler.rs @@ -15,6 +15,7 @@ pub(super) async fn handle( let runtime = shared.active_runtime.load_full(); let previous_cache_generation = shared.cache_generation.swap(runtime.id, Ordering::AcqRel); if previous_cache_generation != runtime.id { + // Entry generation checks also reject late writes from in-flight requests. *shared.minimal_cache.lock().await = None; *shared.runtime_edge_connections_cache.lock().await = None; } diff --git a/src/api/mod.rs b/src/api/mod.rs index 029f15d..6a3f285 100644 --- a/src/api/mod.rs +++ b/src/api/mod.rs @@ -47,6 +47,8 @@ mod http_utils; // Authenticated request admission and route dispatch. mod handler; mod model; +#[cfg(test)] +mod observability_cache_tests; mod patch; #[cfg(test)] mod reload_tests; @@ -116,6 +118,8 @@ pub(super) struct ApiRuntimeState { #[derive(Clone)] pub(super) struct ApiShared { + /// Generation pinned by this request, including cache reads and publication. + pub(super) runtime_generation: u64, pub(super) stats: Arc, pub(super) ip_tracker: Arc, pub(super) me_pool: Arc>>>, @@ -154,6 +158,7 @@ impl ApiShared { fn for_runtime(&self, runtime: &RuntimeGeneration) -> Self { Self { + runtime_generation: runtime.id, stats: runtime.stats.clone(), ip_tracker: runtime.ip_tracker.clone(), me_pool: runtime.me_pool_runtime.clone(), @@ -377,6 +382,7 @@ pub(crate) async fn serve( }); let shared = Arc::new(ApiShared { + runtime_generation: active_runtime.load().id, stats, ip_tracker, me_pool, diff --git a/src/api/observability_cache_tests.rs b/src/api/observability_cache_tests.rs new file mode 100644 index 0000000..6ea334d --- /dev/null +++ b/src/api/observability_cache_tests.rs @@ -0,0 +1,206 @@ +use super::*; +use crate::api::discovery::http_tests::Fixture; +use crate::maestro::generation::test_runtime_generation; +use std::time::Instant; + +fn enabled_config(fixture: &Fixture) -> ProxyConfig { + let mut cfg = (*fixture + .shared + .active_runtime + .load() + .config_rx + .borrow() + .clone()) + .clone(); + cfg.server.api.minimal_runtime_enabled = true; + cfg.server.api.minimal_runtime_cache_ttl_ms = 60_000; + cfg.server.api.runtime_edge_enabled = true; + cfg.server.api.runtime_edge_cache_ttl_ms = 60_000; + cfg.server.api.runtime_edge_top_n = 7; + cfg +} + +#[tokio::test] +async fn late_edge_recompute_cannot_contaminate_new_generation_reads() { + let fixture = Fixture::new(false); + let old_cfg = enabled_config(&fixture); + let old_runtime = test_runtime_generation(1, old_cfg.clone()); + let old_request = fixture.shared.for_runtime(&old_runtime); + let (release, resume) = tokio::sync::oneshot::channel(); + // A request already pinned to generation 1 finishes after generation 2's + // handler has invalidated the shared caches. + let pending = tokio::spawn(async move { + resume.await.unwrap(); + build_runtime_connections_summary_data(&old_request, &old_cfg).await + }); + let mut new_cfg = enabled_config(&fixture); + new_cfg.server.api.runtime_edge_top_n = 1; + fixture + .shared + .active_runtime + .store(test_runtime_generation(2, new_cfg)); + assert_eq!(fixture.request("GET", "/v1/health", true).await.0, 200); + release.send(()).unwrap(); + assert_eq!(pending.await.unwrap().data.unwrap().top.limit, 7); + + let mut reads = tokio::task::JoinSet::new(); + let fixture = Arc::new(fixture); + for _ in 0..16 { + let fixture = fixture.clone(); + reads.spawn(async move { + let (status, _, body) = fixture + .request("GET", "/v1/runtime/connections/summary", true) + .await; + assert_eq!(status, 200); + assert_eq!(body["data"]["enabled"], true); + if let Some(payload) = body["data"].get("data") { + assert_eq!(payload["top"]["limit"], 1, "{body}"); + assert_eq!(payload["cache"]["ttl_ms"], 60_000); + } else { + assert_eq!(body["data"]["reason"], "source_unavailable"); + } + }); + } + while let Some(result) = reads.join_next().await { + result.unwrap(); + } +} + +#[tokio::test] +async fn late_minimal_cache_publication_is_not_served_by_new_generation() { + let fixture = Fixture::new(false); + let cfg = enabled_config(&fixture); + let old_request = fixture + .shared + .for_runtime(&test_runtime_generation(1, cfg.clone())); + let payload = build_minimal_all_data(&old_request, &cfg.server.api) + .await + .data + .unwrap(); + fixture + .shared + .active_runtime + .store(test_runtime_generation(2, cfg)); + assert_eq!(fixture.request("GET", "/v1/health", true).await.0, 200); + // Model the publication of a completed old-generation pool snapshot after + // invalidation. The new generation has no pool and must report that fact. + *fixture.shared.minimal_cache.lock().await = Some(MinimalCacheEntry { + generation: 1, + expires_at: Instant::now() + Duration::from_secs(60), + payload, + generated_at_epoch_secs: 42, + }); + let (status, _, body) = fixture.request("GET", "/v1/stats/minimal/all", true).await; + assert_eq!(status, 200); + assert_eq!(body["data"]["reason"], "source_unavailable", "{body}"); + assert_ne!(body["data"]["generated_at_epoch_secs"], 42); +} + +#[tokio::test] +async fn edge_cache_respects_ttl_zero_expiry_top_n_and_recompute_contention() { + let fixture = Fixture::new(false); + let mut cfg = enabled_config(&fixture); + cfg.server.api.runtime_edge_top_n = 1; + let runtime = test_runtime_generation(1, cfg.clone()); + let request = fixture.shared.for_runtime(&runtime); + request.stats.add_user_octets_from("alice", 20); + request.stats.add_user_octets_from("bob", 10); + let fresh = build_runtime_connections_summary_data(&request, &cfg) + .await + .data + .unwrap(); + assert!(!fresh.cache.served_from_cache); + assert_eq!(fresh.top.by_throughput.len(), 1); + assert_eq!(fresh.top.by_throughput[0].username, "alice"); + request.stats.add_user_octets_from("bob", 100); + let cached = build_runtime_connections_summary_data(&request, &cfg) + .await + .data + .unwrap(); + assert!(cached.cache.served_from_cache); + assert!(!cached.cache.stale_cache_used); + assert_eq!(cached.top.by_throughput[0].username, "alice"); + request + .runtime_edge_connections_cache + .lock() + .await + .as_mut() + .unwrap() + .expires_at = Instant::now(); + let guard = request.runtime_edge_recompute_lock.lock().await; + let stale = build_runtime_connections_summary_data(&request, &cfg) + .await + .data + .unwrap(); + assert!(stale.cache.stale_cache_used); + let new_request = fixture + .shared + .for_runtime(&test_runtime_generation(2, cfg.clone())); + let unavailable = build_runtime_connections_summary_data(&new_request, &cfg).await; + assert_eq!(unavailable.reason, Some("source_unavailable")); + assert!(unavailable.data.is_none()); + cfg.server.api.runtime_edge_cache_ttl_ms = 0; + let zero = build_runtime_connections_summary_data(&request, &cfg).await; + assert_eq!(zero.reason, Some("source_unavailable")); + assert!(zero.data.is_none()); + drop(guard); + for _ in 0..2 { + let uncached = build_runtime_connections_summary_data(&request, &cfg) + .await + .data + .unwrap(); + assert_eq!(uncached.cache.ttl_ms, 0); + assert!(!uncached.cache.served_from_cache); + assert_eq!(uncached.top.by_throughput[0].username, "bob"); + } + cfg.server.api.runtime_edge_cache_ttl_ms = 60_000; + let refreshed = build_runtime_connections_summary_data(&request, &cfg) + .await + .data + .unwrap(); + assert!(!refreshed.cache.served_from_cache); + assert_eq!(refreshed.top.by_throughput[0].username, "bob"); +} + +#[tokio::test] +async fn minimal_cache_checks_generation_expiry_and_zero_ttl() { + let fixture = Fixture::new(false); + let mut cfg = enabled_config(&fixture); + let request = fixture + .shared + .for_runtime(&test_runtime_generation(1, cfg.clone())); + let payload = build_minimal_all_data(&request, &cfg.server.api) + .await + .data + .unwrap(); + *request.minimal_cache.lock().await = Some(MinimalCacheEntry { + generation: 1, + expires_at: Instant::now() + Duration::from_secs(60), + payload, + generated_at_epoch_secs: 42, + }); + let cached = build_minimal_all_data(&request, &cfg.server.api).await; + assert_eq!(cached.generated_at_epoch_secs, 42); + assert!(cached.reason.is_none()); + cfg.server.api.minimal_runtime_cache_ttl_ms = 0; + assert_eq!( + build_minimal_all_data(&request, &cfg.server.api) + .await + .reason, + Some("source_unavailable") + ); + cfg.server.api.minimal_runtime_cache_ttl_ms = 60_000; + request + .minimal_cache + .lock() + .await + .as_mut() + .unwrap() + .expires_at = Instant::now(); + assert_eq!( + build_minimal_all_data(&request, &cfg.server.api) + .await + .reason, + Some("source_unavailable") + ); +} diff --git a/src/api/runtime_edge.rs b/src/api/runtime_edge.rs index 31235bc..4f928ed 100644 --- a/src/api/runtime_edge.rs +++ b/src/api/runtime_edge.rs @@ -70,6 +70,7 @@ pub(super) struct RuntimeEdgeConnectionsSummaryData { #[derive(Clone)] pub(crate) struct EdgeConnectionsCacheEntry { + pub(super) generation: u64, pub(super) expires_at: Instant, pub(super) payload: RuntimeEdgeConnectionsSummaryPayload, pub(super) generated_at_epoch_secs: u64, @@ -270,6 +271,7 @@ async fn get_connections_payload_cached( let now = Instant::now(); let cached = shared.runtime_edge_connections_cache.lock().await.clone(); if let Some(entry) = cached + && entry.generation == shared.runtime_generation && now < entry.expires_at { let mut payload = entry.payload; @@ -281,7 +283,10 @@ async fn get_connections_payload_cached( let Ok(_guard) = shared.runtime_edge_recompute_lock.try_lock() else { let cached = shared.runtime_edge_connections_cache.lock().await.clone(); - if let Some(entry) = cached { + if let Some(entry) = cached + && cache_ttl_ms > 0 + && entry.generation == shared.runtime_generation + { let mut payload = entry.payload; payload.cache.served_from_cache = true; payload.cache.stale_cache_used = true; @@ -295,6 +300,7 @@ async fn get_connections_payload_cached( if cache_ttl_ms > 0 { let entry = EdgeConnectionsCacheEntry { + generation: shared.runtime_generation, expires_at: Instant::now() + Duration::from_millis(cache_ttl_ms), payload: payload.clone(), generated_at_epoch_secs, diff --git a/src/api/runtime_stats.rs b/src/api/runtime_stats.rs index 1563df2..fce975b 100644 --- a/src/api/runtime_stats.rs +++ b/src/api/runtime_stats.rs @@ -19,6 +19,7 @@ const SOURCE_UNAVAILABLE_REASON: &str = "source_unavailable"; #[derive(Clone)] pub(crate) struct MinimalCacheEntry { + pub(super) generation: u64, pub(super) expires_at: Instant, pub(super) payload: MinimalAllPayload, pub(super) generated_at_epoch_secs: u64, @@ -342,6 +343,7 @@ async fn get_minimal_payload_cached( let now = Instant::now(); let cached = shared.minimal_cache.lock().await.clone(); if let Some(entry) = cached + && entry.generation == shared.runtime_generation && now < entry.expires_at { return Some((entry.generated_at_epoch_secs, entry.payload)); @@ -522,6 +524,7 @@ async fn get_minimal_payload_cached( if cache_ttl_ms > 0 { let entry = MinimalCacheEntry { + generation: shared.runtime_generation, expires_at: Instant::now() + Duration::from_millis(cache_ttl_ms), payload: payload.clone(), generated_at_epoch_secs, diff --git a/src/api/users/period_tests.rs b/src/api/users/period_tests.rs index 2ce4619..7186843 100644 --- a/src/api/users/period_tests.rs +++ b/src/api/users/period_tests.rs @@ -49,6 +49,7 @@ impl Fixture { mutable.proxy_shared = proxy_shared.clone(); mutable.config_rx = config_rx; let shared = ApiShared { + runtime_generation: runtime.id, stats, ip_tracker: runtime.ip_tracker.clone(), me_pool: runtime.me_pool_runtime.clone(), diff --git a/tools/generate_api_openapi.py b/tools/generate_api_openapi.py index 0912e8c..75a84eb 100644 --- a/tools/generate_api_openapi.py +++ b/tools/generate_api_openapi.py @@ -41,6 +41,7 @@ def build_document(): "quota_period": nullable({"enum": ["daily", "weekly", "monthly"]}), "rate_limit_up_bps": nullable(count), "rate_limit_down_bps": nullable(count), "max_unique_ips": nullable(count), "enabled": nullable(boolean), + "source_deny": nullable({"type": "array", "items": {"type": "string", "format": "cidr"}}), } schemas = { "SuccessEnvelope": object_schema({"ok": {"const": True}, "data": {}, @@ -58,7 +59,17 @@ def build_document(): **{k: nullable({"type": "object"}) for k in ("general", "timeouts", "censorship", "dc_overrides", "web")}, "upstreams": nullable({"type": "array", "items": {"type": "object"}}), - "server": nullable(object_schema({"listeners": nullable({"type": "array", "items": {"type": "object"}})})), + "server": nullable(object_schema({ + "listeners": nullable({"type": "array", "items": {"type": "object"}}), + "api": nullable(object_schema({ + "minimal_runtime_enabled": nullable(boolean), + "minimal_runtime_cache_ttl_ms": nullable({"type": "integer", "minimum": 0, "maximum": 60000}), + "runtime_edge_enabled": nullable(boolean), + "runtime_edge_cache_ttl_ms": nullable({"type": "integer", "minimum": 0, "maximum": 60000}), + "runtime_edge_top_n": nullable({"type": "integer", "minimum": 1, "maximum": 1000}), + })), + })), + "network": nullable(object_schema({"dns_overrides": nullable({"type": "array", "items": string, "maxItems": 4096})})), }), "ReloadRequest": object_schema({ "mode": {"enum": ["instant", "drain"], "default": "instant"}, @@ -128,6 +139,23 @@ def build_document(): "code": {"enum": ["normalized", "null_ignored", "alias_canonicalized"]}}, ("path", "code")) schemas["RuntimeBaseline"] = object_schema({"active_generation": count, "config_epoch": count, "runtime_match": string}, ("active_generation", "config_epoch", "runtime_match")) + rates = object_schema({"up_bps": {**count, "maximum": 100000000000}, + "down_bps": {**count, "maximum": 100000000000}}) + policy = {"user_max_tcp_conns_global_each": count, "user_max_unique_ips_global_each": count, + "user_max_unique_ips_mode": {"enum": ["active_window", "time_window", "combined"]}, + "user_max_unique_ips_window_secs": {"type": "integer", "minimum": 1}, + "cidr_rate_limits": {"type": "object", "additionalProperties": rates}} + schemas["AccessPolicy"] = object_schema(policy, policy.keys()) + schemas["AccessPolicyPatch"] = {**object_schema({key: nullable(value) for key, value in policy.items()}), + "minProperties": 1, "description": "Omitted fields stay unchanged. Scalar null restores the type default. cidr_rate_limits null clears the map; otherwise keys merge, null entries delete, and non-null entries replace the whole rate pair in bits/second. At least one direction must be positive. One writable source per mutation."} + schemas["AccessPolicyPatch"]["properties"]["cidr_rate_limits"] = nullable({"type": "object", "additionalProperties": nullable(rates)}) + policy_state = {"desired": ref("AccessPolicy"), "effective": ref("AccessPolicy"), + "runtime": ref("RuntimeBaseline"), "published_match": boolean, + "effective_scope": {"const": "active_config_snapshot"}, "subsystem_convergence": {"const": "unknown"}, + "apply_mode": {"const": "watcher"}, "changed_paths": strings} + schemas["AccessPolicyData"] = object_schema(policy_state, [key for key in policy_state if key != "changed_paths"]) + schemas["AccessPolicyResponse"] = object_schema({"ok": {"const": True}, "data": ref("AccessPolicyData"), + "revision": string}, ("ok", "data", "revision")) impact = {**{k: strings for k in ("watcher_paths", "generation_paths", "process_restart_paths", "deferred_process_fields")}, **{k: boolean for k in ("restart_required", "runtime_reload_required", "process_restart_required")}} schemas["ApplyImpact"] = object_schema(impact, impact.keys()) @@ -231,6 +259,7 @@ def build_document(): "description": "Comma-separated sections; omitted selects all. One parameter only, at most 256 query bytes. Snapshots are independently sampled; comparison is not a convergence acknowledgment."}) response_schema = {"capabilities": "CapabilitiesResponse", "config_schema": "ConfigSchemaResponse", "config_validate": "ConfigValidationResponse", + "access_policy_get": "AccessPolicyResponse", "access_policy_patch": "AccessPolicyResponse", "config_state": "ConfigStateResponse"}.get(operation["id"], "SuccessEnvelope") responses = {str(status): {"description": "Success or documented state payload", "content": {"application/json": {"schema": ref(response_schema)}}} diff --git a/tools/telemt_api.py b/tools/telemt_api.py index b7d58c5..3e0d4f0 100644 --- a/tools/telemt_api.py +++ b/tools/telemt_api.py @@ -67,6 +67,9 @@ class APIResponse: # Main client # --------------------------------------------------------------------------- +_UNSET = object() + + class TelemtAPI: """ HTTP client for the Telemt Control API. @@ -229,6 +232,17 @@ class TelemtAPI: query = {"sections": ",".join(sections)} return self._get("/v1/config/state", query) + def access_policy(self) -> APIResponse: + """Desired/published access defaults and CIDR shaping, without credentials.""" + return self._get("/v1/access/policy") + + def patch_access_policy(self, patch: dict, *, if_match: str | None = None, + if_runtime_match: str | None = None) -> APIResponse: + """Preserve explicit null resets and CIDR entry deletion semantics.""" + _object(patch, "patch") + return self._request("PATCH", "/v1/access/policy", patch, if_match, + if_runtime_match=if_runtime_match) + def patch_config(self, patch: dict, *, if_match: str | None = None, if_runtime_match: str | None = None, reload: str | None = None, timeout_secs: int | None = None, failure_policy: str | None = None) -> APIResponse: @@ -413,6 +427,7 @@ class TelemtAPI: rate_limit_up_bps: int | None = None, rate_limit_down_bps: int | None = None, enabled: bool | None = None, + source_deny: list[str] | None | object = _UNSET, if_match: str | None = None, ) -> APIResponse: """POST /v1/users — create a new user. @@ -436,9 +451,12 @@ class TelemtAPI: quota_period: Optional UTC recurring period: daily, weekly or monthly. rate_limit_up_bps, rate_limit_down_bps: - Per-user upload/download byte rates; zero values are transmitted. + Per-user upload/download bit rates; zero values are transmitted. enabled: Optional admission flag; False is transmitted. + source_deny: + Source CIDRs; omission retains an orphan rule, None removes it. + Changes require a generation reload. if_match: Optional ``If-Match`` revision for optimistic concurrency. """ @@ -453,6 +471,8 @@ class TelemtAPI: _opt(body, "rate_limit_up_bps", rate_limit_up_bps) _opt(body, "rate_limit_down_bps", rate_limit_down_bps) _opt(body, "enabled", enabled) + if source_deny is not _UNSET: + body["source_deny"] = source_deny return self._post("/v1/users", body=body, if_match=if_match) def patch_user( @@ -469,6 +489,7 @@ class TelemtAPI: rate_limit_up_bps: int | None = None, rate_limit_down_bps: int | None = None, enabled: bool | None = None, + source_deny: list[str] | None = None, if_match: str | None = None, ) -> APIResponse: """PATCH /v1/users/{username} — partial update; only provided fields change. @@ -490,8 +511,10 @@ class TelemtAPI: max_unique_ips: New unique IP limit. quota_period, rate_limit_up_bps, rate_limit_down_bps, enabled: - Recurring quota, byte rates and admission flag. None omits a field, + Recurring quota, bit rates and admission flag. None omits a field, preserving the legacy helper contract; use patch_user_fields to clear. + source_deny: + Replace the source CIDR list; use patch_user_fields to send null. if_match: Optional ``If-Match`` revision. """ @@ -506,6 +529,7 @@ class TelemtAPI: _opt(body, "rate_limit_up_bps", rate_limit_up_bps) _opt(body, "rate_limit_down_bps", rate_limit_down_bps) _opt(body, "enabled", enabled) + _opt(body, "source_deny", source_deny) return self.patch_user_fields(username, body, if_match=if_match) def patch_user_fields(self, username: str, fields: dict, *, if_match: str | None = None) -> APIResponse: @@ -665,7 +689,7 @@ class TelemtAPI: # --------------------------------------------------------------------------- USER_FIELDS = {"secret", "user_ad_tag", "max_tcp_conns", "expiration_rfc3339", "data_quota_bytes", - "quota_period", "rate_limit_up_bps", "rate_limit_down_bps", "max_unique_ips", "enabled"} + "quota_period", "rate_limit_up_bps", "rate_limit_down_bps", "max_unique_ips", "enabled", "source_deny"} def _safe(value: str) -> str: diff --git a/tools/telemt_api_cli.py b/tools/telemt_api_cli.py index eee196a..aac5cc3 100644 --- a/tools/telemt_api_cli.py +++ b/tools/telemt_api_cli.py @@ -16,7 +16,7 @@ else: READ_COMMANDS = { "health": "health", "ready": "health_ready", "capabilities": "capabilities", - "schema": "config_schema", "config": "get_config", "info": "system_info", + "access-policy": "access_policy", "schema": "config_schema", "config": "get_config", "info": "system_info", "status": "runtime_gates", "init": "runtime_initialization", "limits": "limits_effective", "posture": "security_posture", "whitelist": "security_whitelist", "summary": "stats_summary", "zero": "stats_zero_all", "upstreams": "stats_upstreams", "minimal": "stats_minimal_all", @@ -85,6 +85,9 @@ def build_parser(): _reload_args(sub) if name == "config-patch": _poll_args(sub, optional=True) + sub = command("access-policy-patch") + sub.add_argument("--json", required=True, metavar="FILE") + sub.add_argument("--if-runtime-match") sub = command("reload") _reload_args(sub, submission=True) _poll_args(sub, optional=True) @@ -101,6 +104,12 @@ def build_parser(): for option, (field, kind) in USER_OPTIONS.items(): sub.add_argument(option, dest=field, type=kind, default=argparse.SUPPRESS, **({"choices": ("daily", "weekly", "monthly")} if field == "quota_period" else {})) + deny = sub.add_mutually_exclusive_group() + deny.add_argument("--source-deny", action="append", default=argparse.SUPPRESS, metavar="CIDR", + help="Replace the source deny list (repeat for multiple CIDRs); generation reload required") + if name == "create": + deny.add_argument("--clear-source-deny", dest="source_deny", action="store_const", const=None, + default=argparse.SUPPRESS, help="Remove a retained rule when recreating this username") enabled = sub.add_mutually_exclusive_group() enabled.add_argument("--enabled", dest="enabled", action="store_const", const=True, default=argparse.SUPPRESS) enabled.add_argument("--disabled", dest="enabled", action="store_const", const=False, default=argparse.SUPPRESS) @@ -177,6 +186,9 @@ def _dispatch(api, args): if getattr(args, "wait", False) and response.http_status == 202: raise TelemtAPIError("Accepted config patch lacks reload metadata", code="invalid_response", last_response=response) return response + if command == "access-policy-patch": + return api.patch_access_policy(_json_file(args.json), if_match=revision, + if_runtime_match=args.if_runtime_match) if command == "reload": response = api.reload(args.mode, timeout_secs=args.timeout_secs, failure_policy=args.failure_policy, if_match=revision) if args.wait: diff --git a/tools/tests/test_telemt_api.py b/tools/tests/test_telemt_api.py index 2c72c6b..24ae2ed 100644 --- a/tools/tests/test_telemt_api.py +++ b/tools/tests/test_telemt_api.py @@ -24,7 +24,7 @@ class ClientTests(unittest.TestCase): def test_all_json_operations_match_the_rust_catalog(self): reads = { - "health": "health", "health_ready": "health_ready", "capabilities": "capabilities", + "access_policy_get": "access_policy", "health": "health", "health_ready": "health_ready", "capabilities": "capabilities", "config_schema": "config_schema", "system_info": "system_info", "runtime_gates": "runtime_gates", "runtime_initialization": "runtime_initialization", "limits_effective": "limits_effective", "security_posture": "security_posture", "security_whitelist": "security_whitelist", @@ -48,6 +48,7 @@ class ClientTests(unittest.TestCase): "web_drain": ("web_drain", (INSTANCE, 30), {}, {"runtime_instance": INSTANCE, "timeout_secs": 30}), "config_validate": ("validate_config", ({"general": {"log_level": "debug"}},), {}, {"general": {"log_level": "debug"}}), "config_patch": ("patch_config", ({"web": {"enabled": False}},), {}, {"web": {"enabled": False}}), + "access_policy_patch": ("patch_access_policy", ({"user_max_tcp_conns_global_each": None, "cidr_rate_limits": {"192.0.2.0/24": None}},), {}, {"user_max_tcp_conns_global_each": None, "cidr_rate_limits": {"192.0.2.0/24": None}}), "reload": ("reload", (), {}, {"mode": "instant"}), "reload_status": ("reload_status", (7,), {}, None), "users_create": ("create_user", ("alice",), {}, {"username": "alice"}), @@ -85,7 +86,10 @@ class ClientTests(unittest.TestCase): self.assertEqual(USER_FIELDS, set(artifact["components"]["schemas"]["PatchUserRequest"]["properties"])) def test_config_sparse_body_queries_and_both_preconditions_are_unchanged(self): - body = {"general": {"ad_tag": None, "me_keepalive_enabled": False}, "upstreams": []} + body = {"general": {"ad_tag": None, "me_keepalive_enabled": False}, "upstreams": [], + "server": {"api": {"minimal_runtime_enabled": False, "minimal_runtime_cache_ttl_ms": 0, + "runtime_edge_enabled": True, "runtime_edge_cache_ttl_ms": None, + "runtime_edge_top_n": 1}}} for method in (self.api.validate_config, self.api.patch_config): self.peer.reply({"reload": {"reload_id": 7}}, 202 if method == self.api.patch_config else 200) method(body, if_match='"source"', if_runtime_match='"process:1:2"', reload="drain", timeout_secs=30, failure_policy="rollback") @@ -117,6 +121,22 @@ class ClientTests(unittest.TestCase): self.api.rotate_secret("alice", secret="0" * 32) self.assertEqual(self.peer.requests[-1]["body"], {"secret": "0" * 32}) + def test_source_deny_creation_distinguishes_omitted_null_and_empty(self): + for options, expected in [({}, {"username": "alice"}), + ({"source_deny": None}, {"username": "alice", "source_deny": None}), + ({"source_deny": []}, {"username": "alice", "source_deny": []}), + ({"source_deny": ["192.0.2.0/24", "2001:db8::/32"]}, + {"username": "alice", "source_deny": ["192.0.2.0/24", "2001:db8::/32"]})]: + self.peer.reply({}) + self.api.create_user("alice", **options) + self.assertEqual(self.peer.requests[-1]["body"], expected) + self.peer.reply({}) + self.api.patch_user("alice", source_deny=[]) + self.assertEqual(self.peer.requests[-1]["body"], {"source_deny": []}) + self.peer.reply({}) + self.api.patch_user_fields("alice", {"source_deny": None}) + self.assertEqual(self.peer.requests[-1]["body"], {"source_deny": None}) + def test_ready_503_and_web_410_are_data_only_on_the_documented_routes(self): for status, method, args, data in [(503, self.api.health_ready, (), {"ready": False}), (410, self.api.web_session, (SESSION,), {"state": "closed", "reason": "timeout"})]: diff --git a/tools/tests/test_telemt_api_cli.py b/tools/tests/test_telemt_api_cli.py index dd3ff72..bfba4ea 100644 --- a/tools/tests/test_telemt_api_cli.py +++ b/tools/tests/test_telemt_api_cli.py @@ -78,6 +78,38 @@ class CLITests(unittest.TestCase): self.assertEqual(request["headers"]["if-runtime-match"], ["opaque"]) self.assertEqual(parse_qs(urlsplit(request["path"]).query), {"reload": ["drain"], "timeout_secs": ["12"], "failure_policy": ["rollback"]}) + def test_access_policy_preserves_null_entries_and_both_fences(self): + body = {"user_max_tcp_conns_global_each": None, "cidr_rate_limits": {"192.0.2.0/24": None}} + self.peer.reply({}) + result = self.run_cli(["access-policy-patch", "--json", "-", "--if-match", "source", + "--if-runtime-match", "runtime"], json.dumps(body)) + self.assertEqual(result[0], 0, result[2]) + request = self.peer.requests[-1] + self.assertEqual(request["path"], "/v1/access/policy") + self.assertEqual(request["body"], body) + self.assertEqual(request["headers"]["if-match"], ["source"]) + self.assertEqual(request["headers"]["if-runtime-match"], ["runtime"]) + self.peer.reply({}) + self.assertEqual(self.run_cli(["access-policy"])[0], 0) + self.assertEqual(self.peer.requests[-1]["method"], "GET") + + def test_source_deny_replacement_and_explicit_removal_on_recreation(self): + for command in ("create", "patch"): + self.peer.reply({}) + result = self.run_cli([command, "alice", "--source-deny", "192.0.2.0/24", + "--source-deny", "2001:db8::/32"]) + self.assertEqual(result[0], 0, result[2]) + self.assertEqual(self.peer.requests[-1]["body"]["source_deny"], ["192.0.2.0/24", "2001:db8::/32"]) + for command, option in [("create", "--clear-source-deny"), ("patch", "--clear")]: + self.peer.reply({}) + result = self.run_cli([command, "alice", option, *(["source_deny"] if command == "patch" else [])]) + self.assertEqual(result[0], 0, result[2]) + self.assertIsNone(self.peer.requests[-1]["body"]["source_deny"]) + count = len(self.peer.requests) + self.assertEqual(self.run_cli(["create", "alice", "--source-deny", "192.0.2.0/24", "--clear-source-deny"])[0], 2) + self.assertEqual(self.run_cli(["patch", "alice", "--source-deny", "192.0.2.0/24", "--clear", "source_deny"])[0], 2) + self.assertEqual(len(self.peer.requests), count) + def test_reload_waits_for_terminal_state_and_reports_failure(self): self.peer.reply({"reload_id": 7, "config_revision": "target", "state": "accepted"}, 202) self.peer.reply({"reload_id": 7, "config_revision": "target", "state": "draining"})