Skip to content

Commit 8c8a05a

Browse files
committed
feat(api): extend mutation replay through gateway interceptors (#3323)
Add typed durable replay receipts for 24 ordinary unary mutations, protect sensitive payload fingerprints, and revalidate intercepted retries without repeating post-commit observation. Part of #3051 (phase 3b). Signed-off-by: Mrunal Patel <[email protected]>
1 parent 132dfcf commit 8c8a05a

23 files changed

Lines changed: 3119 additions & 172 deletions

File tree

‎architecture/gateway.md‎

Lines changed: 25 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -62,8 +62,8 @@ transport status, metadata, and unknown details alongside decoded fields.
6262
SDK deletion waits recognize missing-resource status through typed error wrappers
6363
without suppressing other failures.
6464

65-
Workspace lifecycle, membership, and sandbox-template mutations explicitly opt
66-
into durable request admission when the client supplies a UUID. Typed adapters
65+
Ordinary user-callable unary mutations explicitly opt into durable request
66+
admission when the client supplies a UUID. Typed adapters
6767
check current authorization before looking up a caller/method/workspace-scoped
6868
key. The payload fingerprint excludes that UUID and canonicalizes protobuf maps.
6969
An atomic, quota-checked insert chooses one executor; owned execution survives
@@ -73,10 +73,25 @@ interruption leave permanent unresolved claims, never stealable leases.
7373
Admission rows live outside user workspace namespaces and are bounded per caller.
7474
Successes expire after 24 hours; cleanup uses the unique admission incarnation
7575
and version so an old cleaner cannot delete a new attempt. Replay stores only
76-
resource UUID/version references or deletion outcomes. It checks the original
77-
workspace identity and current authorization, and never substitutes a same-name
78-
resource. Intercepted mutations and credential capabilities require separate
79-
adapters; this mechanism does not replay streams or repeat interceptor observers.
76+
resource references and reviewed public scalar/diagnostic receipts, never
77+
credential-bearing response snapshots. It checks original identities and current
78+
authorization and never substitutes a same-name resource. Sandbox responses are
79+
live projections of the original UUID; normal status reconciliation does not
80+
invalidate replay. Refresh status additionally requires the original grant epoch
81+
and no deletion timestamp, including a timestamp at the Unix epoch.
82+
Other resource projections retain exact-version guards. Terminal delete receipts
83+
do not require the deleted target or parent to remain present.
84+
85+
Sandbox, service, provider/profile, and policy/config adapters use keyed payload
86+
fingerprints derived from existing gateway JWT or primary TLS private material.
87+
Replicas must share that material; missing keys or key changes fail closed without
88+
changing admission identity. Workspace/template adapters retain their original
89+
format. Intercepted requests carry the original decoded payload only in a private
90+
in-memory extension. Replay reauthorizes original and current effective scopes,
91+
requires the same effective payload, and reruns current interceptor validation.
92+
Interceptors cannot mutate the request UUID. Server-marked replay suppresses
93+
post-commit observation, which remains best-effort rather than an outbox.
94+
Credential capabilities and streaming execution require separate contracts.
8095

8196
The gateway listens on one service port and multiplexes gRPC and HTTP traffic.
8297
The default local single-user deployment mode is mTLS user authentication:
@@ -407,8 +422,8 @@ Missing targets return `NOT_FOUND` unless `allow_missing` explicitly requests
407422
failures remain errors. Already-revoked sessions complete without another write
408423
after current authorization. The removed response booleans are reserved by name
409424
and number; this coordinated pre-1.0 API change does not alter durable schemas.
410-
The outcome alone does not provide request deduplication. The six opted-in
411-
workspace/template methods require a request UUID for the admission contract.
425+
The outcome alone does not provide request deduplication. Opted-in unary methods
426+
require a request UUID for the admission contract.
412427

413428
| Dual-purpose encoded root | Current decision |
414429
|---|---|
@@ -461,8 +476,8 @@ advisor drafts without creating resource-specific tables.
461476

462477
Mutation admission uses a private, version-tagged JSON envelope in the same
463478
object store. Its identity namespace stays stable across format changes, and an
464-
unknown format fails closed. It contains no public response payloads and is not
465-
part of the protobuf storage closure.
479+
unknown format fails closed. It contains explicit typed receipts, not arbitrary
480+
public response payloads, and is not part of the protobuf storage closure.
466481

467482
Each sandbox policy revision stores the complete provenance annotation map
468483
supplied with that update. The revision payload is the authoritative immutable

‎crates/openshell-cli/src/commands/provider.rs‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,7 @@ pub async fn sandbox_provider_attach(
109109

110110
let response = match client
111111
.attach_sandbox_provider(AttachSandboxProviderRequest {
112+
request_id: String::new(),
112113
sandbox_name: name.to_string(),
113114
provider_name: provider.to_string(),
114115
expected_resource_version: resource_version,
@@ -165,6 +166,7 @@ pub async fn sandbox_provider_detach(
165166

166167
let response = match client
167168
.detach_sandbox_provider(DetachSandboxProviderRequest {
169+
request_id: String::new(),
168170
sandbox_name: name.to_string(),
169171
provider_name: provider.to_string(),
170172
expected_resource_version: resource_version,
@@ -477,6 +479,7 @@ async fn auto_create_provider(
477479
if let Some(exact_name) = preferred_name {
478480
// Explicit name: create with exactly that name, no retries.
479481
let request = CreateProviderRequest {
482+
request_id: String::new(),
480483
provider: Some(Provider {
481484
metadata: Some(openshell_core::proto::datamodel::v1::ObjectMeta {
482485
id: String::new(),
@@ -525,6 +528,7 @@ async fn auto_create_provider(
525528
};
526529

527530
let request = CreateProviderRequest {
531+
request_id: String::new(),
528532
provider: Some(Provider {
529533
metadata: Some(openshell_core::proto::datamodel::v1::ObjectMeta {
530534
id: String::new(),
@@ -676,6 +680,7 @@ async fn rollback_provider_create_after_gcloud_adc_failure(
676680
) -> Result<()> {
677681
match client
678682
.delete_provider(DeleteProviderRequest {
683+
request_id: String::new(),
679684
allow_missing: true,
680685
name: provider_name.to_string(),
681686
workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
@@ -1107,6 +1112,7 @@ pub async fn provider_create_with_options(options: ProviderCreateOptions<'_>) ->
11071112

11081113
let response = client
11091114
.create_provider(CreateProviderRequest {
1115+
request_id: String::new(),
11101116
provider: Some(Provider {
11111117
metadata: Some(openshell_core::proto::datamodel::v1::ObjectMeta {
11121118
id: String::new(),
@@ -1153,6 +1159,7 @@ pub async fn provider_create_with_options(options: ProviderCreateOptions<'_>) ->
11531159

11541160
if let Err(configure_err) = client
11551161
.configure_provider_refresh(ConfigureProviderRefreshRequest {
1162+
request_id: String::new(),
11561163
provider: provider_name.clone(),
11571164
credential_key: adc_credential_key.clone(),
11581165
strategy: ProviderCredentialRefreshStrategy::Oauth2RefreshToken as i32,
@@ -1178,6 +1185,7 @@ pub async fn provider_create_with_options(options: ProviderCreateOptions<'_>) ->
11781185

11791186
if let Err(rotate_err) = client
11801187
.rotate_provider_credential(RotateProviderCredentialRequest {
1188+
request_id: String::new(),
11811189
provider: provider_name.clone(),
11821190
credential_key: adc_credential_key,
11831191
workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
@@ -1601,6 +1609,7 @@ pub async fn provider_profile_import(
16011609
if !items.is_empty() {
16021610
let response = client
16031611
.import_provider_profiles(ImportProviderProfilesRequest {
1612+
request_id: String::new(),
16041613
profiles: items,
16051614
workspace: workspace.to_string(),
16061615
})
@@ -1650,6 +1659,7 @@ pub async fn provider_profile_update(
16501659
.map_or(0, |profile| profile.resource_version);
16511660
let response = client
16521661
.update_provider_profiles(UpdateProviderProfilesRequest {
1662+
request_id: String::new(),
16531663
profile: Some(item),
16541664
expected_resource_version,
16551665
id: id.to_string(),
@@ -1714,6 +1724,7 @@ pub async fn provider_profile_delete(
17141724
for id in ids {
17151725
let response = match client
17161726
.delete_provider_profile(DeleteProviderProfileRequest {
1727+
request_id: String::new(),
17171728
allow_missing: true,
17181729
id: id.clone(),
17191730
workspace: workspace.to_string(),
@@ -1826,6 +1837,7 @@ pub async fn provider_refresh_config(
18261837
let mut client = grpc_client(server, tls).await?;
18271838
let status = client
18281839
.configure_provider_refresh(ConfigureProviderRefreshRequest {
1840+
request_id: String::new(),
18291841
provider: input.name.to_string(),
18301842
credential_key: input.credential_key.to_string(),
18311843
strategy: strategy as i32,
@@ -1863,6 +1875,7 @@ pub async fn provider_rotate(
18631875
let mut client = grpc_client(server, tls).await?;
18641876
let status = client
18651877
.rotate_provider_credential(RotateProviderCredentialRequest {
1878+
request_id: String::new(),
18661879
provider: name.to_string(),
18671880
credential_key: credential_key.to_string(),
18681881
workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
@@ -1900,6 +1913,7 @@ pub async fn provider_refresh_delete(
19001913
let mut client = grpc_client(server, tls).await?;
19011914
let response = client
19021915
.delete_provider_refresh(DeleteProviderRefreshRequest {
1916+
request_id: String::new(),
19031917
allow_missing: true,
19041918
provider: name.to_string(),
19051919
credential_key: credential_key.to_string(),
@@ -2337,6 +2351,7 @@ pub async fn provider_update(options: ProviderUpdateOptions<'_>) -> Result<()> {
23372351

23382352
let response = client
23392353
.update_provider(UpdateProviderRequest {
2354+
request_id: String::new(),
23402355
provider: Some(Provider {
23412356
metadata: Some(openshell_core::proto::datamodel::v1::ObjectMeta {
23422357
id: String::new(),
@@ -2399,6 +2414,7 @@ pub async fn provider_delete(
23992414
for name in names {
24002415
let response = match client
24012416
.delete_provider(DeleteProviderRequest {
2417+
request_id: String::new(),
24022418
allow_missing: true,
24032419
name: name.clone(),
24042420
workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),

‎crates/openshell-cli/src/run.rs‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -642,6 +642,7 @@ pub async fn sandbox_create(
642642
)])
643643
};
644644
let request = CreateSandboxRequest {
645+
request_id: String::new(),
645646
spec: Some(SandboxSpec {
646647
resource_requirements,
647648
environment: if template.is_none() {
@@ -3302,6 +3303,7 @@ pub async fn sandbox_delete(
33023303

33033304
let response = match client
33043305
.delete_sandbox(DeleteSandboxRequest {
3306+
request_id: String::new(),
33053307
allow_missing: true,
33063308
name: name.clone(),
33073309
workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
@@ -3362,6 +3364,7 @@ pub async fn sandbox_stop(
33623364
let mut client = grpc_client(server, tls).await?;
33633365
let sandbox = client
33643366
.stop_sandbox(StopSandboxRequest {
3367+
request_id: String::new(),
33653368
name: name.to_string(),
33663369
workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
33673370
})
@@ -3385,6 +3388,7 @@ pub async fn sandbox_start(
33853388
let mut client = grpc_client(server, tls).await?;
33863389
let sandbox = client
33873390
.start_sandbox(StartSandboxRequest {
3391+
request_id: String::new(),
33883392
name: name.to_string(),
33893393
workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
33903394
})
@@ -3483,6 +3487,7 @@ pub async fn service_expose(
34833487
let mut client = grpc_client(server, tls).await?;
34843488
let response = client
34853489
.expose_service(ExposeServiceRequest {
3490+
request_id: String::new(),
34863491
sandbox: sandbox.to_string(),
34873492
service: service.to_string(),
34883493
target_port: u32::from(target_port),
@@ -3609,6 +3614,7 @@ pub async fn service_delete(
36093614
let mut client = grpc_client(server, tls).await?;
36103615
let response = client
36113616
.delete_service(DeleteServiceRequest {
3617+
request_id: String::new(),
36123618
allow_missing: false,
36133619
sandbox: sandbox.to_string(),
36143620
service: service.to_string(),
@@ -5882,6 +5888,7 @@ pub async fn sandbox_draft_approve(
58825888

58835889
let response = client
58845890
.approve_draft_chunk(ApproveDraftChunkRequest {
5891+
request_id: String::new(),
58855892
name: name.to_string(),
58865893
chunk_id: chunk_id.to_string(),
58875894
workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
@@ -5914,6 +5921,7 @@ pub async fn sandbox_draft_reject(
59145921

59155922
client
59165923
.reject_draft_chunk(RejectDraftChunkRequest {
5924+
request_id: String::new(),
59175925
name: name.to_string(),
59185926
chunk_id: chunk_id.to_string(),
59195927
reason: reason.to_string(),
@@ -5955,6 +5963,7 @@ pub async fn sandbox_draft_approve_all(
59555963

59565964
let response = client
59575965
.approve_all_draft_chunks(ApproveAllDraftChunksRequest {
5966+
request_id: String::new(),
59585967
name: name.to_string(),
59595968
include_security_flagged,
59605969
workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
@@ -5986,6 +5995,7 @@ pub async fn sandbox_draft_clear(
59865995

59875996
let response = client
59885997
.clear_draft_chunks(ClearDraftChunksRequest {
5998+
request_id: String::new(),
59895999
name: name.to_string(),
59906000
workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
59916001
})

‎crates/openshell-gateway-interceptors/src/proto_json.rs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -308,6 +308,7 @@ mod tests {
308308
let codec =
309309
ProtoJsonCodec::from_descriptor_set(openshell_core::FILE_DESCRIPTOR_SET).unwrap();
310310
let request = CreateSandboxRequest {
311+
request_id: String::new(),
311312
spec: Some(SandboxSpec {
312313
providers: vec!["github".to_string()],
313314
..SandboxSpec::default()
@@ -336,6 +337,7 @@ mod tests {
336337
fn interceptor_view_omits_nested_secrets_but_keeps_non_secret_fields() {
337338
let codec = ProtoJsonCodec::openshell().unwrap();
338339
let request = CreateProviderRequest {
340+
request_id: String::new(),
339341
provider: Some(Provider {
340342
r#type: "github".to_string(),
341343
credentials: HashMap::from([(
@@ -396,6 +398,7 @@ mod tests {
396398
fn generic_sandbox_environment_remains_visible() {
397399
let codec = ProtoJsonCodec::openshell().unwrap();
398400
let request = CreateSandboxRequest {
401+
request_id: String::new(),
399402
spec: Some(SandboxSpec {
400403
environment: HashMap::from([("FEATURE_FLAG".to_string(), "on".to_string())]),
401404
..SandboxSpec::default()

‎crates/openshell-gateway-interceptors/src/runtime.rs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -755,6 +755,7 @@ mod tests {
755755

756756
fn create_provider_operation(codec: &ProtoJsonCodec) -> ValidatedOperation {
757757
let request = CreateProviderRequest {
758+
request_id: String::new(),
758759
provider: Some(Provider {
759760
r#type: "github".to_string(),
760761
credentials: HashMap::from([(
@@ -1009,6 +1010,7 @@ mod tests {
10091010
codec: codec.clone(),
10101011
};
10111012
let request = UpdateConfigRequest {
1013+
request_id: String::new(),
10121014
name: "demo".to_string(),
10131015
expected_resource_version: u64::MAX - 1,
10141016
annotations: HashMap::from([
@@ -1049,6 +1051,7 @@ mod tests {
10491051
let codec =
10501052
ProtoJsonCodec::from_descriptor_set(openshell_core::FILE_DESCRIPTOR_SET).unwrap();
10511053
let request = CreateSandboxRequest {
1054+
request_id: String::new(),
10521055
spec: Some(SandboxSpec {
10531056
template: Some(SandboxTemplate {
10541057
resources: Some(

‎crates/openshell-sdk/src/client.rs‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -356,6 +356,7 @@ impl OpenShellClient {
356356
let response = self
357357
.unary(|mut grpc| {
358358
let request = proto::DeleteSandboxRequest {
359+
request_id: String::new(),
359360
allow_missing: opts.allow_missing,
360361
name: name.to_string(),
361362
workspace_scope: Some(proto::workspace_selector("default")),
@@ -374,6 +375,7 @@ impl OpenShellClient {
374375
let response = self
375376
.unary(|mut grpc| {
376377
let request = proto::StopSandboxRequest {
378+
request_id: String::new(),
377379
name: name.to_string(),
378380
workspace_scope: Some(proto::workspace_selector("default")),
379381
};
@@ -388,6 +390,7 @@ impl OpenShellClient {
388390
let response = self
389391
.unary(|mut grpc| {
390392
let request = proto::StartSandboxRequest {
393+
request_id: String::new(),
391394
name: name.to_string(),
392395
workspace_scope: Some(proto::workspace_selector("default")),
393396
};
@@ -950,6 +953,7 @@ impl WorkspaceScopedClient {
950953
.client
951954
.unary(|mut grpc| {
952955
let request = proto::DeleteSandboxRequest {
956+
request_id: String::new(),
953957
allow_missing: opts.allow_missing,
954958
name: name.to_string(),
955959
workspace_scope: Some(proto::workspace_selector(&self.workspace)),
@@ -969,6 +973,7 @@ impl WorkspaceScopedClient {
969973
.client
970974
.unary(|mut grpc| {
971975
let request = proto::StopSandboxRequest {
976+
request_id: String::new(),
972977
name: name.to_string(),
973978
workspace_scope: Some(proto::workspace_selector(&self.workspace)),
974979
};
@@ -984,6 +989,7 @@ impl WorkspaceScopedClient {
984989
.client
985990
.unary(|mut grpc| {
986991
let request = proto::StartSandboxRequest {
992+
request_id: String::new(),
987993
name: name.to_string(),
988994
workspace_scope: Some(proto::workspace_selector(&self.workspace)),
989995
};
@@ -1181,6 +1187,7 @@ fn create_sandbox_request(spec: SandboxSpec) -> proto::CreateSandboxRequest {
11811187
gpu: Some(proto::GpuResourceRequirements { count: None }),
11821188
});
11831189
proto::CreateSandboxRequest {
1190+
request_id: String::new(),
11841191
spec: Some(proto::SandboxSpec {
11851192
environment,
11861193
template,
@@ -1212,6 +1219,7 @@ fn create_sandbox_from_template_request(
12121219
policy,
12131220
} = spec;
12141221
proto::CreateSandboxRequest {
1222+
request_id: String::new(),
12151223
spec: Some(proto::SandboxSpec {
12161224
providers,
12171225
command,

0 commit comments

Comments
 (0)