Skip to content

Commit 123d95e

Browse files
authored
fix(pagination): document list contract and harden SDK pagers (NVIDIA#3279)
* fix(pagination): document list contract and harden SDK pagers Signed-off-by: Gaizka Menendez Hernandez <gmenende@redhat.com> * fix(pagination): bound pager token history Signed-off-by: Gaizka Menendez Hernandez <gmenende@redhat.com> * fix(pagination): preflight token history limits Signed-off-by: Gaizka Menendez Hernandez <gmenende@redhat.com> * fix(pagination): paginate sandbox providers Signed-off-by: Gaizka Menendez Hernandez <gmenende@redhat.com> * fix(pagination): harden TypeScript pager Signed-off-by: Gaizka Menendez Hernandez <gmenende@redhat.com> * fix(pagination): expose provider pagers in SDKs Signed-off-by: Gaizka Menendez Hernandez <gmenende@redhat.com> * docs(pagination): describe a uniform list contract Signed-off-by: Gaizka Menendez Hernandez <gmenende@redhat.com> * fix(pagination): use stable provider cursors Signed-off-by: Gaizka Menendez Hernandez <gmenende@redhat.com> * docs(pagination): clarify mutation semantics Signed-off-by: Gaizka Menendez Hernandez <gmenende@redhat.com> * fix(cli): expose sandbox provider pagination Signed-off-by: Gaizka Menendez Hernandez <gmenende@redhat.com> * fix(proto): refresh pagination schema inventory Signed-off-by: Gaizka Menendez Hernandez <gmenende@redhat.com> * fix(proto): refresh rebased schema inventory Signed-off-by: Gaizka Menendez Hernandez <gmenende@redhat.com> Signed-off-by: Kris Hicks <khicks@nvidia.com> --------- Signed-off-by: Gaizka Menendez Hernandez <gmenende@redhat.com> Signed-off-by: Kris Hicks <khicks@nvidia.com>
1 parent 52aac37 commit 123d95e

26 files changed

Lines changed: 909 additions & 114 deletions

‎architecture/gateway.md‎

Lines changed: 20 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -858,10 +858,16 @@ modes:
858858
and `page_token` fields, and responses carry `next_page_token`. The gateway
859859
clamps page sizes to 1,000 and returns opaque base64url continuation tokens.
860860
Tokens bind the RPC and every request parameter except `page_size`, contain no
861-
authorization grant, and use immutable keyset cursors rather than database
862-
offsets. Each page repeats normal authentication and authorization. Pagination
863-
is weakly consistent under concurrent writes and deletes; it does not provide a
864-
historical snapshot.
861+
authorization grant, and use immutable keyset cursors. Each page repeats normal
862+
authentication and authorization. Pagination is resumable and keyset-based; it
863+
does not provide a historical snapshot while the collection is mutated
864+
concurrently.
865+
866+
Object-backed lists (`ListSandboxTemplates`, `ListSandboxes`, `ListServices`,
867+
`ListProviders`, `ListWorkspaces`, and `ListWorkspaceMembers`) sort ascending
868+
by `(created_at_ms, name, workspace, id)`. `ListProviderProfiles` sorts
869+
ascending by `(id, scope)`, and `ListSandboxPolicies` sorts by descending policy
870+
version. Provider attachments sort ascending by provider name.
865871

866872
The token wire format is a private shared protobuf used only by the gateway.
867873
Public request and response messages repeat the standard AIP fields directly
@@ -878,6 +884,16 @@ Curated Rust, Python, Go, and TypeScript SDK list methods return lazy pagers.
878884
Advancing a pager issues one list RPC and exposes its continuation token;
879885
explicit `list_all` helpers are the only curated APIs that exhaust a collection.
880886

887+
**Migration.** This pagination contract is a breaking replacement for the
888+
former `limit`/`offset` list APIs. Protocol clients must send `page_size` and
889+
resume only with the returned `next_page_token`; an empty token is the sole
890+
completion signal. SDK callers that need every item must use the explicit
891+
full-iteration helper (for example, Rust's `list_all_sandboxes`) rather than
892+
awaiting `list_sandboxes`, which now returns one-page `Pager` state. Callers
893+
that need one page should advance that pager once and retain its token. Internal
894+
full scans use the reusable iteration helpers from the persistence pagination
895+
audit rather than manually advancing offsets.
896+
881897
Persistence distinguishes one-page operations from exhaustive scans.
882898
`list_object_page` and `list_message_page` return one keyset page and its next
883899
cursor. `collect_records` and `collect_messages` exhaust those pages, fail on

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

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,8 @@ fn aggregate_delete_failures(resource: &str, failures: &[String]) -> Result<()>
8787
pub async fn sandbox_provider_list(
8888
server: &str,
8989
name: &str,
90+
page_size: i32,
91+
page_token: &str,
9092
output: &str,
9193
workspace: &str,
9294
tls: &TlsOptions,
@@ -98,14 +100,25 @@ pub async fn sandbox_provider_list(
98100
workspace_scope: Some(openshell_core::proto::workspace_selector(
99101
(workspace).to_string(),
100102
)),
103+
page_size,
104+
page_token: page_token.to_string(),
101105
})
102106
.await
103107
.into_diagnostic()?;
104-
let providers = response.into_inner().providers;
108+
let response = response.into_inner();
109+
let next_page_token = response.next_page_token;
110+
let providers = response.providers;
105111

106-
if crate::output::print_output_collection(output, &providers, attached_provider_to_json)? {
112+
if crate::output::print_paginated_output_collection(
113+
output,
114+
"providers",
115+
&providers,
116+
&next_page_token,
117+
attached_provider_to_json,
118+
)? {
107119
return Ok(());
108120
}
121+
crate::output::print_next_page_token(&next_page_token);
109122

110123
if providers.is_empty() {
111124
println!("No providers attached to sandbox {name}.");

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

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1799,6 +1799,14 @@ enum SandboxProviderCommands {
17991799
#[arg(add = ArgValueCompleter::new(completers::complete_sandbox_names))]
18001800
name: Option<String>,
18011801

1802+
/// Maximum number of attached providers to return in this page.
1803+
#[arg(long, default_value_t = 100)]
1804+
page_size: i32,
1805+
1806+
/// Opaque continuation token from a previous page.
1807+
#[arg(long, default_value = "")]
1808+
page_token: String,
1809+
18021810
/// Output format.
18031811
#[arg(short = 'o', long = "output", value_enum, default_value_t = OutputFormat::Table)]
18041812
output: OutputFormat,
@@ -3573,11 +3581,18 @@ async fn run_async() -> Result<()> {
35733581
run::print_ssh_config(&ctx.name, &name, &cli.workspace);
35743582
}
35753583
SandboxCommands::Provider(command) => match command {
3576-
SandboxProviderCommands::List { name, output } => {
3584+
SandboxProviderCommands::List {
3585+
name,
3586+
page_size,
3587+
page_token,
3588+
output,
3589+
} => {
35773590
let name = resolve_sandbox_name(name, &ctx.name, &cli.workspace)?;
35783591
run::sandbox_provider_list(
35793592
endpoint,
35803593
&name,
3594+
page_size,
3595+
&page_token,
35813596
output.as_str(),
35823597
&cli.workspace,
35833598
&tls,

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

Lines changed: 106 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,7 @@ struct ProviderState {
103103
fail_delete_provider_profile_message: Arc<Mutex<Option<String>>>,
104104
sandbox_providers: Arc<Mutex<HashMap<String, Vec<String>>>>,
105105
sandbox_provider_requests: Arc<Mutex<Vec<SandboxProviderRequestLog>>>,
106+
sandbox_provider_next_page_token: Arc<Mutex<String>>,
106107
readiness_receipts: Arc<Mutex<HashMap<String, ProviderMutationReceipt>>>,
107108
readiness_scripts: Arc<Mutex<ReadinessScript>>,
108109
readiness_requests: Arc<Mutex<Vec<GetSandboxProviderStatusRequest>>>,
@@ -139,6 +140,8 @@ enum ProviderRefreshRequestLog {
139140
enum SandboxProviderRequestLog {
140141
List {
141142
sandbox_name: String,
143+
page_size: i32,
144+
page_token: String,
142145
},
143146
Attach {
144147
sandbox_name: String,
@@ -376,6 +379,8 @@ impl OpenShell for TestOpenShell {
376379
.await
377380
.push(SandboxProviderRequestLog::List {
378381
sandbox_name: sandbox_name.clone(),
382+
page_size: request.page_size,
383+
page_token: request.page_token,
379384
});
380385
let provider_names = self
381386
.state
@@ -390,7 +395,15 @@ impl OpenShell for TestOpenShell {
390395
.iter()
391396
.filter_map(|name| providers_by_name.get(name).cloned())
392397
.collect();
393-
Ok(Response::new(ListSandboxProvidersResponse { providers }))
398+
Ok(Response::new(ListSandboxProvidersResponse {
399+
providers,
400+
next_page_token: self
401+
.state
402+
.sandbox_provider_next_page_token
403+
.lock()
404+
.await
405+
.clone(),
406+
}))
394407
}
395408

396409
async fn attach_sandbox_provider(
@@ -4160,9 +4173,17 @@ async fn sandbox_provider_cli_run_functions_wire_requests_and_idempotent_results
41604173
)
41614174
.await
41624175
.expect("sandbox provider attach is idempotent");
4163-
run::sandbox_provider_list(&ts.endpoint, "dev-sandbox", "table", "default", &ts.tls)
4164-
.await
4165-
.expect("sandbox provider list");
4176+
run::sandbox_provider_list(
4177+
&ts.endpoint,
4178+
"dev-sandbox",
4179+
100,
4180+
"",
4181+
"table",
4182+
"default",
4183+
&ts.tls,
4184+
)
4185+
.await
4186+
.expect("sandbox provider list");
41664187
run::sandbox_provider_detach(
41674188
&ts.endpoint,
41684189
"dev-sandbox",
@@ -4198,6 +4219,8 @@ async fn sandbox_provider_cli_run_functions_wire_requests_and_idempotent_results
41984219
},
41994220
SandboxProviderRequestLog::List {
42004221
sandbox_name: "dev-sandbox".to_string(),
4222+
page_size: 100,
4223+
page_token: String::new(),
42014224
},
42024225
SandboxProviderRequestLog::Detach {
42034226
sandbox_name: "dev-sandbox".to_string(),
@@ -4214,6 +4237,85 @@ async fn sandbox_provider_cli_run_functions_wire_requests_and_idempotent_results
42144237
assert!(providers.get("dev-sandbox").is_none_or(Vec::is_empty));
42154238
}
42164239

4240+
#[tokio::test]
4241+
async fn sandbox_provider_list_cli_forwards_pagination_and_emits_envelopes() {
4242+
let ts = run_server().await;
4243+
ts.state.providers.lock().await.insert(
4244+
"work-github".to_string(),
4245+
Provider {
4246+
metadata: Some(openshell_core::proto::datamodel::v1::ObjectMeta {
4247+
id: "provider-work-github".to_string(),
4248+
name: "work-github".to_string(),
4249+
workspace: "default".to_string(),
4250+
resource_version: 1,
4251+
..Default::default()
4252+
}),
4253+
r#type: "github".to_string(),
4254+
..Default::default()
4255+
},
4256+
);
4257+
ts.state
4258+
.sandbox_providers
4259+
.lock()
4260+
.await
4261+
.insert("dev-sandbox".to_string(), vec!["work-github".to_string()]);
4262+
*ts.state.sandbox_provider_next_page_token.lock().await = "next-page".to_string();
4263+
4264+
for format in ["json", "yaml"] {
4265+
let output = run_readiness_cli(
4266+
&ts,
4267+
&[
4268+
"sandbox",
4269+
"provider",
4270+
"list",
4271+
"dev-sandbox",
4272+
"--page-size",
4273+
"1",
4274+
"--page-token",
4275+
"prior-page",
4276+
"--output",
4277+
format,
4278+
],
4279+
)
4280+
.await;
4281+
assert!(
4282+
output.status.success(),
4283+
"sandbox provider list {format} failed:\n{}",
4284+
String::from_utf8_lossy(&output.stderr)
4285+
);
4286+
assert!(
4287+
output.stderr.is_empty(),
4288+
"structured output wrote to stderr"
4289+
);
4290+
4291+
let value: serde_json::Value = match format {
4292+
"json" => serde_json::from_slice(&output.stdout).expect("parse JSON envelope"),
4293+
"yaml" => serde_yml::from_slice(&output.stdout).expect("parse YAML envelope"),
4294+
_ => unreachable!(),
4295+
};
4296+
assert_eq!(value["next_page_token"], "next-page");
4297+
assert_eq!(value["providers"].as_array().map(Vec::len), Some(1));
4298+
assert_eq!(value["providers"][0]["name"], "work-github");
4299+
}
4300+
4301+
let requests = ts.state.sandbox_provider_requests.lock().await.clone();
4302+
assert_eq!(
4303+
requests,
4304+
vec![
4305+
SandboxProviderRequestLog::List {
4306+
sandbox_name: "dev-sandbox".to_string(),
4307+
page_size: 1,
4308+
page_token: "prior-page".to_string(),
4309+
},
4310+
SandboxProviderRequestLog::List {
4311+
sandbox_name: "dev-sandbox".to_string(),
4312+
page_size: 1,
4313+
page_token: "prior-page".to_string(),
4314+
},
4315+
]
4316+
);
4317+
}
4318+
42174319
#[tokio::test]
42184320
async fn sandbox_provider_attach_cli_surfaces_server_errors() {
42194321
let ts = run_server().await;

‎crates/openshell-sdk/README.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -81,9 +81,11 @@ if deletion.outcome == openshell_sdk::DeletionOutcome::Accepted {
8181
```
8282

8383
Curated `list_*` methods return a lazy `Pager<T>`. Each `next_page()` call
84-
issues at most one RPC and returns a `Page<T>` with its opaque continuation
85-
token. The explicit `list_all_*` conveniences exhaust that pager; `page_size`
86-
always controls one gateway request, and `page_token` resumes a saved traversal.
84+
fetches one logical page and returns a `Page<T>` with its opaque continuation
85+
token. OIDC authentication can retry that page once after an `Unauthenticated`
86+
response. The explicit `list_all_*` conveniences exhaust that pager;
87+
`page_size` always controls one gateway request, and `page_token` resumes a
88+
saved traversal.
8789

8890
```rust
8991
let mut pages = client.list_sandboxes(ListOptions {

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,9 @@ pub struct Page<T> {
2222
/// A lazy, single-pass iterator over response pages.
2323
///
2424
/// Constructed by curated `list_*` methods. No RPC is issued until
25-
/// [`Pager::next_page`] is called, and each call fetches at most one page.
25+
/// [`Pager::next_page`] is called, and each call fetches one logical page.
26+
/// A refreshed OIDC credential may retry that page once after an
27+
/// `Unauthenticated` response.
2628
pub struct Pager<T> {
2729
fetch: PageFetcher<T>,
2830
next_page_token: Option<String>,

0 commit comments

Comments
 (0)