Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions architecture/gateway.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 7 additions & 1 deletion crates/openshell-cli/src/commands/provider.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2202,6 +2202,7 @@ fn print_provider_type_row(
}

pub struct ProviderUpdateOptions<'a> {
pub expected_resource_version: Option<u64>,
pub server: &'a str,
pub name: &'a str,
pub from_existing: bool,
Expand All @@ -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,
Expand All @@ -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"
Expand Down Expand Up @@ -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,
Expand Down
43 changes: 43 additions & 0 deletions crates/openshell-cli/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<u64>,

/// Provider name.
#[arg(add = ArgValueCompleter::new(completers::complete_provider_names))]
name: String,
Expand Down Expand Up @@ -3727,6 +3731,7 @@ async fn run_async() -> Result<()> {
}
}
ProviderCommands::Update {
expected_resource_version,
name,
from_existing,
from_oidc_token,
Expand All @@ -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,
Expand Down Expand Up @@ -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([
Expand Down
90 changes: 89 additions & 1 deletion crates/openshell-cli/tests/provider_commands_integration.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<String, String>,
incoming: HashMap<String, String>|
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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;
Expand All @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down
13 changes: 13 additions & 0 deletions docs/sandboxes/manage-providers.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions skills/openshell-cli/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,10 @@ openshell <group> <cmd> --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.
Expand Down
Loading