Skip to content

Commit ff9af8e

Browse files
fix(sandbox): acknowledge initial policy revision; expose SDK labels/selectors (#2170)
* fix(sandbox): acknowledge initial policy revision The supervisor loaded and enforced a sandbox-scoped policy but never told the gateway which revision it loaded. The policy poll loop seeded itself with the initial revision's hash on its first poll, so `policy_changed` was never true for that revision and `ReportPolicyStatus(LOADED)` — which only ran in the hot-reload branch — was never called. The revision stayed `Pending` and `current_policy_version` stayed 0 even though the sandbox was `Ready` and the policy was effective. This was most visible with sparse policies that get baseline-enriched into a new revision during startup. After the OPA engine is constructed, report the exact sandbox revision the supervisor loaded as LOADED, and seed the poll loop from that revision so it is not re-reported. Report FAILED with the original construction error if engine construction or conversion fails. Only sandbox-sourced revisions (version > 0) whose canonical content matches the loaded policy are acknowledged; global and local-file policies are untouched. Delivery uses the shared bounded retry, is non-fatal on transient failure, and a pending initial acknowledgement is delivered before any newer revision so policy history is never reordered. Signed-off-by: Kyle Zheng <[email protected]> * feat(python): expose sandbox labels and selectors The gateway protobuf and CLI already support request-level sandbox labels (`CreateSandboxRequest.name`/`labels`) and selector-based listing (`ListSandboxesRequest.label_selector`), but the public Python SDK dropped them, so Python-created sandboxes could not be found via `openshell sandbox list --selector ...`. Add optional, source-compatible `name`/`labels` to `SandboxClient.create`, `create_session`, and the high-level `Sandbox`, and `label_selector` to `list`/`list_ids`. `SandboxRef` now carries the gateway labels as an immutable mapping (default empty, so `SandboxRef(id, name, status)` still works). Caller-provided label mappings are copied. Attaching the high-level `Sandbox` to an existing sandbox rejects `name`/`labels` since creation metadata cannot change on attach. Template labels remain a separate concept. No protobuf changes are required. Signed-off-by: Kyle Zheng <[email protected]> * fix(python): keep SandboxRef hashable and copy high-level labels Excluding the new immutable `labels` field from SandboxRef equality/hash (`compare=False`) preserves the original (id, name, status) identity and keeps the frozen dataclass hashable — a MappingProxyType field would otherwise make `hash(SandboxRef(...))` raise. Also defensively copy caller-provided labels in the high-level `Sandbox` so later caller mutation cannot change what is sent. Signed-off-by: Kyle Zheng <[email protected]> * fix(sandbox): bound initial-policy-ack retries The poll loop retried a pending initial acknowledgement before processing any newer revision, but retried unconditionally forever. A permanently undeliverable ack (e.g. the revision was superseded before it could be reported) would then stall all later policy hot-reloads and provider-env refreshes. Cap the retries; after the bound, give up and resume normal polling so the loop cannot livelock on a stuck acknowledgement. Signed-off-by: Kyle Zheng <[email protected]> * test(sandbox): add sparse-policy revision-2 acknowledgement e2e Regression for #2159: create a sandbox with the network-only policy-advisor fixture, which the supervisor enriches with baseline filesystem paths during startup (creating revision 2, superseding revision 1). Assert the effective policy reaches revision 2 and no revision remains Pending once the supervisor acknowledges the load. Adds SandboxGuard::create_keep_with_args to create a kept sandbox with an initial --policy. Signed-off-by: Kyle Zheng <[email protected]> * fix(ci): correct sandbox checks Signed-off-by: Kyle Zheng <[email protected]> * test(cli): serialize mTLS environment access Signed-off-by: Kyle Zheng <[email protected]> * fix(sandbox): address policy review feedback Signed-off-by: Kyle Zheng <[email protected]> * fix(sandbox): preserve exact policy acknowledgements Signed-off-by: Kyle Zheng <[email protected]> * fix(sandbox): preserve local policy overrides Signed-off-by: John Myers <[email protected]> --------- Signed-off-by: Kyle Zheng <[email protected]> Signed-off-by: John Myers <[email protected]> Co-authored-by: John Myers <[email protected]>
1 parent 5207f11 commit ff9af8e

10 files changed

Lines changed: 1368 additions & 92 deletions

File tree

‎architecture/sandbox.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,38 @@ the structured 403 and authors the narrowest rule. Mechanistically mapping L7
171171
would either over-broaden rules or require path-templating logic that rots
172172
quickly.
173173

174+
## Policy Revision Acknowledgement
175+
176+
When the supervisor loads a sandbox-scoped policy from the gateway, it retains
177+
the version, hash, source, and configuration revision returned with that exact
178+
policy snapshot. After the OPA engine is built successfully, the supervisor
179+
reports that revision as `LOADED`, which advances
180+
`SandboxStatus.current_policy_version` and moves the revision out of `Pending`.
181+
If policy construction fails, it reports the captured revision as `FAILED` with
182+
the original construction error. It never infers revision identity by comparing
183+
policy structure.
184+
185+
This holds even when the initial policy is enriched with baseline paths during
186+
startup: the enriched revision the supervisor synced back to the gateway is the
187+
revision it acknowledges, so a successfully constructed initial policy never
188+
remains `Pending`. If the first poll returns a different revision, the supervisor
189+
processes it through the normal reload path instead of treating it as already
190+
loaded.
191+
192+
Policy status delivery uses a FIFO background worker. Retryable delivery
193+
failures retain the ordered update and retry with capped exponential backoff;
194+
terminal errors are logged and discarded. The outbox is nonblocking and does
195+
not discard updates because of a fixed queue capacity, so status endpoint
196+
outages cannot block policy polling, enforcement, settings, or provider
197+
refreshes and cannot permanently lose the initial acknowledgement.
198+
199+
Only sandbox-scoped revisions (`PolicySource::Sandbox`, version greater than
200+
zero) are acknowledged. Global policies and local-file development policies do
201+
not use the sandbox revision API and produce no acknowledgement. When explicit
202+
local Rego and data files are configured, the supervisor continues polling the
203+
gateway for settings and provider refreshes but never replaces the local OPA
204+
engine with a gateway policy revision.
205+
174206
## Failure Behavior
175207

176208
- If gateway config polling fails, the sandbox keeps its last-known-good policy.

‎crates/openshell-cli/tests/mtls_integration.rs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -668,6 +668,7 @@ async fn gateway_add_mtls_loopback_explicit_name_does_not_fallback_to_openshell_
668668

669669
#[tokio::test]
670670
async fn cli_connects_with_client_cert() {
671+
let _env = EnvVarGuard::set(&[]);
671672
install_rustls_provider();
672673

673674
let (ca, ca_key) = build_ca();
@@ -741,6 +742,7 @@ async fn run_server_no_client_auth(
741742

742743
#[tokio::test]
743744
async fn cli_connects_with_gateway_insecure() {
745+
let _env = EnvVarGuard::set(&[]);
744746
install_rustls_provider();
745747

746748
let (ca, ca_key) = build_ca();

‎crates/openshell-core/src/grpc_client.rs‎

Lines changed: 54 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -573,26 +573,46 @@ pub async fn fetch_policy(endpoint: &str, sandbox_id: &str) -> Result<Option<Pro
573573
fetch_policy_with_client(&mut client, sandbox_id).await
574574
}
575575

576-
/// Fetch sandbox policy using an existing client connection.
577-
async fn fetch_policy_with_client(
576+
/// Fetch the authoritative policy and revision metadata in one response.
577+
///
578+
/// Callers that must acknowledge the exact revision they loaded should retain
579+
/// this snapshot instead of re-fetching metadata after policy construction.
580+
pub async fn fetch_settings_snapshot(
581+
endpoint: &str,
582+
sandbox_id: &str,
583+
) -> Result<SettingsPollResult> {
584+
debug!(endpoint = %endpoint, sandbox_id = %sandbox_id, "Connecting to fetch OpenShell settings snapshot");
585+
let mut client = connect(endpoint).await?;
586+
fetch_settings_snapshot_with_client(&mut client, sandbox_id).await
587+
}
588+
589+
async fn fetch_settings_snapshot_with_client(
578590
client: &mut OpenShellClient<AuthedChannel>,
579591
sandbox_id: &str,
580-
) -> Result<Option<ProtoSandboxPolicy>> {
592+
) -> Result<SettingsPollResult> {
581593
let response = client
582594
.get_sandbox_config(GetSandboxConfigRequest {
583595
sandbox_id: sandbox_id.to_string(),
584596
})
585597
.await
586598
.into_diagnostic()?;
587599

588-
let inner = response.into_inner();
600+
Ok(settings_poll_result(response.into_inner()))
601+
}
602+
603+
/// Fetch sandbox policy using an existing client connection.
604+
async fn fetch_policy_with_client(
605+
client: &mut OpenShellClient<AuthedChannel>,
606+
sandbox_id: &str,
607+
) -> Result<Option<ProtoSandboxPolicy>> {
608+
let snapshot = fetch_settings_snapshot_with_client(client, sandbox_id).await?;
589609

590610
// version 0 with no policy means the sandbox was created without one.
591-
if inner.version == 0 && inner.policy.is_none() {
611+
if snapshot.version == 0 && snapshot.policy.is_none() {
592612
return Ok(None);
593613
}
594614

595-
Ok(Some(inner.policy.ok_or_else(|| {
615+
Ok(Some(snapshot.policy.ok_or_else(|| {
596616
miette::miette!("Server returned non-zero version but empty policy")
597617
})?))
598618
}
@@ -661,6 +681,18 @@ pub async fn sync_policy(endpoint: &str, sandbox: &str, policy: &ProtoSandboxPol
661681
sync_policy_with_client(&mut client, sandbox, policy).await
662682
}
663683

684+
/// Sync an enriched policy and return the authoritative revision snapshot.
685+
pub async fn sync_policy_and_fetch_snapshot(
686+
endpoint: &str,
687+
sandbox_id: &str,
688+
sandbox: &str,
689+
policy: &ProtoSandboxPolicy,
690+
) -> Result<SettingsPollResult> {
691+
let mut client = connect(endpoint).await?;
692+
sync_policy_with_client(&mut client, sandbox, policy).await?;
693+
fetch_settings_snapshot_with_client(&mut client, sandbox_id).await
694+
}
695+
664696
/// Fetch provider environment variables for a sandbox from `OpenShell` server via gRPC.
665697
///
666698
/// Returns a map of environment variable names to values derived from provider
@@ -700,6 +732,7 @@ pub struct CachedOpenShellClient {
700732
}
701733

702734
/// Settings poll result returned by [`CachedOpenShellClient::poll_settings`].
735+
#[derive(Clone, Debug)]
703736
pub struct SettingsPollResult {
704737
pub policy: Option<ProtoSandboxPolicy>,
705738
pub version: u32,
@@ -713,6 +746,20 @@ pub struct SettingsPollResult {
713746
pub provider_env_revision: u64,
714747
}
715748

749+
fn settings_poll_result(inner: crate::proto::GetSandboxConfigResponse) -> SettingsPollResult {
750+
SettingsPollResult {
751+
policy: inner.policy,
752+
version: inner.version,
753+
policy_hash: inner.policy_hash,
754+
config_revision: inner.config_revision,
755+
policy_source: PolicySource::try_from(inner.policy_source)
756+
.unwrap_or(PolicySource::Unspecified),
757+
settings: inner.settings,
758+
global_policy_version: inner.global_policy_version,
759+
provider_env_revision: inner.provider_env_revision,
760+
}
761+
}
762+
716763
pub struct ProviderEnvironmentResult {
717764
pub environment: HashMap<String, String>,
718765
pub provider_env_revision: u64,
@@ -743,19 +790,7 @@ impl CachedOpenShellClient {
743790
.await
744791
.into_diagnostic()?;
745792

746-
let inner = response.into_inner();
747-
748-
Ok(SettingsPollResult {
749-
policy: inner.policy,
750-
version: inner.version,
751-
policy_hash: inner.policy_hash,
752-
config_revision: inner.config_revision,
753-
policy_source: PolicySource::try_from(inner.policy_source)
754-
.unwrap_or(PolicySource::Unspecified),
755-
settings: inner.settings,
756-
global_policy_version: inner.global_policy_version,
757-
provider_env_revision: inner.provider_env_revision,
758-
})
793+
Ok(settings_poll_result(response.into_inner()))
759794
}
760795

761796
/// Submit denial summaries and/or agent-authored proposals for policy analysis.

0 commit comments

Comments
 (0)