From c3537a48fd402f11a48ad938ab6ef602944f8d8e Mon Sep 17 00:00:00 2001 From: dimakis Date: Thu, 8 Oct 2026 03:01:36 +0100 Subject: [PATCH] fix(cli): forward version conditions for provider updates Signed-off-by: dimakis --- architecture/gateway.md | 5 ++ crates/openshell-cli/src/commands/provider.rs | 8 +- crates/openshell-cli/src/main.rs | 43 +++++++++ .../tests/provider_commands_integration.rs | 90 ++++++++++++++++++- docs/sandboxes/manage-providers.mdx | 13 +++ skills/openshell-cli/SKILL.md | 4 + 6 files changed, 161 insertions(+), 2 deletions(-) diff --git a/architecture/gateway.md b/architecture/gateway.md index 8fc28dfb21..415885317b 100644 --- a/architecture/gateway.md +++ b/architecture/gateway.md @@ -306,6 +306,11 @@ Domain objects use shared metadata: stable server-generated IDs, human-readable names, creation timestamps, and labels. Crate-level details live in `crates/openshell-core/README.md`. +Provider updates can carry a nonzero resource version in object metadata. The +gateway conditions persistence on that version; a concurrent change rejects the +write. The CLI exposes this through `provider update --expected-resource-version` +so controllers can retain their earlier read boundary through credential rotation. + ## Persistence The gateway persistence layer is a protobuf object store. Domain services store diff --git a/crates/openshell-cli/src/commands/provider.rs b/crates/openshell-cli/src/commands/provider.rs index b85fef0013..7e0ea5167f 100644 --- a/crates/openshell-cli/src/commands/provider.rs +++ b/crates/openshell-cli/src/commands/provider.rs @@ -2202,6 +2202,7 @@ fn print_provider_type_row( } pub struct ProviderUpdateOptions<'a> { + pub expected_resource_version: Option, pub server: &'a str, pub name: &'a str, pub from_existing: bool, @@ -2215,6 +2216,7 @@ pub struct ProviderUpdateOptions<'a> { pub async fn provider_update(options: ProviderUpdateOptions<'_>) -> Result<()> { let ProviderUpdateOptions { + expected_resource_version, server, name, from_existing, @@ -2226,6 +2228,10 @@ pub async fn provider_update(options: ProviderUpdateOptions<'_>) -> Result<()> { tls, } = options; + if expected_resource_version == Some(0) { + return Err(miette::miette!("expected resource version must be nonzero")); + } + if from_existing && !credentials.is_empty() { return Err(miette::miette!( "--from-existing cannot be combined with --credential" @@ -2316,7 +2322,7 @@ pub async fn provider_update(options: ProviderUpdateOptions<'_>) -> Result<()> { name: name.to_string(), created_at_ms: 0, labels: HashMap::new(), - resource_version: 0, + resource_version: expected_resource_version.unwrap_or(0), annotations: HashMap::new(), workspace: workspace.to_string(), deletion_timestamp_ms: 0, diff --git a/crates/openshell-cli/src/main.rs b/crates/openshell-cli/src/main.rs index bffd137c09..2993aa1003 100644 --- a/crates/openshell-cli/src/main.rs +++ b/crates/openshell-cli/src/main.rs @@ -917,6 +917,10 @@ enum ProviderCommands { /// Update an existing provider's credentials or config. #[command(help_template = LEAF_HELP_TEMPLATE, next_help_heading = "FLAGS")] Update { + /// Reject the update unless the provider still has this resource version. + #[arg(long, value_name = "VERSION", value_parser = clap::value_parser!(u64).range(1..))] + expected_resource_version: Option, + /// Provider name. #[arg(add = ArgValueCompleter::new(completers::complete_provider_names))] name: String, @@ -3727,6 +3731,7 @@ async fn run_async() -> Result<()> { } } ProviderCommands::Update { + expected_resource_version, name, from_existing, from_oidc_token, @@ -3735,6 +3740,7 @@ async fn run_async() -> Result<()> { credential_expires_at, } => { run::provider_update(run::ProviderUpdateOptions { + expected_resource_version, server: endpoint, name: &name, from_existing, @@ -5177,6 +5183,43 @@ mod tests { )); } + #[test] + fn provider_update_accepts_nonzero_expected_version() { + let cli = Cli::try_parse_from([ + "openshell", + "provider", + "update", + "work-api", + "--expected-resource-version", + "41", + "--credential", + "OPENAI_API_KEY", + ]) + .expect("conditional provider update should parse"); + assert!(matches!( + cli.command, + Some(Commands::Provider { + command: Some(ProviderCommands::Update { + expected_resource_version: Some(41), + .. + }) + }) + )); + for invalid in ["0", "-1", "invalid"] { + assert!( + Cli::try_parse_from([ + "openshell", + "provider", + "update", + "work-api", + "--expected-resource-version", + invalid + ]) + .is_err() + ); + } + } + #[test] fn provider_update_accepts_credential_expiry() { let cli = Cli::try_parse_from([ diff --git a/crates/openshell-cli/tests/provider_commands_integration.rs b/crates/openshell-cli/tests/provider_commands_integration.rs index 5b8ae54333..a6dfeab89f 100644 --- a/crates/openshell-cli/tests/provider_commands_integration.rs +++ b/crates/openshell-cli/tests/provider_commands_integration.rs @@ -663,6 +663,17 @@ impl OpenShell for TestOpenShell { .get(provider.object_name()) .cloned() .ok_or_else(|| Status::not_found("provider not found"))?; + let expected = provider + .metadata + .as_ref() + .map_or(0, |meta| meta.resource_version); + let current = existing + .metadata + .as_ref() + .map_or(0, |meta| meta.resource_version); + if expected != 0 && expected != current { + return Err(Status::aborted("provider version conflict")); + } // Merge semantics: empty map = no change, empty value = delete key. let merge = |mut base: HashMap, incoming: HashMap| @@ -700,7 +711,7 @@ impl OpenShell for TestOpenShell { name: provider_metadata.name, created_at_ms: existing_metadata.created_at_ms, labels: existing_metadata.labels, - resource_version: 0, + resource_version: current + 1, annotations: HashMap::new(), workspace: String::new(), deletion_timestamp_ms: 0, @@ -1238,6 +1249,78 @@ async fn install_test_profile(ts: &TestServer, id: &str, credential_key: &str) { /// The stored `profile_workspace` is forwarded verbatim rather than recomputed /// from the request workspace. The gateway treats it as immutable, so deriving /// it here would look like a change and be rejected. +#[tokio::test] +async fn provider_update_conditions_write_on_the_supplied_version() { + let ts = run_server().await; + run::provider_create( + &ts.endpoint, + "work-api", + "claude", + false, + &["API_KEY=old".to_string()], + false, + &[], + "default", + &ts.tls, + ) + .await + .expect("create synthetic provider"); + ts.state + .providers + .lock() + .await + .get_mut("work-api") + .unwrap() + .metadata + .as_mut() + .unwrap() + .resource_version = 41; + let credentials = ["API_KEY=rotated".to_string()]; + let update = |expected_resource_version| run::ProviderUpdateOptions { + server: &ts.endpoint, + name: "work-api", + from_existing: false, + from_oidc_token: false, + credentials: &credentials, + config: &[], + credential_expires_at: &[], + expected_resource_version, + workspace: "default", + tls: &ts.tls, + }; + run::provider_update(update(Some(41))) + .await + .expect("matching version"); + let requests = ts.state.provider_update_requests.lock().await; + assert_eq!( + requests + .last() + .unwrap() + .metadata + .as_ref() + .unwrap() + .resource_version, + 41 + ); + drop(requests); + let before = ts + .state + .providers + .lock() + .await + .get("work-api") + .cloned() + .unwrap(); + assert!( + run::provider_update(update(Some(41))).await.is_err(), + "stale version must be rejected by gateway CAS" + ); + assert_eq!( + ts.state.providers.lock().await.get("work-api"), + Some(&before) + ); +} + #[tokio::test] async fn provider_update_preserves_stored_type_and_profile_workspace_when_readable() { let ts = run_server().await; @@ -1257,6 +1340,7 @@ async fn provider_update_preserves_stored_type_and_profile_workspace_when_readab .expect("provider create"); run::provider_update(run::ProviderUpdateOptions { + expected_resource_version: None, server: &ts.endpoint, name: "my-claude", from_existing: false, @@ -1378,6 +1462,7 @@ async fn provider_cli_run_functions_support_full_crud_flow() { ts.state.deny_provider_reads.store(true, Ordering::SeqCst); run::provider_update(run::ProviderUpdateOptions { + expected_resource_version: None, server: &ts.endpoint, name: "my-claude", from_existing: false, @@ -2346,6 +2431,7 @@ async fn provider_update_from_existing_uses_profile_discovery() { let _env = EnvVarGuard::set(&[("CUSTOM_UPDATE_DISCOVERY_API_KEY", "updated-profile-secret")]); run::provider_update(run::ProviderUpdateOptions { + expected_resource_version: None, server: &ts.endpoint, name: "custom-update", from_existing: true, @@ -2418,6 +2504,7 @@ async fn provider_update_from_existing_preserves_global_profile_scope() { ]); run::provider_update(run::ProviderUpdateOptions { + expected_resource_version: None, server: &ts.endpoint, name: "global-update", from_existing: true, @@ -2495,6 +2582,7 @@ async fn provider_update_from_oidc_token_preserves_global_profile_scope() { ); let err = run::provider_update(run::ProviderUpdateOptions { + expected_resource_version: None, server: &ts.endpoint, name: "global-oidc-update", from_existing: false, diff --git a/docs/sandboxes/manage-providers.mdx b/docs/sandboxes/manage-providers.mdx index 93f5b004b6..3b0dfa67c6 100644 --- a/docs/sandboxes/manage-providers.mdx +++ b/docs/sandboxes/manage-providers.mdx @@ -178,6 +178,19 @@ Update a provider's credentials: openshell provider update my-claude --from-existing ``` +For a controller that previously read a provider version, condition the write on +that exact version to avoid overwriting a concurrent change: + +```shell +openshell provider update my-claude \ + --expected-resource-version 41 --credential ANTHROPIC_API_KEY +``` + +The credential value comes from the named environment variable. A stale version +fails without updating the provider. Versions must be positive; omitting the flag +retains the existing update behavior. Do not automatically retry a conflict with +a newly read version unless the replacement is still explicitly intended. + Set or clear a credential expiry timestamp: ```shell diff --git a/skills/openshell-cli/SKILL.md b/skills/openshell-cli/SKILL.md index d986a45cc1..c93bf44a41 100644 --- a/skills/openshell-cli/SKILL.md +++ b/skills/openshell-cli/SKILL.md @@ -23,6 +23,10 @@ openshell --help # Flags for a specific command This is your primary fallback. Use it freely -- the CLI's help output is authoritative and always up-to-date. +For controller-driven credential rotation, check `openshell provider update --help` +for `--expected-resource-version`. Use the version from the intended provider read +and handle a conflict explicitly; do not silently retry against a newer version. + ## Prerequisites - `openshell` is on the PATH. Follow the published [installation guide](https://docs.nvidia.com/openshell/latest/about/installation.md) when it is not installed.