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/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/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/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 e3c8b27186..720edb9617 100644 --- a/crates/openshell-server/src/cli.rs +++ b/crates/openshell-server/src/cli.rs @@ -59,12 +59,29 @@ 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")] + /// + /// `--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. + /// 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 +98,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,15 +474,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 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 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 @@ -491,10 +513,69 @@ 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, + config_sources, + 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!( @@ -808,49 +889,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"; @@ -935,6 +974,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"); } @@ -1090,7 +1135,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( @@ -1114,26 +1165,29 @@ 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 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, + sources, + } = load_config( + &mut run, + matches, + path_override, + dir_override, + ConfigLoad::Preflight, + )?; + for source in &sources { + println!("config: merged {}", source.display()); } let validation = (|| { @@ -1435,19 +1489,120 @@ fn validate_preflight_semantics( Ok(()) } -fn resolve_config_path(args: &RunArgs) -> Result> { - if let Some(path) = args.config.clone() { - return Ok(Some(path)); +/// 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() } +} - 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)), +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 a command selected, if any. +struct LoadedConfig { + /// 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 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, + base_override: Option, + dir_override: Option, + mode: ConfigLoad, +) -> Result { + 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> { @@ -2094,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(|| { @@ -3691,13 +3870,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) + ); }); } @@ -3710,12 +3899,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(); @@ -3922,8 +4355,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"); @@ -4004,7 +4443,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.rs b/crates/openshell-server/src/config_file/mod.rs similarity index 85% rename from crates/openshell-server/src/config_file.rs rename to crates/openshell-server/src/config_file/mod.rs index bd04a38eef..5d21845ee6 100644 --- a/crates/openshell-server/src/config_file.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,508 @@ 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_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..f6e5f8dff9 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* (alias **--config**)] [**--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 (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 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..c0e3e02d03 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. +`--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. 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 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/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_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..c815944b6e 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,43 @@ # 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: Create the gateway drop-in directory 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.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.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