use crate::error::{PackageError, Result};
use crate::slot::{ConfigSlot, SlotType, SuppliedBy};
use std::collections::{BTreeMap, BTreeSet};
const ACCEPTED_KINDS: [&str; 3] = ["endpoint", "secret", "auth_mode"];
const ACCEPTED_FIELDS: [&str; 5] = ["key", "kind", "name", "tested_value", "supplied_by"];
const ACCEPTED_SUPPLIED_BY: [&str; 3] = ["environment", "platform", "runtime"];
const DOCUMENT_LABEL: &str = "<config document>";
const TABLE_LABEL: &str = "config_slots";
fn violation(key: &str, reason: impl Into<String>) -> PackageError {
PackageError::ConfigSlotViolation {
key: key.to_string(),
reason: reason.into(),
}
}
pub(crate) fn parse_document(config_bytes: &[u8]) -> Result<toml::Value> {
let text = std::str::from_utf8(config_bytes)
.map_err(|_| violation(DOCUMENT_LABEL, "config bytes are not valid UTF-8"))?;
toml::from_str::<toml::Value>(text).map_err(|e| {
let where_ = e
.span()
.map_or_else(String::new, |s| format!(" at byte offset {}", s.start));
violation(
DOCUMENT_LABEL,
format!(
"config bytes are not valid TOML{where_} (the parser's message is withheld \
because it would quote config content)"
),
)
})
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct DeclaredConfigSlot {
pub key: String,
pub kind: String,
pub name: String,
pub tested_value: Option<String>,
pub supplied_by: SuppliedBy,
}
pub fn parse_declared_config_slots(config_bytes: &[u8]) -> Result<Vec<DeclaredConfigSlot>> {
parse_declared_config_slots_in(&parse_document(config_bytes)?)
}
pub(crate) fn parse_declared_config_slots_in(
document: &toml::Value,
) -> Result<Vec<DeclaredConfigSlot>> {
let Some(raw) = document.get(TABLE_LABEL) else {
return Ok(Vec::new());
};
let entries = raw.as_array().ok_or_else(|| {
violation(
TABLE_LABEL,
"`config_slots` must be an array of tables (`[[config_slots]]`)",
)
})?;
entries
.iter()
.enumerate()
.map(|(index, entry)| parse_declaration_entry(index, entry))
.collect()
}
fn parse_declaration_entry(index: usize, entry: &toml::Value) -> Result<DeclaredConfigSlot> {
let positional = format!("{TABLE_LABEL}[{index}]");
let table = entry
.as_table()
.ok_or_else(|| violation(&positional, "declaration entry is not a table"))?;
let key = required_string(table, "key", &positional)?;
let label = if key.is_empty() {
positional.clone()
} else {
key.clone()
};
let kind = required_string(table, "kind", &label)?;
if !ACCEPTED_KINDS.contains(&kind.as_str()) {
return Err(violation(
&label,
format!(
"unknown config-slot kind; the accepted kinds are {}",
ACCEPTED_KINDS.join(", ")
),
));
}
let name = required_string(table, "name", &label)?;
let tested_value = match table.get("tested_value") {
None => None,
Some(toml::Value::String(value)) => Some(value.clone()),
Some(_) => return Err(violation(&label, "`tested_value` must be a string")),
};
let supplied_by = parse_supplied_by(table, &label)?;
for field in table.keys() {
if !ACCEPTED_FIELDS.contains(&field.as_str()) {
return Err(violation(
&label,
format!(
"unknown field `{field}` on a `[[config_slots]]` entry; the accepted fields \
are {}. The server that boots from these same bytes parses this table with \
`deny_unknown_fields`, so packing it would ship a package that cannot boot",
ACCEPTED_FIELDS.join(", ")
),
));
}
}
Ok(DeclaredConfigSlot {
key,
kind,
name,
tested_value,
supplied_by,
})
}
fn parse_supplied_by(table: &toml::Table, label: &str) -> Result<SuppliedBy> {
let Some(raw) = table.get("supplied_by") else {
return Ok(SuppliedBy::Environment);
};
let Some(text) = raw.as_str() else {
return Err(violation(label, "`supplied_by` must be a string"));
};
match text {
"environment" => Ok(SuppliedBy::Environment),
"platform" => Ok(SuppliedBy::Platform),
"runtime" => Ok(SuppliedBy::Runtime),
_ => Err(violation(
label,
format!(
"unknown `supplied_by`; the accepted values are {}",
ACCEPTED_SUPPLIED_BY.join(", ")
),
)),
}
}
fn required_string(table: &toml::Table, field: &str, label: &str) -> Result<String> {
match table.get(field) {
Some(toml::Value::String(value)) => Ok(value.clone()),
Some(_) => Err(violation(label, format!("`{field}` must be a string"))),
None => Err(violation(
label,
format!("`{field}` is required on a `[[config_slots]]` entry"),
)),
}
}
type SlotFacts<'a> = (&'a str, &'a str, Option<&'a str>, SuppliedBy);
pub fn validate_config_slot_agreement(
declared: &[DeclaredConfigSlot],
package_slots: &[ConfigSlot],
) -> Result<()> {
let declared_facts = declared_fact_map(declared)?;
let package_facts = package_fact_map(package_slots)?;
let keys: std::collections::BTreeSet<&str> = declared_facts
.keys()
.chain(package_facts.keys())
.copied()
.collect();
for key in keys {
match (declared_facts.get(key), package_facts.get(key)) {
(Some(declaration), Some(package)) => compare_facts(key, *declaration, *package)?,
(Some(_), None) => {
return Err(violation(
key,
"declared in the config's `[[config_slots]]` table but absent from the \
package's config_slots list — the shipped config is the source of truth, \
so add the slot to the package rather than dropping the declaration",
))
},
(None, Some(_)) => {
return Err(violation(
key,
"present in the package's config_slots list but absent from the config's \
`[[config_slots]]` table — a package may not claim a slot the config it \
ships does not declare",
))
},
(None, None) => {},
}
}
Ok(())
}
fn compare_facts(key: &str, declaration: SlotFacts<'_>, package: SlotFacts<'_>) -> Result<()> {
if declaration.0 != package.0 {
return Err(violation(
key,
format!(
"the config declares kind '{}' but the package slot is '{}'",
declaration.0, package.0
),
));
}
if declaration.1 != package.1 {
return Err(violation(
key,
"the declared slot `name` disagrees with the package slot's name",
));
}
if declaration.2 != package.2 {
return Err(violation(
key,
"the declared `tested_value` disagrees with the package slot's tested value",
));
}
if declaration.3 != package.3 {
return Err(violation(
key,
format!(
"the config declares supplied_by '{}' but the package slot is '{}'",
supplied_by_label(declaration.3),
supplied_by_label(package.3)
),
));
}
Ok(())
}
fn supplied_by_label(supplied_by: SuppliedBy) -> &'static str {
match supplied_by {
SuppliedBy::Environment => "environment",
SuppliedBy::Platform => "platform",
SuppliedBy::Runtime => "runtime",
}
}
fn declared_fact_map(declared: &[DeclaredConfigSlot]) -> Result<BTreeMap<&str, SlotFacts<'_>>> {
let mut map = BTreeMap::new();
for declaration in declared {
let facts = (
declaration.kind.as_str(),
declaration.name.as_str(),
declaration.tested_value.as_deref(),
declaration.supplied_by,
);
if map.insert(declaration.key.as_str(), facts).is_some() {
return Err(violation(
&declaration.key,
"declared more than once in the config's `[[config_slots]]` table",
));
}
}
Ok(map)
}
fn package_fact_map(package_slots: &[ConfigSlot]) -> Result<BTreeMap<&str, SlotFacts<'_>>> {
let mut map = BTreeMap::new();
for slot in package_slots {
let Some(config_key) = slot.config_key.as_deref() else {
continue;
};
let (kind, name) = slot.slot.key();
let facts = (kind, name, slot.slot.tested_value(), slot.supplied_by);
if map.insert(config_key, facts).is_some() {
return Err(violation(
config_key,
"claimed by more than one slot in the package's config_slots list",
));
}
}
Ok(map)
}
pub fn validate_config_slot_placeholders(config_bytes: &[u8], slots: &[ConfigSlot]) -> Result<()> {
validate_config_slot_placeholders_in(&parse_document(config_bytes)?, slots)
}
pub(crate) fn validate_config_slot_placeholders_in(
document: &toml::Value,
slots: &[ConfigSlot],
) -> Result<()> {
for slot in slots {
check_slot_placeholder(document, slot)?;
}
Ok(())
}
fn check_slot_placeholder(document: &toml::Value, slot: &ConfigSlot) -> Result<()> {
match &slot.slot {
SlotType::Endpoint { name, .. } | SlotType::Secret { name } => {
let Some(config_key) = slot.config_key.as_deref() else {
return Err(violation(
name,
"a value slot (endpoint or secret) on a package that ships a config file \
must name the config key it fills — without one, pack cannot validate it \
and a target environment cannot be told where to write",
));
};
let value = resolve_dotted_key(document, config_key)?;
let toml::Value::String(raw) = value else {
return Err(violation(
config_key,
"a slot-declared value key must hold a string; this key holds a non-string \
TOML value, which no environment reference can be expressed as",
));
};
if is_env_reference(raw) {
Ok(())
} else if is_malformed_env_reference(raw) {
Err(violation(
config_key,
"holds a malformed environment reference; a reference is exactly one \
`${VAR}` or `env:VAR` naming a single variable ([A-Za-z0-9_]+) — a \
multi-placeholder composition like `${SCHEME}://${HOST}` cannot be \
resolved by any target environment, so compose the full value in ONE \
variable instead",
))
} else {
Err(violation(
config_key,
"holds a resolved literal; a slot-declared value key must hold an \
environment reference (`${VAR}` or `env:VAR`) so the resolved value never \
travels inside a packed layer",
))
}
},
SlotType::AuthMode { tested_value, .. } => {
let Some(config_key) = slot.config_key.as_deref() else {
return Ok(());
};
let value = resolve_dotted_key(document, config_key)?;
let toml::Value::String(baked) = value else {
return Err(violation(
config_key,
"an auth-mode slot must address a string key (the serde tag); this key \
holds a non-string TOML value",
));
};
if baked == tested_value {
Ok(())
} else {
Err(violation(
config_key,
"the baked auth-mode literal disagrees with the slot's declared \
`tested_value`; the config is the source of truth, so update the \
declaration (and the package slot) to the mode the config actually ships",
))
}
},
SlotType::OauthClient { .. }
| SlotType::ChannelBinding { .. }
| SlotType::HumanRole { .. }
| SlotType::LlmProvider { .. }
| SlotType::BudgetOverride { .. } => match slot.config_key.as_deref() {
None => Ok(()),
Some(config_key) => Err(violation(
config_key,
"this slot kind has no config-value semantics, so it cannot fill a TOML config \
key; only endpoint and secret slots address a config value, and auth_mode is \
structural",
)),
},
}
}
fn resolve_dotted_key<'a>(document: &'a toml::Value, config_key: &str) -> Result<&'a toml::Value> {
if config_key.is_empty() {
return Err(violation(
config_key,
"config key is empty; the grammar is one or more dot-separated non-empty TOML bare keys",
));
}
let mut current = document;
for component in config_key.split('.') {
if component.is_empty() {
return Err(violation(
config_key,
"config key has an empty path component (a leading dot, a trailing dot or a \
doubled dot); the grammar is dot-separated non-empty TOML bare keys",
));
}
if !is_bare_key(component) {
return Err(violation(
config_key,
"config key has a component that is not a TOML bare key (A-Z a-z 0-9 _ -); \
quoted keys and array indexing are out of scope, so a TOML key whose literal \
name contains a dot is unaddressable by this grammar",
));
}
let table = current.as_table().ok_or_else(|| {
violation(
config_key,
"config key traverses a value that is not a table; the grammar addresses TOML \
tables only",
)
})?;
current = table.get(component).ok_or_else(|| {
violation(
config_key,
"config key resolves to nothing in the packed config — a slot declaration \
pointing at no key is a defect, not a pass",
)
})?;
}
Ok(current)
}
fn is_bare_key(component: &str) -> bool {
component
.chars()
.all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
}
fn is_env_reference(raw: &str) -> bool {
env_ref_name(raw).is_some()
}
fn env_ref_name(raw: &str) -> Option<&str> {
if let Some(rest) = raw.strip_prefix("env:") {
return (!rest.is_empty()).then_some(rest);
}
raw.strip_prefix("${")
.and_then(|inner| inner.strip_suffix('}'))
.filter(|name| is_valid_env_var_name(name))
}
fn is_valid_env_var_name(name: &str) -> bool {
!name.is_empty() && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
}
const UNREPORTABLE_NAME: &str = "<name withheld: not a settable variable name>";
fn reportable_name(name: &str) -> &str {
if is_valid_env_var_name(name) {
name
} else {
UNREPORTABLE_NAME
}
}
fn is_malformed_env_reference(raw: &str) -> bool {
if let Some(rest) = raw.strip_prefix("env:") {
return rest.is_empty();
}
raw.strip_prefix("${")
.and_then(|inner| inner.strip_suffix('}'))
.is_some_and(|name| !is_valid_env_var_name(name))
}
pub fn validate_no_undeclared_env_refs(config_bytes: &[u8], slots: &[ConfigSlot]) -> Result<()> {
validate_no_undeclared_env_refs_in(&parse_document(config_bytes)?, slots)
}
pub(crate) fn validate_no_undeclared_env_refs_in(
document: &toml::Value,
slots: &[ConfigSlot],
) -> Result<()> {
let Some(root) = document.as_table() else {
return Err(violation(
DOCUMENT_LABEL,
"the config document does not root in a TOML table, so no `config_key` can address \
anything in it and no deferred value could be checked",
));
};
let declared: BTreeSet<&str> = slots
.iter()
.filter_map(|slot| slot.config_key.as_deref())
.collect();
let mut undeclared = BTreeMap::new();
collect_undeclared_env_refs(root, "", &declared, &mut undeclared);
let Some((first, _)) = undeclared.first_key_value() else {
return Ok(());
};
Err(violation(first, undeclared_reason(&undeclared)))
}
fn collect_undeclared_env_refs(
table: &toml::value::Table,
prefix: &str,
declared: &BTreeSet<&str>,
out: &mut BTreeMap<String, String>,
) {
for (key, value) in table {
if key.is_empty() || !is_bare_key(key) {
continue;
}
match value {
toml::Value::String(raw) => {
let Some(name) = env_ref_name(raw) else {
continue;
};
let path = join_dotted(prefix, key);
if !declared.contains(path.as_str()) {
out.insert(path, reportable_name(name).to_string());
}
},
toml::Value::Table(nested) => {
collect_undeclared_env_refs(nested, &join_dotted(prefix, key), declared, out);
},
_ => {},
}
}
}
fn join_dotted(prefix: &str, key: &str) -> String {
if prefix.is_empty() {
key.to_string()
} else {
format!("{prefix}.{key}")
}
}
fn undeclared_reason(undeclared: &BTreeMap<String, String>) -> String {
let listed = undeclared
.iter()
.take(MAX_LISTED_UNDECLARED)
.map(|(key, name)| format!("{key} -> {name}"))
.collect::<Vec<_>>()
.join(", ");
let elided = match undeclared.len().saturating_sub(MAX_LISTED_UNDECLARED) {
0 => String::new(),
n => format!(", and {n} more"),
};
format!(
"the config defers this key to the environment, but it is not among the config keys the \
slot list names — so the packed package under-reports what a target environment must \
supply and the server cannot start where the variable is unset. Declare one slot per \
deferred key ({listed}{elided}). Note only [[config_slots]] entries are read as \
declarations; a slot must carry a `key` for this gate to see it"
)
}
const MAX_LISTED_UNDECLARED: usize = 20;
#[cfg(test)]
mod tests {
use super::*;
use proptest::prelude::*;
const LONDON_TUBE_TOML: &[u8] =
include_bytes!("../../tests/golden_fixtures/config_server_london_tube_v1/london-tube.toml");
fn endpoint_slot() -> ConfigSlot {
ConfigSlot::new(SlotType::Endpoint {
name: "TFL_BASE_URL".to_string(),
tested_value: "https://api.tfl.gov.uk".to_string(),
})
.with_config_key("backend.base_url")
}
fn secret_slot() -> ConfigSlot {
ConfigSlot::new(SlotType::Secret {
name: "TFL_APP_KEY".to_string(),
})
.with_config_key("backend.auth.query_params.app_key")
}
fn auth_mode_slot() -> ConfigSlot {
ConfigSlot::new(SlotType::AuthMode {
name: "backend-auth-mode".to_string(),
tested_value: "api_key".to_string(),
})
.with_config_key("backend.auth.type")
}
fn london_tube_package_slots() -> Vec<ConfigSlot> {
vec![endpoint_slot(), secret_slot(), auth_mode_slot()]
}
fn expect_violation(err: PackageError) -> (String, String) {
match err {
PackageError::ConfigSlotViolation { key, reason } => (key, reason),
other => panic!("expected ConfigSlotViolation, got: {other}"),
}
}
fn naive_leaf_paths(value: &toml::Value, prefix: &str, out: &mut Vec<(String, String)>) {
match value {
toml::Value::String(raw) if !prefix.is_empty() => {
out.push((prefix.to_string(), raw.clone()));
},
toml::Value::Table(table) => {
for (key, nested) in table {
let path = if prefix.is_empty() {
key.clone()
} else {
format!("{prefix}.{key}")
};
naive_leaf_paths(nested, &path, out);
}
},
toml::Value::Array(items) => {
for (index, nested) in items.iter().enumerate() {
let path = if prefix.is_empty() {
index.to_string()
} else {
format!("{prefix}.{index}")
};
naive_leaf_paths(nested, &path, out);
}
},
_ => {},
}
}
fn arbitrary_toml_document() -> impl Strategy<Value = toml::Value> {
let leaf = prop_oneof![
Just(toml::Value::String("${TFL_BASE_URL}".to_string())),
Just(toml::Value::String("env:TFL_APP_KEY".to_string())),
Just(toml::Value::String("${A}-${B}".to_string())),
Just(toml::Value::String("https://api.tfl.gov.uk".to_string())),
Just(toml::Value::Integer(7)),
Just(toml::Value::Boolean(true)),
];
let key = prop_oneof![
Just("a".to_string()),
Just("backend".to_string()),
Just("auth".to_string()),
Just("my".to_string()),
Just("key".to_string()),
Just("my.key".to_string()),
Just(String::new()),
];
let table_of = |inner: BoxedStrategy<toml::Value>, key: BoxedStrategy<String>| {
proptest::collection::btree_map(key, inner, 0..4)
.prop_map(|entries| toml::Value::Table(entries.into_iter().collect()))
};
let tree = leaf.boxed().prop_recursive(4, 32, 4, move |inner| {
prop_oneof![
proptest::collection::vec(inner.clone(), 0..3).prop_map(toml::Value::Array),
table_of(inner, key.clone().boxed()),
]
});
proptest::collection::btree_map(
prop_oneof![
Just("a".to_string()),
Just("backend".to_string()),
Just("my".to_string()),
Just("my.key".to_string()),
],
tree,
0..4,
)
.prop_map(|entries| toml::Value::Table(entries.into_iter().collect()))
}
#[test]
fn the_real_fixture_parses_to_its_three_declared_slots() {
let declared = parse_declared_config_slots(LONDON_TUBE_TOML).unwrap();
assert_eq!(declared.len(), 3, "declared slots were: {declared:?}");
assert_eq!(declared[0].key, "backend.base_url");
assert_eq!(declared[0].kind, "endpoint");
assert_eq!(declared[0].name, "TFL_BASE_URL");
assert_eq!(
declared[0].tested_value.as_deref(),
Some("https://api.tfl.gov.uk"),
"the endpoint records the value it was tested against"
);
assert_eq!(declared[1].key, "backend.auth.query_params.app_key");
assert_eq!(declared[1].kind, "secret");
assert_eq!(declared[1].name, "TFL_APP_KEY");
assert_eq!(
declared[1].tested_value, None,
"an identity-bearing slot structurally carries no tested value"
);
assert_eq!(declared[2].key, "backend.auth.type");
assert_eq!(declared[2].kind, "auth_mode");
assert_eq!(declared[2].name, "backend-auth-mode");
assert_eq!(declared[2].tested_value.as_deref(), Some("api_key"));
}
#[test]
fn a_declaration_without_supplied_by_defaults_to_environment() {
let declared = parse_declared_config_slots(LONDON_TUBE_TOML).unwrap();
assert_eq!(declared.len(), 3);
for entry in &declared {
assert_eq!(entry.supplied_by, SuppliedBy::Environment);
}
}
#[test]
fn a_declaration_can_name_platform_or_runtime() {
let config = br#"
[[config_slots]]
key = "backend.base_url"
kind = "endpoint"
name = "TFL_BASE_URL"
tested_value = "https://api.tfl.gov.uk"
supplied_by = "platform"
[[config_slots]]
key = "backend.function_name"
kind = "secret"
name = "AWS_LAMBDA_FUNCTION_NAME"
supplied_by = "runtime"
"#;
let declared = parse_declared_config_slots(config).unwrap();
assert_eq!(declared[0].supplied_by, SuppliedBy::Platform);
assert_eq!(declared[1].supplied_by, SuppliedBy::Runtime);
}
#[test]
fn an_unknown_supplied_by_value_is_refused_and_never_echoed() {
let config = br#"
[[config_slots]]
key = "backend.base_url"
kind = "endpoint"
name = "TFL_BASE_URL"
tested_value = "x"
supplied_by = "sekrit-injector"
"#;
let (key, reason) = expect_violation(parse_declared_config_slots(config).unwrap_err());
assert_eq!(key, "backend.base_url");
assert!(reason.contains("unknown `supplied_by`"), "was: {reason}");
assert!(
!reason.contains("sekrit-injector"),
"the rejected value leaked into the error: {reason}"
);
}
#[test]
fn a_non_string_supplied_by_is_refused() {
let config = br#"
[[config_slots]]
key = "backend.base_url"
kind = "endpoint"
name = "TFL_BASE_URL"
tested_value = "x"
supplied_by = 3
"#;
let (_, reason) = expect_violation(parse_declared_config_slots(config).unwrap_err());
assert!(reason.contains("must be a string"), "was: {reason}");
}
#[test]
fn supplied_by_is_an_accepted_field_not_an_unknown_one() {
assert!(ACCEPTED_FIELDS.contains(&"supplied_by"));
let config = br#"
[[config_slots]]
key = "backend.base_url"
kind = "endpoint"
name = "TFL_BASE_URL"
tested_value = "x"
supplied_by = "platform"
"#;
parse_declared_config_slots(config)
.expect("a declaration carrying supplied_by must not trip the unknown-field gate");
}
#[test]
fn accepted_supplied_by_matches_the_supplied_by_variants() {
let round_tripped: Vec<SuppliedBy> = ACCEPTED_SUPPLIED_BY
.iter()
.map(|name| {
serde_json::from_value::<SuppliedBy>(serde_json::Value::String((*name).to_string()))
.unwrap_or_else(|_| panic!("`{name}` is not a SuppliedBy serde name"))
})
.collect();
assert_eq!(
round_tripped,
vec![
SuppliedBy::Environment,
SuppliedBy::Platform,
SuppliedBy::Runtime
],
"ACCEPTED_SUPPLIED_BY must stay in step with SuppliedBy's serde names"
);
for (name, value) in ACCEPTED_SUPPLIED_BY.iter().zip(round_tripped.iter()) {
assert_eq!(supplied_by_label(*value), *name);
}
}
#[test]
fn a_supplied_by_disagreement_between_config_and_package_is_refused() {
let config = br#"
[[config_slots]]
key = "backend.base_url"
kind = "endpoint"
name = "TFL_BASE_URL"
tested_value = "https://api.tfl.gov.uk"
supplied_by = "platform"
"#;
let declared = parse_declared_config_slots(config).unwrap();
let package = vec![ConfigSlot::new(SlotType::Endpoint {
name: "TFL_BASE_URL".to_string(),
tested_value: "https://api.tfl.gov.uk".to_string(),
})
.with_config_key("backend.base_url")];
let (key, reason) =
expect_violation(validate_config_slot_agreement(&declared, &package).unwrap_err());
assert_eq!(key, "backend.base_url");
assert!(reason.contains("supplied_by"), "was: {reason}");
assert!(reason.contains("platform"), "was: {reason}");
assert!(reason.contains("environment"), "was: {reason}");
}
#[test]
fn agreement_holds_when_both_sides_name_the_same_supplied_by() {
let config = br#"
[[config_slots]]
key = "backend.base_url"
kind = "endpoint"
name = "TFL_BASE_URL"
tested_value = "https://api.tfl.gov.uk"
supplied_by = "platform"
"#;
let declared = parse_declared_config_slots(config).unwrap();
let package = vec![ConfigSlot::new(SlotType::Endpoint {
name: "TFL_BASE_URL".to_string(),
tested_value: "https://api.tfl.gov.uk".to_string(),
})
.with_config_key("backend.base_url")
.with_supplied_by(SuppliedBy::Platform)];
validate_config_slot_agreement(&declared, &package)
.expect("both sides name platform — this must agree");
}
#[test]
fn accepted_kinds_are_exactly_the_key_discriminators_of_the_config_slot_types() {
let discriminators = [
SlotType::Endpoint {
name: String::new(),
tested_value: String::new(),
}
.key()
.0,
SlotType::Secret {
name: String::new(),
}
.key()
.0,
SlotType::AuthMode {
name: String::new(),
tested_value: String::new(),
}
.key()
.0,
];
assert_eq!(
ACCEPTED_KINDS, discriminators,
"ACCEPTED_KINDS must stay byte-identical to the SlotType::key() discriminators \
of the config-capable kinds — update both together"
);
}
#[test]
fn a_config_with_no_declaration_table_parses_to_an_empty_vec() {
let declared =
parse_declared_config_slots(b"name = \"x\"\n[backend]\nkind = \"openapi\"\n")
.expect("a config that declares nothing is legal");
assert!(declared.is_empty());
}
#[test]
fn agreement_holds_when_both_sides_describe_the_same_three_slots() {
let declared = parse_declared_config_slots(LONDON_TUBE_TOML).unwrap();
validate_config_slot_agreement(&declared, &london_tube_package_slots()).unwrap();
}
#[test]
fn agreement_compares_as_sets_so_declaration_order_is_not_load_bearing() {
let declared = parse_declared_config_slots(LONDON_TUBE_TOML).unwrap();
let reordered = vec![auth_mode_slot(), secret_slot(), endpoint_slot()];
validate_config_slot_agreement(&declared, &reordered).unwrap();
}
#[test]
fn a_declaration_with_no_matching_package_slot_names_that_key() {
let declared = parse_declared_config_slots(LONDON_TUBE_TOML).unwrap();
let missing_the_secret = vec![endpoint_slot(), auth_mode_slot()];
let (key, reason) = expect_violation(
validate_config_slot_agreement(&declared, &missing_the_secret).unwrap_err(),
);
assert_eq!(key, "backend.auth.query_params.app_key");
assert!(reason.contains("absent from the package"), "was: {reason}");
}
#[test]
fn a_package_slot_the_config_never_declares_names_that_key() {
let declared = parse_declared_config_slots(LONDON_TUBE_TOML).unwrap();
let mut invented = london_tube_package_slots();
invented.push(
ConfigSlot::new(SlotType::Secret {
name: "INVENTED".to_string(),
})
.with_config_key("backend.auth.invented"),
);
let (key, reason) =
expect_violation(validate_config_slot_agreement(&declared, &invented).unwrap_err());
assert_eq!(key, "backend.auth.invented");
assert!(reason.contains("absent from the config"), "was: {reason}");
}
#[test]
fn a_kind_disagreement_names_the_key_and_both_kinds() {
let declared = parse_declared_config_slots(LONDON_TUBE_TOML).unwrap();
let wrong_kind = vec![
ConfigSlot::new(SlotType::Secret {
name: "TFL_BASE_URL".to_string(),
})
.with_config_key("backend.base_url"),
secret_slot(),
auth_mode_slot(),
];
let (key, reason) =
expect_violation(validate_config_slot_agreement(&declared, &wrong_kind).unwrap_err());
assert_eq!(key, "backend.base_url");
assert!(reason.contains("endpoint"), "was: {reason}");
assert!(reason.contains("secret"), "was: {reason}");
}
#[test]
fn a_name_disagreement_names_the_key_and_the_field_but_not_the_values() {
let declared = parse_declared_config_slots(LONDON_TUBE_TOML).unwrap();
let wrong_name = vec![
ConfigSlot::new(SlotType::Endpoint {
name: "SOMETHING_ELSE".to_string(),
tested_value: "https://api.tfl.gov.uk".to_string(),
})
.with_config_key("backend.base_url"),
secret_slot(),
auth_mode_slot(),
];
let (key, reason) =
expect_violation(validate_config_slot_agreement(&declared, &wrong_name).unwrap_err());
assert_eq!(key, "backend.base_url");
assert!(reason.contains("`name`"), "was: {reason}");
assert!(
!reason.contains("SOMETHING_ELSE"),
"the message must name the FIELD, not echo the values; was: {reason}"
);
}
#[test]
fn a_tested_value_disagreement_names_the_key_and_the_field_but_not_the_values() {
let declared = parse_declared_config_slots(LONDON_TUBE_TOML).unwrap();
let wrong_tested = vec![
ConfigSlot::new(SlotType::Endpoint {
name: "TFL_BASE_URL".to_string(),
tested_value: "https://sentinel.invalid/other".to_string(),
})
.with_config_key("backend.base_url"),
secret_slot(),
auth_mode_slot(),
];
let (key, reason) =
expect_violation(validate_config_slot_agreement(&declared, &wrong_tested).unwrap_err());
assert_eq!(key, "backend.base_url");
assert!(reason.contains("`tested_value`"), "was: {reason}");
assert!(
!reason.contains("sentinel.invalid"),
"the message must not echo either value; was: {reason}"
);
}
#[test]
fn a_package_slot_with_no_config_key_does_not_participate_in_agreement() {
let declared = parse_declared_config_slots(LONDON_TUBE_TOML).unwrap();
let mut with_unkeyed = london_tube_package_slots();
with_unkeyed.push(ConfigSlot::new(SlotType::LlmProvider {
name: "primary".to_string(),
tested_value: "anthropic".to_string(),
}));
validate_config_slot_agreement(&declared, &with_unkeyed).unwrap();
}
#[test]
fn the_same_key_declared_twice_in_the_config_is_a_violation() {
let declared = vec![
DeclaredConfigSlot {
key: "backend.base_url".to_string(),
kind: "endpoint".to_string(),
name: "A".to_string(),
tested_value: None,
supplied_by: SuppliedBy::Environment,
},
DeclaredConfigSlot {
key: "backend.base_url".to_string(),
kind: "endpoint".to_string(),
name: "B".to_string(),
tested_value: None,
supplied_by: SuppliedBy::Environment,
},
];
let (key, reason) = expect_violation(
validate_config_slot_agreement(&declared, &london_tube_package_slots()).unwrap_err(),
);
assert_eq!(key, "backend.base_url");
assert!(reason.contains("more than once"), "was: {reason}");
}
#[test]
fn the_same_config_key_claimed_by_two_package_slots_is_a_violation() {
let declared = parse_declared_config_slots(LONDON_TUBE_TOML).unwrap();
let mut doubled = london_tube_package_slots();
doubled.push(endpoint_slot());
let (key, reason) =
expect_violation(validate_config_slot_agreement(&declared, &doubled).unwrap_err());
assert_eq!(key, "backend.base_url");
assert!(reason.contains("more than one slot"), "was: {reason}");
}
#[test]
fn an_unknown_kind_names_the_key_and_the_accepted_kinds_without_echoing_it() {
let config = br#"
[[config_slots]]
key = "backend.base_url"
kind = "endpont"
name = "TFL_BASE_URL"
"#;
let (key, reason) = expect_violation(parse_declared_config_slots(config).unwrap_err());
assert_eq!(key, "backend.base_url");
assert!(reason.contains("endpoint"), "was: {reason}");
assert!(reason.contains("secret"), "was: {reason}");
assert!(reason.contains("auth_mode"), "was: {reason}");
assert!(
!reason.contains("endpont"),
"the rejected discriminator is document content and must not be echoed; was: {reason}"
);
}
#[test]
fn a_declaration_missing_its_key_is_named_by_position() {
let config = b"[[config_slots]]\nkind = \"secret\"\nname = \"A\"\n";
let (key, reason) = expect_violation(parse_declared_config_slots(config).unwrap_err());
assert_eq!(key, "config_slots[0]");
assert!(reason.contains("`key` is required"), "was: {reason}");
}
#[test]
fn a_declaration_missing_its_name_is_named_by_key() {
let config = b"[[config_slots]]\nkey = \"backend.base_url\"\nkind = \"endpoint\"\n";
let (key, reason) = expect_violation(parse_declared_config_slots(config).unwrap_err());
assert_eq!(key, "backend.base_url");
assert!(reason.contains("`name` is required"), "was: {reason}");
}
#[test]
fn a_non_string_tested_value_is_a_violation() {
let config =
b"[[config_slots]]\nkey = \"k\"\nkind = \"endpoint\"\nname = \"N\"\ntested_value = 7\n";
let (key, reason) = expect_violation(parse_declared_config_slots(config).unwrap_err());
assert_eq!(key, "k");
assert!(reason.contains("`tested_value` must be"), "was: {reason}");
}
#[test]
fn a_config_slots_key_that_is_not_an_array_of_tables_is_a_violation() {
let config = b"config_slots = \"not-an-array\"\n";
let (key, _) = expect_violation(parse_declared_config_slots(config).unwrap_err());
assert_eq!(key, "config_slots");
}
#[test]
fn a_toml_syntax_error_is_reported_without_quoting_the_offending_line() {
let config = b"backend = { api_key = \"super-secret-sentinel\"\n";
let (key, reason) = expect_violation(parse_declared_config_slots(config).unwrap_err());
assert_eq!(key, DOCUMENT_LABEL);
assert!(
!reason.contains("super-secret-sentinel"),
"the parser's snippet must not reach the message; was: {reason}"
);
}
#[test]
fn non_utf8_config_bytes_are_an_error_not_a_panic() {
let (key, _) =
expect_violation(parse_declared_config_slots(&[0xff, 0xfe, 0x00]).unwrap_err());
assert_eq!(key, DOCUMENT_LABEL);
}
proptest! {
#[test]
fn parse_declared_config_slots_never_panics_on_arbitrary_bytes(
bytes in proptest::collection::vec(any::<u8>(), 0..512)
) {
let _ = parse_declared_config_slots(&bytes);
}
#[test]
fn parse_declared_config_slots_never_panics_on_arbitrary_text(
text in "\\PC{0,200}"
) {
let _ = parse_declared_config_slots(text.as_bytes());
}
}
const SENTINEL_CREDENTIAL: &str = "sentinel-leaked-credential";
const SENTINEL_ENDPOINT: &str = "https://sentinel.invalid/leaked";
fn assert_names_key_without_echoing(err: PackageError, key: &str, forbidden: &str) {
let message = err.to_string();
assert!(
message.contains(key),
"the error must name the config key; message was: {message}"
);
assert!(
!message.contains(forbidden),
"the error must NOT echo the offending value; message was: {message}"
);
}
#[test]
fn an_endpoint_slot_over_an_environment_reference_is_accepted() {
let config = b"[backend]\nbase_url = \"${TFL_BASE_URL}\"\n";
validate_config_slot_placeholders(config, &[endpoint_slot()]).unwrap();
}
#[test]
fn the_env_colon_reference_form_is_accepted_too() {
let config = b"[backend]\nbase_url = \"env:TFL_BASE_URL\"\n";
validate_config_slot_placeholders(config, &[endpoint_slot()]).unwrap();
}
#[test]
fn a_multi_placeholder_composition_is_refused_as_a_malformed_reference() {
let config = b"[backend]\nbase_url = \"${TFL_SCHEME}://${TFL_HOST}\"\n";
let err = validate_config_slot_placeholders(config, &[endpoint_slot()]).unwrap_err();
let msg = err.to_string();
assert!(
msg.contains("malformed environment reference"),
"the error must name the real defect, got: {msg}"
);
assert!(msg.contains("backend.base_url"), "must name the key: {msg}");
}
#[test]
fn the_empty_brace_form_is_refused_as_a_malformed_reference_too() {
let config = b"[backend]\nbase_url = \"${}\"\n";
let err = validate_config_slot_placeholders(config, &[endpoint_slot()]).unwrap_err();
assert!(
err.to_string().contains("malformed environment reference"),
"got: {err}"
);
}
#[test]
fn an_endpoint_slot_over_a_resolved_literal_is_refused_without_echoing_it() {
let config = format!("[backend]\nbase_url = \"{SENTINEL_ENDPOINT}\"\n");
let err =
validate_config_slot_placeholders(config.as_bytes(), &[endpoint_slot()]).unwrap_err();
assert_names_key_without_echoing(err, "backend.base_url", SENTINEL_ENDPOINT);
}
#[test]
fn a_secret_slot_over_a_resolved_literal_is_refused_without_echoing_it() {
let config = format!("[backend.auth.query_params]\napp_key = \"{SENTINEL_CREDENTIAL}\"\n");
let err =
validate_config_slot_placeholders(config.as_bytes(), &[secret_slot()]).unwrap_err();
assert_names_key_without_echoing(
err,
"backend.auth.query_params.app_key",
SENTINEL_CREDENTIAL,
);
}
#[test]
fn an_auth_mode_slot_over_a_baked_literal_is_accepted_because_it_is_structural() {
let config = b"[backend.auth]\ntype = \"api_key\"\n";
validate_config_slot_placeholders(config, &[auth_mode_slot()]).unwrap();
}
#[test]
fn an_auth_mode_slot_whose_config_key_resolves_to_nothing_is_a_violation() {
let config = b"[backend]\nbase_url = \"${X}\"\n";
let (key, reason) = expect_violation(
validate_config_slot_placeholders(config, &[auth_mode_slot()]).unwrap_err(),
);
assert_eq!(key, "backend.auth.type");
assert!(reason.contains("resolves to nothing"), "was: {reason}");
}
#[test]
fn an_auth_mode_baked_literal_disagreeing_with_tested_value_is_refused_without_echo() {
let config = b"[backend.auth]\ntype = \"bearer\"\n";
let err = validate_config_slot_placeholders(config, &[auth_mode_slot()]).unwrap_err();
let message = err.to_string();
assert!(message.contains("backend.auth.type"), "was: {message}");
assert!(message.contains("`tested_value`"), "was: {message}");
assert!(
!message.contains("bearer"),
"the baked literal is document content and must not be echoed; was: {message}"
);
}
#[test]
fn an_auth_mode_key_addressing_a_non_string_is_a_violation() {
let config = b"[backend.auth]\ntype = 7\n";
let (key, reason) = expect_violation(
validate_config_slot_placeholders(config, &[auth_mode_slot()]).unwrap_err(),
);
assert_eq!(key, "backend.auth.type");
assert!(reason.contains("non-string"), "was: {reason}");
}
#[test]
fn an_auth_mode_slot_with_no_config_key_anchors_nothing_and_is_skipped() {
let config = b"[backend.auth]\ntype = \"api_key\"\n";
let slot = ConfigSlot::new(SlotType::AuthMode {
name: "backend-auth-mode".to_string(),
tested_value: "api_key".to_string(),
});
validate_config_slot_placeholders(config, &[slot]).unwrap();
}
#[test]
fn a_value_slot_with_no_config_key_is_a_violation_when_a_config_is_present() {
let config = b"[backend]\nbase_url = \"${TFL_BASE_URL}\"\n";
for slot in [
ConfigSlot::new(SlotType::Secret {
name: "TFL_APP_KEY".to_string(),
}),
ConfigSlot::new(SlotType::Endpoint {
name: "TFL_BASE_URL".to_string(),
tested_value: "https://api.tfl.gov.uk".to_string(),
}),
] {
let err =
validate_config_slot_placeholders(config, std::slice::from_ref(&slot)).unwrap_err();
let (key, reason) = expect_violation(err);
assert_eq!(key, slot.slot.key().1);
assert!(reason.contains("must name the config key"), "was: {reason}");
}
}
#[test]
fn a_non_config_slot_kind_with_no_config_key_is_skipped_not_rejected() {
let config = b"[backend]\nbase_url = \"${TFL_BASE_URL}\"\n";
let slots = vec![
ConfigSlot::new(SlotType::LlmProvider {
name: "primary".to_string(),
tested_value: "anthropic".to_string(),
}),
ConfigSlot::new(SlotType::BudgetOverride {
name: "cap".to_string(),
tested_value: "10".to_string(),
}),
ConfigSlot::new(SlotType::OauthClient {
name: "client".to_string(),
}),
ConfigSlot::new(SlotType::ChannelBinding {
name: "notify".to_string(),
}),
ConfigSlot::new(SlotType::HumanRole {
role: "approver".to_string(),
description: "approves".to_string(),
responsibilities: vec![],
channel_hints: vec![],
}),
];
validate_config_slot_placeholders(config, &slots).unwrap();
}
#[test]
fn a_non_config_slot_kind_carrying_a_config_key_is_a_violation() {
let config = b"[backend]\nbase_url = \"${TFL_BASE_URL}\"\n";
let cases = [
ConfigSlot::new(SlotType::LlmProvider {
name: "primary".to_string(),
tested_value: "anthropic".to_string(),
})
.with_config_key("backend.base_url"),
ConfigSlot::new(SlotType::HumanRole {
role: "approver".to_string(),
description: "approves".to_string(),
responsibilities: vec![],
channel_hints: vec![],
})
.with_config_key("backend.base_url"),
ConfigSlot::new(SlotType::BudgetOverride {
name: "cap".to_string(),
tested_value: "10".to_string(),
})
.with_config_key("backend.base_url"),
ConfigSlot::new(SlotType::OauthClient {
name: "client".to_string(),
})
.with_config_key("backend.base_url"),
ConfigSlot::new(SlotType::ChannelBinding {
name: "notify".to_string(),
})
.with_config_key("backend.base_url"),
];
for slot in cases {
let err =
validate_config_slot_placeholders(config, std::slice::from_ref(&slot)).unwrap_err();
let (key, reason) = expect_violation(err);
assert_eq!(key, "backend.base_url");
assert!(
reason.contains("no config-value semantics"),
"was: {reason}"
);
}
}
#[test]
fn a_config_key_that_resolves_to_nothing_is_a_violation() {
let config = b"[backend]\nother = \"x\"\n";
let (key, reason) = expect_violation(
validate_config_slot_placeholders(config, &[endpoint_slot()]).unwrap_err(),
);
assert_eq!(key, "backend.base_url");
assert!(reason.contains("resolves to nothing"), "was: {reason}");
}
#[test]
fn every_malformed_config_key_is_a_named_violation_not_a_silent_pass() {
let config = b"[backend]\nbase_url = \"${TFL_BASE_URL}\"\n";
let cases: [(&str, &str); 6] = [
("", "is empty"),
(".", "empty path component"),
(".backend", "empty path component"),
("backend.", "empty path component"),
("backend..base_url", "empty path component"),
("backend.base_url.inner", "not a table"),
];
for (config_key, expected_rule) in cases {
let slot = ConfigSlot::new(SlotType::Endpoint {
name: "TFL_BASE_URL".to_string(),
tested_value: "https://api.tfl.gov.uk".to_string(),
})
.with_config_key(config_key);
let (key, reason) =
expect_violation(validate_config_slot_placeholders(config, &[slot]).unwrap_err());
assert_eq!(key, config_key, "the error must name the offending key");
assert!(
reason.contains(expected_rule),
"key {config_key:?} must state which rule it broke; was: {reason}"
);
}
}
#[test]
fn a_quoted_or_indexed_config_key_is_rejected_rather_than_mis_resolved() {
let config = b"[backend]\nbase_url = \"${TFL_BASE_URL}\"\n";
for config_key in ["backend.\"base.url\"", "tools[0].path"] {
let slot = ConfigSlot::new(SlotType::Endpoint {
name: "N".to_string(),
tested_value: "v".to_string(),
})
.with_config_key(config_key);
let (_, reason) =
expect_violation(validate_config_slot_placeholders(config, &[slot]).unwrap_err());
assert!(reason.contains("bare key"), "was: {reason}");
}
}
#[test]
fn a_value_slot_key_addressing_a_non_string_is_a_violation() {
let config = b"[backend]\nbase_url = 7\n";
let (key, reason) = expect_violation(
validate_config_slot_placeholders(config, &[endpoint_slot()]).unwrap_err(),
);
assert_eq!(key, "backend.base_url");
assert!(reason.contains("must hold a string"), "was: {reason}");
}
#[test]
fn is_env_reference_recognises_exactly_the_two_reference_forms() {
assert!(is_env_reference("${TFL_BASE_URL}"));
assert!(is_env_reference("env:TFL_BASE_URL"));
assert!(!is_env_reference("${}"));
assert!(!is_env_reference("env:"));
assert!(!is_env_reference("${TFL_BASE_URL"));
assert!(!is_env_reference("${TFL_BASE_URL}-suffix"));
assert!(!is_env_reference("${TFL_SCHEME}://${TFL_HOST}"));
assert!(!is_env_reference("${A}-${B}"));
assert!(!is_env_reference("${TFL-HOST}"));
assert!(is_env_reference("env:FOO}BAR"));
assert!(is_malformed_env_reference("${TFL_SCHEME}://${TFL_HOST}"));
assert!(is_malformed_env_reference("${}"));
assert!(is_malformed_env_reference("env:"));
assert!(!is_malformed_env_reference("https://api.tfl.gov.uk"));
assert!(!is_malformed_env_reference("${TFL_BASE_URL}"));
assert!(!is_env_reference("https://api.tfl.gov.uk"));
assert!(!is_env_reference(""));
assert!(!is_env_reference(" ${TFL_BASE_URL} "));
}
#[test]
fn the_real_fixture_passes_placeholder_validation_for_all_three_slots() {
validate_config_slot_placeholders(LONDON_TUBE_TOML, &london_tube_package_slots()).unwrap();
}
proptest! {
#[test]
fn validate_config_slot_placeholders_never_panics(
bytes in proptest::collection::vec(any::<u8>(), 0..512),
config_key in "\\PC{0,40}"
) {
let slot = ConfigSlot::new(SlotType::Secret { name: "N".to_string() })
.with_config_key(config_key);
let _ = validate_config_slot_placeholders(&bytes, &[slot]);
}
#[test]
fn resolve_dotted_key_never_panics_on_arbitrary_dotted_keys(
config_key in "[.a-zA-Z0-9_-]{0,40}"
) {
let document: toml::Value =
toml::from_str("[backend]\nbase_url = \"${X}\"\n[backend.auth]\ntype = \"t\"\n")
.unwrap();
let _ = resolve_dotted_key(&document, &config_key);
}
#[test]
fn undeclared_agrees_with_what_resolve_dotted_key_can_address(
document in arbitrary_toml_document()
) {
let table = document
.as_table()
.expect("arbitrary_toml_document always roots in a table");
let declared = BTreeSet::new();
let mut found = BTreeMap::new();
collect_undeclared_env_refs(table, "", &declared, &mut found);
for (path, name) in &found {
let addressable = matches!(
resolve_dotted_key(&document, path),
Ok(toml::Value::String(raw))
if env_ref_name(raw).map(reportable_name) == Some(name.as_str())
);
prop_assert!(
addressable,
"collector emitted `{path}` -> `{name}`, which resolve_dotted_key does not \
address as that reference"
);
}
let mut naive = Vec::new();
naive_leaf_paths(&document, "", &mut naive);
for (path, leaf) in naive {
if env_ref_name(&leaf).is_none() {
continue;
}
let addresses_this_leaf = matches!(
resolve_dotted_key(&document, &path),
Ok(toml::Value::String(raw)) if *raw == leaf
);
if !addresses_this_leaf {
continue;
}
prop_assert!(
found.contains_key(&path),
"resolve_dotted_key addresses `{path}`, which holds the reference `{leaf}`, \
but the collector did not report it — the two walkers have diverged and the \
gate is now fail-open at that shape"
);
}
}
#[test]
fn declaring_a_path_suppresses_exactly_that_path_and_no_other(
document in arbitrary_toml_document()
) {
let table = document
.as_table()
.expect("arbitrary_toml_document always roots in a table");
let mut all = BTreeMap::new();
collect_undeclared_env_refs(table, "", &BTreeSet::new(), &mut all);
let every: BTreeSet<&str> = all.keys().map(String::as_str).collect();
let mut none_left = BTreeMap::new();
collect_undeclared_env_refs(table, "", &every, &mut none_left);
prop_assert!(
none_left.is_empty(),
"declaring every reported path must leave nothing, but {none_left:?} survived"
);
if let Some(dropped) = all.keys().next().cloned() {
let partial: BTreeSet<&str> = every
.iter()
.copied()
.filter(|path| *path != dropped)
.collect();
let mut remaining = BTreeMap::new();
collect_undeclared_env_refs(table, "", &partial, &mut remaining);
let expected: BTreeMap<String, String> = all
.iter()
.filter(|(path, _)| **path == dropped)
.map(|(path, name)| (path.clone(), name.clone()))
.collect();
prop_assert_eq!(
remaining,
expected,
"un-declaring `{}` must bring back exactly that one path",
dropped
);
}
}
#[test]
fn validate_no_undeclared_env_refs_never_panics_on_arbitrary_documents(
document in arbitrary_toml_document(),
config_key in "\\PC{0,40}"
) {
let slot = ConfigSlot::new(SlotType::Secret { name: "N".to_string() })
.with_config_key(config_key);
let _ = validate_no_undeclared_env_refs_in(&document, &[slot]);
if let Ok(text) = toml::to_string(&document) {
let _ = validate_no_undeclared_env_refs(text.as_bytes(), &[]);
}
}
#[test]
fn validate_no_undeclared_env_refs_never_panics(
bytes in proptest::collection::vec(any::<u8>(), 0..512),
config_key in "\\PC{0,40}"
) {
let slot = ConfigSlot::new(SlotType::Secret { name: "N".to_string() })
.with_config_key(config_key);
let _ = validate_no_undeclared_env_refs(&bytes, &[slot]);
}
#[test]
fn a_declared_key_holding_any_valid_reference_always_passes(
name in "[A-Za-z0-9_]{1,24}",
key in "[a-z][a-z0-9_]{0,12}"
) {
let document: toml::Value =
toml::from_str(&format!("[backend]\n{key} = \"${{{name}}}\"\n")).unwrap();
let config_key = format!("backend.{key}");
let slot = ConfigSlot::new(SlotType::Secret { name })
.with_config_key(&config_key);
prop_assert!(validate_no_undeclared_env_refs_in(&document, &[slot]).is_ok());
}
#[test]
fn an_undeclared_reference_is_always_refused_naming_its_key(
name in "[A-Za-z0-9_]{1,24}",
key in "[a-z][a-z0-9_]{0,12}"
) {
let document: toml::Value =
toml::from_str(&format!("[backend]\n{key} = \"${{{name}}}\"\n")).unwrap();
let err = validate_no_undeclared_env_refs_in(&document, &[])
.expect_err("an undeclared reference must never pack");
let rendered = err.to_string();
let expected_key = format!("backend.{key}");
prop_assert!(rendered.contains(&expected_key));
prop_assert!(rendered.contains(&name));
}
}
#[test]
fn a_reference_with_no_slot_is_refused_naming_the_key_and_the_variable() {
let config = b"[server]\nname = \"repro\"\n\n[backend]\nbase_url = \"${SOME_ENDPOINT}\"\n";
assert!(validate_config_slot_placeholders(config, &[]).is_ok());
let err = validate_no_undeclared_env_refs(config, &[])
.expect_err("a deferred value with no slot must not pack");
let rendered = err.to_string();
assert!(rendered.contains("backend.base_url"), "was: {rendered}");
assert!(rendered.contains("SOME_ENDPOINT"), "was: {rendered}");
}
#[test]
fn a_reference_whose_slot_is_declared_is_accepted() {
let config = b"[backend]\nbase_url = \"${TFL_BASE_URL}\"\n";
assert!(validate_no_undeclared_env_refs(config, &[endpoint_slot()]).is_ok());
}
#[test]
fn the_env_prefixed_form_is_gated_identically_to_the_brace_form() {
let config = b"[backend]\nbase_url = \"env:SOME_ENDPOINT\"\n";
let err = validate_no_undeclared_env_refs(config, &[])
.expect_err("`env:VAR` defers a value exactly as `${VAR}` does");
assert!(err.to_string().contains("SOME_ENDPOINT"));
}
#[test]
fn the_real_fixture_has_no_undeclared_references() {
assert!(
validate_no_undeclared_env_refs(LONDON_TUBE_TOML, &london_tube_package_slots()).is_ok()
);
}
#[test]
fn a_reference_inside_an_array_of_tables_is_not_demanded() {
let config = br#"
[[tools]]
name = "t"
script = "await api.get(`/Line/${line.id}/Disruption`)"
[[tools]]
name = "whole-value"
script = "${NOT_ADDRESSABLE}"
"#;
assert!(
validate_no_undeclared_env_refs(config, &[]).is_ok(),
"array elements are unaddressable by the dotted key grammar, so demanding a slot \
for one would be a demand no config author could satisfy"
);
}
#[test]
fn an_embedded_reference_is_not_demanded_because_no_slot_could_fill_it() {
let config = b"[backend]\nbase_url = \"${SCHEME}://${HOST}\"\nother = \"${VAR}-suffix\"\n";
assert!(validate_no_undeclared_env_refs(config, &[]).is_ok());
}
#[test]
fn an_env_prefixed_name_that_is_not_a_settable_variable_is_not_echoed() {
let config = b"[backend]\napi_key = \"env:sk-live-DEADBEEF secret text\"\n";
let (key, reason) =
expect_violation(validate_no_undeclared_env_refs(config, &[]).unwrap_err());
assert_eq!(key, "backend.api_key");
assert!(
!reason.contains("sk-live-DEADBEEF"),
"the credential must never reach the message: {reason}"
);
assert!(reason.contains(UNREPORTABLE_NAME), "was: {reason}");
}
#[test]
fn an_env_prefixed_name_cannot_forge_extra_entries_in_the_list() {
let config = b"[backend]\napi_key = \"env:A, backend.forged -> B\"\n";
let (_, reason) =
expect_violation(validate_no_undeclared_env_refs(config, &[]).unwrap_err());
assert!(
!reason.contains("backend.forged"),
"a config value must not be able to fabricate a listed key: {reason}"
);
}
#[test]
fn a_well_formed_env_prefixed_name_is_still_reported() {
let config = b"[backend]\napi_key = \"env:TFL_APP_KEY\"\n";
let (_, reason) =
expect_violation(validate_no_undeclared_env_refs(config, &[]).unwrap_err());
assert!(reason.contains("TFL_APP_KEY"), "was: {reason}");
}
#[test]
fn the_listed_keys_are_capped_and_the_remainder_is_counted() {
let mut config = String::from("[backend]\n");
let total = MAX_LISTED_UNDECLARED + 5;
for i in 0..total {
config.push_str(&format!("k{i:03} = \"${{VAR{i:03}}}\"\n"));
}
let (_, reason) =
expect_violation(validate_no_undeclared_env_refs(config.as_bytes(), &[]).unwrap_err());
assert!(reason.contains("and 5 more"), "was: {reason}");
assert!(
!reason.contains(&format!("VAR{:03}", total - 1)),
"the tail must be elided, not spelled out: {reason}"
);
}
#[test]
fn a_malformed_whole_value_reference_is_out_of_scope() {
let config = b"[backend]\nbase_url = \"${}\"\napi_key = \"env:\"\n";
assert!(validate_no_undeclared_env_refs(config, &[]).is_ok());
}
#[test]
fn a_resolved_literal_never_triggers_the_gate() {
let config = b"[backend]\nbase_url = \"https://api.tfl.gov.uk\"\n";
assert!(validate_no_undeclared_env_refs(config, &[]).is_ok());
}
#[test]
fn every_undeclared_reference_is_listed_in_one_error() {
let config = br#"
[backend]
base_url = "${BT_ENDPOINT}"
[backend.auth]
client_id = "${BT_CLIENT_ID}"
client_secret = "${BT_CLIENT_SECRET}"
[code_mode]
token_secret = "${CODE_MODE_SECRET}"
"#;
let err = validate_no_undeclared_env_refs(config, &[]).unwrap_err();
let (key, reason) = expect_violation(err);
assert_eq!(
key, "backend.auth.client_id",
"first in lexicographic order"
);
for expected in [
"backend.auth.client_id -> BT_CLIENT_ID",
"backend.auth.client_secret -> BT_CLIENT_SECRET",
"backend.base_url -> BT_ENDPOINT",
"code_mode.token_secret -> CODE_MODE_SECRET",
] {
assert!(reason.contains(expected), "missing {expected} in: {reason}");
}
}
#[test]
fn a_partially_declared_config_reports_only_what_is_still_missing() {
let config = b"[backend]\nbase_url = \"${TFL_BASE_URL}\"\napi_key = \"${TFL_APP_KEY}\"\n";
let err = validate_no_undeclared_env_refs(config, &[endpoint_slot()]).unwrap_err();
let rendered = err.to_string();
assert!(rendered.contains("backend.api_key"), "was: {rendered}");
assert!(
!rendered.contains("backend.base_url"),
"the declared key must not be reported: {rendered}"
);
}
#[test]
fn the_gate_reaches_through_an_inline_table() {
let config = b"[backend.auth]\nquery_params = { app_key = \"${TFL_APP_KEY}\" }\n";
let err = validate_no_undeclared_env_refs(config, &[]).unwrap_err();
assert!(err
.to_string()
.contains("backend.auth.query_params.app_key"));
assert!(validate_no_undeclared_env_refs(config, &[secret_slot()]).is_ok());
}
#[test]
fn a_non_bare_key_is_skipped_as_unaddressable() {
let config = b"[backend]\n\"my.key\" = \"${SOME_VAR}\"\n";
assert!(validate_no_undeclared_env_refs(config, &[]).is_ok());
}
#[test]
fn env_ref_name_yields_the_variable_for_every_accept_row() {
for (raw, expected) in [
("${TFL_BASE_URL}", Some("TFL_BASE_URL")),
("env:TFL_APP_KEY", Some("TFL_APP_KEY")),
("${A}", Some("A")),
("env:A", Some("A")),
("env:FOO}BAR", Some("FOO}BAR")),
("https://api.tfl.gov.uk", None),
("the price is $5 per call", None),
("${}", None),
("env:", None),
("${TFL_BASE_URL", None),
("${TFL_BASE_URL}-suffix", None),
(" ${TFL_BASE_URL} ", None),
("${TFL_SCHEME}://${TFL_HOST}", None),
("${A}-${B}", None),
("${TFL-HOST}", None),
("", None),
] {
assert_eq!(env_ref_name(raw), expected, "env_ref_name({raw:?})");
}
}
}