From 7f00f71a922a86eb3d46b5770db9ecda1747c08d Mon Sep 17 00:00:00 2001 From: Evan Lezar Date: Wed, 18 Nov 2026 13:40:26 +0100 Subject: [PATCH 1/6] refactor(gateway): move config_file into a module directory Move `config_file.rs` to `config_file/mod.rs` with no change to its contents, so the code that loads layered configs can live in its own file. Signed-off-by: Evan Lezar --- .agents/skills/update-docs/SKILL.md | 2 +- .../openshell-server/src/{config_file.rs => config_file/mod.rs} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename crates/openshell-server/src/{config_file.rs => config_file/mod.rs} (100%) diff --git a/.agents/skills/update-docs/SKILL.md b/.agents/skills/update-docs/SKILL.md index a4ecd862b4..8ad24d7ccf 100644 --- a/.agents/skills/update-docs/SKILL.md +++ b/.agents/skills/update-docs/SKILL.md @@ -54,7 +54,7 @@ For each relevant commit, determine which doc page(s) it affects. Use this mappi | `crates/openshell-cli/` (sandbox commands) | `docs/how-it-works/sandboxes/overview.mdx` | | `crates/openshell-cli/` (provider commands) | `docs/how-it-works/providers/overview.mdx` | | `crates/openshell-cli/` (new top-level command) | May need a new page or `docs/reference/` entry | -| `crates/openshell-server/src/config_file.rs` or gateway TOML parsing | `docs/how-it-works/gateways/configuration.mdx` | +| `crates/openshell-server/src/config_file/` or gateway TOML parsing | `docs/how-it-works/gateways/configuration.mdx` | | `crates/openshell-server/src/cli.rs` gateway config merge/default behavior | `docs/how-it-works/gateways/configuration.mdx` | | `crates/openshell-driver-*/` config structs or driver defaults | `docs/how-it-works/gateways/configuration.mdx`, `docs/how-it-works/sandboxes/runtimes.mdx` | | `deploy/helm/openshell/templates/gateway-config.yaml` | `docs/how-it-works/gateways/configuration.mdx`, `docs/how-it-works/sandboxes/runtimes.mdx`, Helm docs if values change | diff --git a/crates/openshell-server/src/config_file.rs b/crates/openshell-server/src/config_file/mod.rs similarity index 100% rename from crates/openshell-server/src/config_file.rs rename to crates/openshell-server/src/config_file/mod.rs From 2c5277ec992ff7126b5f7a54e7f933ef9ab723d4 Mon Sep 17 00:00:00 2001 From: Evan Lezar Date: Wed, 18 Nov 2026 14:06:44 +0100 Subject: [PATCH 2/6] refactor(gateway): share config file loading between startup and preflight Select, read and fold the configuration file into the daemon arguments in one function that both startup and preflight call, so they cannot drift apart on which file they read. Preflight still reports failures in its stable format. Signed-off-by: Evan Lezar --- crates/openshell-server/src/cli.rs | 67 ++++++++++++++++++++---------- 1 file changed, 46 insertions(+), 21 deletions(-) diff --git a/crates/openshell-server/src/cli.rs b/crates/openshell-server/src/cli.rs index e3c8b27186..76c067c921 100644 --- a/crates/openshell-server/src/cli.rs +++ b/crates/openshell-server/src/cli.rs @@ -448,15 +448,7 @@ fn prepare_server_config_with_drivers( // Load TOML when explicitly requested, or from the default XDG location // when that file exists. Missing default config is not an error: runtime // defaults and OPENSHELL_* env vars are enough for package-managed starts. - let config_path = resolve_config_path(args)?; - let mut file: Option = if let Some(path) = config_path { - Some(config_file::load(&path).map_err(|e| miette::miette!("{e}"))?) - } else { - None - }; - if let Some(file) = file.as_ref() { - merge_file_into_args(args, &file.openshell.gateway, matches); - } + let mut file = load_config(args, matches, None, ConfigLoad::Startup)?.file; let legacy_compute_driver_env_seen = resolve_legacy_driver_selector_env(args)?; normalize_compute_driver_socket_args(args)?; let compute_driver = compute_drivers @@ -1123,18 +1115,8 @@ fn run_effective_config_preflight( matches: &ArgMatches, compute_drivers: &ComputeDriverRegistry, ) -> Result> { - let path = if path_override.is_some() { - path_override - } else { - resolve_config_path(&run)? - }; - let mut file = path - .as_ref() - .map(|path| config_file::preflight(path).map_err(|error| miette::miette!("{error}"))) - .transpose()?; - if let Some(file) = file.as_ref() { - merge_file_into_args(&mut run, &file.openshell.gateway, matches); - } + let LoadedConfig { path, mut file } = + load_config(&mut run, matches, path_override, ConfigLoad::Preflight)?; let validation = (|| { // These argument relationships are shared with daemon startup and @@ -1435,6 +1417,49 @@ fn validate_preflight_semantics( Ok(()) } +/// How a configuration file is loaded. Preflight reports a failure in its +/// stable format, while startup reports the full error. +#[derive(Clone, Copy)] +enum ConfigLoad { + Startup, + Preflight, +} + +/// The configuration file a command selected, if any. +struct LoadedConfig { + /// The file that was read, for messages that name it. + path: Option, + file: Option, +} + +/// Load the configuration file selected by `path_override`, `--config` or the +/// default location, and fold its gateway section into `args`. Startup and +/// preflight both go through here so they select and read the same file. +fn load_config( + args: &mut RunArgs, + matches: &ArgMatches, + path_override: Option, + mode: ConfigLoad, +) -> Result { + let path = match path_override { + Some(path) => Some(path), + None => resolve_config_path(args)?, + }; + let file = path + .as_ref() + .map(|path| match mode { + ConfigLoad::Startup => config_file::load(path).map_err(|e| miette::miette!("{e}")), + ConfigLoad::Preflight => { + config_file::preflight(path).map_err(|e| miette::miette!("{e}")) + } + }) + .transpose()?; + if let Some(file) = file.as_ref() { + merge_file_into_args(args, &file.openshell.gateway, matches); + } + Ok(LoadedConfig { path, file }) +} + fn resolve_config_path(args: &RunArgs) -> Result> { if let Some(path) = args.config.clone() { return Ok(Some(path)); From c808c817479ef1b13d67551638a642b6f1eb7ae5 Mon Sep 17 00:00:00 2001 From: Evan Lezar Date: Wed, 18 Nov 2026 14:15:39 +0100 Subject: [PATCH 3/6] refactor(gateway): separate building the runtime config from startup effects Move the assembly of the gateway's runtime configuration out of `prepare_server_config_with_drivers` into `assemble_server_config`, which takes the effective arguments and the configuration file and has no side effects. Startup keeps the steps that create directories, probe drivers and stage artifacts, and behaves as before. Signed-off-by: Evan Lezar --- crates/openshell-server/src/cli.rs | 104 +++++++++++++++++------------ 1 file changed, 60 insertions(+), 44 deletions(-) diff --git a/crates/openshell-server/src/cli.rs b/crates/openshell-server/src/cli.rs index 76c067c921..dcc2d4cd55 100644 --- a/crates/openshell-server/src/cli.rs +++ b/crates/openshell-server/src/cli.rs @@ -483,10 +483,68 @@ fn prepare_server_config_with_drivers( None => defaults::complete_local_jwt_config()?, }; + let config = assemble_server_config(args, matches, file.as_ref(), gateway_jwt)?; + + if let Some(normalized) = normalized_network_trust.as_ref() { + // Use the same resolver as runtime construction, with the explicit + // configuration marker but no synthetic/staged artifact. This rejects + // remote endpoints and factories that have not opted into trust + // propagation before any state is written. + let driver_startup = crate::compute::driver_config::DriverStartupContext { + file: file.as_ref(), + guest_tls: guest_tls.as_ref(), + network_trust: None, + network_trust_configured: true, + gateway_port: config.bind_address.port(), + gateway_tls_enabled: config.tls.is_some(), + endpoint_overrides: &config.compute_driver_endpoints, + }; + crate::validate_compute_driver_config( + compute_drivers, + compute_driver.name(), + &config.name, + config.bind_address, + &config.log_level, + driver_startup, + false, + ) + .map_err(|error| { + miette::miette!( + "Network supervisor additional destination trust configured: certificate_count={} digest={}: {error}", + normalized.certificate_count(), + normalized.digest() + ) + })?; + } + let network_trust = normalized_network_trust + .map(crate::network_trust::stage_normalized) + .transpose()?; + + Ok(ServerStartupConfig { + config, + config_file: file, + guest_tls, + network_trust, + compute_driver, + legacy_compute_driver_env_seen, + }) +} + +/// Build the gateway's runtime configuration from the effective arguments and +/// the configuration file. This has no side effects beyond reading +/// `OPENSHELL_PROVISIONING_REPAIR_WINDOW_SECONDS`: it creates no directories, +/// stages no artifacts and probes no drivers, so a failure here is a pure +/// configuration error. +fn assemble_server_config( + args: &RunArgs, + matches: &ArgMatches, + file: Option<&ConfigFile>, + gateway_jwt: Option, +) -> Result { let bind = SocketAddr::new(args.bind_address, args.port); let has_client_ca = args.tls_client_ca.is_some(); - let mtls_auth_enabled = resolve_mtls_auth_enabled(args, matches, file.as_ref()); + let mtls_auth_enabled = resolve_mtls_auth_enabled(args, matches, file); if args.disable_tls && has_client_ca { return Err(miette::miette!( @@ -800,49 +858,7 @@ fn prepare_server_config_with_drivers( // user-authored config file. config.gateway_jwt = gateway_jwt; - if let Some(normalized) = normalized_network_trust.as_ref() { - // Use the same resolver as runtime construction, with the explicit - // configuration marker but no synthetic/staged artifact. This rejects - // remote endpoints and factories that have not opted into trust - // propagation before any state is written. - let driver_startup = crate::compute::driver_config::DriverStartupContext { - file: file.as_ref(), - guest_tls: guest_tls.as_ref(), - network_trust: None, - network_trust_configured: true, - gateway_port: config.bind_address.port(), - gateway_tls_enabled: config.tls.is_some(), - endpoint_overrides: &config.compute_driver_endpoints, - }; - crate::validate_compute_driver_config( - compute_drivers, - compute_driver.name(), - &config.name, - config.bind_address, - &config.log_level, - driver_startup, - false, - ) - .map_err(|error| { - miette::miette!( - "Network supervisor additional destination trust configured: certificate_count={} digest={}: {error}", - normalized.certificate_count(), - normalized.digest() - ) - })?; - } - let network_trust = normalized_network_trust - .map(crate::network_trust::stage_normalized) - .transpose()?; - - Ok(ServerStartupConfig { - config, - config_file: file, - guest_tls, - network_trust, - compute_driver, - legacy_compute_driver_env_seen, - }) + Ok(config) } const UNAUTHENTICATED_USERS_WARNING: &str = "unauthenticated user access is enabled; only use this for trusted local development or a fully trusted fronting proxy"; From c487a507f2201c125a6bce74b509786525b10319 Mon Sep 17 00:00:00 2001 From: Evan Lezar Date: Wed, 18 Nov 2026 13:00:44 +0100 Subject: [PATCH 4/6] feat(gateway): merge drop-in configs over the base file Load `*.toml` drop-in configs from a directory and merge them over the base config in lexical order, so operators and packages can customize a gateway without editing the base file. Select the directory with `--config-dir` or `OPENSHELL_GATEWAY_CONFIG_DIR`, or let the gateway use `gateway.d` beside the base file. An empty value turns drop-in configs off. `--config` and `--config-dir` compose. Tables merge key by key; scalars and arrays replace; a drop-in cannot unset a key. Every file must declare `[openshell] version = 2` as an integer, but a drop-in may set only some keys of a table. The merged result is validated once. An error names the file that sets the offending key, with its line and column for a single file and its key path for several. Errors that no single key explains, such as a missing required key or a rule over a table that several files set, name the merged configuration and its files. Unknown keys are rejected. Follow a drop-in symlink only when it resolves inside the drop-in directory, which covers Kubernetes ConfigMap mounts, and keep the base file strict. Treat a `gateway.d` with no drop-in configs and no base file as no configuration. `load` and `preflight` use the same loader, `config preflight` lists the files it merged, and the gateway logs them at startup. Signed-off-by: Evan Lezar --- Cargo.lock | 1 + crates/openshell-server/Cargo.toml | 1 + crates/openshell-server/src/cli.rs | 472 ++++++++++-- .../src/config_file/layered.rs | 381 ++++++++++ .../openshell-server/src/config_file/mod.rs | 680 ++++++++++++++++-- crates/openshell-server/src/lib.rs | 3 + deploy/man/openshell-gateway.8.md | 17 +- deploy/rpm/CONFIGURATION.md | 10 + docs/how-it-works/gateways/configuration.mdx | 26 +- skills/debug-openshell-cluster/SKILL.md | 6 +- 10 files changed, 1475 insertions(+), 122 deletions(-) create mode 100644 crates/openshell-server/src/config_file/layered.rs diff --git a/Cargo.lock b/Cargo.lock index 458b6000aa..837c9625f5 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -5156,6 +5156,7 @@ dependencies = [ "rustls-pki-types", "serde", "serde_json", + "serde_path_to_error", "sha2 0.10.9", "socket2", "spiffe", diff --git a/crates/openshell-server/Cargo.toml b/crates/openshell-server/Cargo.toml index 9d7f9299db..886a916778 100644 --- a/crates/openshell-server/Cargo.toml +++ b/crates/openshell-server/Cargo.toml @@ -88,6 +88,7 @@ bytes = { workspace = true } pin-project-lite = { workspace = true } serde = { workspace = true } serde_json = { workspace = true } +serde_path_to_error = { workspace = true } toml = { workspace = true } tokio-stream = { workspace = true } sqlx = { workspace = true } diff --git a/crates/openshell-server/src/cli.rs b/crates/openshell-server/src/cli.rs index dcc2d4cd55..9d3e48101d 100644 --- a/crates/openshell-server/src/cli.rs +++ b/crates/openshell-server/src/cli.rs @@ -59,12 +59,27 @@ enum ConfigCommand { Preflight(ConfigPreflightArgs), } +/// Parse a path, accepting the empty string that clap's `PathBuf` parser rejects. +fn allow_empty_path() -> impl clap::builder::TypedValueParser { + use clap::builder::TypedValueParser as _; + clap::builder::OsStringValueParser::new().map(PathBuf::from) +} + #[derive(clap::Args, Debug, Default)] struct ConfigPreflightArgs { /// Explicit configuration path. Overrides `OPENSHELL_GATEWAY_CONFIG` and XDG discovery. #[arg(long, conflicts_with = "gateway_args")] path: Option, + /// Explicit drop-in directory. Defaults to `gateway.d` next to the base file. + /// An empty value disables drop-in configs. + #[arg( + long, + conflicts_with = "gateway_args", + value_parser = allow_empty_path() + )] + config_dir: Option, + /// Gateway daemon arguments to replay after `--`. #[arg(last = true, allow_hyphen_values = true, value_name = "GATEWAY_ARGS")] gateway_args: Vec, @@ -81,6 +96,15 @@ struct RunArgs { #[arg(long, env = "OPENSHELL_GATEWAY_CONFIG")] config: Option, + /// Directory of `*.toml` drop-in configs merged over the base file. + /// + /// Drop-in configs apply in lexical order and a later drop-in config wins. Tables + /// merge key by key; scalars and arrays replace. Defaults to `gateway.d` + /// next to the base file when that directory exists. An empty value + /// disables drop-in configs. + #[arg(long, env = "OPENSHELL_GATEWAY_CONFIG_DIR", value_parser = allow_empty_path())] + config_dir: Option, + /// Operator-assigned name for this gateway installation. #[arg( long = "name", @@ -448,7 +472,11 @@ fn prepare_server_config_with_drivers( // Load TOML when explicitly requested, or from the default XDG location // when that file exists. Missing default config is not an error: runtime // defaults and OPENSHELL_* env vars are enough for package-managed starts. - let mut file = load_config(args, matches, None, ConfigLoad::Startup)?.file; + let LoadedConfig { + mut file, + sources: config_sources, + .. + } = load_config(args, matches, None, None, ConfigLoad::Startup)?; let legacy_compute_driver_env_seen = resolve_legacy_driver_selector_env(args)?; normalize_compute_driver_socket_args(args)?; let compute_driver = compute_drivers @@ -523,6 +551,7 @@ fn prepare_server_config_with_drivers( Ok(ServerStartupConfig { config, config_file: file, + config_sources, guest_tls, network_trust, compute_driver, @@ -943,6 +972,12 @@ async fn run_from_args( gateway_resource, ); + if !prepared.config_sources.is_empty() { + info!( + files = ?prepared.config_sources, + "Gateway configuration loaded from base file and drop-in configs" + ); + } if prepared.legacy_compute_driver_env_seen { warn!("OPENSHELL_DRIVERS is deprecated; migrate to OPENSHELL_COMPUTE_DRIVER"); } @@ -1098,7 +1133,13 @@ fn run_config_preflight_with_drivers( compute_drivers: &ComputeDriverRegistry, ) -> Result> { if args.gateway_args.is_empty() { - return run_effective_config_preflight(args.path, run, matches, compute_drivers); + return run_effective_config_preflight( + args.path, + args.config_dir, + run, + matches, + compute_drivers, + ); } let replay_matches = match command().try_get_matches_from( @@ -1122,17 +1163,30 @@ fn run_config_preflight_with_drivers( // configuration. Let the immediately following invocation perform it. return Ok(None); } - run_effective_config_preflight(None, replay.run, &replay_matches, compute_drivers) + run_effective_config_preflight(None, None, replay.run, &replay_matches, compute_drivers) } fn run_effective_config_preflight( path_override: Option, + dir_override: Option, mut run: RunArgs, matches: &ArgMatches, compute_drivers: &ComputeDriverRegistry, ) -> Result> { - let LoadedConfig { path, mut file } = - load_config(&mut run, matches, path_override, ConfigLoad::Preflight)?; + let LoadedConfig { + path, + mut file, + sources, + } = load_config( + &mut run, + matches, + path_override, + dir_override, + ConfigLoad::Preflight, + )?; + for source in &sources { + println!("config: merged {}", source.display()); + } let validation = (|| { // These argument relationships are shared with daemon startup and @@ -1433,62 +1487,120 @@ fn validate_preflight_semantics( Ok(()) } -/// How a configuration file is loaded. Preflight reports a failure in its -/// stable format, while startup reports the full error. +/// Where gateway configuration is read from: an optional base file and an +/// optional directory of `*.toml` drop-in configs merged over it. +#[derive(Debug, Default)] +struct ConfigSources { + base: Option, + dir: Option, +} + +impl ConfigSources { + fn is_empty(&self) -> bool { + self.base.is_none() && self.dir.is_none() + } +} + +fn resolve_config_sources( + args: &RunArgs, + base_override: Option, + dir_override: Option, +) -> Result { + let base = if let Some(path) = base_override.or_else(|| args.config.clone()) { + Some(path) + } else { + let default_path = defaults::default_gateway_config_path()?; + match std::fs::symlink_metadata(&default_path) { + Err(error) if error.kind() == std::io::ErrorKind::NotFound => None, + // Fail closed when the path exists or cannot be inspected. + // Returning it lets the shared loader produce the same safe, + // path-specific error used for an explicit configuration. + Ok(_) | Err(_) => Some(default_path), + } + }; + // An explicit directory must exist, and an empty one turns drop-in configs + // off. Otherwise use `gateway.d` beside the base file (or beside the + // default location) when it is there. + let dir = if let Some(dir) = dir_override.or_else(|| args.config_dir.clone()) { + (!dir.as_os_str().is_empty()).then_some(dir) + } else { + let anchor = match base.clone() { + Some(path) => path, + None => defaults::default_gateway_config_path()?, + }; + anchor + .parent() + .map(|parent| parent.join("gateway.d")) + .filter(|dir| dir.is_dir()) + }; + // A directory with no drop-in configs and no base file holds no + // configuration, so the gateway starts on its defaults as it would + // without the directory. + let dir = match (&base, dir) { + (None, Some(dir)) + if config_file::drop_in_paths(&dir).is_ok_and(|paths| paths.is_empty()) => + { + None + } + (_, dir) => dir, + }; + Ok(ConfigSources { base, dir }) +} + +/// How a configuration is loaded. Preflight reports a failure in its stable +/// format, while startup reports the full error. #[derive(Clone, Copy)] enum ConfigLoad { Startup, Preflight, } -/// The configuration file a command selected, if any. +/// The configuration a command selected, if any. struct LoadedConfig { - /// The file that was read, for messages that name it. + /// The base file, or the drop-in directory when there is none, for + /// messages that name where the configuration came from. path: Option, file: Option, + /// Files merged into `file`, base first, then drop-in configs. + sources: Vec, } -/// Load the configuration file selected by `path_override`, `--config` or the -/// default location, and fold its gateway section into `args`. Startup and -/// preflight both go through here so they select and read the same file. +/// Load the configuration selected by the overrides, `--config`, +/// `--config-dir` or the default location, and fold its gateway section into +/// `args`. Startup and preflight both go through here so they select, read +/// and merge the same files. fn load_config( args: &mut RunArgs, matches: &ArgMatches, - path_override: Option, + base_override: Option, + dir_override: Option, mode: ConfigLoad, ) -> Result { - let path = match path_override { - Some(path) => Some(path), - None => resolve_config_path(args)?, - }; - let file = path - .as_ref() - .map(|path| match mode { - ConfigLoad::Startup => config_file::load(path).map_err(|e| miette::miette!("{e}")), - ConfigLoad::Preflight => { - config_file::preflight(path).map_err(|e| miette::miette!("{e}")) - } - }) - .transpose()?; - if let Some(file) = file.as_ref() { - merge_file_into_args(args, &file.openshell.gateway, matches); - } - Ok(LoadedConfig { path, file }) -} - -fn resolve_config_path(args: &RunArgs) -> Result> { - if let Some(path) = args.config.clone() { - return Ok(Some(path)); - } - - let default_path = defaults::default_gateway_config_path()?; - match std::fs::symlink_metadata(&default_path) { - Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None), - // Fail closed when the path exists or cannot be inspected. Returning it - // lets the shared loader produce the same safe, path-specific error used - // for an explicit configuration instead of treating it as absent. - Ok(_) | Err(_) => Ok(Some(default_path)), + let selected = resolve_config_sources(args, base_override, dir_override)?; + let path = selected.base.clone().or_else(|| selected.dir.clone()); + if selected.is_empty() { + return Ok(LoadedConfig { + path, + file: None, + sources: Vec::new(), + }); } + let layered = match mode { + ConfigLoad::Startup => { + config_file::load_layered(selected.base.as_deref(), selected.dir.as_deref()) + .map_err(|e| miette::miette!("{e}"))? + } + ConfigLoad::Preflight => { + config_file::preflight_layered(selected.base.as_deref(), selected.dir.as_deref()) + .map_err(|e| miette::miette!("{e}"))? + } + }; + merge_file_into_args(args, &layered.file.openshell.gateway, matches); + Ok(LoadedConfig { + path, + file: Some(layered.file), + sources: layered.sources, + }) } fn apply_runtime_defaults(args: &mut RunArgs) -> Result> { @@ -3732,13 +3844,23 @@ require_client_auth = true let tmp = std::path::PathBuf::from(std::env::var_os("XDG_CONFIG_HOME").unwrap()); let (args, _) = parse_with_args(&["openshell-gateway"]); - assert_eq!(super::resolve_config_path(&args).unwrap(), None); + assert_eq!( + super::resolve_config_sources(&args, None, None) + .unwrap() + .base, + None + ); let config = tmp.join("openshell").join("gateway.toml"); std::fs::create_dir_all(config.parent().unwrap()).unwrap(); std::fs::write(&config, "[openshell]\nversion = 2\n").unwrap(); - assert_eq!(super::resolve_config_path(&args).unwrap(), Some(config)); + assert_eq!( + super::resolve_config_sources(&args, None, None) + .unwrap() + .base, + Some(config) + ); }); } @@ -3751,12 +3873,256 @@ require_client_auth = true parse_with_args(&["openshell-gateway", "--config", "/tmp/missing.toml"]); assert_eq!( - super::resolve_config_path(&args).unwrap(), + super::resolve_config_sources(&args, None, None) + .unwrap() + .base, Some(std::path::PathBuf::from("/tmp/missing.toml")) ); }); } + #[test] + fn config_dir_defaults_to_gateway_d_beside_the_base_file() { + let tmp = tempfile::tempdir().unwrap(); + let base = tmp.path().join("gateway.toml"); + std::fs::write(&base, "[openshell]\nversion = 2\n").unwrap(); + Environment::new() + .remove("OPENSHELL_GATEWAY_CONFIG") + .remove("OPENSHELL_GATEWAY_CONFIG_DIR") + .run(|| { + let (args, _) = + parse_with_args(&["openshell-gateway", "--config", base.to_str().unwrap()]); + assert_eq!( + super::resolve_config_sources(&args, None, None) + .unwrap() + .dir, + None, + "a missing gateway.d is not an error" + ); + std::fs::create_dir(tmp.path().join("gateway.d")).unwrap(); + assert_eq!( + super::resolve_config_sources(&args, None, None) + .unwrap() + .dir, + Some(tmp.path().join("gateway.d")) + ); + }); + } + + #[test] + fn a_config_dir_without_drop_ins_or_a_base_file_is_no_configuration() { + let xdg = tempfile::tempdir().unwrap(); + Environment::new() + .set("XDG_CONFIG_HOME", xdg.path().to_str().unwrap()) + .remove("OPENSHELL_GATEWAY_CONFIG") + .remove("OPENSHELL_GATEWAY_CONFIG_DIR") + .run(|| { + // The environment runs this closure in a child process that + // inherits `XDG_CONFIG_HOME`, so build paths from it. + let dir = std::path::PathBuf::from(std::env::var_os("XDG_CONFIG_HOME").unwrap()) + .join("openshell") + .join("gateway.d"); + std::fs::create_dir_all(&dir).unwrap(); + std::fs::write(dir.join("notes.txt"), "not a drop-in").unwrap(); + let (args, _) = parse_with_args(&["openshell-gateway"]); + assert!( + super::resolve_config_sources(&args, None, None) + .unwrap() + .is_empty() + ); + std::fs::write(dir.join("10-a.toml"), "[openshell]\nversion = 2\n").unwrap(); + assert_eq!( + super::resolve_config_sources(&args, None, None) + .unwrap() + .dir, + Some(dir) + ); + }); + } + + #[test] + fn explicit_config_dir_overrides_the_implicit_directory() { + let tmp = tempfile::tempdir().unwrap(); + let other = tmp.path().join("other"); + let base = tmp.path().join("gateway.toml"); + std::fs::write(&base, "[openshell]\nversion = 2\n").unwrap(); + std::fs::create_dir(tmp.path().join("gateway.d")).unwrap(); + Environment::new() + .remove("OPENSHELL_GATEWAY_CONFIG") + .remove("OPENSHELL_GATEWAY_CONFIG_DIR") + .run(|| { + let (args, _) = parse_with_args(&[ + "openshell-gateway", + "--config", + base.to_str().unwrap(), + "--config-dir", + other.to_str().unwrap(), + ]); + assert_eq!( + super::resolve_config_sources(&args, None, None) + .unwrap() + .dir, + Some(other.clone()) + ); + }); + } + + #[test] + fn an_empty_config_dir_disables_drop_in_configs() { + let tmp = tempfile::tempdir().unwrap(); + let base = tmp.path().join("gateway.toml"); + std::fs::write(&base, "[openshell]\nversion = 2\n").unwrap(); + std::fs::create_dir(tmp.path().join("gateway.d")).unwrap(); + std::fs::write( + tmp.path().join("gateway.d").join("10-a.toml"), + "[openshell]\nversion = 2\n", + ) + .unwrap(); + let base_arg = base.to_str().unwrap(); + // The flag, then the environment variable. + Environment::new() + .remove("OPENSHELL_GATEWAY_CONFIG") + .remove("OPENSHELL_GATEWAY_CONFIG_DIR") + .run(|| { + let (args, _) = parse_with_args(&[ + "openshell-gateway", + "--config", + base_arg, + "--config-dir", + "", + ]); + assert_eq!( + super::resolve_config_sources(&args, None, None) + .unwrap() + .dir, + None + ); + }); + Environment::new() + .remove("OPENSHELL_GATEWAY_CONFIG") + .set("OPENSHELL_GATEWAY_CONFIG_DIR", "") + .run(|| { + let (args, _) = parse_with_args(&["openshell-gateway", "--config", base_arg]); + assert_eq!( + super::resolve_config_sources(&args, None, None) + .unwrap() + .dir, + None + ); + }); + } + + #[test] + fn preflight_merges_drop_ins_and_names_a_bad_drop_in() { + let tmp = tempfile::tempdir().unwrap(); + let base = tmp.path().join("gateway.toml"); + std::fs::write(&base, "[openshell]\nversion = 2\n").unwrap(); + let dir = tmp.path().join("gateway.d"); + std::fs::create_dir(&dir).unwrap(); + std::fs::write( + dir.join("10-ok.toml"), + "[openshell]\nversion = 2\n[openshell.gateway]\nlog_level = 'debug'\n", + ) + .unwrap(); + let xdg = tempfile::tempdir().unwrap(); + Environment::new() + .set("XDG_CONFIG_HOME", xdg.path().to_str().unwrap()) + .set("XDG_STATE_HOME", xdg.path().to_str().unwrap()) + .remove("OPENSHELL_GATEWAY_CONFIG") + .remove("OPENSHELL_GATEWAY_CONFIG_DIR") + .remove("OPENSHELL_COMPUTE_DRIVER") + .remove("OPENSHELL_DRIVERS") + .run(|| { + let args = || super::ConfigPreflightArgs { + path: Some(base.clone()), + ..Default::default() + }; + let (run, matches) = parse_with_args(&["openshell-gateway", "--disable-tls"]); + super::run_config_preflight(args(), run, &matches).unwrap(); + + std::fs::write( + dir.join("20-bad.toml"), + "[openshell]\nversion = 2\n[openshell.gateway]\nnot_a_field = 1\n", + ) + .unwrap(); + let (run, matches) = parse_with_args(&["openshell-gateway", "--disable-tls"]); + let error = super::run_config_preflight(args(), run, &matches) + .unwrap_err() + .to_string(); + assert!(error.contains("category=malformed"), "{error}"); + assert!(error.contains("20-bad.toml"), "{error}"); + }); + } + + #[test] + fn an_explicit_config_dir_that_does_not_exist_fails_and_names_the_directory() { + let tmp = tempfile::tempdir().unwrap(); + let base = tmp.path().join("gateway.toml"); + std::fs::write(&base, "[openshell]\nversion = 2\n").unwrap(); + let missing = tmp.path().join("missing.d"); + let xdg = tempfile::tempdir().unwrap(); + Environment::new() + .set("XDG_CONFIG_HOME", xdg.path().to_str().unwrap()) + .set("XDG_STATE_HOME", xdg.path().to_str().unwrap()) + .remove("OPENSHELL_GATEWAY_CONFIG") + .remove("OPENSHELL_GATEWAY_CONFIG_DIR") + .remove("OPENSHELL_COMPUTE_DRIVER") + .remove("OPENSHELL_DRIVERS") + .run(|| { + let (mut run, matches) = parse_with_args(&[ + "openshell-gateway", + "--disable-tls", + "--config", + base.to_str().unwrap(), + "--config-dir", + missing.to_str().unwrap(), + ]); + let error = super::prepare_server_config(&mut run, &matches) + .err() + .expect("a missing directory must fail startup") + .to_string(); + assert!(error.contains("missing.d"), "{error}"); + + let args = super::ConfigPreflightArgs { + path: Some(base.clone()), + config_dir: Some(missing.clone()), + ..Default::default() + }; + let (run, matches) = parse_with_args(&["openshell-gateway", "--disable-tls"]); + let error = super::run_config_preflight(args, run, &matches) + .unwrap_err() + .to_string(); + assert!(error.contains("missing.d"), "{error}"); + }); + } + + #[test] + fn preflight_parses_config_dir_alongside_path() { + for (value, expected) in [("/etc/gateway.d", "/etc/gateway.d"), ("", "")] { + let cli = Cli::try_parse_from([ + "openshell-gateway", + "config", + "preflight", + "--path", + "/etc/gateway.toml", + "--config-dir", + value, + ]) + .unwrap(); + let Some(super::Commands::Config(super::ConfigArgs { + command: super::ConfigCommand::Preflight(args), + })) = cli.command + else { + panic!("expected the preflight subcommand"); + }; + assert_eq!( + args.path, + Some(std::path::PathBuf::from("/etc/gateway.toml")) + ); + assert_eq!(args.config_dir, Some(std::path::PathBuf::from(expected))); + } + } + #[test] fn runtime_defaults_populate_database_url_from_xdg_state() { let tmp = tempfile::tempdir().unwrap(); @@ -3963,8 +4329,14 @@ require_client_auth = true ) .unwrap(); let (preflight_args, preflight_matches) = parse_with_args(&argv); - super::run_effective_config_preflight(None, preflight_args, &preflight_matches, ®istry) - .expect("selected or candidate Podman preflight accepts the legacy alias"); + super::run_effective_config_preflight( + None, + None, + preflight_args, + &preflight_matches, + ®istry, + ) + .expect("selected or candidate Podman preflight accepts the legacy alias"); assert!(!state.path().join("network-supervisor").exists()); let prepared = super::prepare_server_config_with_drivers(&mut run, &matches, ®istry) .expect("global network trust should normalize during startup preparation"); @@ -4045,7 +4417,7 @@ require_client_auth = true argv.extend(["--compute-driver", "docker"]); } let (run, matches) = parse_with_args(&argv); - super::run_effective_config_preflight(None, run, &matches, ®istry) + super::run_effective_config_preflight(None, None, run, &matches, ®istry) .expect("inactive Podman settings must not affect preflight"); let (mut run, matches) = parse_with_args(&argv); let prepared = diff --git a/crates/openshell-server/src/config_file/layered.rs b/crates/openshell-server/src/config_file/layered.rs new file mode 100644 index 0000000000..87e80c24fc --- /dev/null +++ b/crates/openshell-server/src/config_file/layered.rs @@ -0,0 +1,381 @@ +// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +//! Layered gateway configuration: a base file plus `*.toml` drop-in configs +//! merged over it, validated once, with errors attributed to the file that +//! caused them. + +use std::path::{Path, PathBuf}; + +use super::{ + ConfigFile, ConfigFileError, ConfigPreflightError, SCHEMA_VERSION, parse_error_detail, + preflight_error, read_config_contents, validate_loaded, without_quoted_strings, +}; + +/// Result of loading a base file plus drop-in configs. +#[derive(Debug)] +pub struct LayeredConfig { + pub file: ConfigFile, + /// Files that contributed to `file`, in merge order (base first). + pub sources: Vec, +} + +/// List the `*.toml` drop-in configs in `dir`, sorted by file name. +/// +/// Hidden files and entries without a `.toml` extension are ignored so editor +/// backups and package-manager leftovers never take effect. +pub fn drop_in_paths(dir: &Path) -> Result, ConfigFileError> { + let io_error = |source| ConfigFileError::Io { + path: dir.to_path_buf(), + source, + }; + let mut paths = Vec::new(); + for entry in std::fs::read_dir(dir).map_err(io_error)? { + let entry = entry.map_err(io_error)?; + let name = entry.file_name(); + let name = name.to_string_lossy(); + if name.starts_with('.') || Path::new(name.as_ref()).extension() != Some("toml".as_ref()) { + continue; + } + paths.push(entry.path()); + } + paths.sort_by(|a, b| a.file_name().cmp(&b.file_name())); + Ok(paths) +} + +/// Overlay `overlay` onto `base`: tables merge key by key; every other value, +/// arrays included, replaces the existing one. +pub(super) fn merge_tables(base: &mut toml::Table, overlay: toml::Table) { + for (key, value) in overlay { + match (base.get_mut(&key), value) { + (Some(toml::Value::Table(existing)), toml::Value::Table(incoming)) => { + merge_tables(existing, incoming); + } + (_, value) => { + base.insert(key, value); + } + } + } +} + +fn parse_table(path: &Path, contents: &str) -> Result { + contents + .parse::() + .map_err(|error| ConfigFileError::Parse { + path: path.to_path_buf(), + detail: parse_error_detail(contents, &error), + }) +} + +/// A failed layer load with what preflight needs to report it. +struct LayerFailure { + error: ConfigFileError, + /// The file that caused the failure, or the base or directory when the + /// failure belongs to the merged result. + path: PathBuf, + /// The version the failing file or merged result declares. + version: String, +} + +/// The `[openshell]` table's `version` value. The outer error is `true` when +/// `openshell` exists but is not a table. +fn declared_version(table: &toml::Table) -> Result, ()> { + match table.get("openshell") { + None => Ok(None), + Some(toml::Value::Table(openshell)) => Ok(openshell.get("version")), + Some(_) => Err(()), + } +} + +/// Version declared by `table`, in the form preflight reports it. +fn table_version(table: &toml::Table) -> String { + match declared_version(table) { + Ok(None) => "missing".to_string(), + Ok(Some(version)) => version + .as_integer() + .map_or_else(|| "unavailable".to_string(), |v| v.to_string()), + Err(()) => "unavailable".to_string(), + } +} + +/// Check the declared version before deserializing so a legacy schema +/// reports its version instead of tripping over fields it no longer has. +fn check_version(table: &toml::Table) -> Result<(), ConfigFileError> { + match declared_version(table) { + Ok(None) => Err(ConfigFileError::MissingVersion), + Ok(Some(toml::Value::Integer(version))) => match u32::try_from(*version) { + Ok(SCHEMA_VERSION) => Ok(()), + Ok(version) => Err(ConfigFileError::UnsupportedVersion { version }), + // A negative or oversized integer names no schema version. + Err(_) => Err(ConfigFileError::InvalidVersion), + }, + // A string or table here could be overwritten by a later file that + // declares the integer, so each file must declare it itself. + Ok(Some(_)) | Err(()) => Err(ConfigFileError::InvalidVersion), + } +} + +/// One file of a layered configuration. +struct Layer { + path: PathBuf, + contents: String, + table: toml::Table, +} + +/// Read a drop-in config. A symlink is accepted only when it resolves to a +/// regular file inside `dir`, as in a Kubernetes `ConfigMap` mount, so a link +/// can never pull in a file from elsewhere. The resolved path is opened +/// without following further links. +fn read_drop_in_contents(path: &Path, dir: &Path) -> Result { + let is_link = std::fs::symlink_metadata(path).is_ok_and(|meta| meta.file_type().is_symlink()); + if !is_link { + return read_config_contents(path); + } + let io_error = |path: &Path| { + let path = path.to_path_buf(); + move |source| ConfigFileError::Io { path, source } + }; + let target = std::fs::canonicalize(path).map_err(io_error(path))?; + let root = std::fs::canonicalize(dir).map_err(io_error(dir))?; + if !target.starts_with(&root) { + return Err(ConfigFileError::NonRegular { + path: path.to_path_buf(), + kind: "symlink to a file outside the config directory", + }); + } + read_config_contents(&target) +} + +/// Read one file and check that it parses and declares [`SCHEMA_VERSION`]. +/// Everything else is checked on the merged result, because a drop-in may set +/// only some keys of a table whose required keys live in another file. +fn load_layer(path: &Path, drop_in_dir: Option<&Path>) -> Result { + let fail = |error: ConfigFileError, version: String| LayerFailure { + error, + path: path.to_path_buf(), + version, + }; + let contents = drop_in_dir + .map_or_else( + || read_config_contents(path), + |dir| read_drop_in_contents(path, dir), + ) + .map_err(|e| fail(e, "unavailable".into()))?; + let table = parse_table(path, &contents).map_err(|e| fail(e, "unavailable".into()))?; + let version = table_version(&table); + check_version(&table).map_err(|e| fail(e.in_file(path), version))?; + Ok(Layer { + path: path.to_path_buf(), + contents, + table, + }) +} + +/// Load `base` (when present) and the drop-in configs in `dir` (when present), +/// then merge them in order. +/// +/// Every file must parse and declare [`SCHEMA_VERSION`]. The merged result is +/// then validated once, and an error is attributed to the file that holds the +/// offending key. Errors that no single key explains, such as a required key +/// missing from the merged table, name the merged configuration and its files. +#[cfg_attr(target_os = "windows", allow(clippy::result_large_err))] +pub fn load_layered( + base: Option<&Path>, + dir: Option<&Path>, +) -> Result { + load_layered_inner(base, dir).map_err(|failure| failure.error) +} + +fn load_layered_inner( + base: Option<&Path>, + dir: Option<&Path>, +) -> Result { + let origin = base.or(dir).map(Path::to_path_buf).unwrap_or_default(); + let mut layers = Vec::new(); + if let Some(base) = base { + layers.push(load_layer(base, None)?); + } + if let Some(dir) = dir { + let listed = drop_in_paths(dir).map_err(|error| LayerFailure { + error, + path: dir.to_path_buf(), + version: "unavailable".to_string(), + })?; + for path in listed { + layers.push(load_layer(&path, Some(dir))?); + } + } + + let mut merged = toml::Table::new(); + for layer in &layers { + merge_tables(&mut merged, layer.table.clone()); + } + let version = table_version(&merged); + let file = finish_layered(&layers, merged).map_err(|error| LayerFailure { + path: error.file().map_or(origin, Path::to_path_buf), + error, + version, + })?; + Ok(LayeredConfig { + file, + sources: layers.into_iter().map(|layer| layer.path).collect(), + }) +} + +/// Whether `table` sets the key at `path`, however deeply nested. +fn has_path(table: &toml::Table, path: &[String]) -> bool { + match path { + [] => false, + [key] => table.contains_key(key), + [key, rest @ ..] => table + .get(key) + .and_then(toml::Value::as_table) + .is_some_and(|inner| has_path(inner, rest)), + } +} + +/// The value at `path` in `table`. +fn value_at<'a>(table: &'a toml::Table, path: &[String]) -> Option<&'a toml::Value> { + let (first, rest) = path.split_first()?; + let value = table.get(first)?; + if rest.is_empty() { + Some(value) + } else { + value_at(value.as_table()?, rest) + } +} + +/// The file that sets the key at `path`: the last one, whose value wins, or +/// the first one for a key that is wrong wherever it appears. +fn locate<'a>(layers: &'a [Layer], path: &[String], first: bool) -> Option<&'a Path> { + let mut owners = layers.iter().filter(|layer| has_path(&layer.table, path)); + let owner = if first { + owners.next() + } else { + owners.next_back() + }; + owner.map(|layer| layer.path.as_path()) +} + +fn describe_layers(layers: &[Layer]) -> String { + layers + .iter() + .map(|layer| layer.path.display().to_string()) + .collect::>() + .join(", ") +} + +/// Report a deserialization error against the file that holds the key. +fn attribute_parse( + layers: &[Layer], + merged: &toml::Table, + error: &serde_path_to_error::Error, +) -> ConfigFileError { + // With one file nothing was merged, so reread it with spans and report the + // line and column of the problem. + if let [layer] = layers + && let Err(spanned) = toml::from_str::(&layer.contents) + { + return ConfigFileError::Parse { + path: layer.path.clone(), + detail: parse_error_detail(&layer.contents, &spanned), + }; + } + let message = error.inner().message().trim_end(); + let mut detail = without_quoted_strings(message); + // The merged table has no spans, so give the key path instead. It holds + // key names, never values. + if error.path().iter().next().is_some() { + detail = format!("`{}`: {detail}", error.path()); + } + let mut path: Vec = error + .path() + .iter() + .map_while(|segment| match segment { + serde_path_to_error::Segment::Map { key } => Some(key.clone()), + _ => None, + }) + .collect(); + let unknown = message + .strip_prefix("unknown field `") + .and_then(|rest| rest.split('`').next()); + if let Some(name) = unknown + && path.last().map(String::as_str) != Some(name) + { + path.push(name.to_string()); + } + // A missing key is a property of the merged table, not of one file. So is + // an error about a whole table that several files contribute to, such as a + // rule over two of its keys. + let spans_files = unknown.is_none() + && value_at(merged, &path).is_some_and(toml::Value::is_table) + && layers + .iter() + .filter(|layer| has_path(&layer.table, &path)) + .count() + > 1; + let owner = if message.starts_with("missing field") || spans_files { + None + } else { + locate(layers, &path, unknown.is_some()) + }; + match owner { + Some(path) => ConfigFileError::Parse { + path: path.to_path_buf(), + detail, + }, + None => ConfigFileError::MergedParse { + files: describe_layers(layers), + detail, + }, + } +} + +/// Report a validation error against the file that sets the offending key. +fn attribute_semantic(layers: &[Layer], error: ConfigFileError) -> ConfigFileError { + let to_path = |segments: &[&str]| segments.iter().map(ToString::to_string).collect::>(); + let path = match &error { + ConfigFileError::SecretInFile { field, .. } => { + Some(to_path(&["openshell", "gateway", field])) + } + ConfigFileError::InvalidValue { field, .. } => { + Some(field.split('.').map(str::to_string).collect()) + } + ConfigFileError::InvalidDriverTable { name } => { + Some(to_path(&["openshell", "drivers", name])) + } + ConfigFileError::InvalidIsolationBackend { name, .. } => Some(to_path(&[ + "openshell", + "drivers", + name, + "isolation_backend", + ])), + _ => None, + }; + match path.and_then(|path| locate(layers, &path, false).map(Path::to_path_buf)) { + Some(owner) => error.in_file(&owner), + None => error, + } +} + +/// Deserialize and validate the merged table. +fn finish_layered(layers: &[Layer], merged: toml::Table) -> Result { + check_version(&merged)?; + let file: ConfigFile = serde_path_to_error::deserialize(toml::Value::Table(merged.clone())) + .map_err(|error| attribute_parse(layers, &merged, &error))?; + validate_loaded(file).map_err(|error| attribute_semantic(layers, error)) +} + +/// Layered counterpart of [`preflight`]. +/// +/// Validates the base and drop-in configs without starting the gateway. The +/// failure names the offending file, or the base or directory when the error +/// belongs to the merged result. +#[cfg_attr(target_os = "windows", allow(clippy::result_large_err))] +pub fn preflight_layered( + base: Option<&Path>, + dir: Option<&Path>, +) -> Result { + load_layered_inner(base, dir) + .map_err(|failure| preflight_error(&failure.path, failure.version, failure.error)) +} diff --git a/crates/openshell-server/src/config_file/mod.rs b/crates/openshell-server/src/config_file/mod.rs index bd04a38eef..56295e7e24 100644 --- a/crates/openshell-server/src/config_file/mod.rs +++ b/crates/openshell-server/src/config_file/mod.rs @@ -1339,6 +1339,10 @@ pub enum ConfigFileError { "unsupported gateway config version {version}; this build requires version {SCHEMA_VERSION}; migrate legacy fields to the version {SCHEMA_VERSION} schema" )] UnsupportedVersion { version: u32 }, + #[error( + "invalid gateway config version; `openshell.version` must be the integer {SCHEMA_VERSION}" + )] + InvalidVersion, #[error( "`{field}` is not allowed in the gateway config file — set the {env} env var or pass {cli} on the command line" )] @@ -1352,6 +1356,18 @@ pub enum ConfigFileError { field: &'static str, message: &'static str, }, + /// A deserialization error in the merged configuration that no single file + /// explains, such as a required key that no file sets. + #[error("invalid merged gateway config ({files}): {detail}")] + MergedParse { files: String, detail: String }, + /// An error from one file of a layered configuration whose own message + /// names no file. + #[error("gateway config file '{}': {source}", path.display())] + InFile { + path: PathBuf, + #[source] + source: Box, + }, #[error("invalid gateway config field `openshell.drivers.{name}`: expected a TOML table")] InvalidDriverTable { name: String }, #[error("invalid gateway config field `openshell.drivers.{name}.isolation_backend`: {message}")] @@ -1377,6 +1393,42 @@ pub enum ConfigFileError { }, } +impl ConfigFileError { + /// Attach `path` unless the error already names a file. + fn in_file(self, path: &Path) -> Self { + match self { + Self::Io { .. } + | Self::NonRegular { .. } + | Self::Parse { .. } + | Self::MergedParse { .. } + | Self::InFile { .. } => self, + other => Self::InFile { + path: path.to_path_buf(), + source: Box::new(other), + }, + } + } + + /// The file the error names, if any. + fn file(&self) -> Option<&Path> { + match self { + Self::Io { path, .. } + | Self::NonRegular { path, .. } + | Self::Parse { path, .. } + | Self::InFile { path, .. } => Some(path), + _ => None, + } + } + + /// The error without any file attribution. + fn root(&self) -> &Self { + match self { + Self::InFile { source, .. } => source.root(), + other => other, + } + } +} + const CONFIG_MIGRATION_URL: &str = "https://docs.nvidia.com/openshell/latest/how-it-works/gateways/configuration#migrate-to-schema-version-2"; /// Stable package-preflight failure with no configuration contents attached. @@ -1508,21 +1560,28 @@ fn without_quoted_strings(message: &str) -> String { result } -fn parse_and_validate(path: &Path, contents: &str) -> Result { - if contents.trim().is_empty() { - return Err(ConfigFileError::MissingVersion); - } - let file: ConfigFile = toml::from_str(contents).map_err(|error| ConfigFileError::Parse { - path: path.to_path_buf(), - detail: parse_error_detail(contents, &error), - })?; - +/// Validate a deserialized configuration. Runs once on the merged result. +fn validate_loaded(file: ConfigFile) -> Result { match file.openshell.version { Some(SCHEMA_VERSION) => {} Some(version) => return Err(ConfigFileError::UnsupportedVersion { version }), None => return Err(ConfigFileError::MissingVersion), } + validate_shape(&file)?; + for driver_name in file.openshell.drivers.keys() { + file.isolation_backend(driver_name).map_err(|message| { + ConfigFileError::InvalidIsolationBackend { + name: driver_name.clone(), + message, + } + })?; + } + Ok(file) +} +/// Per-field rules. [`validate_loaded`] adds the rules that relate fields, such +/// as resolving a driver's isolation backend against registrations. +fn validate_shape(file: &ConfigFile) -> Result<(), ConfigFileError> { if file.openshell.gateway.database_url.is_some() { return Err(ConfigFileError::SecretInFile { field: "database_url", @@ -1600,15 +1659,7 @@ fn parse_and_validate(path: &Path, contents: &str) -> Result String { - let Ok(value) = contents.parse::() else { - return "unavailable".to_string(); - }; - let Some(openshell) = value.get("openshell") else { - return "missing".to_string(); - }; - let Some(openshell) = openshell.as_table() else { - return "unavailable".to_string(); - }; - openshell.get("version").map_or_else( - || "missing".to_string(), - |version| { - version - .as_integer() - .map_or_else(|| "unavailable".to_string(), |version| version.to_string()) - }, - ) -} - fn preflight_error( path: &Path, detected_version: String, source: ConfigFileError, ) -> ConfigPreflightError { - let category = match &source { + let category = match source.root() { ConfigFileError::NonRegular { .. } => "non_regular_path", ConfigFileError::Io { source, .. } if source.kind() == std::io::ErrorKind::NotFound => { "missing_path" @@ -1697,7 +1728,10 @@ fn preflight_error( "future_version" } ConfigFileError::UnsupportedVersion { .. } => "unsupported_version", - ConfigFileError::Parse { .. } + ConfigFileError::InvalidVersion + | ConfigFileError::Parse { .. } + | ConfigFileError::MergedParse { .. } + | ConfigFileError::InFile { .. } | ConfigFileError::SecretInFile { .. } | ConfigFileError::InvalidValue { .. } | ConfigFileError::InvalidDriverTable { .. } @@ -1712,43 +1746,29 @@ fn preflight_error( } } -/// Validate a gateway configuration without starting the gateway or writing state. +/// Validate a single gateway configuration file without starting the gateway +/// or writing state. This is [`preflight_layered`] with no drop-in configs. #[cfg_attr(target_os = "windows", allow(clippy::result_large_err))] pub fn preflight(path: &Path) -> Result { - let contents = read_config_contents(path) - .map_err(|source| preflight_error(path, "unavailable".to_string(), source))?; - let version = detected_version(&contents); - if version == "missing" { - return Err(preflight_error( - path, - version, - ConfigFileError::MissingVersion, - )); - } - if let Ok(version_number) = version.parse::() - && version_number != SCHEMA_VERSION - { - return Err(preflight_error( - path, - version, - ConfigFileError::UnsupportedVersion { - version: version_number, - }, - )); - } - parse_and_validate(path, &contents).map_err(|source| preflight_error(path, version, source)) + preflight_layered(Some(path), None).map(|layered| layered.file) } -/// Load and validate a TOML config file. +/// Load and validate a single TOML config file. This is [`load_layered`] with +/// no drop-in configs. /// /// Configuration files must declare exactly [`SCHEMA_VERSION`]. Running /// without a config file still uses CLI, environment, and built-in defaults. #[cfg_attr(target_os = "windows", allow(clippy::result_large_err))] pub fn load(path: &Path) -> Result { - let contents = read_config_contents(path)?; - parse_and_validate(path, &contents) + load_layered(Some(path), None).map(|layered| layered.file) } +mod layered; + +#[cfg(test)] +use layered::merge_tables; +pub use layered::{LayeredConfig, drop_in_paths, load_layered, preflight_layered}; + /// Return a driver's table without gateway-level inheritance. /// /// Driver-specific configuration belongs exclusively to @@ -1773,6 +1793,19 @@ pub fn driver_table( #[cfg(test)] mod tests { use super::*; + + /// Strip the file attribution so a test can match the variant. + fn without_file(error: ConfigFileError) -> ConfigFileError { + match error { + ConfigFileError::InFile { source, .. } => without_file(*source), + other => other, + } + } + + /// [`super::load`] with the error's file attribution removed. + fn load(path: &Path) -> Result { + super::load(path).map_err(without_file) + } use std::io::Write; #[test] @@ -3688,4 +3721,519 @@ ssh_gateway_port = 8080 "RPM defaults must retain Podman's readiness health check" ); } + + fn layered_dir(base: &str, drop_ins: &[(&str, &str)]) -> (tempfile::TempDir, PathBuf, PathBuf) { + let dir = tempfile::tempdir().unwrap(); + let base_path = dir.path().join("gateway.toml"); + std::fs::write(&base_path, base).unwrap(); + let frag_dir = dir.path().join("gateway.d"); + std::fs::create_dir(&frag_dir).unwrap(); + for (name, contents) in drop_ins { + std::fs::write(frag_dir.join(name), contents).unwrap(); + } + (dir, base_path, frag_dir) + } + + const BASE: &str = "[openshell]\nversion = 2\n[openshell.drivers.podman]\nuserns = \"auto\"\nsocket = \"/a\"\n"; + + #[test] + fn layered_drop_in_overrides_and_adds_tables() { + let (_dir, base, frags) = layered_dir( + BASE, + &[( + "10-podman.toml", + "[openshell]\nversion = 2\n[openshell.drivers.podman]\nuserns = \"keep-id\"\n[openshell.drivers.docker]\nx = 1\n", + )], + ); + let loaded = load_layered(Some(&base), Some(&frags)).unwrap(); + let podman = loaded.file.openshell.drivers["podman"].as_table().unwrap(); + assert_eq!(podman["userns"].as_str(), Some("keep-id")); + assert_eq!( + podman["socket"].as_str(), + Some("/a"), + "untouched keys survive" + ); + assert!(loaded.file.openshell.drivers.contains_key("docker")); + assert_eq!(loaded.sources.len(), 2); + } + + #[test] + fn layered_later_drop_in_wins_in_lexical_order() { + let (_dir, base, frags) = layered_dir( + BASE, + &[ + ( + "20-b.toml", + "[openshell]\nversion = 2\n[openshell.drivers.podman]\nuserns = \"b\"\n", + ), + ( + "10-a.toml", + "[openshell]\nversion = 2\n[openshell.drivers.podman]\nuserns = \"a\"\n", + ), + ( + "99.txt", + "[openshell]\nversion = 2\n[openshell.drivers.podman]\nuserns = \"ignored\"\n", + ), + ( + ".hidden.toml", + "[openshell]\nversion = 2\n[openshell.drivers.podman]\nuserns = \"ignored\"\n", + ), + ], + ); + let loaded = load_layered(Some(&base), Some(&frags)).unwrap(); + let podman = loaded.file.openshell.drivers["podman"].as_table().unwrap(); + assert_eq!(podman["userns"].as_str(), Some("b")); + assert_eq!(loaded.sources.len(), 3); + } + + #[test] + fn layered_arrays_replace() { + let mut base = toml::Table::new(); + let mut overlay = toml::Table::new(); + base.insert("a".into(), toml::Value::Array(vec![1.into(), 2.into()])); + overlay.insert("a".into(), toml::Value::Array(vec![3.into()])); + merge_tables(&mut base, overlay); + assert_eq!(base["a"].as_array().unwrap().len(), 1); + } + + #[test] + fn layered_unknown_field_names_the_drop_in() { + let (_dir, base, frags) = layered_dir( + BASE, + &[ + ( + "10-ok.toml", + "[openshell]\nversion = 2\n[openshell.drivers.podman]\nuserns = \"x\"\n", + ), + ( + "20-bad.toml", + "[openshell]\nversion = 2\n[openshell.gateway]\nnot_a_field = 1\n", + ), + ], + ); + let error = load_layered(Some(&base), Some(&frags)).unwrap_err(); + assert!(error.to_string().contains("20-bad.toml"), "{error}"); + } + + #[test] + fn layered_parse_error_names_the_drop_in_and_hides_values() { + let (_dir, base, frags) = layered_dir( + BASE, + &[("10-bad.toml", "[openshell\nsecret = \"hunter2\"\n")], + ); + let error = load_layered(Some(&base), Some(&frags)) + .unwrap_err() + .to_string(); + assert!(error.contains("10-bad.toml"), "{error}"); + assert!(!error.contains("hunter2"), "{error}"); + } + + #[test] + fn layered_secret_in_drop_in_is_rejected() { + let (_dir, base, frags) = layered_dir( + BASE, + &[( + "10-db.toml", + "[openshell]\nversion = 2\n[openshell.gateway]\ndatabase_url = \"postgres://u:p@h/db\"\n", + )], + ); + let error = load_layered(Some(&base), Some(&frags)).unwrap_err(); + assert!( + matches!(error.root(), ConfigFileError::SecretInFile { .. }), + "{error}" + ); + assert!(error.to_string().contains("10-db.toml"), "{error}"); + } + + #[test] + fn layered_every_file_must_declare_the_version() { + let (_dir, base, frags) = layered_dir( + BASE, + &[("10-p.toml", "[openshell.drivers.podman]\nuserns = \"x\"\n")], + ); + let error = load_layered(Some(&base), Some(&frags)).unwrap_err(); + assert!(matches!(error.root(), ConfigFileError::MissingVersion)); + assert!(error.to_string().contains("10-p.toml"), "{error}"); + } + + #[test] + fn layered_unsupported_version_names_the_drop_in() { + let (_dir, base, frags) = layered_dir( + BASE, + &[("10-old.toml", "[openshell]\nversion = 1\nlegacy = true\n")], + ); + let error = load_layered(Some(&base), Some(&frags)).unwrap_err(); + assert!(matches!( + error.root(), + ConfigFileError::UnsupportedVersion { version: 1 } + )); + assert!(error.to_string().contains("10-old.toml"), "{error}"); + } + + #[test] + fn layered_overridden_bad_value_is_not_an_error_and_a_later_unknown_key_is() { + let (_dir, base, frags) = layered_dir( + "[openshell]\nversion = 2\n[openshell.gateway]\ndatabase_max_connections = \"bad\"\n", + &[ + ( + "10-fix.toml", + "[openshell]\nversion = 2\n[openshell.gateway]\ndatabase_max_connections = 10\n", + ), + ( + "20-bad.toml", + "[openshell]\nversion = 2\n[openshell.gateway]\nnot_a_field = 1\n", + ), + ], + ); + let error = load_layered(Some(&base), Some(&frags)).unwrap_err(); + assert!(error.to_string().contains("20-bad.toml"), "{error}"); + assert!(!error.to_string().contains("gateway.toml"), "{error}"); + } + + const TLS_BASE: &str = "[openshell]\nversion = 2\n[openshell.gateway.tls]\ncert_path = \"/c\"\nkey_path = \"/k\"\n"; + + #[test] + fn layered_partial_nested_table_is_accepted() { + let (_dir, base, frags) = layered_dir( + TLS_BASE, + &[( + "10-mtls.toml", + "[openshell]\nversion = 2\n[openshell.gateway.tls]\nclient_ca_path = \"/ca\"\n", + )], + ); + let loaded = load_layered(Some(&base), Some(&frags)).unwrap(); + let tls = loaded.file.openshell.gateway.tls.unwrap(); + assert_eq!(tls.cert_path, PathBuf::from("/c")); + assert_eq!(tls.client_ca_path, Some(PathBuf::from("/ca"))); + } + + #[test] + fn layered_unknown_key_in_a_partial_table_names_the_file() { + let (_dir, base, frags) = layered_dir( + TLS_BASE, + &[ + ( + "10-ok.toml", + "[openshell]\nversion = 2\n[openshell.gateway.tls]\nclient_ca_path = \"/ca\"\n", + ), + ( + "20-typo.toml", + "[openshell]\nversion = 2\n[openshell.gateway.tls]\nclient_ca_pth = \"/ca\"\n", + ), + ], + ); + let error = load_layered(Some(&base), Some(&frags)).unwrap_err(); + assert!(error.to_string().contains("20-typo.toml"), "{error}"); + assert!(!error.to_string().contains("10-ok.toml"), "{error}"); + } + + #[test] + fn layered_wrong_type_names_the_file_whose_value_wins() { + let (_dir, base, frags) = layered_dir( + "[openshell]\nversion = 2\n[openshell.gateway]\ndatabase_max_connections = 5\n", + &[( + "10-bad.toml", + "[openshell]\nversion = 2\n[openshell.gateway]\ndatabase_max_connections = \"many\"\n", + )], + ); + let error = load_layered(Some(&base), Some(&frags)).unwrap_err(); + assert!(error.to_string().contains("10-bad.toml"), "{error}"); + assert!(!error.to_string().contains("many"), "{error}"); + } + + #[test] + fn layered_missing_required_key_names_the_merged_config() { + let (_dir, base, frags) = layered_dir( + BASE, + &[( + "10-tls.toml", + "[openshell]\nversion = 2\n[openshell.gateway.tls]\nclient_ca_path = \"/ca\"\n", + )], + ); + let error = load_layered(Some(&base), Some(&frags)) + .unwrap_err() + .to_string(); + assert!(error.contains("merged"), "{error}"); + assert!(error.contains("10-tls.toml"), "{error}"); + assert!(error.contains("gateway.toml"), "{error}"); + assert!(!error.contains("''"), "{error}"); + } + + #[cfg(unix)] + #[test] + fn layered_symlink_is_followed_only_inside_the_directory() { + let (dir, base, frags) = layered_dir(BASE, &[]); + let data = frags.join("..data"); + std::fs::create_dir(&data).unwrap(); + std::fs::write( + data.join("10-link.toml"), + "[openshell]\nversion = 2\n[openshell.drivers.podman]\nuserns = \"linked\"\n", + ) + .unwrap(); + std::os::unix::fs::symlink("..data/10-link.toml", frags.join("10-link.toml")).unwrap(); + let loaded = load_layered(Some(&base), Some(&frags)).unwrap(); + let podman = loaded.file.openshell.drivers["podman"].as_table().unwrap(); + assert_eq!(podman["userns"].as_str(), Some("linked")); + + let outside = dir.path().join("outside.toml"); + std::fs::write(&outside, "[openshell]\nversion = 2\n").unwrap(); + std::os::unix::fs::symlink(&outside, frags.join("20-out.toml")).unwrap(); + let error = load_layered(Some(&base), Some(&frags)).unwrap_err(); + assert!( + matches!(error, ConfigFileError::NonRegular { .. }), + "{error}" + ); + assert!(error.to_string().contains("20-out.toml"), "{error}"); + } + + #[cfg(unix)] + #[test] + fn layered_base_symlink_is_still_rejected() { + let (dir, _base, frags) = layered_dir(BASE, &[]); + let real = dir.path().join("real.toml"); + std::fs::write(&real, BASE).unwrap(); + let link = dir.path().join("link.toml"); + std::os::unix::fs::symlink(&real, &link).unwrap(); + let error = load_layered(Some(&link), Some(&frags)).unwrap_err(); + assert!( + matches!(error, ConfigFileError::NonRegular { .. }), + "{error}" + ); + } + + #[test] + fn layered_semantic_error_names_the_drop_in() { + let (_dir, base, frags) = layered_dir( + BASE, + &[( + "20-bad.toml", + "[openshell]\nversion = 2\n[openshell.gateway]\ndatabase_max_connections = 0\n", + )], + ); + let error = load_layered(Some(&base), Some(&frags)).unwrap_err(); + assert!(error.to_string().contains("20-bad.toml"), "{error}"); + let preflight = preflight_layered(Some(&base), Some(&frags)) + .unwrap_err() + .to_string(); + assert!(preflight.contains("20-bad.toml"), "{preflight}"); + assert!(preflight.contains("detected_version=2"), "{preflight}"); + } + + #[test] + fn layered_cross_file_rules_run_on_the_merged_result_and_name_the_setting_file() { + let (_dir, base, frags) = layered_dir( + BASE, + &[( + "10-backend.toml", + "[openshell]\nversion = 2\n[openshell.drivers.podman]\nisolation_backend = \"agent\"\n", + )], + ); + let error = load_layered(Some(&base), Some(&frags)).unwrap_err(); + assert!( + matches!( + error.root(), + ConfigFileError::InvalidIsolationBackend { .. } + ), + "{error}" + ); + assert!(error.to_string().contains("10-backend.toml"), "{error}"); + } + + #[test] + fn layered_a_non_integer_version_is_rejected_even_when_a_later_file_overrides_it() { + let (_dir, base, frags) = layered_dir( + "[openshell]\nversion = \"two\"\n", + &[("10-ok.toml", "[openshell]\nversion = 2\n")], + ); + let error = load_layered(Some(&base), Some(&frags)).unwrap_err(); + assert!(matches!(error.root(), ConfigFileError::InvalidVersion)); + assert!(error.to_string().contains("gateway.toml"), "{error}"); + + let (_dir, base, frags) = + layered_dir(BASE, &[("10-bad.toml", "[openshell]\nversion = \"two\"\n")]); + let error = load_layered(Some(&base), Some(&frags)).unwrap_err(); + assert!(matches!(error.root(), ConfigFileError::InvalidVersion)); + assert!(error.to_string().contains("10-bad.toml"), "{error}"); + } + + #[test] + fn layered_a_quoted_version_is_rejected_in_a_drop_in() { + let (_dir, base, frags) = layered_dir( + BASE, + &[("10-quoted.toml", "[openshell]\nversion = \"2\"\n")], + ); + let error = load_layered(Some(&base), Some(&frags)).unwrap_err(); + assert!(matches!(error.root(), ConfigFileError::InvalidVersion)); + assert!(error.to_string().contains("10-quoted.toml"), "{error}"); + } + + #[test] + fn layered_whole_table_error_across_files_names_the_merged_config() { + let log = + |body: &str| format!("[openshell]\nversion = 2\n[openshell.gateway.ocsf_log]\n{body}"); + let (_dir, base, frags) = layered_dir( + &log("path = 'log'\nrotation = 'never'\nmax_files = 7\n"), + &[("10-path.toml", &log("path = 'other'\n"))], + ); + let error = load_layered(Some(&base), Some(&frags)).unwrap_err(); + assert!( + matches!(error.root(), ConfigFileError::MergedParse { .. }), + "{error}" + ); + assert!( + error.to_string().contains("max_files requires daily"), + "{error}" + ); + + // One file owns the whole table, so it is named. + let (_dir, base, frags) = layered_dir( + "[openshell]\nversion = 2\n", + &[( + "10-log.toml", + &log("path = 'log'\nrotation = 'never'\nmax_files = 7\n"), + )], + ); + let error = load_layered(Some(&base), Some(&frags)).unwrap_err(); + assert!(error.to_string().contains("10-log.toml"), "{error}"); + } + + #[test] + fn layered_with_no_base_runs_on_the_drop_ins_alone() { + let dir = tempfile::tempdir().unwrap(); + std::fs::write( + dir.path().join("10-a.toml"), + "[openshell]\nversion = 2\n[openshell.drivers.podman]\nuserns = \"auto\"\n", + ) + .unwrap(); + let loaded = load_layered(None, Some(dir.path())).unwrap(); + assert_eq!( + loaded.file.openshell.drivers["podman"]["userns"].as_str(), + Some("auto") + ); + assert_eq!(loaded.sources, vec![dir.path().join("10-a.toml")]); + + // A failure that no single file explains names the directory, not an + // empty path. + std::fs::write( + dir.path().join("10-a.toml"), + "[openshell]\nversion = 2\n[openshell.gateway.tls]\nclient_ca_path = \"/ca\"\n", + ) + .unwrap(); + // Startup lists the drop-in configs that were merged. + let startup = load_layered(None, Some(dir.path())) + .unwrap_err() + .to_string(); + assert!(startup.contains("10-a.toml"), "{startup}"); + let error = preflight_layered(None, Some(dir.path())).unwrap_err(); + let message = error.to_string(); + assert!( + message.contains(&dir.path().display().to_string()), + "{message}" + ); + assert!(!message.contains("''"), "{message}"); + } + + #[test] + fn layered_the_drop_in_that_sets_the_bad_value_is_named_when_the_base_sets_a_good_one() { + let (_dir, base, frags) = layered_dir( + "[openshell]\nversion = 2\n[openshell.gateway]\ndatabase_max_connections = 5\n", + &[( + "20-bad.toml", + "[openshell]\nversion = 2\n[openshell.gateway]\ndatabase_max_connections = 0\n", + )], + ); + let error = load_layered(Some(&base), Some(&frags)).unwrap_err(); + let message = error.to_string(); + assert!(message.contains("20-bad.toml"), "{message}"); + assert!(!message.contains("gateway.toml"), "{message}"); + } + + #[test] + fn layered_an_invalid_driver_table_names_the_drop_in_that_sets_it() { + let (_dir, base, frags) = layered_dir( + BASE, + &[( + "20-driver.toml", + "[openshell]\nversion = 2\n[openshell.drivers]\npodman = 1\n", + )], + ); + let error = load_layered(Some(&base), Some(&frags)).unwrap_err(); + assert!(error.to_string().contains("20-driver.toml"), "{error}"); + } + + #[test] + fn a_single_file_reports_the_line_and_column_of_a_wrong_value() { + let (_dir, base, _) = layered_dir( + "[openshell]\nversion = 2\n[openshell.gateway]\ndatabase_max_connections = \"secret\"\n", + &[], + ); + let message = load_layered(Some(&base), None).unwrap_err().to_string(); + assert!(message.contains("gateway.toml"), "{message}"); + assert!(message.contains("line 4, column"), "{message}"); + assert!(!message.contains("secret"), "{message}"); + } + + #[test] + fn a_single_file_missing_a_required_key_names_the_file() { + let (_dir, base, _) = layered_dir( + "[openshell]\nversion = 2\n[openshell.gateway.tls]\nclient_ca_path = \"/ca\"\n", + &[], + ); + let message = load_layered(Some(&base), None).unwrap_err().to_string(); + assert!(message.contains("gateway.toml"), "{message}"); + assert!(!message.contains("merged"), "{message}"); + } + + #[test] + fn layered_a_wrong_value_across_files_reports_the_key_path_and_hides_the_value() { + let (_dir, base, frags) = layered_dir( + BASE, + &[( + "10-bad.toml", + "[openshell]\nversion = 2\n[openshell.gateway]\ndatabase_max_connections = \"secret\"\n", + )], + ); + let message = load_layered(Some(&base), Some(&frags)) + .unwrap_err() + .to_string(); + assert!(message.contains("10-bad.toml"), "{message}"); + assert!( + message.contains("openshell.gateway.database_max_connections"), + "{message}" + ); + assert!(!message.contains("secret"), "{message}"); + } + + #[test] + fn layered_an_out_of_range_or_misplaced_version_is_malformed() { + for contents in [ + "[openshell]\nversion = -1\n", + "[openshell]\nversion = 4294967296\n", + "openshell = 5\n", + ] { + let (_dir, base, frags) = layered_dir(contents, &[]); + let error = preflight_layered(Some(&base), Some(&frags)).unwrap_err(); + assert_eq!(error.category(), "malformed", "{contents}"); + } + let (_dir, base, _) = layered_dir("[openshell]\nversion = -1\n", &[]); + let error = load_layered(Some(&base), None).unwrap_err(); + assert!(matches!(error.root(), ConfigFileError::InvalidVersion)); + } + + #[test] + fn layered_preflight_keeps_unavailable_for_a_malformed_version() { + let (_dir, base, frags) = layered_dir(BASE, &[]); + std::fs::write(&base, "[openshell]\nversion = \"two\"\n").unwrap(); + let error = preflight_layered(Some(&base), Some(&frags)).unwrap_err(); + assert_eq!(error.detected_version(), "unavailable"); + assert_eq!(error.category(), "malformed"); + } + + #[test] + fn layered_without_drop_ins_matches_single_file() { + let (_dir, base, frags) = layered_dir(BASE, &[]); + let layered = load_layered(Some(&base), Some(&frags)).unwrap(); + let single = load(&base).unwrap(); + assert_eq!(layered.file.openshell.drivers, single.openshell.drivers); + } } diff --git a/crates/openshell-server/src/lib.rs b/crates/openshell-server/src/lib.rs index 4f591f004f..353e7a5ec0 100644 --- a/crates/openshell-server/src/lib.rs +++ b/crates/openshell-server/src/lib.rs @@ -315,6 +315,8 @@ use tracing_bus::TracingLogBus; pub(crate) struct ServerStartupConfig { pub config: Config, pub config_file: Option, + /// Files merged into `config_file`, base first, then drop-in configs. + pub config_sources: Vec, pub guest_tls: Option, pub network_trust: Option, pub compute_driver: ComputeDriverSelection, @@ -763,6 +765,7 @@ pub(crate) async fn run_server( let ServerStartupConfig { config, config_file, + config_sources: _, guest_tls, network_trust, compute_driver, diff --git a/deploy/man/openshell-gateway.8.md b/deploy/man/openshell-gateway.8.md index 3fdfc3e3e4..403b71847f 100644 --- a/deploy/man/openshell-gateway.8.md +++ b/deploy/man/openshell-gateway.8.md @@ -14,7 +14,7 @@ openshell-gateway - OpenShell gateway server daemon **openshell-gateway** \[*OPTIONS*\] -**openshell-gateway** **config preflight** [**--path** *PATH* | **--** *GATEWAY_ARGS*...] +**openshell-gateway** **config preflight** [[**--path** *PATH*] [**--config-dir** *DIR*] | **--** *GATEWAY_ARGS*...] # DESCRIPTION @@ -163,17 +163,28 @@ Compute driver settings such as sandbox image, callback endpoint, image pull policy, network name, VM state directory, and guest TLS material are configured in the TOML file passed with **--config**. +**--config-dir** *DIR* +: Directory of **\*.toml** drop-in configs merged over the **--config** + file. Drop-in configs apply in lexical order and a later drop-in config wins. Each file must declare **version = 2**; a drop-in config may set only some keys of a table. Tables + merge key by key; scalars and arrays replace. Defaults to **gateway.d** + next to the config file when that directory exists. An empty value turns + drop-in configs off. + Environment: **OPENSHELL_GATEWAY_CONFIG_DIR**. + # CONFIGURATION PREFLIGHT Validate a gateway configuration before starting the daemon: - openshell-gateway config preflight [--path PATH | -- GATEWAY_ARGS...] + openshell-gateway config preflight [[--path PATH] [--config-dir DIR] | -- GATEWAY_ARGS...] With no path, preflight validates a nonempty OPENSHELL_GATEWAY_CONFIG. If that variable is unset, it optionally validates an auto-discovered XDG config. The absence of either config still validates the effective daemon arguments. An explicit missing path, legacy schema-v1 file, invalid TOML, symlink, or nonregular file fails with a nonzero status. -Preflight merges file and environment values and applies read-only startup checks +Preflight merges the selected file with the drop-in configs from **--config-dir** +or the **gateway.d** directory beside it, prints the files it merged, and fails +on the same errors as startup. It also merges environment values and applies +read-only startup checks for selector and socket normalization, registered compute-driver configuration, rate limits, TLS and mTLS, interceptors, and middleware. When a selected file omits the selector, it validates configured tables for auto-detectable drivers diff --git a/deploy/rpm/CONFIGURATION.md b/deploy/rpm/CONFIGURATION.md index 79777fa561..a59d21bdaf 100644 --- a/deploy/rpm/CONFIGURATION.md +++ b/deploy/rpm/CONFIGURATION.md @@ -66,6 +66,16 @@ startup use the same resolution. These values are trusted operator inputs, not sandbox request fields. Keep registry credentials in Podman's credential store rather than embedding them in image references. +To customize settings without editing `gateway.toml`, add `*.toml` drop-in configs to +`~/.config/openshell/gateway.d/`. Drop-in configs apply in lexical order after +`gateway.toml`; a later file wins. Tables merge key by key, and scalars and +arrays replace. For example, `gateway.d/10-podman.toml` containing +`[openshell]` with `version = 2` and `[openshell.drivers.podman]` with +`userns = "keep-id"` changes only that key. Every drop-in config declares the +version. +Set `OPENSHELL_GATEWAY_CONFIG_DIR` to use a different directory, or to an empty +value to turn drop-in configs off. + To override the path to the TOML config file entirely: ```shell diff --git a/docs/how-it-works/gateways/configuration.mdx b/docs/how-it-works/gateways/configuration.mdx index cec79ad5a7..b9fcb37a86 100644 --- a/docs/how-it-works/gateways/configuration.mdx +++ b/docs/how-it-works/gateways/configuration.mdx @@ -56,6 +56,30 @@ preflight and gateway startup. `name` assigns an operator-facing identity to the gateway installation. Set it with `[openshell.gateway].name`, `--name`, or `OPENSHELL_GATEWAY_NAME`. It defaults to `openshell`; the Helm chart defaults it to the chart fullname so all replicas in one installation share a name. Chart fullnames are only unique within their Kubernetes namespace, so set `server.name` explicitly when one collector receives telemetry from multiple namespaces or clusters. This identity is independent of client-side gateway aliases, TLS names, and `gateway_jwt.gateway_id`. +## Drop-In Configs + +The gateway merges `*.toml` drop-in configs from a directory over the base file. Use drop-in configs to customize a package-seeded `gateway.toml` without editing it. Set the directory with `--config-dir` or `OPENSHELL_GATEWAY_CONFIG_DIR`. When you do not set it, the gateway uses `gateway.d` next to the base file if that directory exists. An explicit directory must exist. Set `--config-dir` or `OPENSHELL_GATEWAY_CONFIG_DIR` to an empty value to turn drop-in configs off. + +Drop-in configs apply in lexical order by file name, and a later one wins. Each file must declare `[openshell] version = 2` as an integer. The merge works as follows: + +- Tables merge key by key. +- Scalars and arrays replace the earlier value. An array in a drop-in config replaces the whole array. +- A drop-in config cannot unset a key. Set it to a different value instead. +- Hidden files and files without a `.toml` extension are ignored. +- The gateway does not follow a symlinked base file. A drop-in config can be a symlink only when it resolves to a file inside the drop-in directory, as in a Kubernetes ConfigMap mount; a link that leaves the directory fails startup. +- A `gateway.d` directory next to an explicit `--config` file is merged too, so remove files you do not want applied. + +The gateway reads each file, requires its version, merges the files, and validates the merged result once. A drop-in config can set part of a table, such as a single key under `[openshell.gateway.tls]`, and a key a file sets wrongly is reported against that file: an unknown key, a value of the wrong type, or a value that must come from the environment. With a single file, an error also gives the line and column. With several files, it gives the key path, which holds key names and never values. A required key that no file sets, and rules that relate keys across files, name the merged configuration and list the files merged. The gateway logs the files it merged at startup. The precedence is: command-line flag, then `OPENSHELL_*` environment variable, then drop-in configs, then the base file, then the built-in default. + +```toml +# ~/.config/openshell/gateway.d/10-podman.toml +[openshell] +version = 2 + +[openshell.drivers.podman] +userns = "keep-id" +``` + ## Package-Managed Locations Package-managed gateways use either built-in defaults or a package-seeded TOML file. Set `OPENSHELL_GATEWAY_CONFIG` in the launch environment to use a different file. @@ -1971,7 +1995,7 @@ changing it: openshell-gateway config preflight --path ~/.config/openshell/gateway.toml ``` -Without `--path`, the command validates a nonempty `OPENSHELL_GATEWAY_CONFIG`. Otherwise, it validates an existing XDG gateway config when one is discovered. When neither source selects a config, preflight validates the effective daemon arguments. An explicit missing path, a legacy schema-v1 file, invalid TOML, a symlink, or any nonregular file fails. Preflight merges the selected file with the current `OPENSHELL_*` environment and applies the daemon's read-only startup checks. These checks include selector and socket normalization, registered-driver selection and configuration, rate-limit pairs, TLS and mTLS relationships, interceptor registrations, and supervisor middleware registrations. When a selected file omits `compute_driver`, preflight validates each configured table for an auto-detectable driver without running the runtime detection probes, which can connect local sockets or launch discovery commands. It validates configured driver TLS requirements, including the gateway CA, without requiring package-generated certificate files to exist before certificate generation. It does not construct a compute driver or connect to a transport. A failed preflight always preserves the file; it never migrates, replaces, or rewrites configuration. +Without `--path`, the command validates a nonempty `OPENSHELL_GATEWAY_CONFIG`. Otherwise, it validates an existing XDG gateway config when one is discovered. When neither source selects a config, preflight validates the effective daemon arguments, and it still loads a `gateway.d` directory beside the default config path when one holds drop-in configs. An explicit missing path, a legacy schema-v1 file, invalid TOML, a symlink, or any nonregular file fails. Preflight also loads the drop-in configs, prints the files it merged, and fails on the same errors as startup; pass `--config-dir` to select a directory. It merges the selected file with the current `OPENSHELL_*` environment and applies the daemon's read-only startup checks. These checks include selector and socket normalization, registered-driver selection and configuration, rate-limit pairs, TLS and mTLS relationships, interceptor registrations, and supervisor middleware registrations. When a selected file omits `compute_driver`, preflight validates each configured table for an auto-detectable driver without running the runtime detection probes, which can connect local sockets or launch discovery commands. It validates configured driver TLS requirements, including the gateway CA, without requiring package-generated certificate files to exist before certificate generation. It does not construct a compute driver or connect to a transport. A failure found after the configuration loads, such as an invalid driver setting, reports only the base file, or the drop-in directory when there is no base file, and no detail, even when a drop-in config set the key. A failed preflight always preserves the file; it never migrates, replaces, or rewrites configuration. Config preflight validates configuration without loading launch-signing keys, so a successful result does not confirm that the key files exist or form a usable pair. Gateway startup validates configured or discovered signing bundles. Sandbox creation checks the selected driver's launch-signing requirement before image preparation. diff --git a/skills/debug-openshell-cluster/SKILL.md b/skills/debug-openshell-cluster/SKILL.md index 578097b5ad..e5dc65a940 100644 --- a/skills/debug-openshell-cluster/SKILL.md +++ b/skills/debug-openshell-cluster/SKILL.md @@ -1702,11 +1702,13 @@ For a Debian, Ubuntu, or snap gateway that stops before certificate generation o daemon startup, validate the selected configuration without starting the service: ```shell -openshell-gateway config preflight [--path PATH | -- GATEWAY_ARGS...] +openshell-gateway config preflight [[--path PATH] [--config-dir DIR] | -- GATEWAY_ARGS...] ``` Without a path, preflight validates a nonempty `OPENSHELL_GATEWAY_CONFIG` or an -auto-discovered XDG config; no config succeeds. An explicit missing path, legacy +auto-discovered XDG config; no config succeeds. It also merges the drop-in configs +in `--config-dir`, or in a `gateway.d` directory beside the config, and prints the +files it merged. An explicit missing path, legacy schema-v1 file, malformed TOML, symlink, or nonregular file fails before gateway startup. It also applies read-only effective-config checks for driver selection and configuration, sockets, rate limits, TLS, interceptors, and supervisor From e46c82e664d2af0f7c8b129f066401f4b1ac0baa Mon Sep 17 00:00:00 2001 From: Evan Lezar Date: Wed, 18 Nov 2026 13:02:50 +0100 Subject: [PATCH 5/6] test(tmachine): apply gateway overrides as a drop-in config Install an environment's gateway overrides as `gateway.d/90-test-overrides.toml` next to the gateway's own config instead of merging them into it with a script. A package with no default config runs on the drop-in config alone. The override files declare `[openshell] version = 2`. Signed-off-by: Evan Lezar --- TESTING.md | 34 ++-- tasks/test.toml | 5 - .../playbooks/drivers/podman/userns.yaml | 15 +- .../roles/cdi_fixtures/tasks/main.yaml | 2 + .../openshell_external_driver/tasks/main.yaml | 2 + .../files/merge-gateway-toml.py | 165 ------------------ .../files/merge_gateway_toml_test.py | 100 ----------- .../tasks/merge-settings.yaml | 60 +++++-- .../tasks/main.yaml | 13 +- 9 files changed, 83 insertions(+), 313 deletions(-) delete mode 100755 tests/tmachine/ansible/roles/openshell_gateway/files/merge-gateway-toml.py delete mode 100644 tests/tmachine/ansible/roles/openshell_gateway/files/merge_gateway_toml_test.py diff --git a/TESTING.md b/TESTING.md index 5a8a3942aa..f51acaf397 100644 --- a/TESTING.md +++ b/TESTING.md @@ -593,27 +593,25 @@ nix run .#openshell-test-runner -- run \ An environment overrides gateway settings by writing the tables to change to `/etc/openshell-test/gateway-overrides.toml` in a playbook that runs before the -installer. The file holds whole tables, such as `[openshell.gateway]` or -`[openshell.drivers.podman]`, and is not a complete configuration. Each -installer applies it to the gateway's own file: - -- `binaries` applies it to the `/etc/openshell/gateway.toml` it generates. -- `deb` and `rpm` apply it to the service user's +installer. The file declares `[openshell] version = 2` and the tables to change, such as +`[openshell.gateway]` or `[openshell.drivers.podman]`. Each +installer installs it as the drop-in config `gateway.d/90-test-overrides.toml` +next to the gateway's own `gateway.toml`, and the gateway merges it over that +file. The base file is never edited: + +- `binaries` installs it beside the `/etc/openshell/gateway.toml` it generates. +- `deb` and `rpm` install it beside the service user's `~/.config/openshell/gateway.toml`, the file the packaged service reads. The - file starts as a copy of the rpm's - `/usr/share/openshell-gateway/gateway.toml.default`, where the service would - seed it on first start, or as a minimal `version = 2` file when the package - has no default. No environment replaces the packaged file, and an environment - with no overrides leaves it untouched. + rpm still seeds that file from + `/usr/share/openshell-gateway/gateway.toml.default` on first start. A package + with no default runs on the drop-in config alone. An environment with no + overrides leaves the packaged configuration untouched. - `k3s` installers ignore the file. -`tests/tmachine/ansible/roles/openshell_gateway/files/merge-gateway-toml.py` -does the work. Each key in the overrides replaces the same key in the table, or -is added to it, and a table the file lacks is appended. The rest of the file, -comments included, stays. The script parses the result and fails the setup, -leaving the file unchanged, when it isn't valid TOML. It can't remove a key. -Settings that the packaged service reads from `gateway.env` instead of the -TOML are not covered. +A key in the drop-in config replaces the same key in the base file's table, or is +added to it, and a table the base lacks is added. Arrays replace the base +array. A drop-in config can't remove a key. Settings that the packaged service reads +from `gateway.env` instead of the TOML are not covered. The `oci-image` feature suite (`tests/suites/features/oci-image`) checks OCI image identity and working-directory behavior shared by the Docker and Podman diff --git a/tasks/test.toml b/tasks/test.toml index 26c2ddd6a5..1fe5efa2c0 100644 --- a/tasks/test.toml +++ b/tasks/test.toml @@ -26,15 +26,10 @@ depends = [ "test:maintainer-approval", "test:cargo-lockfile-alignment", "test:review-readiness", - "test:merge-gateway-toml", "test:accepted-work", "test:label-issue", ] -["test:merge-gateway-toml"] -description = "Test the tmachine gateway TOML merge script" -run = "uv run --no-project --with pytest pytest tests/tmachine/ansible/roles/openshell_gateway/files/merge_gateway_toml_test.py" - ["test:cargo-lockfile-alignment"] description = "Test the Cargo lockfile alignment check" run = "uv run --no-project --with pytest pytest tasks/scripts/check_cargo_lockfile_alignment_test.py" diff --git a/tests/tmachine/ansible/playbooks/drivers/podman/userns.yaml b/tests/tmachine/ansible/playbooks/drivers/podman/userns.yaml index 202270100f..bdd28ca088 100644 --- a/tests/tmachine/ansible/playbooks/drivers/podman/userns.yaml +++ b/tests/tmachine/ansible/playbooks/drivers/podman/userns.yaml @@ -5,9 +5,10 @@ # # `podman_userns_mode` is default, auto, keep-id or private. Every mode except # default writes its `[openshell.drivers.podman]` settings to -# `/etc/openshell-test/gateway-overrides.toml`, which every installer applies to the active -# gateway-overrides.toml (the openshell_gateway role for `binaries`, the -# openshell_packaged_gateway role for the packages); default removes the file. The +# `/etc/openshell-test/gateway-overrides.toml`, which every installer installs as a +# `gateway.d` drop-in next to the active gateway.toml (the openshell_gateway role +# for `binaries`, the openshell_packaged_gateway role for the packages); default +# removes the file. The # Podman support crate (tests/support/podman) reads the published mode and # runs Podman's own reference container in it. --- @@ -19,12 +20,18 @@ podman_userns_settings: default: "" auto: | + [openshell] + version = 2 [openshell.drivers.podman] userns = "auto" keep-id: | + [openshell] + version = 2 [openshell.drivers.podman] userns = "keep-id" private: | + [openshell] + version = 2 [openshell.drivers.podman] userns = "private" uidmap = ["0:0:1", "1:1:65535"] @@ -62,7 +69,7 @@ mode: "0644" when: podman_userns_mode != "default" - # The fragment is the only source of userns, uidmap and gidmap settings in + # The drop-in config is the only source of userns, uidmap and gidmap settings in # the gateway's configuration, so default mode leaves them unset. - name: Remove Podman driver user-namespace settings for default mode become: true diff --git a/tests/tmachine/ansible/roles/cdi_fixtures/tasks/main.yaml b/tests/tmachine/ansible/roles/cdi_fixtures/tasks/main.yaml index 5f0c04586c..69ec016226 100644 --- a/tests/tmachine/ansible/roles/cdi_fixtures/tasks/main.yaml +++ b/tests/tmachine/ansible/roles/cdi_fixtures/tasks/main.yaml @@ -55,6 +55,8 @@ ansible.builtin.copy: dest: /etc/openshell-test/gateway-overrides.toml content: | + [openshell] + version = 2 [openshell.drivers.{{ environment_driver }}] allow_driver_config = true owner: root diff --git a/tests/tmachine/ansible/roles/openshell_external_driver/tasks/main.yaml b/tests/tmachine/ansible/roles/openshell_external_driver/tasks/main.yaml index a31363d57d..aa653391bb 100644 --- a/tests/tmachine/ansible/roles/openshell_external_driver/tasks/main.yaml +++ b/tests/tmachine/ansible/roles/openshell_external_driver/tasks/main.yaml @@ -121,5 +121,7 @@ dest: /etc/openshell-test/gateway-overrides.toml mode: "0644" content: | + [openshell] + version = 2 [openshell.drivers.{{ openshell_external_driver_name }}] socket_path = "{{ openshell_external_driver_socket }}" diff --git a/tests/tmachine/ansible/roles/openshell_gateway/files/merge-gateway-toml.py b/tests/tmachine/ansible/roles/openshell_gateway/files/merge-gateway-toml.py deleted file mode 100755 index 02ef6e874c..0000000000 --- a/tests/tmachine/ansible/roles/openshell_gateway/files/merge-gateway-toml.py +++ /dev/null @@ -1,165 +0,0 @@ -#!/usr/bin/python3 -# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 - -"""Apply an environment's gateway overrides to a gateway.toml. - -usage: merge-gateway-toml.py BASE OVERRIDES [--default DEFAULT] - -OVERRIDES holds whole tables, such as `[openshell.gateway]` or -`[openshell.drivers.podman]`. Each key in it replaces the same key in BASE's -table, or is added to the table, and a table BASE lacks is appended. Everything -else in BASE stays, including its comments, so a package's own configuration is -never replaced. Running it again with the same overrides changes nothing. - -If BASE does not exist it is created first: from DEFAULT when that file exists -(the rpm's packaged default), else as a minimal `version = 2` file. The merged -text is parsed as TOML before it is written, and the script fails, leaving BASE -as it was, if it is not valid. - -The overrides must be valid TOML, and the script fails if any of their values is -missing from the merged result, so a statement it cannot rewrite is an error -rather than a silent no-op. - -Limits: a key's value in BASE is replaced as written lines, up to the next key, -header, comment or blank line. A key can't be removed. -""" - -import argparse -import os -import re -import sys -import tomllib - -HEADER = re.compile(r"^\s*\[([^\[\]]+)\]\s*(#.*)?$") -ARRAY_HEADER = re.compile(r"^\s*\[\[[^\[\]]+\]\]\s*(#.*)?$") -KEY = re.compile(r"^\s*([A-Za-z0-9_-]+|\"[^\"]+\"|'[^']+')\s*=") -MINIMAL = "[openshell]\nversion = 2\n" - - -def table_name(line): - return re.sub(r"\s+", "", HEADER.match(line).group(1)) - - -def is_boundary(line): - """A table or array-of-tables header ends the current table.""" - return bool(HEADER.match(line) or ARRAY_HEADER.match(line)) - - -def key_name(raw): - return raw[1:-1] if raw[0] in "\"'" else raw - - -def is_statement_start(line): - return bool(is_boundary(line) or KEY.match(line)) - - -def is_break(line): - stripped = line.strip() - return not stripped or stripped.startswith("#") - - -def statements(lines): - """The (key, lines) pairs of a table body, in order.""" - found = [] - for line in lines: - key = KEY.match(line) - if key: - found.append((key_name(key.group(1)), [line])) - elif found and not is_break(line): - found[-1][1].append(line) - return found - - -def override_tables(text): - if any(line.lstrip().startswith("[[") for line in text.splitlines()): - sys.exit("array-of-tables headers are not supported in the overrides") - tables, current = {}, None - for line in text.splitlines(): - if HEADER.match(line): - current = table_name(line) - tables.setdefault(current, []) - elif current is not None: - tables[current].append(line) - elif not is_break(line): - sys.exit(f"override key outside a table: {line!r}") - return {name: statements(body) for name, body in tables.items()} - - -def apply(lines, table, new): - start = next( - (i for i, l in enumerate(lines) if HEADER.match(l) and table_name(l) == table), - None, - ) - if start is None: - return lines + ["", f"[{table}]", *(l for _, stmt in new for l in stmt)] - for key, stmt in new: - end = next( - (i for i in range(start + 1, len(lines)) if is_boundary(lines[i])), - len(lines), - ) - existing = next( - ( - i - for i in range(start + 1, end) - if (m := KEY.match(lines[i])) and key_name(m.group(1)) == key - ), - None, - ) - if existing is None: - lines[start + 1 : start + 1] = stmt - continue - stop = existing + 1 - while stop < end and not is_statement_start(lines[stop]) and not is_break(lines[stop]): - stop += 1 - lines[existing:stop] = stmt - return lines - - -def contains(merged, expected): - """Whether every table and value in EXPECTED is present in MERGED.""" - if isinstance(expected, dict): - return isinstance(merged, dict) and all( - k in merged and contains(merged[k], v) for k, v in expected.items() - ) - return merged == expected - - -def main(): - parser = argparse.ArgumentParser() - parser.add_argument("base") - parser.add_argument("overrides") - parser.add_argument("--default") - args = parser.parse_args() - - created = not os.path.exists(args.base) - if not created: - text = open(args.base).read() - elif args.default and os.path.exists(args.default): - text = open(args.default).read() - else: - text = MINIMAL - lines = text.splitlines() - override_text = open(args.overrides).read() - try: - wanted = tomllib.loads(override_text) - except tomllib.TOMLDecodeError as error: - sys.exit(f"{args.overrides} is not valid TOML: {error}") - for table, new in override_tables(override_text).items(): - lines = apply(lines, table, new) - merged = "\n".join(lines) + "\n" - try: - result = tomllib.loads(merged) - except tomllib.TOMLDecodeError as error: - sys.exit(f"merged {args.base} is not valid TOML: {error}") - # The rewriter works on lines, so confirm every override really landed - # rather than trusting it to have handled each statement. - if not contains(result, wanted): - sys.exit(f"the overrides in {args.overrides} were not all applied to {args.base}") - with open(args.base, "w") as out: - out.write(merged) - if created: - os.chmod(args.base, 0o644) - - -main() diff --git a/tests/tmachine/ansible/roles/openshell_gateway/files/merge_gateway_toml_test.py b/tests/tmachine/ansible/roles/openshell_gateway/files/merge_gateway_toml_test.py deleted file mode 100644 index ba6926169a..0000000000 --- a/tests/tmachine/ansible/roles/openshell_gateway/files/merge_gateway_toml_test.py +++ /dev/null @@ -1,100 +0,0 @@ -# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 - -import subprocess -import sys -import tomllib -from pathlib import Path - -import pytest - -SCRIPT = Path(__file__).with_name("merge-gateway-toml.py") -BASE = '[openshell]\nversion = 2\n\n[openshell.drivers.podman]\n# keep\nhealth_check_interval_secs = 10\n' - - -def merge(tmp_path, base, overrides, default=None): - base_file, override_file = tmp_path / "gateway.toml", tmp_path / "overrides.toml" - if base is not None: - base_file.write_text(base) - override_file.write_text(overrides) - args = [sys.executable, str(SCRIPT), str(base_file), str(override_file)] - if default is not None: - default_file = tmp_path / "default.toml" - default_file.write_text(default) - args += ["--default", str(default_file)] - run = subprocess.run(args, capture_output=True, text=True) - return run, base_file - - -def test_replaces_and_preserves_comments(tmp_path): - run, base = merge(tmp_path, BASE, '[openshell.drivers.podman]\nhealth_check_interval_secs = 15\nuserns = "keep-id"\n') - assert run.returncode == 0, run.stderr - text = base.read_text() - assert "# keep" in text - assert tomllib.loads(text)["openshell"]["drivers"]["podman"] == { - "health_check_interval_secs": 15, - "userns": "keep-id", - } - - -def test_idempotent(tmp_path): - overrides = '[openshell.drivers.podman]\nuserns = "private"\nuidmap = ["0:0:1",\n "1:1:65535"]\n' - merge(tmp_path, BASE, overrides) - first = (tmp_path / "gateway.toml").read_text() - run, base = merge(tmp_path, first, overrides) - assert run.returncode == 0 and base.read_text() == first - - -def test_array_of_tables_header_is_a_boundary(tmp_path): - base = ( - "[openshell.drivers.podman]\nhealth_check_interval_secs = 10\n" - '[[openshell.supervisor.middleware]]\nname = "local-guard"\n' - 'grpc_endpoint = "https://127.0.0.1:50051"\n' - ) - run, out = merge(tmp_path, base, "[openshell.drivers.podman]\nhealth_check_interval_secs = 15\n") - assert run.returncode == 0, run.stderr - parsed = tomllib.loads(out.read_text())["openshell"] - assert parsed["drivers"]["podman"] == {"health_check_interval_secs": 15} - assert parsed["supervisor"]["middleware"] == [ - {"name": "local-guard", "grpc_endpoint": "https://127.0.0.1:50051"} - ] - - -@pytest.mark.parametrize("quote", ['"', "'"]) -def test_quoted_key_is_applied(tmp_path, quote): - run, base = merge(tmp_path, BASE, f'[openshell.drivers.podman]\n{quote}userns{quote} = "keep-id"\n') - assert run.returncode == 0, run.stderr - assert tomllib.loads(base.read_text())["openshell"]["drivers"]["podman"]["userns"] == "keep-id" - - -@pytest.mark.parametrize( - "overrides", - [ - '[openshell.drivers.podman]\nuserns "keep-id"\n', - '[openshell.drivers.podman]\nuserns = "keep-id\n', - '[[openshell.supervisor.middleware]]\nname = "x"\n', - 'userns = "keep-id"\n', - ], -) -def test_rejects_unusable_overrides_and_leaves_base(tmp_path, overrides): - run, base = merge(tmp_path, BASE, overrides) - assert run.returncode != 0 - assert base.read_text() == BASE - - -def test_dotted_key_not_silently_dropped(tmp_path): - run, base = merge(tmp_path, BASE, "[openshell.drivers]\npodman.userns = \"auto\"\n") - if run.returncode == 0: - assert tomllib.loads(base.read_text())["openshell"]["drivers"]["podman"]["userns"] == "auto" - else: - assert base.read_text() == BASE - - -def test_creates_from_default_else_minimal(tmp_path): - run, base = merge(tmp_path, None, '[openshell.drivers.podman]\nuserns = "auto"\n', default=BASE) - assert run.returncode == 0 and "health_check_interval_secs = 10" in base.read_text() - other = tmp_path / "other" - other.mkdir() - run, base = merge(other, None, '[openshell.drivers.podman]\nuserns = "auto"\n') - parsed = tomllib.loads(base.read_text()) - assert parsed["openshell"]["version"] == 2 diff --git a/tests/tmachine/ansible/roles/openshell_gateway/tasks/merge-settings.yaml b/tests/tmachine/ansible/roles/openshell_gateway/tasks/merge-settings.yaml index 6d167a3ec8..7c61c6fc02 100644 --- a/tests/tmachine/ansible/roles/openshell_gateway/tasks/merge-settings.yaml +++ b/tests/tmachine/ansible/roles/openshell_gateway/tasks/merge-settings.yaml @@ -4,27 +4,59 @@ # An environment overrides gateway settings by writing the tables to change, # such as `[openshell.drivers.podman]`, to # /etc/openshell-test/gateway-overrides.toml before the installer runs (for -# example playbooks/drivers/podman/userns.yaml). Apply them to -# `openshell_gateway_merge_target` without replacing the file; see -# files/merge-gateway-toml.py. +# example playbooks/drivers/podman/userns.yaml). The file declares +# `[openshell] version = 2` like any gateway configuration. Install it as a +# drop-in config in the `gateway.d` directory next to +# `openshell_gateway_merge_target`; the gateway merges it over the base file +# without that file being edited. # -# `openshell_gateway_merge_default` is a default configuration to start from -# when the target doesn't exist yet, and `openshell_gateway_merge_user` is who -# owns the target. +# The base file need not exist: a drop-in config alone is a complete +# configuration. `openshell_gateway_merge_user` owns the files. --- - name: Check for environment gateway overrides ansible.builtin.stat: path: /etc/openshell-test/gateway-overrides.toml register: openshell_gateway_overrides -- name: Apply environment gateway overrides +- name: Read environment gateway overrides + become: true + ansible.builtin.slurp: + src: /etc/openshell-test/gateway-overrides.toml + register: openshell_gateway_overrides_content + when: openshell_gateway_overrides.stat.exists + +# A drop-in config without its own version fails gateway startup, so fail here +# with a message that names the file. +- name: Require the overrides to declare the schema version + ansible.builtin.assert: + that: + - openshell_gateway_overrides_content.content | b64decode is regex('^\s*version\s*=\s*2\s*$', multiline=True) + fail_msg: /etc/openshell-test/gateway-overrides.toml must declare `[openshell]` and `version = 2` + when: openshell_gateway_overrides.stat.exists + +- name: Create the gateway drop-in directory + become: true + become_user: "{{ openshell_gateway_merge_user | default('root') }}" + ansible.builtin.file: + path: "{{ openshell_gateway_merge_target | dirname }}/gateway.d" + state: directory + mode: "0755" + when: openshell_gateway_overrides.stat.exists + +- name: Install environment gateway overrides as a drop-in become: true become_user: "{{ openshell_gateway_merge_user | default('root') }}" - ansible.builtin.script: - cmd: >- - merge-gateway-toml.py {{ openshell_gateway_merge_target }} - /etc/openshell-test/gateway-overrides.toml - {{ '--default ' ~ openshell_gateway_merge_default - if openshell_gateway_merge_default | default('') else '' }} - executable: /usr/bin/python3 + ansible.builtin.copy: + src: /etc/openshell-test/gateway-overrides.toml + remote_src: true + dest: "{{ openshell_gateway_merge_target | dirname }}/gateway.d/90-test-overrides.toml" + mode: "0644" when: openshell_gateway_overrides.stat.exists + +- name: Remove stale environment gateway overrides + become: true + become_user: "{{ openshell_gateway_merge_user | default('root') }}" + ansible.builtin.file: + path: "{{ openshell_gateway_merge_target | dirname }}/gateway.d/90-test-overrides.toml" + state: absent + when: not openshell_gateway_overrides.stat.exists diff --git a/tests/tmachine/ansible/roles/openshell_packaged_gateway/tasks/main.yaml b/tests/tmachine/ansible/roles/openshell_packaged_gateway/tasks/main.yaml index 6d95a7a9a6..70cbcd4ca6 100644 --- a/tests/tmachine/ansible/roles/openshell_packaged_gateway/tasks/main.yaml +++ b/tests/tmachine/ansible/roles/openshell_packaged_gateway/tasks/main.yaml @@ -53,19 +53,18 @@ OPENSHELL_SANDBOX_RUNTIME_IMAGE=docker.io/openshell/sandbox:tmachine OPENSHELL_SUPERVISOR_IMAGE=docker.io/openshell/supervisor:tmachine -# Override settings in the package's own configuration. The rpm seeds -# ~/.config/openshell/gateway.toml from its default on first start, which comes -# after this, so start from that default here and the package's seeding then -# leaves the file alone. A package with no default, such as the deb, gets a -# minimal file; its driver comes from gateway.env. An environment with no -# overrides leaves the packaged configuration untouched. +# Override settings in the package's own configuration with a drop-in config +# in ~/.config/openshell/gateway.d, so the package's gateway.toml stays +# untouched. The rpm seeds gateway.toml from its default on first start, which +# comes after this. A package with no default, such as the deb, runs on the +# drop-in config alone; its driver comes from gateway.env. +# An environment with no overrides leaves the packaged configuration untouched. - name: Apply environment gateway overrides to the packaged gateway ansible.builtin.include_role: name: openshell_gateway tasks_from: merge-settings.yaml vars: openshell_gateway_merge_target: "{{ openshell_gateway_home }}/.config/openshell/gateway.toml" - openshell_gateway_merge_default: /usr/share/openshell-gateway/gateway.toml.default openshell_gateway_merge_user: "{{ openshell_gateway_user }}" - name: Start gateway user manager From 6a9f1386bb48f87510ca8312789e3eca969d4d75 Mon Sep 17 00:00:00 2001 From: Evan Lezar Date: Wed, 18 Nov 2026 13:04:12 +0100 Subject: [PATCH 6/6] feat(gateway): accept --config as an alias for config preflight --path Match the daemon flag so the same name selects the base config file in both places. Keep --path for compatibility. Signed-off-by: Evan Lezar --- crates/openshell-server/src/cli.rs | 28 +++++++++++++++++++- deploy/man/openshell-gateway.8.md | 4 +-- docs/how-it-works/gateways/configuration.mdx | 2 +- skills/debug-openshell-cluster/SKILL.md | 2 +- 4 files changed, 31 insertions(+), 5 deletions(-) diff --git a/crates/openshell-server/src/cli.rs b/crates/openshell-server/src/cli.rs index 9d3e48101d..720edb9617 100644 --- a/crates/openshell-server/src/cli.rs +++ b/crates/openshell-server/src/cli.rs @@ -68,7 +68,9 @@ fn allow_empty_path() -> impl clap::builder::TypedValueParser { #[derive(clap::Args, Debug, Default)] struct ConfigPreflightArgs { /// Explicit configuration path. Overrides `OPENSHELL_GATEWAY_CONFIG` and XDG discovery. - #[arg(long, conflicts_with = "gateway_args")] + /// + /// `--config` is an alias that matches the daemon flag. + #[arg(long, visible_alias = "config", conflicts_with = "gateway_args")] path: Option, /// Explicit drop-in directory. Defaults to `gateway.d` next to the base file. @@ -2247,6 +2249,30 @@ mod tests { }); } + #[test] + fn preflight_accepts_config_as_an_alias_for_path() { + for flag in ["--path", "--config"] { + let cli = Cli::try_parse_from([ + "openshell-gateway", + "config", + "preflight", + flag, + "/etc/gateway.toml", + ]) + .unwrap(); + let Some(super::Commands::Config(super::ConfigArgs { + command: super::ConfigCommand::Preflight(args), + })) = cli.command + else { + panic!("expected the preflight subcommand"); + }; + assert_eq!( + args.path, + Some(std::path::PathBuf::from("/etc/gateway.toml")) + ); + } + } + #[test] fn command_parses_bind_address() { Environment::new().remove("OPENSHELL_BIND_ADDRESS").run(|| { diff --git a/deploy/man/openshell-gateway.8.md b/deploy/man/openshell-gateway.8.md index 403b71847f..39cebc5e4a 100644 --- a/deploy/man/openshell-gateway.8.md +++ b/deploy/man/openshell-gateway.8.md @@ -14,7 +14,7 @@ openshell-gateway - OpenShell gateway server daemon **openshell-gateway** \[*OPTIONS*\] -**openshell-gateway** **config preflight** [[**--path** *PATH*] [**--config-dir** *DIR*] | **--** *GATEWAY_ARGS*...] +**openshell-gateway** **config preflight** [[**--path** *PATH* (alias **--config**)] [**--config-dir** *DIR*] | **--** *GATEWAY_ARGS*...] # DESCRIPTION @@ -175,7 +175,7 @@ configured in the TOML file passed with **--config**. Validate a gateway configuration before starting the daemon: - openshell-gateway config preflight [[--path PATH] [--config-dir DIR] | -- GATEWAY_ARGS...] + openshell-gateway config preflight [[--path PATH (alias --config)] [--config-dir DIR] | -- GATEWAY_ARGS...] With no path, preflight validates a nonempty OPENSHELL_GATEWAY_CONFIG. If that variable is unset, it optionally validates an auto-discovered XDG config. The diff --git a/docs/how-it-works/gateways/configuration.mdx b/docs/how-it-works/gateways/configuration.mdx index b9fcb37a86..a4f0a65b65 100644 --- a/docs/how-it-works/gateways/configuration.mdx +++ b/docs/how-it-works/gateways/configuration.mdx @@ -1995,7 +1995,7 @@ changing it: openshell-gateway config preflight --path ~/.config/openshell/gateway.toml ``` -Without `--path`, the command validates a nonempty `OPENSHELL_GATEWAY_CONFIG`. Otherwise, it validates an existing XDG gateway config when one is discovered. When neither source selects a config, preflight validates the effective daemon arguments, and it still loads a `gateway.d` directory beside the default config path when one holds drop-in configs. An explicit missing path, a legacy schema-v1 file, invalid TOML, a symlink, or any nonregular file fails. Preflight also loads the drop-in configs, prints the files it merged, and fails on the same errors as startup; pass `--config-dir` to select a directory. It merges the selected file with the current `OPENSHELL_*` environment and applies the daemon's read-only startup checks. These checks include selector and socket normalization, registered-driver selection and configuration, rate-limit pairs, TLS and mTLS relationships, interceptor registrations, and supervisor middleware registrations. When a selected file omits `compute_driver`, preflight validates each configured table for an auto-detectable driver without running the runtime detection probes, which can connect local sockets or launch discovery commands. It validates configured driver TLS requirements, including the gateway CA, without requiring package-generated certificate files to exist before certificate generation. It does not construct a compute driver or connect to a transport. A failure found after the configuration loads, such as an invalid driver setting, reports only the base file, or the drop-in directory when there is no base file, and no detail, even when a drop-in config set the key. A failed preflight always preserves the file; it never migrates, replaces, or rewrites configuration. +`--config` is an alias for `--path`. Without either, the command validates a nonempty `OPENSHELL_GATEWAY_CONFIG`. Otherwise, it validates an existing XDG gateway config when one is discovered. When neither source selects a config, preflight validates the effective daemon arguments, and it still loads a `gateway.d` directory beside the default config path when one holds drop-in configs. An explicit missing path, a legacy schema-v1 file, invalid TOML, a symlink, or any nonregular file fails. Preflight also loads the drop-in configs, prints the files it merged, and fails on the same errors as startup; pass `--config-dir` to select a directory. It merges the selected file with the current `OPENSHELL_*` environment and applies the daemon's read-only startup checks. These checks include selector and socket normalization, registered-driver selection and configuration, rate-limit pairs, TLS and mTLS relationships, interceptor registrations, and supervisor middleware registrations. When a selected file omits `compute_driver`, preflight validates each configured table for an auto-detectable driver without running the runtime detection probes, which can connect local sockets or launch discovery commands. It validates configured driver TLS requirements, including the gateway CA, without requiring package-generated certificate files to exist before certificate generation. It does not construct a compute driver or connect to a transport. A failure found after the configuration loads, such as an invalid driver setting, reports only the base file, or the drop-in directory when there is no base file, and no detail, even when a drop-in config set the key. A failed preflight always preserves the file; it never migrates, replaces, or rewrites configuration. Config preflight validates configuration without loading launch-signing keys, so a successful result does not confirm that the key files exist or form a usable pair. Gateway startup validates configured or discovered signing bundles. Sandbox creation checks the selected driver's launch-signing requirement before image preparation. diff --git a/skills/debug-openshell-cluster/SKILL.md b/skills/debug-openshell-cluster/SKILL.md index e5dc65a940..bc03940c80 100644 --- a/skills/debug-openshell-cluster/SKILL.md +++ b/skills/debug-openshell-cluster/SKILL.md @@ -1702,7 +1702,7 @@ For a Debian, Ubuntu, or snap gateway that stops before certificate generation o daemon startup, validate the selected configuration without starting the service: ```shell -openshell-gateway config preflight [[--path PATH] [--config-dir DIR] | -- GATEWAY_ARGS...] +openshell-gateway config preflight [[--path PATH (alias --config)] [--config-dir DIR] | -- GATEWAY_ARGS...] ``` Without a path, preflight validates a nonempty `OPENSHELL_GATEWAY_CONFIG` or an