Repository navigation
Description
User Story
I run the OpenShell gateway from the deb, rpm and snap packages, where openshell-gateway config preflight runs before startup. I need a passing preflight to mean that startup will accept the same configuration, so a bad setting is caught before the service restarts and not after.
Problem Statement
Preflight and startup validate the effective configuration in two separate code paths (validate_preflight_semantics and prepare_server_config_with_drivers in crates/openshell-server/src/cli.rs). Comments say preflight must fail exactly when startup would, but nothing enforces it. Startup checks have been added next to the settings they apply to, and preflight was not updated.
Impact / Why This Matters
A configuration can pass preflight and then fail at startup. On current main, with a registered driver and a single setting changed, preflight succeeded and startup failed for each of:
image_preparation_timeout_seconds = 0mutation_admission_limit_per_caller = 0mutation_replay_window_seconds = 0max_ssh_connections_per_sandbox = 0provisioning_repair_window_seconds = -5
The package units run preflight as ExecStartPre, so the service fails at start with a message from the later step. When preflight does fail on a late step, it prints only path=... category=malformed with no detail. It also cannot name the file that set the key when the configuration is merged from drop-in configs. The TLS, mTLS and port checks exist twice with different messages.
Proposed Design
- One validation stage with no side effects, taking the effective arguments, the configuration and the driver choice, used by both commands.
- Preflight keeps its constraints: no directories created, no driver probes, no artifacts staged, and no requirement that package-generated TLS files already exist (the packaging tests require preflight to run before
generate-certs). - The stable one-line preflight failure stays unchanged for automation. The detail goes to stderr.
- Errors carry the key path, so they can name the file that set it once the loader exposes where each key came from.
Suggested UX (if applicable)
config preflight failed: path='/etc/openshell/gateway.toml' category=malformed detected_version=2; ...
detail: image_preparation_timeout_seconds must be between 1 and 86400 (set in /etc/openshell/gateway.d/20-images.toml)
Acceptance Criteria
- A table of configurations, including the five above, is run through both startup and preflight, and the two agree on pass or fail.
- The default database URL is computed without creating directories.
- Preflight validates TLS without requiring the generated files to exist.
- The stable preflight failure line is unchanged, and its detail appears on stderr.
- A failing key that came from a drop-in config is reported with that file.
- The Helm, packaging and snap wrapper checks that use preflight still pass.
Alternatives Considered
- Copy each startup range check into preflight. This is a quick fix, but it keeps two lists that drift apart.
- Have preflight start the gateway in a dry-run mode. That risks side effects and probes that the packaging checks forbid.
Preflight becomes stricter, so this needs a release note. Background: #5446 and #5489, which prepared the code by sharing load_config and splitting out assemble_server_config.
Activity