API: add dry-run validation with change preview and runtime guards

This commit is contained in:
Alexey
2026-11-02 21:03:19 +03:00
parent 108e14f628
commit e0cbced3e9
28 changed files with 1910 additions and 182 deletions
+47 -155
View File
@@ -6,14 +6,13 @@ use serde_json::Value as Json;
use toml::Value as Toml;
use super::ApiShared;
#[cfg(test)]
use super::config_store::write_atomic;
use super::config_store::{
EDITABLE_SECTIONS, EDITABLE_SERVER_FIELDS, compute_snapshot_revision, is_editable_section,
load_candidate_snapshot, load_config_snapshot, render_server_listeners,
render_top_level_section, resolve_single_source_owner, upsert_toml_table,
write_atomic_if_unchanged,
load_config_snapshot, render_server_listeners, render_top_level_section,
resolve_single_source_owner, upsert_toml_table,
};
#[cfg(test)]
use super::config_store::{write_atomic, write_atomic_if_unchanged};
use super::model::ApiFailure;
use crate::config::ProxyConfig;
use crate::config::hot_reload::classify_config_changes;
@@ -25,6 +24,12 @@ use serde::Serialize;
use std::path::{Path, PathBuf};
use std::sync::Arc;
mod diagnostics;
mod preflight;
mod preparation;
pub(super) use preflight::{parse_runtime_match, validate_config};
use preparation::prepare_patch_to_path;
/// Result of one validated managed-config mutation.
#[derive(Debug, Serialize)]
pub(super) struct PatchConfigResponse {
@@ -40,6 +45,9 @@ pub(super) struct PatchConfigResponse {
pub deferred_process_fields: Vec<String>,
/// Top-level managed sections changed by the mutation.
pub changed: Vec<String>,
/// Canonical changed leaf paths, without configuration values.
pub changed_paths: Vec<String>,
pub normalization_effects: Vec<diagnostics::NormalizationEffect>,
#[serde(skip_serializing_if = "Option::is_none")]
/// Accepted runtime reload when one was requested and required.
pub reload: Option<ReloadAccepted>,
@@ -53,6 +61,8 @@ struct PreparedConfigPatch {
owner_contents: String,
desired_config: Arc<ProxyConfig>,
response: PatchConfigResponse,
touched: Vec<String>,
_guard: preparation::PreparationLease,
}
/// Serializes config mutations behind `mutation_lock`, commits them, and records
@@ -60,6 +70,7 @@ struct PreparedConfigPatch {
pub(super) async fn patch_config(
patch_json: Json,
expected_revision: Option<String>,
expected_runtime: Option<String>,
reload_request: Option<ReloadRequest>,
shared: &ApiShared,
) -> Result<PatchConfigResponse, ApiFailure> {
@@ -67,7 +78,14 @@ pub(super) async fn patch_config(
shared
.clone()
.run_mutation_completion(async move {
patch_config_to_completion(patch_json, expected_revision, reload_request, &shared).await
patch_config_to_completion(
patch_json,
expected_revision,
expected_runtime,
reload_request,
&shared,
)
.await
})
.await
}
@@ -75,18 +93,27 @@ pub(super) async fn patch_config(
async fn patch_config_to_completion(
patch_json: Json,
expected_revision: Option<String>,
expected_runtime: Option<String>,
reload_request: Option<ReloadRequest>,
shared: &ApiShared,
) -> Result<PatchConfigResponse, ApiFailure> {
let _guard = shared.mutation_lock.lock().await;
let active_config = shared.active_runtime.load_full().config();
let mut prepared =
let fence = preflight::RuntimeFence::capture(shared, expected_runtime.as_deref())?;
let prepared =
prepare_patch_to_path(&shared.config_path, &patch_json, expected_revision).await?;
let resolved = reconcile_runtime_effect(
&mut prepared.response,
&active_config,
&prepared.desired_config,
)?;
let active_config = fence.config.clone();
let (mut prepared, resolved) = tokio::task::spawn_blocking(move || {
let mut prepared = prepared;
let resolved = reconcile_runtime_effect(
&mut prepared.response,
&active_config,
&prepared.desired_config,
)?;
Ok::<_, ApiFailure>((prepared, resolved))
})
.await
.map_err(|_| ApiFailure::internal("Mutation classification worker failed"))??;
fence.ensure_current()?;
let reservation = if let Some(request) = reload_request.filter(|_| resolved.runtime_changed) {
Some(
shared
@@ -98,12 +125,13 @@ async fn patch_config_to_completion(
} else {
None
};
prepared.response.revision = write_atomic_if_unchanged(
prepared.response.revision = super::config_store::write_atomic_with_runtime_check(
prepared.config_path,
prepared.expected_revision,
prepared.owner_path,
prepared.expected_owner_contents,
prepared.owner_contents,
Some(fence.commit_check()),
)
.await?;
if let Some(reservation) = reservation {
@@ -122,8 +150,8 @@ fn reconcile_runtime_effect(
active_config: &ProxyConfig,
desired_config: &ProxyConfig,
) -> Result<ResolvedReloadConfig, ApiFailure> {
let resolved =
resolve_reload_config(active_config, desired_config).map_err(ApiFailure::bad_request)?;
let resolved = resolve_reload_config(active_config, desired_config)
.map_err(|error| diagnostics::validation_error("effective_config_invalid", "web", error))?;
response.runtime_reload_required = resolved.runtime_changed;
response.process_restart_required = !resolved.deferred_process_fields.is_empty();
response.deferred_process_fields = resolved.deferred_process_fields.clone();
@@ -151,145 +179,6 @@ pub(super) async fn apply_patch_to_path(
Ok(prepared.response)
}
async fn prepare_patch_to_path(
config_path: &Path,
patch_json: &Json,
expected_revision: Option<String>,
) -> Result<PreparedConfigPatch, ApiFailure> {
// 1. optimistic concurrency
let loaded = load_config_snapshot(config_path, false).await?;
let current = compute_snapshot_revision(&loaded.source_contents);
if expected_revision.is_some_and(|expected| expected != current) {
return Err(ApiFailure::new(
hyper::StatusCode::CONFLICT,
"revision_conflict",
"Config revision mismatch",
));
}
// 2. convert + reject access / unknown sections / forbidden server fields
let patch_toml = json_to_toml(patch_json)
.map_err(|e| ApiFailure::bad_request(format!("invalid patch: {}", e)))?;
let patch_table = patch_toml
.as_table()
.ok_or_else(|| ApiFailure::bad_request("patch must be a JSON object"))?;
if patch_table.contains_key("access") {
return Err(ApiFailure::new(
hyper::StatusCode::BAD_REQUEST,
"access_not_editable",
"access.* is managed via the users API, not editable here",
));
}
for (key, value) in patch_table {
if !is_editable_section(key.as_str()) {
return Err(ApiFailure::new(
hyper::StatusCode::BAD_REQUEST,
"section_not_editable",
format!("section not editable: {}", key),
));
}
if key == "server" {
validate_server_patch(value)?;
}
}
let touched: Vec<&str> = patch_table
.keys()
.map(|k| k.as_str())
.filter(|k| is_editable_section(k))
.collect();
if touched.is_empty() {
return Err(ApiFailure::bad_request("empty patch: no editable sections"));
}
// 3. Merge against the fully expanded and normalized desired config. The
// source owner is resolved separately so included sections stay in their
// original file and unrelated source files remain byte-identical.
let old_cfg = loaded.config.clone();
let mut merged = Toml::try_from(&old_cfg)
.map_err(|e| ApiFailure::internal(format!("failed to serialize config: {}", e)))?;
deep_merge(&mut merged, &patch_toml);
ProxyConfig::validate_decoy_source_keys(&merged)
.map_err(|error| ApiFailure::bad_request(format!("invalid patched config: {error}")))?;
let requested_cfg: ProxyConfig = merged
.clone()
.try_into()
.map_err(|e| ApiFailure::bad_request(format!("config does not deserialize: {}", e)))?;
requested_cfg
.validate()
.map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
let ownership_targets: Vec<&str> = touched
.iter()
.map(|section| {
if *section == "server" {
"server.listeners"
} else {
*section
}
})
.collect();
let owner_path = resolve_single_source_owner(&loaded, config_path, &ownership_targets)?;
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();
for section in &touched {
if *section == "server" {
let rendered = render_server_listeners(&requested_cfg)?;
owner_contents = upsert_toml_table(&owner_contents, "server.listeners", &rendered);
} else {
let rendered = render_top_level_section(&requested_cfg, section)?;
owner_contents = upsert_toml_table(&owner_contents, section, &rendered);
}
}
let candidate = load_candidate_snapshot(
config_path,
&loaded.source_contents,
owner_path.clone(),
owner_contents.clone(),
)
.await?;
if touched.contains(&"server")
&& serde_json::to_value(&candidate.config.server.listeners).ok()
!= serde_json::to_value(&requested_cfg.server.listeners).ok()
{
return Err(ApiFailure::new(
hyper::StatusCode::BAD_REQUEST,
"ambiguous_listeners",
"server.listeners normalizes to a different effective listener set",
));
}
// 4. classify the validated, normalized candidate.
let revision = compute_snapshot_revision(&candidate.source_contents);
let new_cfg = candidate.config;
let class = classify_config_changes(&old_cfg, &new_cfg);
let deferred_process_fields =
deferred_process_fields(&old_cfg, &new_cfg).map_err(ApiFailure::bad_request)?;
Ok(PreparedConfigPatch {
config_path: config_path.to_path_buf(),
expected_revision: current,
owner_path,
expected_owner_contents,
owner_contents,
desired_config: Arc::new(new_cfg),
response: PatchConfigResponse {
revision,
restart_required: class.restart_required,
runtime_reload_required: class.restart_required,
process_restart_required: !deferred_process_fields.is_empty(),
deferred_process_fields,
changed: class.changed,
reload: None,
},
})
}
fn reload_submit_failure(error: ReloadSubmitError) -> ApiFailure {
match error {
ReloadSubmitError::InProgress(reload_id) => ApiFailure::new(
@@ -470,3 +359,6 @@ mod host_list_tests;
#[cfg(test)]
mod quota_period_tests;
#[cfg(test)]
mod preflight_tests;
+347
View File
@@ -0,0 +1,347 @@
use std::collections::BTreeSet;
use super::*;
use crate::api::model::FieldIssue;
pub(super) const MAX_PATHS: usize = 4096;
pub(super) fn issue(
path: impl Into<String>,
code: &'static str,
message: impl Into<String>,
) -> FieldIssue {
FieldIssue {
path: path.into(),
code,
message: message.into(),
}
}
/// Raw validators can quote credentials, origins and source excerpts. Only known
/// metadata paths and fixed explanations are projected into an API error.
pub(super) fn validation_error(
code: &'static str,
fallback: &str,
error: impl std::fmt::Display,
) -> ApiFailure {
let text = error.to_string();
let canonical = regex::Regex::new(r"\[\d+\]")
.map(|pattern| pattern.replace_all(&text, "[]").into_owned())
.unwrap_or_default();
let path = crate::api::discovery::config_field_paths()
.unwrap_or_default()
.into_iter()
.filter(|path| canonical.contains(path))
.max_by_key(|path| path.len())
.unwrap_or(fallback);
let explanation = if text.contains("overlaps WEB listener") {
"Decoy origin overlaps WEB listener"
} else if text.contains("only valid for mode=http_upstream") {
"Field is only valid for mode=http_upstream"
} else if text.contains("allow_wildcard_hosts") {
"Wildcard selectors require web.allow_wildcard_hosts=true in the active process"
} else {
match code {
"source_load_failed" => "Cannot load the desired configuration source",
"deserialization_failed" => "Value has an invalid type or enum variant",
"preparation_failed" => "DNS or static-asset preparation failed",
"effective_config_invalid" => {
"Candidate is incompatible with retained process configuration"
}
_ => "Value violates configuration or dependent-field constraints",
}
};
let message = format!("{path}: {explanation}");
let mut failure = if code == "source_load_failed" {
// Preserve PATCH's existing server-error status for an unreadable or
// invalid current source, while keeping its raw excerpt private.
ApiFailure::internal(message)
} else {
ApiFailure::bad_request(message)
};
failure.details.push(issue(path, code, explanation));
failure
}
/// This document carries key structure only. Null members must be checked even
/// though normal PATCH merging omits them; values never enter key diagnostics.
fn key_document(value: &Json) -> Toml {
match value {
Json::Object(object) => Toml::Table(
object
.iter()
.map(|(key, value)| {
let key = if key.len() > 128 {
"{unknown}".to_owned()
} else {
key.clone()
};
(key, key_document(value))
})
.collect(),
),
Json::Array(items) => Toml::Array(items.iter().map(key_document).collect()),
_ => Toml::Boolean(false),
}
}
pub(super) fn reject_unknown(patch: &Json) -> Result<(), ApiFailure> {
let paths = ProxyConfig::unknown_source_paths(&key_document(patch));
if paths.is_empty() {
return Ok(());
}
let mut error = ApiFailure::bad_request("Unknown configuration fields");
error.details = paths
.into_iter()
.take(64)
.map(|path| {
let path = if path.len() <= 256
&& path
.chars()
.all(|c| c.is_ascii_alphanumeric() || "_.[]".contains(c))
{
path
} else {
"$".to_owned()
};
issue(
path,
"unknown_field",
"Field is not part of the configuration contract",
)
})
.collect();
Err(error)
}
/// Paths only: no before/after values or dynamic keys are returned. Arrays use
/// indices, open maps use their documented placeholder to avoid leaking identities.
pub(super) fn changed_paths(old: &Json, new: &Json) -> Vec<String> {
fn walk(old: Option<&Json>, new: Option<&Json>, path: &str, out: &mut BTreeSet<String>) {
if old == new {
return;
}
if out.len() > MAX_PATHS {
return;
}
let map_key = if path == "dc_overrides" {
Some("{dc}")
} else if path == "censorship.exclusive_mask" {
Some("{hostname}")
} else if path.starts_with("access.") {
Some("{entry}")
} else {
None
};
match (old, new) {
(Some(Json::Object(_)), _) | (_, Some(Json::Object(_))) => {
let a = old.and_then(Json::as_object);
let b = new.and_then(Json::as_object);
let keys: BTreeSet<_> = a
.into_iter()
.flat_map(|v| v.keys())
.chain(b.into_iter().flat_map(|v| v.keys()))
.collect();
if keys.is_empty() {
out.insert(path.to_string());
}
for key in keys {
let key_path = map_key.unwrap_or(key);
let next = if path.is_empty() {
key_path.to_string()
} else {
format!("{path}.{key_path}")
};
walk(
a.and_then(|v| v.get(key)),
b.and_then(|v| v.get(key)),
&next,
out,
);
}
}
(Some(Json::Array(_)), _) | (_, Some(Json::Array(_))) => {
let a = old
.and_then(Json::as_array)
.map(Vec::as_slice)
.unwrap_or_default();
let b = new
.and_then(Json::as_array)
.map(Vec::as_slice)
.unwrap_or_default();
if a.is_empty() && b.is_empty() {
out.insert(path.to_string());
}
for index in 0..a.len().max(b.len()) {
walk(a.get(index), b.get(index), &format!("{path}[{index}]"), out);
}
}
_ => {
out.insert(path.to_string());
}
}
}
let mut paths = BTreeSet::new();
walk(Some(old), Some(new), "", &mut paths);
paths.into_iter().collect()
}
#[derive(Debug, Serialize)]
pub(in crate::api) struct NormalizationEffect {
pub(super) path: String,
pub(super) code: &'static str,
}
pub(super) fn source_conflict(mut error: ApiFailure) -> ApiFailure {
error.message = "Patch requires one independently writable config source".into();
error.details.push(issue(
"$",
"source_ownership_conflict",
error.message.clone(),
));
error
}
pub(super) fn canonicalize_aliases(
patch: &mut Toml,
) -> Result<Vec<NormalizationEffect>, ApiFailure> {
let mut effects = Vec::new();
if let Some(vhosts) = patch
.get("web")
.and_then(|web| web.get("vhosts"))
.and_then(Toml::as_array)
{
for (index, vhost) in vhosts.iter().enumerate() {
let Some(decoy) = vhost.get("decoy").and_then(Toml::as_table) else {
continue;
};
let allowed: &[&str] = match decoy.get("mode").and_then(Toml::as_str) {
Some("http_upstream") => &["mode", "upstream", "resolve"],
Some("static_directory") => &["mode", "directory", "index"],
_ => continue,
};
for key in decoy.keys().filter(|key| !allowed.contains(&key.as_str())) {
let message = if key == "resolve" {
"Field is only valid for mode=http_upstream"
} else {
"Field does not apply to the selected decoy mode"
};
let mut error = ApiFailure::bad_request(message);
error.details.push(issue(
format!("web.vhosts[{index}].decoy.{key}"),
"field_not_applicable",
message,
));
return Err(error);
}
}
}
if let Some(upstreams) = patch.get_mut("upstreams").and_then(Toml::as_array_mut) {
for (index, upstream) in upstreams.iter_mut().enumerate() {
let Some(table) = upstream.as_table_mut() else {
continue;
};
if let Some(value) = table.remove("force_bind") {
if table.contains_key("bindtodevice") {
let mut error = ApiFailure::bad_request(
"Alias and canonical field cannot be supplied together",
);
error.details.push(issue(
format!("upstreams[{index}].bindtodevice"),
"duplicate_alias",
error.message.clone(),
));
return Err(error);
}
table.insert("bindtodevice".into(), value);
effects.push(NormalizationEffect {
path: format!("upstreams[{index}].bindtodevice"),
code: "alias_canonicalized",
});
}
let variant_fields: &[&str] = match table.get("type").and_then(Toml::as_str) {
Some("direct") => &["interface", "bind_addresses", "bindtodevice"],
Some("socks4") => &["address", "interface", "user_id"],
Some("socks5") => &["address", "interface", "username", "password"],
Some("shadowsocks") => &["url", "interface"],
_ => continue,
};
for key in table.keys() {
if ![
"type", "weight", "enabled", "scopes", "ipv4", "ipv6", "prefer",
]
.contains(&key.as_str())
&& !variant_fields.contains(&key.as_str())
{
let mut error = ApiFailure::bad_request(
"Field does not apply to the selected upstream type",
);
error.details.push(issue(
format!("upstreams[{index}].{key}"),
"field_not_applicable",
error.message.clone(),
));
return Err(error);
}
}
}
}
Ok(effects)
}
pub(super) fn normalization(
patch: &Json,
requested: &ProxyConfig,
candidate: &ProxyConfig,
) -> Result<Vec<NormalizationEffect>, ApiFailure> {
let before = serde_json::to_value(requested)
.map_err(|_| ApiFailure::internal("Cannot project candidate fields"))?;
let after = serde_json::to_value(candidate)
.map_err(|_| ApiFailure::internal("Cannot project candidate fields"))?;
let mut effects: Vec<_> = changed_paths(&before, &after)
.into_iter()
.map(|path| NormalizationEffect {
path,
code: "normalized",
})
.collect();
fn ignored(value: &Json, path: &str, effects: &mut Vec<NormalizationEffect>) {
if effects.len() > MAX_PATHS {
return;
}
match value {
Json::Object(object) => {
for (key, value) in object {
let key = if path == "dc_overrides" {
"{dc}"
} else if path == "censorship.exclusive_mask" {
"{hostname}"
} else {
key.as_str()
};
let next = if path.is_empty() {
key.to_string()
} else {
format!("{path}.{key}")
};
if value.is_null() {
effects.push(NormalizationEffect {
path: next,
code: "null_ignored",
});
} else {
ignored(value, &next, effects);
}
}
}
Json::Array(array) => {
for (index, value) in array.iter().enumerate() {
ignored(value, &format!("{path}[{index}]"), effects);
}
}
_ => {}
}
}
ignored(patch, "", &mut effects);
Ok(effects)
}
+269
View File
@@ -0,0 +1,269 @@
use std::sync::OnceLock;
use std::time::Duration;
use crate::api::config_store::CommitCheck;
use crate::api::model::FieldIssue;
use crate::config::hot_reload::overlay_hot_fields;
use crate::maestro::generation::RuntimeGeneration;
use hyper::{HeaderMap, StatusCode};
use super::*;
#[derive(Debug, Serialize)]
pub(super) struct RuntimeBaseline {
pub(super) active_generation: u64,
pub(super) config_epoch: u64,
pub(super) runtime_match: String,
}
#[derive(Clone)]
pub(super) struct RuntimeFence {
active: Arc<arc_swap::ArcSwap<RuntimeGeneration>>,
generation: Arc<RuntimeGeneration>,
pub(super) config: Arc<ProxyConfig>,
}
impl RuntimeFence {
pub(super) fn capture(shared: &ApiShared, expected: Option<&str>) -> Result<Self, ApiFailure> {
let generation = shared.active_runtime.load_full();
let config = generation.config();
let fence = Self {
active: shared.active_runtime.clone(),
generation,
config,
};
fence.ensure_current()?;
if expected.is_some_and(|expected| expected != fence.baseline().runtime_match) {
return Err(runtime_conflict());
}
Ok(fence)
}
pub(super) fn baseline(&self) -> RuntimeBaseline {
static PROCESS: OnceLock<String> = OnceLock::new();
let process = PROCESS.get_or_init(|| {
let mut bytes = [0_u8; 16];
crate::crypto::SecureRandom::new().fill(&mut bytes);
hex::encode(bytes)
});
RuntimeBaseline {
active_generation: self.generation.id,
config_epoch: self.config.runtime_config_epoch,
runtime_match: format!(
"{process}:{}:{}",
self.generation.id, self.config.runtime_config_epoch
),
}
}
fn matches(&self) -> bool {
let current = self.active.load_full();
Arc::ptr_eq(&current, &self.generation)
&& Arc::ptr_eq(&current.config(), &self.config)
&& Arc::ptr_eq(&self.active.load_full(), &self.generation)
}
pub(super) fn ensure_current(&self) -> Result<(), ApiFailure> {
if self.matches() {
Ok(())
} else {
Err(runtime_conflict())
}
}
pub(super) fn commit_check(&self) -> CommitCheck {
let fence = self.clone();
Arc::new(move || fence.matches())
}
}
fn runtime_conflict() -> ApiFailure {
let mut error = ApiFailure::new(
StatusCode::CONFLICT,
"runtime_conflict",
"Runtime configuration changed; validate against a fresh baseline",
);
error.details.push(diagnostics::issue(
"$",
"runtime_conflict",
error.message.clone(),
));
error
}
pub(in crate::api) fn parse_runtime_match(
headers: &HeaderMap,
) -> Result<Option<String>, ApiFailure> {
let mut values = headers.get_all("if-runtime-match").iter();
let Some(value) = values.next() else {
return Ok(None);
};
let value = value
.to_str()
.map_err(|_| ApiFailure::bad_request("Invalid If-Runtime-Match header"))?
.trim()
.trim_matches('"');
if values.next().is_some()
|| value.is_empty()
|| value.len() > 128
|| !value
.bytes()
.all(|byte| byte.is_ascii_hexdigit() || byte == b':')
{
return Err(ApiFailure::bad_request("Invalid If-Runtime-Match header"));
}
Ok(Some(value.to_owned()))
}
#[derive(Debug, Serialize)]
pub(super) struct ApplyImpact {
pub(super) watcher_paths: Vec<String>,
pub(super) generation_paths: Vec<String>,
pub(super) process_restart_paths: Vec<String>,
pub(super) restart_required: bool,
pub(super) runtime_reload_required: bool,
pub(super) process_restart_required: bool,
pub(super) deferred_process_fields: Vec<String>,
}
#[derive(Debug, Serialize)]
pub(in crate::api) struct ValidationResponse {
pub(super) valid: bool,
pub(in crate::api) base_revision: String,
pub(super) candidate_revision: String,
pub(super) runtime: RuntimeBaseline,
pub(super) changed_paths: Vec<String>,
pub(super) normalization_effects: Vec<diagnostics::NormalizationEffect>,
pub(super) apply: ApplyImpact,
pub(super) source_ownership: &'static str,
pub(super) touched_sections: Vec<String>,
pub(super) reload: Option<ReloadRequest>,
pub(super) warnings: Vec<FieldIssue>,
}
/// All blocking workers retain the same lease. Dropping this future cannot
/// publish data, reserve a reload, or let an abandoned worker bypass the budget.
pub(in crate::api) async fn validate_config(
patch: Json,
expected_revision: Option<String>,
expected_runtime: Option<String>,
reload: Option<ReloadRequest>,
shared: &ApiShared,
) -> Result<ValidationResponse, ApiFailure> {
if let Some(request) = &reload {
request.validate().map_err(ApiFailure::bad_request)?;
}
let permit = shared
.config_preflight_slots
.clone()
.try_acquire_owned()
.map_err(|_| {
ApiFailure::new(
StatusCode::TOO_MANY_REQUESTS,
"config_preflight_busy",
"Both configuration preparation slots are occupied",
)
})?;
let guard = Arc::new(Some(permit));
let fence = RuntimeFence::capture(shared, expected_runtime.as_deref())?;
let preparation = async {
let prepared =
preparation::prepare_guarded(&shared.config_path, &patch, expected_revision, guard)
.await?;
let active = fence.config.clone();
let (prepared, apply) = tokio::task::spawn_blocking(move || {
let mut prepared = prepared;
let resolved = reconcile_runtime_effect(
&mut prepared.response,
&active,
&prepared.desired_config,
)?;
let hot = overlay_hot_fields(&active, &prepared.desired_config);
let json = |config: &ProxyConfig| {
serde_json::to_value(config)
.map_err(|_| ApiFailure::internal("Cannot project application paths"))
};
let active = json(&active)?;
let hot = json(&hot)?;
let effective = json(&resolved.effective)?;
let desired = json(&prepared.desired_config)?;
let apply = ApplyImpact {
watcher_paths: diagnostics::changed_paths(&active, &hot),
generation_paths: diagnostics::changed_paths(&hot, &effective),
process_restart_paths: diagnostics::changed_paths(&effective, &desired),
restart_required: prepared.response.restart_required,
runtime_reload_required: prepared.response.runtime_reload_required,
process_restart_required: prepared.response.process_restart_required,
deferred_process_fields: prepared.response.deferred_process_fields.clone(),
};
if [
&apply.watcher_paths,
&apply.generation_paths,
&apply.process_restart_paths,
]
.into_iter()
.any(|paths| paths.len() > diagnostics::MAX_PATHS)
{
return Err(ApiFailure::bad_request(
"Preview exceeds the 4096-path feedback limit",
));
}
// Keep the preparation lease in this worker through the final source
// read, including when its awaiting HTTP request has been cancelled.
let graph = ProxyConfig::read_source_graph(&prepared.config_path)
.map_err(|error| diagnostics::validation_error("source_load_failed", "$", error))?;
if compute_snapshot_revision(&graph.source_contents) != prepared.expected_revision {
return Err(ApiFailure::new(
StatusCode::CONFLICT,
"revision_conflict",
"Config revision changed during validation",
));
}
Ok((prepared, apply))
})
.await
.map_err(|_| ApiFailure::internal("Preview classification worker failed"))??;
fence.ensure_current()?;
let mut warnings = vec![diagnostics::issue(
"$",
"preparation_reads",
"Preparation may read DNS and static assets; listener binding and runtime startup are not tested",
)];
if !apply.generation_paths.is_empty() && reload.is_none() {
warnings.push(diagnostics::issue(
"$",
"reload_not_requested",
"Generation-owned changes require an explicit reload",
));
}
if apply.process_restart_required {
warnings.push(diagnostics::issue(
"$",
"process_restart_required",
"Some desired fields remain deferred until process restart",
));
}
Ok(ValidationResponse {
valid: true,
base_revision: prepared.expected_revision,
candidate_revision: prepared.response.revision,
runtime: fence.baseline(),
changed_paths: prepared.response.changed_paths,
normalization_effects: prepared.response.normalization_effects,
apply,
source_ownership: "single_source",
touched_sections: prepared.touched,
reload,
warnings,
})
};
tokio::time::timeout(Duration::from_secs(30), preparation)
.await
.map_err(|_| {
ApiFailure::new(
StatusCode::GATEWAY_TIMEOUT,
"config_preflight_timeout",
"Configuration preparation exceeded 30 seconds",
)
})?
}
+734
View File
@@ -0,0 +1,734 @@
use super::*;
use crate::api::discovery::http_tests::Fixture;
use crate::maestro::generation::test_runtime_generation;
use serde_json::json;
use tokio::sync::watch;
async fn fixture(source: &str, read_only: bool) -> (Fixture, watch::Sender<Arc<ProxyConfig>>) {
let fixture = Fixture::new(false);
std::fs::write(&fixture.shared.config_path, format!("{source}\n[server.api]\nenabled = true\nread_only = {read_only}\nauth_header = \"Bearer discovery-test\"\n")).unwrap();
let config = ProxyConfig::load_prepared(fixture.shared.config_path.clone())
.await
.unwrap()
.config;
let mut runtime = test_runtime_generation(1, config);
let (sender, receiver) = watch::channel(runtime.config());
Arc::get_mut(&mut runtime).unwrap().config_rx = receiver;
fixture.shared.active_runtime.store(runtime);
(fixture, sender)
}
fn files(fixture: &Fixture) -> std::collections::BTreeMap<PathBuf, Vec<u8>> {
std::fs::read_dir(fixture.shared.config_path.parent().unwrap())
.unwrap()
.map(|entry| {
let path = entry.unwrap().path();
let bytes = std::fs::read(&path).unwrap();
(path, bytes)
})
.collect()
}
async fn preview(fixture: &Fixture, patch: Json) -> preflight::ValidationResponse {
validate_config(patch, None, None, None, &fixture.shared)
.await
.unwrap()
}
#[tokio::test]
async fn unknown_nested_patch_key_is_rejected_before_serde_discards_it() {
let directory = tempfile::tempdir().unwrap();
let path = directory.path().join("config.toml");
let source = "[general]\nconfig_strict = true\n";
std::fs::write(&path, source).unwrap();
let result = apply_patch_to_path(
&path,
&serde_json::json!({"general": {"me_keepalive_enabld": true}}),
None,
)
.await;
assert!(
result.is_err(),
"unknown nested key must not become a successful write"
);
assert_eq!(std::fs::read_to_string(&path).unwrap(), source);
}
#[tokio::test]
async fn preflight_http_auth_read_only_queries_and_no_side_effects() {
let (fixture, _sender) = fixture("", true).await;
let before = files(&fixture);
let active = fixture.shared.active_runtime.load_full();
let patch = json!({"general":{"log_level":"debug"}});
for (method, path, authorized, status, code) in [
("POST", "/v1/config/validate", false, 401, "unauthorized"),
(
"GET",
"/v1/config/validate",
true,
405,
"method_not_allowed",
),
(
"POST",
"/v1/config/validate?timeout_secs=1",
true,
400,
"bad_request",
),
(
"POST",
"/v1/config/validate?reload=drain",
true,
400,
"bad_request",
),
("PATCH", "/v1/config", true, 403, "read_only"),
] {
let response = fixture
.request_body(method, path, authorized, Some(&patch), &[])
.await;
assert_eq!(response.0, status, "{}", response.2);
assert_eq!(response.2["error"]["code"], code);
if status == 405 {
assert_eq!(response.1, "POST");
}
}
let response = fixture
.request_body(
"POST",
"/v1/config/validate?reload=drain&timeout_secs=10",
true,
Some(&patch),
&[],
)
.await;
assert_eq!(response.0, 200, "{}", response.2);
assert_eq!(response.2["data"]["valid"], true);
assert_eq!(response.2["data"]["reload"]["mode"], "drain");
assert_eq!(response.2["revision"], response.2["data"]["base_revision"]);
assert_eq!(files(&fixture), before);
assert!(Arc::ptr_eq(
&fixture.shared.active_runtime.load_full(),
&active
));
assert!(Arc::ptr_eq(
&fixture.shared.active_runtime.load().config(),
&active.config()
));
assert!(fixture.shared.reload_control.in_progress().await.is_none());
assert!(fixture.shared.reload_control.status(1).await.is_none());
assert!(fixture.shared.runtime_events.snapshot(64).events.is_empty());
let denied = Fixture::new(true);
assert_eq!(
denied
.request_body("POST", "/v1/config/validate", true, Some(&patch), &[])
.await
.0,
403
);
let caps = fixture.request("GET", "/v1/capabilities", true).await.2;
let operation = caps["data"]["operations"]
.as_array()
.unwrap()
.iter()
.find(|op| op["id"] == "config_validate")
.unwrap();
assert_eq!(operation["mutable"], false);
assert_eq!(operation["available"], true);
assert!(operation["mutation_blocked_reason"].is_null());
}
#[tokio::test]
async fn preflight_commit_parity_for_hot_generation_and_process_changes() {
let (fixture, _sender) = fixture("", false).await;
let active = fixture.shared.active_runtime.load().config();
let patch = json!({"general":{
"log_level":"debug", "me_keepalive_interval_secs":active.general.me_keepalive_interval_secs + 5,
"disable_colors":!active.general.disable_colors
}});
let before = files(&fixture);
let response = preview(&fixture, patch.clone()).await;
assert_eq!(response.apply.watcher_paths, ["general.log_level"]);
assert_eq!(
response.apply.generation_paths,
["general.me_keepalive_interval_secs"]
);
assert_eq!(
response.apply.process_restart_paths,
["general.disable_colors"]
);
assert_eq!(
response.apply.deferred_process_fields,
["general.disable_colors"]
);
assert_eq!(files(&fixture), before);
let committed = fixture
.request_body(
"PATCH",
"/v1/config",
true,
Some(&patch),
&[
("If-Match", &response.base_revision),
("If-Runtime-Match", &response.runtime.runtime_match),
],
)
.await;
assert_eq!(committed.0, 200, "{}", committed.2);
let data = &committed.2["data"];
assert_eq!(data["revision"], response.candidate_revision);
assert_eq!(data["changed_paths"], json!(response.changed_paths));
assert_eq!(data["restart_required"], response.apply.restart_required);
assert_eq!(
data["runtime_reload_required"],
response.apply.runtime_reload_required
);
assert_eq!(
data["process_restart_required"],
response.apply.process_restart_required
);
assert_eq!(data["changed"], json!(["general"]));
assert_eq!(
data["deferred_process_fields"],
json!(response.apply.deferred_process_fields)
);
assert!(Arc::ptr_eq(
&fixture.shared.active_runtime.load().config(),
&active
));
}
#[tokio::test]
async fn preflight_stale_source_and_runtime_tokens_reject_without_writes() {
let (fixture, sender) = fixture("", false).await;
let patch = json!({"general":{"log_level":"debug"}});
let response = preview(&fixture, patch.clone()).await;
let before = files(&fixture);
for method in ["POST", "PATCH"] {
let path = if method == "POST" {
"/v1/config/validate"
} else {
"/v1/config"
};
let rejected = fixture
.request_body(method, path, true, Some(&patch), &[("If-Match", "stale")])
.await;
assert_eq!(rejected.0, 409);
assert_eq!(rejected.2["error"]["code"], "revision_conflict");
let rejected = fixture
.request_body(
method,
path,
true,
Some(&patch),
&[("If-Runtime-Match", "invalid token")],
)
.await;
assert_eq!(rejected.0, 400);
}
// A -> B -> A retains the same generation and source bytes, but not its epoch.
let original = (*sender.borrow()).as_ref().clone();
let mut hot = original.clone();
hot.general.log_level = crate::config::LogLevel::Verbose;
sender.send(Arc::new(hot.with_publication_epoch())).unwrap();
sender
.send(Arc::new(original.with_publication_epoch()))
.unwrap();
for method in ["POST", "PATCH"] {
let path = if method == "POST" {
"/v1/config/validate"
} else {
"/v1/config"
};
let rejected = fixture
.request_body(
method,
path,
true,
Some(&patch),
&[
("If-Match", &response.base_revision),
("If-Runtime-Match", &response.runtime.runtime_match),
],
)
.await;
assert_eq!(rejected.0, 409, "{}", rejected.2);
assert_eq!(rejected.2["error"]["code"], "runtime_conflict");
}
let fresh = preview(&fixture, patch.clone()).await;
assert_eq!(
fresh.runtime.active_generation,
response.runtime.active_generation
);
assert!(fresh.runtime.config_epoch > response.runtime.config_epoch);
let config = fixture.shared.active_runtime.load().config();
fixture
.shared
.active_runtime
.store(test_runtime_generation(2, (*config).clone()));
assert_eq!(
validate_config(
patch,
None,
Some(fresh.runtime.runtime_match),
None,
&fixture.shared
)
.await
.unwrap_err()
.code,
"runtime_conflict"
);
assert_eq!(files(&fixture), before);
}
#[tokio::test]
async fn unknown_nested_and_variant_fields_never_silently_disappear() {
let (fixture, _sender) = fixture("[general]\nconfig_strict = false\n", false).await;
let before = files(&fixture);
for (patch, expected) in [
(
json!({"general":{"me_keepalive_enabld":null,"log_level":"debug"}}),
"general.me_keepalive_enabld",
),
(
json!({"web":{"limits":{"max_boddy_bytes":123}}}),
"web.limits.max_boddy_bytes",
),
(
json!({"web":{"vhosts":[{"profiles":[{"unknwon":true}]}]}}),
"web.vhosts[0].profiles[0].unknwon",
),
(
json!({"upstreams":[{"type":"direct","password":"synthetic-credential"}]}),
"upstreams[0].password",
),
(
json!({"web":{"vhosts":[{"decoy":{"mode":"http_upstream","directory":"synthetic-credential"}}]}}),
"web.vhosts[0].decoy.directory",
),
] {
for method in ["POST", "PATCH"] {
let path = if method == "POST" {
"/v1/config/validate"
} else {
"/v1/config"
};
let response = fixture
.request_body(method, path, true, Some(&patch), &[])
.await;
assert_eq!(response.0, 400, "{}", response.2);
assert_eq!(response.2["error"]["details"][0]["path"], expected);
assert!(!response.2.to_string().contains("synthetic-credential"));
}
assert_eq!(files(&fixture), before);
}
}
#[tokio::test]
async fn preflight_aliases_open_maps_nulls_and_credentials_are_redacted() {
let (fixture, _sender) = fixture("", false).await;
let patch = json!({
"upstreams":[{"type":"direct","force_bind":"lo"}],
"general":{"log_level":null},
"dc_overrides":{"2":["149.154.167.50:443"]},
"censorship":{"exclusive_mask":{"private-sentinel.example":"private-origin.example:443"}}
});
let response = preview(&fixture, patch.clone()).await;
let encoded = serde_json::to_value(&response).unwrap();
assert!(
encoded["normalization_effects"]
.as_array()
.unwrap()
.contains(&json!({"path":"upstreams[0].bindtodevice","code":"alias_canonicalized"}))
);
assert!(
encoded["normalization_effects"]
.as_array()
.unwrap()
.contains(&json!({"path":"general.log_level","code":"null_ignored"}))
);
assert!(
response
.changed_paths
.contains(&"dc_overrides.{dc}[0]".into())
);
assert!(
response
.changed_paths
.contains(&"censorship.exclusive_mask.{hostname}".into())
);
assert!(!encoded.to_string().contains("private-"));
let credential_change = preview(
&fixture,
json!({"upstreams":[{
"type":"socks5", "address":"127.0.0.1:1080", "password":"synthetic-diff-credential"
}]}),
)
.await;
assert!(
credential_change
.changed_paths
.contains(&"upstreams[0].password".into())
);
assert!(
!serde_json::to_string(&credential_change)
.unwrap()
.contains("synthetic-diff-credential")
);
// The strict-key facade must leave open user maps to their owner API.
let open_users: Toml =
toml::from_str("[access.users]\n'arbitrary.user-name' = 'synthetic-user-secret'\n")
.unwrap();
assert!(ProxyConfig::unknown_source_paths(&open_users).is_empty());
let committed = patch_config(
patch,
Some(response.base_revision),
None,
None,
&fixture.shared,
)
.await
.unwrap();
assert_eq!(committed.revision, response.candidate_revision);
assert!(
std::fs::read_to_string(&fixture.shared.config_path)
.unwrap()
.contains("bindtodevice")
);
for patch in [
json!({"general":{"me_writer_pick_mode":"synthetic-credential"}}),
json!({"upstreams":[{"type":"shadowsocks","url":"ss://synthetic-credential@private-sentinel.example"}]}),
json!({"web":{"carrier_method":"synthetic-credential"}}),
] {
let error = validate_config(patch, None, None, None, &fixture.shared)
.await
.unwrap_err();
let public = format!(
"{} {}",
error.message,
serde_json::to_string(&error.details).unwrap()
);
assert!(!public.contains("synthetic-credential"), "{public}");
assert!(!public.contains("private-sentinel"));
assert!(!error.details.is_empty());
}
}
#[tokio::test]
async fn preflight_multi_source_conflict_and_conditional_web_capacity() {
let (fixture, _sender) = fixture("", false).await;
let path = &fixture.shared.config_path;
let old = std::fs::read_to_string(path).unwrap();
std::fs::write(path, format!("include = \"censorship.toml\"\n{old}")).unwrap();
std::fs::write(
path.parent().unwrap().join("censorship.toml"),
"[censorship]\ntls_domain = \"old.example\"\n",
)
.unwrap();
let before = files(&fixture);
let patch = json!({"general":{"log_level":"debug"},"censorship":{"tls_domain":"new.example"}});
for commit in [false, true] {
let error = if commit {
patch_config(patch.clone(), None, None, None, &fixture.shared)
.await
.err()
.unwrap()
} else {
validate_config(patch.clone(), None, None, None, &fixture.shared)
.await
.unwrap_err()
};
assert_eq!(error.code, "config_patch_not_atomic");
assert_eq!(error.details[0].code, "source_ownership_conflict");
assert_eq!(files(&fixture), before);
}
let (fixture, _sender) =
self::fixture("[web.limits]\ndebug_bytes_global = 4096\n", false).await;
let hot = preview(&fixture, json!({"web":{"debug":{"body_prefix_bytes":128}}})).await;
assert!(
hot.apply
.watcher_paths
.contains(&"web.debug.body_prefix_bytes".into())
);
let deferred = preview(
&fixture,
json!({"web":{"limits":{"debug_bytes_global":8192},"debug":{"body_prefix_bytes":6144}}}),
)
.await;
assert!(
!deferred
.apply
.watcher_paths
.contains(&"web.debug.body_prefix_bytes".into())
);
assert!(
deferred
.apply
.process_restart_paths
.contains(&"web.debug.body_prefix_bytes".into())
);
assert!(
deferred
.apply
.deferred_process_fields
.contains(&"web.debug".into())
);
let result = patch_config(
json!({"web":{"limits":{"debug_bytes_global":8192},"debug":{"body_prefix_bytes":6144}}}),
Some(deferred.base_revision),
None,
None,
&fixture.shared,
)
.await
.unwrap();
assert_eq!(
result.deferred_process_fields,
deferred.apply.deferred_process_fields
);
}
#[tokio::test]
async fn preflight_runtime_fence_rejects_at_atomic_persistence_and_removes_staging_file() {
let (fixture, sender) = fixture("", false).await;
let fence = preflight::RuntimeFence::capture(&fixture.shared, None).unwrap();
let patch = json!({"general":{"log_level":"debug"}});
let prepared = prepare_patch_to_path(&fixture.shared.config_path, &patch, None)
.await
.unwrap();
let before = std::fs::read(&fixture.shared.config_path).unwrap();
let mut changed = (*fence.config).clone();
changed.general.log_level = crate::config::LogLevel::Verbose;
sender
.send(Arc::new(changed.with_publication_epoch()))
.unwrap();
let error = crate::api::config_store::write_atomic_with_runtime_check(
prepared.config_path,
prepared.expected_revision,
prepared.owner_path,
prepared.expected_owner_contents,
prepared.owner_contents,
Some(fence.commit_check()),
)
.await
.unwrap_err();
assert_eq!(error.code, "runtime_conflict");
assert_eq!(std::fs::read(&fixture.shared.config_path).unwrap(), before);
assert!(
files(&fixture)
.keys()
.all(|path| path.ends_with("config.toml") || path.ends_with("config.toml.lock"))
);
}
#[tokio::test]
async fn preflight_concurrency_budget_does_not_block_or_reserve_reload() {
let (fixture, _sender) = fixture("", false).await;
let permits = fixture
.shared
.config_preflight_slots
.clone()
.acquire_many_owned(2)
.await
.unwrap();
let response = fixture
.request_body(
"POST",
"/v1/config/validate",
true,
Some(&json!({"general":{"log_level":"debug"}})),
&[],
)
.await;
assert_eq!(response.0, 429);
assert_eq!(response.2["error"]["code"], "config_preflight_busy");
drop(permits);
let _ = preview(&fixture, json!({"general":{"log_level":"debug"}})).await;
assert!(fixture.shared.reload_control.in_progress().await.is_none());
}
fn abandoned_preflight_retains_budget(timeout: bool) {
let runtime = tokio::runtime::Builder::new_current_thread()
.enable_all()
.max_blocking_threads(1)
.build()
.unwrap();
runtime.block_on(async {
let (fixture, _sender) = fixture("", false).await;
let before = files(&fixture);
let active = fixture.shared.active_runtime.load().config();
let (release, wait) = std::sync::mpsc::channel();
let (started, ready) = tokio::sync::oneshot::channel();
let blocker = tokio::task::spawn_blocking(move || {
started.send(()).unwrap();
wait.recv().unwrap();
});
ready.await.unwrap();
tokio::time::pause();
let shared = fixture.shared.clone();
let task = tokio::spawn(async move {
validate_config(
json!({"general":{"log_level":"debug"}}),
None,
None,
Some(ReloadRequest::default()),
&shared,
)
.await
});
// The only blocking thread is occupied; candidate parsing is queued.
while fixture.shared.config_preflight_slots.available_permits() == 2 {
tokio::task::yield_now().await;
}
if timeout {
tokio::time::advance(std::time::Duration::from_secs(31)).await;
let error = task.await.unwrap().unwrap_err();
assert_eq!(error.status, hyper::StatusCode::GATEWAY_TIMEOUT);
assert_eq!(error.code, "config_preflight_timeout");
} else {
task.abort();
assert!(task.await.unwrap_err().is_cancelled());
}
assert_eq!(fixture.shared.config_preflight_slots.available_permits(), 1);
tokio::time::resume();
release.send(()).unwrap();
blocker.await.unwrap();
let _permits = tokio::time::timeout(
std::time::Duration::from_secs(5),
fixture
.shared
.config_preflight_slots
.clone()
.acquire_many_owned(2),
)
.await
.unwrap()
.unwrap();
assert_eq!(files(&fixture), before);
assert!(Arc::ptr_eq(
&fixture.shared.active_runtime.load().config(),
&active
));
assert!(fixture.shared.reload_control.status(1).await.is_none());
assert!(fixture.shared.runtime_events.snapshot(64).events.is_empty());
});
}
#[test]
fn preflight_cancellation_retains_budget_until_abandoned_worker_finishes() {
abandoned_preflight_retains_budget(false);
}
#[test]
fn preflight_timeout_retains_budget_until_abandoned_worker_finishes() {
abandoned_preflight_retains_budget(true);
}
#[tokio::test]
async fn preflight_dns_failure_and_normalization_share_commit_preparation() {
let source = r#"
[access.users]
alice = "000102030405060708090a0b0c0d0e0f"
[[server.listeners]]
ip = "127.0.0.1"
port = 18080
transport = "web"
web_trusted_proxy_cidrs = ["127.0.0.1/32"]
[web]
enabled = true
[[web.vhosts]]
host = "proxy.example.com"
public_addr = "203.0.113.10:443"
[web.vhosts.decoy]
mode = "http_upstream"
upstream = "http://127.0.0.1:18081"
[[web.vhosts.profiles]]
user = "alice"
secret_mode = "dd"
"#;
let (fixture, _sender) = fixture(source, false).await;
let mut vhosts =
serde_json::to_value(&fixture.shared.active_runtime.load().config().web.vhosts).unwrap();
vhosts[0]["host"] = json!("MixedCase.Example.COM");
let patch = json!({"web":{"vhosts":vhosts}});
let normalized = preview(&fixture, patch.clone()).await;
assert!(
normalized
.normalization_effects
.iter()
.any(|effect| effect.path == "web.vhosts[0].host" && effect.code == "normalized")
);
let committed = patch_config(
patch,
Some(normalized.base_revision),
None,
None,
&fixture.shared,
)
.await
.unwrap();
assert_eq!(committed.revision, normalized.candidate_revision);
let before = files(&fixture);
// The reserved .invalid TLD cannot yield a usable decoy origin. DNS itself
// remains bounded by the configured one-second preparation timeout.
vhosts[0]["decoy"] = json!({"mode":"http_upstream", "upstream":"http://preflight-unresolvable.invalid:18081", "resolve":"startup"});
let patch = json!({"web":{"vhosts":vhosts,"timeouts":{"decoy_resolve_secs":1}}});
for commit in [false, true] {
let error = if commit {
patch_config(patch.clone(), None, None, None, &fixture.shared)
.await
.err()
.unwrap()
} else {
validate_config(patch.clone(), None, None, None, &fixture.shared)
.await
.unwrap_err()
};
assert_eq!(error.status, hyper::StatusCode::BAD_REQUEST);
assert_eq!(error.details[0].code, "preparation_failed");
assert!(!error.message.contains("preflight-unresolvable"));
assert_eq!(files(&fixture), before);
}
}
#[tokio::test]
async fn preflight_invalid_current_source_preserves_status_and_hides_source_excerpt() {
let (fixture, _sender) = fixture("", false).await;
std::fs::write(
&fixture.shared.config_path,
"[general]\nme_writer_pick_mode = 'synthetic-source-credential'\n",
)
.unwrap();
let before = files(&fixture);
for method in ["POST", "PATCH"] {
let path = if method == "POST" {
"/v1/config/validate"
} else {
"/v1/config"
};
let response = fixture
.request_body(
method,
path,
true,
Some(&json!({"general":{"log_level":"debug"}})),
&[],
)
.await;
assert_eq!(response.0, 500);
assert_eq!(response.2["error"]["code"], "internal_error");
assert_eq!(
response.2["error"]["details"][0]["code"],
"source_load_failed"
);
assert!(
!response
.2
.to_string()
.contains("synthetic-source-credential")
);
assert_eq!(files(&fixture), before);
}
}
+233
View File
@@ -0,0 +1,233 @@
//! One source-preserving candidate pipeline shared by preview and commit.
use super::*;
use crate::config::{LoadedConfig, ParsedConfigSource};
use tokio::sync::OwnedSemaphorePermit;
pub(super) type PreparationLease = Arc<Option<OwnedSemaphorePermit>>;
struct PatchSource {
config_path: PathBuf,
expected_revision: String,
owner_path: PathBuf,
expected_owner_contents: String,
owner_contents: String,
old_config: ProxyConfig,
requested_config: ProxyConfig,
patch: Json,
touched: Vec<String>,
alias_effects: Vec<diagnostics::NormalizationEffect>,
}
pub(super) async fn prepare_patch_to_path(
config_path: &Path,
patch: &Json,
expected: Option<String>,
) -> Result<PreparedConfigPatch, ApiFailure> {
prepare_guarded(config_path, patch, expected, Arc::new(None)).await
}
pub(super) async fn prepare_guarded(
config_path: &Path,
patch: &Json,
expected: Option<String>,
guard: PreparationLease,
) -> Result<PreparedConfigPatch, ApiFailure> {
let config_path = config_path.to_path_buf();
let patch = patch.clone();
let worker_guard = guard.clone();
let (source, details) = tokio::task::spawn_blocking(move || {
let _guard = worker_guard;
parse_patch(&config_path, &patch, expected)
})
.await
.map_err(|_| ApiFailure::internal("Candidate source worker failed"))??;
let candidate = source
.prepare_guarded(guard.clone())
.await
.map_err(|error| {
diagnostics::validation_error("preparation_failed", "web.vhosts[].decoy", error)
})?;
tokio::task::spawn_blocking(move || finish(details, candidate, guard))
.await
.map_err(|_| ApiFailure::internal("Candidate classification worker failed"))?
}
fn parse_patch(
config_path: &Path,
patch_json: &Json,
expected_revision: Option<String>,
) -> Result<(ParsedConfigSource, PatchSource), ApiFailure> {
// 1. optimistic concurrency
let loaded = ProxyConfig::parse_source(config_path)
.map_err(|error| diagnostics::validation_error("source_load_failed", "$", error))?;
let current = compute_snapshot_revision(&loaded.source_contents);
if expected_revision.is_some_and(|expected| expected != current) {
return Err(ApiFailure::new(
hyper::StatusCode::CONFLICT,
"revision_conflict",
"Config revision mismatch",
));
}
// 2. convert + reject access / unknown sections / forbidden server fields
let mut patch_toml = json_to_toml(patch_json)
.map_err(|e| ApiFailure::bad_request(format!("invalid patch: {}", e)))?;
let patch_table = patch_toml
.as_table()
.ok_or_else(|| ApiFailure::bad_request("patch must be a JSON object"))?;
if patch_table.contains_key("access") {
return Err(ApiFailure::new(
hyper::StatusCode::BAD_REQUEST,
"access_not_editable",
"access.* is managed via the users API, not editable here",
));
}
for (key, value) in patch_table {
if !is_editable_section(key.as_str()) {
return Err(ApiFailure::new(
hyper::StatusCode::BAD_REQUEST,
"section_not_editable",
format!("section not editable: {}", key),
));
}
if key == "server" {
validate_server_patch(value)?;
}
}
let touched: Vec<String> = patch_table
.keys()
.map(|k| k.as_str())
.filter(|k| is_editable_section(k))
.map(str::to_owned)
.collect();
if touched.is_empty() {
return Err(ApiFailure::bad_request("empty patch: no editable sections"));
}
diagnostics::reject_unknown(patch_json)?;
let alias_effects = diagnostics::canonicalize_aliases(&mut patch_toml)?;
// 3. Merge against the fully expanded and normalized desired config. The
// source owner is resolved separately so included sections stay in their
// original file and unrelated source files remain byte-identical.
let old_cfg = loaded.config.clone();
let mut merged = Toml::try_from(&old_cfg)
.map_err(|e| ApiFailure::internal(format!("failed to serialize config: {}", e)))?;
deep_merge(&mut merged, &patch_toml);
ProxyConfig::validate_decoy_source_keys(&merged)
.map_err(|error| diagnostics::validation_error("constraint_violation", "$", error))?;
let requested_cfg: ProxyConfig = merged
.clone()
.try_into()
.map_err(|error| diagnostics::validation_error("deserialization_failed", "$", error))?;
requested_cfg
.validate()
.map_err(|error| diagnostics::validation_error("constraint_violation", "$", error))?;
let ownership_targets: Vec<&str> = touched
.iter()
.map(|section| {
if section == "server" {
"server.listeners"
} else {
section.as_str()
}
})
.collect();
let owner_path = resolve_single_source_owner(&loaded, config_path, &ownership_targets)
.map_err(diagnostics::source_conflict)?;
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();
for section in &touched {
if *section == "server" {
let rendered = render_server_listeners(&requested_cfg)?;
owner_contents = upsert_toml_table(&owner_contents, "server.listeners", &rendered);
} else {
let rendered = render_top_level_section(&requested_cfg, section)?;
owner_contents = upsert_toml_table(&owner_contents, section, &rendered);
}
}
let mut overrides = loaded.source_contents.clone();
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")
&& serde_json::to_value(&candidate.config.server.listeners).ok()
!= serde_json::to_value(&requested_cfg.server.listeners).ok()
{
return Err(ApiFailure::new(
hyper::StatusCode::BAD_REQUEST,
"ambiguous_listeners",
"server.listeners normalizes to a different effective listener set",
));
}
Ok((
candidate,
PatchSource {
config_path: config_path.to_path_buf(),
expected_revision: current,
owner_path,
expected_owner_contents,
owner_contents,
old_config: old_cfg,
requested_config: requested_cfg,
patch: patch_json.clone(),
touched,
alias_effects,
},
))
}
fn finish(
source: PatchSource,
candidate: LoadedConfig,
guard: PreparationLease,
) -> Result<PreparedConfigPatch, ApiFailure> {
let revision = compute_snapshot_revision(&candidate.source_contents);
let new_config = candidate.config;
let class = classify_config_changes(&source.old_config, &new_config);
let deferred_process_fields = deferred_process_fields(&source.old_config, &new_config)
.map_err(|error| diagnostics::validation_error("effective_config_invalid", "web", error))?;
let old = serde_json::to_value(&source.old_config)
.map_err(|_| ApiFailure::internal("Cannot project source fields"))?;
let new = serde_json::to_value(&new_config)
.map_err(|_| ApiFailure::internal("Cannot project candidate fields"))?;
let changed_paths = diagnostics::changed_paths(&old, &new);
let mut normalization_effects =
diagnostics::normalization(&source.patch, &source.requested_config, &new_config)?;
normalization_effects.extend(source.alias_effects);
if changed_paths.len() > diagnostics::MAX_PATHS
|| normalization_effects.len() > diagnostics::MAX_PATHS
{
return Err(ApiFailure::bad_request(
"Mutation exceeds the 4096-path feedback limit",
));
}
Ok(PreparedConfigPatch {
config_path: source.config_path,
expected_revision: source.expected_revision,
owner_path: source.owner_path,
expected_owner_contents: source.expected_owner_contents,
owner_contents: source.owner_contents,
desired_config: Arc::new(new_config),
touched: source.touched,
_guard: guard,
response: PatchConfigResponse {
revision,
restart_required: class.restart_required,
runtime_reload_required: class.restart_required,
process_restart_required: !deferred_process_fields.is_empty(),
deferred_process_fields,
changed: class.changed,
changed_paths,
normalization_effects,
reload: None,
},
})
}
+4 -1
View File
@@ -13,7 +13,10 @@ mod persistence;
// Compare-and-replace file persistence and metadata preservation.
mod atomic;
pub(in crate::api) use atomic::{write_atomic, write_atomic_if_unchanged};
pub(in crate::api) use atomic::write_atomic;
#[cfg(test)]
pub(in crate::api) use atomic::write_atomic_if_unchanged;
pub(in crate::api) use atomic::{CommitCheck, write_atomic_with_runtime_check};
#[cfg(test)]
pub(in crate::api) use persistence::save_access_sections_to_disk;
#[cfg(test)]
+64 -4
View File
@@ -1,6 +1,7 @@
use std::fs::File;
use std::io::{Read, Write};
use std::path::{Path, PathBuf};
use std::sync::Arc;
#[cfg(unix)]
use std::os::unix::fs::{MetadataExt, PermissionsExt};
@@ -26,8 +27,20 @@ enum AtomicWriteError {
Conflict,
ReadGraph(String),
Io(std::io::Error),
RuntimeConflict,
}
pub(in crate::api) type CommitCheck = Arc<dyn Fn() -> bool + Send + Sync>;
#[derive(Debug)]
struct RuntimeConflict;
impl std::fmt::Display for RuntimeConflict {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str("Runtime configuration changed before persistence")
}
}
impl std::error::Error for RuntimeConflict {}
struct ExistingTarget {
contents: String,
metadata: std::fs::Metadata,
@@ -36,6 +49,7 @@ struct ExistingTarget {
struct GraphFence<'a> {
config_path: &'a Path,
expected_revision: &'a str,
runtime_check: Option<&'a CommitCheck>,
}
struct ConfigWriteLock {
@@ -98,6 +112,27 @@ pub(in crate::api) async fn write_atomic_if_unchanged(
path: PathBuf,
expected_contents: String,
contents: String,
) -> Result<String, ApiFailure> {
write_atomic_with_runtime_check(
config_path,
expected_revision,
path,
expected_contents,
contents,
None,
)
.await
}
/// The runtime check runs after source fencing, immediately before the rename.
/// It is an optimistic check, not a lock against later runtime publication.
pub(in crate::api) async fn write_atomic_with_runtime_check(
config_path: PathBuf,
expected_revision: String,
path: PathBuf,
expected_contents: String,
contents: String,
runtime_check: Option<CommitCheck>,
) -> Result<String, ApiFailure> {
tokio::task::spawn_blocking(move || {
let config_path = normalize_path(&config_path);
@@ -116,10 +151,16 @@ pub(in crate::api) async fn write_atomic_if_unchanged(
Some(GraphFence {
config_path: &config_path,
expected_revision: &expected_revision,
runtime_check: runtime_check.as_ref(),
}),
)
.map_err(|error| {
if error.kind() == std::io::ErrorKind::AlreadyExists {
if error
.get_ref()
.is_some_and(|inner| inner.is::<RuntimeConflict>())
{
AtomicWriteError::RuntimeConflict
} else if error.kind() == std::io::ErrorKind::AlreadyExists {
AtomicWriteError::Conflict
} else {
AtomicWriteError::Io(error)
@@ -135,6 +176,11 @@ pub(in crate::api) async fn write_atomic_if_unchanged(
.map_err(|error| ApiFailure::internal(format!("failed to join writer: {error}")))?
.map_err(|error| match error {
AtomicWriteError::Conflict => revision_conflict(),
AtomicWriteError::RuntimeConflict => ApiFailure::new(
hyper::StatusCode::CONFLICT,
"runtime_conflict",
"Runtime configuration changed before persistence",
),
AtomicWriteError::ReadGraph(error) => {
ApiFailure::internal(format!("failed to verify config graph: {error}"))
}
@@ -203,7 +249,14 @@ fn fenced_post_commit_revision(
));
};
*owner = contents.to_string();
Ok(compute_source_revision(&graph))
let revision = compute_source_revision(&graph);
if fence.runtime_check.is_some_and(|check| !check()) {
return Err(std::io::Error::new(
std::io::ErrorKind::WouldBlock,
RuntimeConflict,
));
}
Ok(revision)
}
#[cfg(unix)]
@@ -393,9 +446,16 @@ fn write_atomic_sync(
"config target changed during persistence",
));
}
let committed_revision = graph_fence
let committed_revision = match graph_fence
.map(|fence| fenced_post_commit_revision(fence, path, contents))
.transpose()?;
.transpose()
{
Ok(revision) => revision,
Err(error) => {
let _ = std::fs::remove_file(&temp);
return Err(error);
}
};
std::fs::rename(temp, path)?;
Ok(committed_revision)
}
+10 -2
View File
@@ -14,13 +14,17 @@ use super::ApiShared;
use super::model::ApiFailure;
#[cfg(test)]
mod http_tests;
pub(in crate::api) mod http_tests;
mod schema;
#[cfg(test)]
mod tests;
pub(super) use schema::config_schema;
pub(super) fn config_field_paths() -> Result<Vec<&'static str>, ApiFailure> {
schema::field_paths()
}
pub(super) const SCHEMA_VERSION: u32 = 1;
#[derive(Debug, Deserialize, Serialize)]
@@ -43,6 +47,10 @@ pub(super) struct Operation {
pub(super) exact_json_content_type: bool,
#[serde(default)]
pub(super) if_match: bool,
#[serde(default)]
pub(super) if_runtime_match: bool,
#[serde(default)]
pub(super) read_only_operation: bool,
}
#[derive(Debug, Clone, Copy, Deserialize, Serialize)]
@@ -162,7 +170,7 @@ fn build_capabilities(
_ => (Some(true), None),
}
};
let mutation = operation.method != "GET";
let mutation = operation.method != "GET" && !operation.read_only_operation;
entries.push(OperationCapability {
operation,
supported: true,
+29 -4
View File
@@ -16,13 +16,13 @@ use crate::maestro::{
use crate::quota_state::QuotaStateOwner;
use crate::stats::QuotaStore;
struct Fixture {
pub(in crate::api) struct Fixture {
_directory: tempfile::TempDir,
shared: Arc<ApiShared>,
pub(in crate::api) shared: Arc<ApiShared>,
}
impl Fixture {
fn new(whitelist_denied: bool) -> Self {
pub(in crate::api) fn new(whitelist_denied: bool) -> Self {
let directory = tempfile::tempdir().unwrap();
let config_path = directory.path().join("config.toml");
std::fs::write(&config_path, "# discovery must not edit this source\n").unwrap();
@@ -49,6 +49,7 @@ impl Fixture {
),
detected_ips_rx: watch::channel((None, None)).1,
mutation_lock: Arc::new(Mutex::new(())),
config_preflight_slots: Arc::new(tokio::sync::Semaphore::new(2)),
minimal_cache: Arc::new(Mutex::new(None)),
runtime_edge_connections_cache: Arc::new(Mutex::new(None)),
runtime_edge_recompute_lock: Arc::new(Mutex::new(())),
@@ -76,7 +77,23 @@ impl Fixture {
}
}
async fn request(&self, method: &str, path: &str, authorized: bool) -> (u16, String, Value) {
pub(in crate::api) async fn request(
&self,
method: &str,
path: &str,
authorized: bool,
) -> (u16, String, Value) {
self.request_body(method, path, authorized, None, &[]).await
}
pub(in crate::api) async fn request_body(
&self,
method: &str,
path: &str,
authorized: bool,
body: Option<&Value>,
headers: &[(&str, &str)],
) -> (u16, String, Value) {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
let shared = self.shared.clone();
@@ -101,6 +118,14 @@ impl Fixture {
if authorized {
request = request.header("Authorization", "Bearer discovery-test");
}
if let Some(body) = body {
request = request
.header("Content-Type", "application/json")
.body(serde_json::to_vec(body).unwrap());
}
for (name, value) in headers {
request = request.header(*name, *value);
}
let response = request.send().await.unwrap();
let status = response.status().as_u16();
let allow = response
+2 -1
View File
@@ -37,7 +37,8 @@
{"id": "users_active_ips","method": "GET","path": "/v1/stats/users/active-ips","gate": "always","success": [200]},
{"id": "users_quota","method": "GET","path": "/v1/stats/users/quota","gate": "always","success": [200]},
{"id": "config_get","method": "GET","path": "/v1/config","gate": "always","success": [200],"credential_bearing": true},
{"id": "config_patch","method": "PATCH","path": "/v1/config","gate": "always","success": [200,202],"body": "PatchConfigRequest","if_match": true},
{"id": "config_validate","method": "POST","path": "/v1/config/validate","gate": "always","success": [200],"body": "PatchConfigRequest","if_match": true,"if_runtime_match": true,"read_only_operation": true},
{"id": "config_patch","if_runtime_match": true,"method": "PATCH","path": "/v1/config","gate": "always","success": [200,202],"body": "PatchConfigRequest","if_match": true},
{"id": "reload","method": "POST","path": "/v1/system/reload","gate": "always","success": [202],"body": "ReloadRequest","optional_body": true,"if_match": true},
{"id": "reload_status","method": "GET","path": "/v1/system/reload/{id}","gate": "always","success": [200]},
{"id": "users_list","method": "GET","path": "/v1/users","gate": "always","success": [200],"aliases": ["/v1/stats/users"],"credential_bearing": true},
+8
View File
@@ -104,6 +104,14 @@ pub(in crate::api) fn config_schema() -> Result<&'static ConfigSchemaData, ApiFa
.map_err(|error| ApiFailure::internal(error.clone()))
}
pub(super) fn field_paths() -> Result<Vec<&'static str>, ApiFailure> {
Ok(config_schema()?
.fields
.iter()
.map(|field| field.spec.path.as_str())
.collect())
}
fn field_specs() -> Result<Vec<FieldSpec>, String> {
serde_json::from_str(include_str!("fields.json"))
.map_err(|error| format!("invalid compiled config field catalog: {error}"))
+3
View File
@@ -163,6 +163,9 @@ async fn dispatch(
.await
}
("GET", "/v1/config") => fixed_routes::get_config_route(shared).await,
("POST", "/v1/config/validate") => {
fixed_routes::validate_config_route(req, shared, query, body_limit).await
}
("POST", "/v1/system/reload") => {
fixed_routes::reload_route(req, shared, cfg, request_id, body_limit).await
}
+32 -1
View File
@@ -107,9 +107,18 @@ pub(super) async fn patch_config_route(
));
}
let expected_revision = parse_if_match(req.headers());
let expected_runtime = config_edit::parse_runtime_match(req.headers())?;
let reload_request = ReloadRequest::from_query(query).map_err(ApiFailure::bad_request)?;
let body = read_json::<serde_json::Value>(req.into_body(), body_limit).await?;
match config_edit::patch_config(body, expected_revision, reload_request, shared).await {
match config_edit::patch_config(
body,
expected_revision,
expected_runtime,
reload_request,
shared,
)
.await
{
Ok(resp) => {
let revision = resp.revision.clone();
let status = if resp.reload.is_some() {
@@ -127,3 +136,25 @@ pub(super) async fn patch_config_route(
}
}
}
pub(super) async fn validate_config_route(
req: Request<Incoming>,
shared: &Arc<ApiShared>,
query: Option<&str>,
body_limit: usize,
) -> Result<Response<Full<Bytes>>, ApiFailure> {
let expected_revision = parse_if_match(req.headers());
let expected_runtime = config_edit::parse_runtime_match(req.headers())?;
let reload_request = ReloadRequest::from_query(query).map_err(ApiFailure::bad_request)?;
let body = read_json::<serde_json::Value>(req.into_body(), body_limit).await?;
let response = config_edit::validate_config(
body,
expected_revision,
expected_runtime,
reload_request,
shared,
)
.await?;
let revision = response.base_revision.clone();
Ok(success_response(StatusCode::OK, response, revision))
}
+1
View File
@@ -33,6 +33,7 @@ pub(super) fn error_response(request_id: u64, failure: ApiFailure) -> hyper::Res
error: ErrorBody {
code: failure.code,
message: failure.message,
details: failure.details,
},
request_id,
};
+4
View File
@@ -121,6 +121,7 @@ pub(super) struct ApiShared {
pub(super) quota_state: Arc<QuotaStateOwner>,
pub(super) detected_ips_rx: watch::Receiver<(Option<IpAddr>, Option<IpAddr>)>,
pub(super) mutation_lock: Arc<Mutex<()>>,
pub(super) config_preflight_slots: Arc<Semaphore>,
pub(super) minimal_cache: Arc<Mutex<Option<MinimalCacheEntry>>>,
pub(super) runtime_edge_connections_cache: Arc<Mutex<Option<EdgeConnectionsCacheEntry>>>,
pub(super) runtime_edge_recompute_lock: Arc<Mutex<()>>,
@@ -157,6 +158,7 @@ impl ApiShared {
quota_state: self.quota_state.clone(),
detected_ips_rx: self.detected_ips_rx.clone(),
mutation_lock: self.mutation_lock.clone(),
config_preflight_slots: self.config_preflight_slots.clone(),
minimal_cache: self.minimal_cache.clone(),
runtime_edge_connections_cache: self.runtime_edge_connections_cache.clone(),
runtime_edge_recompute_lock: self.runtime_edge_recompute_lock.clone(),
@@ -297,6 +299,7 @@ fn allowed_methods_for_path(path: &str) -> Option<&'static str> {
| "/v1/stats/users"
| "/web-status" => Some(ALLOW_GET),
"/v1/system/reload" => Some(ALLOW_POST),
"/v1/config/validate" => Some(ALLOW_POST),
"/v1/users" => Some(ALLOW_GET_POST),
"/v1/config" => Some(ALLOW_GET_PATCH),
_ if user_action_route_matches(path, "/reset-quota") => Some(ALLOW_POST),
@@ -376,6 +379,7 @@ pub(crate) async fn serve(
quota_state,
detected_ips_rx,
mutation_lock: Arc::new(Mutex::new(())),
config_preflight_slots: Arc::new(Semaphore::new(2)),
minimal_cache: Arc::new(Mutex::new(None)),
runtime_edge_connections_cache: Arc::new(Mutex::new(None)),
runtime_edge_recompute_lock: Arc::new(Mutex::new(())),
+13
View File
@@ -16,6 +16,7 @@ pub(super) struct ApiFailure {
pub(super) code: &'static str,
pub(super) message: String,
pub(super) allow: Option<&'static str>,
pub(super) details: Vec<FieldIssue>,
}
impl ApiFailure {
@@ -25,6 +26,7 @@ impl ApiFailure {
code,
message: message.into(),
allow: None,
details: Vec::new(),
}
}
@@ -42,14 +44,25 @@ impl ApiFailure {
code: "method_not_allowed",
message: "Unsupported HTTP method for this route".to_string(),
allow: Some(allow),
details: Vec::new(),
}
}
}
/// Value-free diagnostics shared by config preview, mutation and validation.
#[derive(Debug, Clone, Serialize)]
pub(super) struct FieldIssue {
pub(super) path: String,
pub(super) code: &'static str,
pub(super) message: String,
}
#[derive(Serialize)]
pub(super) struct ErrorBody {
pub(super) code: &'static str,
pub(super) message: String,
#[serde(skip_serializing_if = "Vec::is_empty")]
pub(super) details: Vec<FieldIssue>,
}
#[derive(Serialize)]
+1
View File
@@ -57,6 +57,7 @@ impl Fixture {
quota_state: QuotaStateOwner::new(dir.path().join("quota.json"), store.clone()),
detected_ips_rx: watch::channel((None, None)).1,
mutation_lock: Arc::new(Mutex::new(())),
config_preflight_slots: Arc::new(tokio::sync::Semaphore::new(2)),
minimal_cache: Arc::new(Mutex::new(None)),
runtime_edge_connections_cache: Arc::new(Mutex::new(None)),
runtime_edge_recompute_lock: Arc::new(Mutex::new(())),
+1 -1
View File
@@ -58,7 +58,7 @@ pub use fields::HotFields;
pub use watcher::spawn_config_watcher;
use diff::{config_equal, warn_non_hot_changes};
use fields::overlay_hot_fields;
pub(crate) use fields::overlay_hot_fields;
use reporting::log_changes;
#[cfg(test)]
use watcher::{ReloadState, reload_config};
+1 -1
View File
@@ -229,7 +229,7 @@ impl HotFields {
}
}
pub(super) fn overlay_hot_fields(old: &ProxyConfig, new: &ProxyConfig) -> ProxyConfig {
pub(crate) fn overlay_hot_fields(old: &ProxyConfig, new: &ProxyConfig) -> ProxyConfig {
let mut cfg = old.clone();
cfg.quota_source_read_at = new.quota_source_read_at;
+27
View File
@@ -1,5 +1,32 @@
use super::*;
#[test]
fn watcher_publication_epoch_distinguishes_hot_round_trips_and_rejected_candidates() {
let directory = tempfile::tempdir().unwrap();
let path = directory.path().join("config.toml");
let source = "[general]\nlog_level = 'normal'\n";
std::fs::write(&path, source).unwrap();
let initial = Arc::new(ProxyConfig::load(&path).unwrap().with_publication_epoch());
let (sender, _receiver) = watch::channel(initial.clone());
let (log_sender, _log_receiver) = watch::channel(initial.general.log_level.clone());
let mut state = ReloadState::new(None);
let mut last_epoch = initial.runtime_config_epoch;
for level in ["debug", "normal"] {
std::fs::write(&path, format!("[general]\nlog_level = '{level}'\n")).unwrap();
assert!(reload_config(&path, &sender, &log_sender, None, None, &mut state).is_some());
assert!(sender.borrow().runtime_config_epoch > last_epoch);
last_epoch = sender.borrow().runtime_config_epoch;
}
assert_eq!(
serde_json::to_value(initial.as_ref()).unwrap(),
serde_json::to_value(sender.borrow().as_ref()).unwrap()
);
assert_eq!(std::fs::read_to_string(&path).unwrap(), source);
std::fs::write(&path, "[general]\nlog_level = 'invalid'\n").unwrap();
assert!(reload_config(&path, &sender, &log_sender, None, None, &mut state).is_none());
assert_eq!(sender.borrow().runtime_config_epoch, last_epoch);
}
fn sample_config() -> ProxyConfig {
ProxyConfig::default()
}
+8 -3
View File
@@ -180,7 +180,9 @@ fn reload_config_with_resolver(
if !hot_changed {
if refresh_quota_source {
config_tx.send(Arc::new(applied_cfg)).ok();
config_tx
.send(Arc::new(applied_cfg.with_publication_epoch()))
.ok();
}
reload_state.mark_applied(rendered_hash);
return Some(next_manifest);
@@ -205,7 +207,9 @@ fn reload_config_with_resolver(
detected_ip_v4,
detected_ip_v6,
);
config_tx.send(Arc::new(applied_cfg)).ok();
config_tx
.send(Arc::new(applied_cfg.with_publication_epoch()))
.ok();
reload_state.mark_applied(rendered_hash);
Some(next_manifest)
}
@@ -261,7 +265,8 @@ pub fn spawn_config_watcher(
impl std::future::Future<Output = ()> + Send + 'static,
) {
let initial_level = initial.general.log_level.clone();
let (config_tx, config_rx) = watch::channel(initial);
let (config_tx, config_rx) =
watch::channel(Arc::new((*initial).clone().with_publication_epoch()));
let (log_tx, log_rx) = watch::channel(initial_level);
let config_path = normalize_watch_path(&config_path);
+3 -1
View File
@@ -53,7 +53,9 @@ pub(super) async fn reload(
{
let mut refreshed = (**config_tx.borrow()).clone();
refreshed.quota_source_read_at = source.config.quota_source_read_at;
config_tx.send(Arc::new(refreshed)).ok();
config_tx
.send(Arc::new(refreshed.with_publication_epoch()))
.ok();
reload_state.mark_applied(source.rendered_hash);
return Some(manifest);
}
+5
View File
@@ -29,6 +29,7 @@ mod runtime_web;
mod decode;
mod effective;
mod pipeline;
mod publication;
// Candidate-owned DNS preparation is separate from pure runtime reconstruction.
mod decoy_dns;
mod validate_core;
@@ -156,6 +157,10 @@ pub struct ProxyConfig {
#[serde(default)]
pub default_dc: Option<u8>,
/// Process-local identity assigned by the owner of a published config snapshot.
#[serde(skip)]
pub(crate) runtime_config_epoch: u64,
/// Monotonic start of source acquisition, used only for cold quota policy fencing.
#[serde(skip)]
pub(crate) quota_source_read_at: Option<std::time::Instant>,
+28 -7
View File
@@ -38,15 +38,36 @@ pub(super) fn finish(mut parsed: ParsedConfigSource) -> Result<LoadedConfig> {
impl ParsedConfigSource {
/// Resolves each unique decoy origin once, then builds a fully validated candidate.
pub(crate) async fn prepare(mut self) -> Result<LoadedConfig> {
decoy_dns::prepare(&mut self.config, |host, port| async move {
tokio::net::lookup_host((host.as_str(), port))
pub(crate) async fn prepare(self) -> Result<LoadedConfig> {
self.prepare_guarded(Arc::new(())).await
}
/// Retains a caller's preparation budget inside blocking work even if the
/// request or DNS timeout drops its future. No worker publishes this data.
pub(crate) async fn prepare_guarded<G: Send + Sync + 'static>(
mut self,
guard: Arc<G>,
) -> Result<LoadedConfig> {
decoy_dns::prepare(&mut self.config, |host, port| {
let guard = guard.clone();
async move {
tokio::task::spawn_blocking(move || {
use std::net::ToSocketAddrs;
let _guard = guard;
(host.as_str(), port)
.to_socket_addrs()
.map(|answers| answers.collect())
})
.await
.map(|answers| answers.collect())
.map_err(|_| std::io::Error::other("DNS preparation worker failed"))?
}
})
.await?;
tokio::task::spawn_blocking(move || finish(self))
.await
.map_err(|error| ProxyError::Config(format!("config preparation failed: {error}")))?
tokio::task::spawn_blocking(move || {
let _guard = guard;
finish(self)
})
.await
.map_err(|error| ProxyError::Config(format!("config preparation failed: {error}")))?
}
}
+13
View File
@@ -0,0 +1,13 @@
use std::sync::atomic::{AtomicU64, Ordering};
use super::ProxyConfig;
impl ProxyConfig {
/// Identifies a publication, including a return to an earlier value. This is
/// not a guarantee that asynchronous policy consumers have converged.
pub(crate) fn with_publication_epoch(mut self) -> Self {
static NEXT_EPOCH: AtomicU64 = AtomicU64::new(1);
self.runtime_config_epoch = NEXT_EPOCH.fetch_add(1, Ordering::Relaxed);
self
}
}
+8
View File
@@ -505,6 +505,14 @@ const LOGGING_CONFIG_KEYS: &[&str] = &[
// Recursive table traversal and key suggestion logic.
mod check;
impl super::ProxyConfig {
/// Checks sparse API input without permissive-mode logging or key suggestions.
/// Dynamic map keys and accepted source aliases retain the source loader rules.
pub(crate) fn unknown_source_paths(document: &toml::Value) -> Vec<String> {
check::unknown_paths(document)
}
}
/// Rejects or reports unknown configuration keys according to strict mode.
pub(super) fn handle_unknown_config_keys(parsed_toml: &toml::Value) -> Result<()> {
let unknown = check::collect_unknown_config_keys(parsed_toml);
+14
View File
@@ -148,6 +148,20 @@ fn check_nested_table_value(
/// Collects unknown keys across every supported nested configuration table.
pub(super) fn collect_unknown_config_keys(parsed_toml: &toml::Value) -> Vec<UnknownConfigKey> {
let known_for_suggestion = known_config_keys_for_suggestion();
collect(parsed_toml, &known_for_suggestion)
}
pub(super) fn unknown_paths(parsed_toml: &toml::Value) -> Vec<String> {
collect(parsed_toml, &[])
.into_iter()
.map(|key| key.path)
.collect()
}
fn collect(
parsed_toml: &toml::Value,
known_for_suggestion: &[&'static str],
) -> Vec<UnknownConfigKey> {
let mut unknown = Vec::new();
if let Some(root) = parsed_toml.as_table() {
+1 -1
View File
@@ -380,7 +380,7 @@ pub(crate) fn test_runtime_generation_with_admission(
config: ProxyConfig,
admission_rx: watch::Receiver<bool>,
) -> Arc<RuntimeGeneration> {
let (config_tx, config_rx) = watch::channel(Arc::new(config.clone()));
let (config_tx, config_rx) = watch::channel(Arc::new(config.clone().with_publication_epoch()));
let stats = Arc::new(Stats::new());
let upstream_manager = Arc::new(UpstreamManager::new(
config.upstreams,