Skip to content

Commit 947d537

Browse files
committed
refactor(sdk)!: make wait_ready succeed only on Ready
wait_ready previously also returned Ok for a sandbox that reached Completed. A caller waiting for a sandbox almost always needs a live one, and the name suggests that, so a sandbox that completes before becoming ready is now an error that fails fast, like Stopped, Error and the suspended phases. This applies to the Rust SDK's OpenShellClient and WorkspaceScopedClient, the Go SDK's WaitReady and the TypeScript SDK's waitReady, so the three SDKs agree. BREAKING CHANGE: Rust wait_ready, Go SandboxInterface.WaitReady and TypeScript waitReady return an error instead of the sandbox when it reaches the Completed phase. Callers that need to wait for a finished workload should poll the sandbox. Signed-off-by: Evan Lezar <[email protected]>
1 parent 845dc5e commit 947d537

6 files changed

Lines changed: 41 additions & 22 deletions

File tree

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

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -474,14 +474,16 @@ impl OpenShellClient {
474474
}
475475

476476
/// Poll [`OpenShellClient::get_sandbox`] until the sandbox reaches
477-
/// [`SandboxPhase::Ready`] or successful [`SandboxPhase::Completed`], or
478-
/// until the `timeout` elapses.
477+
/// [`SandboxPhase::Ready`], or until the `timeout` elapses.
479478
///
480-
/// Returns the terminal sandbox snapshot on success. Returns an
481-
/// [`SdkError::Connect`] when the timeout expires, or whatever error
482-
/// the gateway returns if the sandbox transitions into
479+
/// Returns the sandbox snapshot on success. Returns an
480+
/// [`SdkError::Connect`] when the timeout expires, or when the sandbox
481+
/// transitions into [`SandboxPhase::Completed`],
483482
/// [`SandboxPhase::Stopped`], [`SandboxPhase::Error`],
484483
/// [`SandboxPhase::Suspending`], or [`SandboxPhase::Suspended`].
484+
/// A sandbox that completes before becoming ready is an error: callers
485+
/// that need to wait for a finished workload should poll
486+
/// [`OpenShellClient::get_sandbox`] themselves.
485487
pub async fn wait_ready(&self, name: &str, timeout: Duration) -> Result<SandboxRef> {
486488
self.wait_ready_in("default", name, timeout).await
487489
}
@@ -973,7 +975,10 @@ impl OpenShellClient {
973975
|| async {
974976
let snapshot = self.get_sandbox_in(workspace, name).await?;
975977
match snapshot.phase {
976-
SandboxPhase::Ready | SandboxPhase::Completed => Ok(Some(snapshot)),
978+
SandboxPhase::Ready => Ok(Some(snapshot)),
979+
SandboxPhase::Completed => Err(SdkError::connect(format!(
980+
"sandbox '{name}' completed before becoming ready"
981+
))),
977982
SandboxPhase::Stopped => {
978983
let detail = snapshot.exit_code.map_or_else(
979984
|| "stopped before becoming ready".to_string(),
@@ -1297,8 +1302,11 @@ impl WorkspaceScopedClient {
12971302
sandbox_from_response(response.sandbox)
12981303
}
12991304

1300-
/// Poll until the sandbox reaches [`SandboxPhase::Ready`] or successful
1301-
/// [`SandboxPhase::Completed`], or the timeout elapses.
1305+
/// Poll until the sandbox reaches [`SandboxPhase::Ready`], or the timeout
1306+
/// elapses.
1307+
///
1308+
/// Fails fast, like [`OpenShellClient::wait_ready`], when the sandbox
1309+
/// completes, stops, errors or is suspended before becoming ready.
13021310
pub async fn wait_ready(&self, name: &str, timeout: Duration) -> Result<SandboxRef> {
13031311
self.client
13041312
.wait_ready_in(&self.workspace, name, timeout)

‎crates/openshell-sdk/tests/client_mock.rs‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1654,16 +1654,23 @@ async fn wait_ready_transitions_through_phases() {
16541654
}
16551655

16561656
#[tokio::test]
1657-
async fn wait_ready_accepts_successful_completion() {
1657+
async fn wait_ready_rejects_completion() {
16581658
let state = MockState {
16591659
phase_sequence: vec![
16601660
proto::SandboxPhase::Provisioning,
16611661
proto::SandboxPhase::Completed,
16621662
],
16631663
..Default::default()
16641664
};
1665-
for (result, _, _) in wait_ready_both(state, Duration::from_secs(5)).await {
1666-
assert_eq!(result.unwrap().phase, SandboxPhase::Completed);
1665+
for (result, _, calls) in wait_ready_both(state, Duration::from_secs(5)).await {
1666+
let err = result.unwrap_err();
1667+
assert_eq!(err.code(), "connect");
1668+
assert!(
1669+
err.to_string()
1670+
.contains("sandbox 'my-box' completed before becoming ready"),
1671+
"unexpected message: {err}"
1672+
);
1673+
assert_eq!(calls, 2, "must fail fast instead of polling to timeout");
16671674
}
16681675
}
16691676

‎sdk/go/openshell/v1/sandbox_client.go‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -368,9 +368,6 @@ func checkTerminalPhase(sb *Sandbox, name string, target SandboxPhase) (*Sandbox
368368
}
369369
switch sb.Status.Phase {
370370
case SandboxCompleted:
371-
if target == SandboxReady {
372-
return sb, nil
373-
}
374371
return nil, &StatusError{Code: ErrorInternal, Message: fmt.Sprintf("sandbox %q completed before reaching %s", name, target)}
375372
case SandboxStopped:
376373
return nil, &StatusError{Code: ErrorInternal, Message: fmt.Sprintf("sandbox %q stopped before reaching %s", name, target)}

‎sdk/go/openshell/v1/sandbox_client_test.go‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -974,7 +974,7 @@ func TestSandboxWaitReady_SandboxFailed(t *testing.T) {
974974
require.Error(t, err)
975975
}
976976

977-
func TestSandboxWaitReady_SandboxCompleted(t *testing.T) {
977+
func TestSandboxWaitReady_RejectsCompleted(t *testing.T) {
978978
mock := newMockSandboxServer()
979979
mock.sandboxes["complete-sb"] = &pb.Sandbox{
980980
Metadata: &dm.ObjectMeta{Name: "complete-sb"},
@@ -983,10 +983,10 @@ func TestSandboxWaitReady_SandboxCompleted(t *testing.T) {
983983
client, cleanup := setupSandboxTest(t, mock)
984984
defer cleanup()
985985

986-
result, err := client.WaitReady(context.Background(), "default", "complete-sb")
986+
_, err := client.WaitReady(context.Background(), "default", "complete-sb")
987987

988-
require.NoError(t, err)
989-
assert.Equal(t, SandboxCompleted, result.Status.Phase)
988+
require.Error(t, err)
989+
assert.Contains(t, err.Error(), "completed before reaching Ready")
990990
}
991991

992992
func TestSandboxWaitReady_SandboxStopped(t *testing.T) {

‎sdk/typescript/src/client.test.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1325,7 +1325,7 @@ describe('sandbox templates', () => {
13251325
});
13261326

13271327
describe('waits', () => {
1328-
it('waitReady accepts successful main-process completion', async () => {
1328+
it('waitReady rejects main-process completion without waiting for timeout', async () => {
13291329
const sandbox = client({
13301330
getSandbox: () => ({
13311331
sandbox: {
@@ -1334,7 +1334,10 @@ describe('waits', () => {
13341334
},
13351335
}),
13361336
});
1337-
await expect(sandbox.waitReady('sb', 1)).resolves.toMatchObject({ phase: 'completed', exitCode: 0 });
1337+
await expect(sandbox.waitReady('sb', 30)).rejects.toMatchObject({
1338+
code: 'connect',
1339+
message: expect.stringContaining('completed before becoming ready'),
1340+
});
13381341
});
13391342

13401343
it('waitReady rejects stopped main-process results without waiting for timeout', async () => {

‎sdk/typescript/src/client.ts‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1341,7 +1341,8 @@ export class SandboxClient {
13411341
}
13421342
}
13431343

1344-
// Poll until the sandbox is ready. The timeout bounds the returned promise,
1344+
// Poll until the sandbox is ready; a sandbox that completes, stops, errors or
1345+
// is suspended first is an error. The timeout bounds the returned promise,
13451346
// not just the sleep loop: each poll RPC carries the remaining deadline (and
13461347
// any caller signal), so a stalled get() is aborted rather than hanging.
13471348
async waitReady(name: string, timeoutSecs: number, options?: WaitOptions | null): Promise<SandboxRef> {
@@ -1361,7 +1362,10 @@ export class SandboxClient {
13611362
} catch (e) {
13621363
throw mapWaitError(e, name, deadline, signal, pollOptions.signal);
13631364
}
1364-
if (ref.phase === 'ready' || ref.phase === 'completed') return ref;
1365+
if (ref.phase === 'ready') return ref;
1366+
if (ref.phase === 'completed') {
1367+
throw new SdkError('connect', `sandbox '${name}' completed before becoming ready`);
1368+
}
13651369
if (ref.phase === 'stopped') throw new SdkError('connect', `sandbox '${name}' stopped before becoming ready`);
13661370
if (ref.phase === 'error') throw new SdkError('connect', `sandbox '${name}' entered error phase`);
13671371
if (ref.phase === 'suspending' || ref.phase === 'suspended') {

0 commit comments

Comments
 (0)