@@ -40,8 +40,29 @@ export { errorCode };
4040
4141// ---- Curated public types --------------------------------------------------
4242
43+ // The gateway enums (SandboxPhase, ServiceStatus, SettingScope, PolicySource)
44+ // arrive as protoc-gen-es numeric enums. The lowercase literal unions below are
45+ // a hand-maintained mirror of them so consumers get exhaustive, typo-proof
46+ // switches instead of a bare `string`. They are deliberately duplicated by
47+ // hand, not generated, and are expected to stay stable. If a proto enum ever
48+ // gains, removes, or renames a member, update the matching union AND its
49+ // `*_NAMES` map below: the exhaustive `Record` stops compiling, and the
50+ // 'enum name maps' drift test in client.test.ts fails until both sides agree.
51+
52+ /** Lowercase mirror of the generated `SandboxPhase` enum. Hand-maintained. */
53+ export type SandboxPhaseName = 'unspecified' | 'provisioning' | 'ready' | 'error' | 'deleting' | 'unknown' ;
54+
55+ /** Lowercase mirror of the generated `ServiceStatus` enum. Hand-maintained. */
56+ export type HealthStatus = 'unspecified' | 'healthy' | 'degraded' | 'unhealthy' ;
57+
58+ /** Lowercase mirror of the generated `SettingScope` enum. Hand-maintained. */
59+ export type SettingScopeName = 'unspecified' | 'sandbox' | 'global' ;
60+
61+ /** Lowercase mirror of the generated `PolicySource` enum. Hand-maintained. */
62+ export type PolicySourceName = 'unspecified' | 'sandbox' | 'global' ;
63+
4364export interface Health {
44- status : string ;
65+ status : HealthStatus ;
4566 version : string ;
4667}
4768
@@ -71,7 +92,7 @@ export interface SandboxSpec {
7192export interface SandboxRef {
7293 id : string ;
7394 name : string ;
74- phase : string ;
95+ phase : SandboxPhaseName ;
7596 labels : Record < string , string > ;
7697 /** u64 rendered as a string — JS numbers can't hold it safely. */
7798 resourceVersion : string ;
@@ -88,6 +109,8 @@ export interface ExecOptions {
88109 environment ?: Record < string , string > ;
89110 timeoutSecs ?: number ;
90111 stdin ?: Buffer ;
112+ /** Abort the exec (and the in-flight stream RPC) early. */
113+ signal ?: AbortSignal ;
91114}
92115
93116export interface ExecResult {
@@ -123,6 +146,8 @@ export interface ExecInteractiveOptions {
123146 cols ?: number ;
124147 /** Initial terminal rows (0 = server default). */
125148 rows ?: number ;
149+ /** Abort the interactive exec (and the in-flight stream RPC) early. */
150+ signal ?: AbortSignal ;
126151}
127152
128153// The transport half of an interactive exec: raw stdin/stdout/stderr plus
@@ -152,6 +177,8 @@ export interface ForwardOptions {
152177 localPort ?: number ;
153178 /** Local address to bind. Default 127.0.0.1. */
154179 localHost ?: string ;
180+ /** Abort forward setup and tear down the local listener early. */
181+ signal ?: AbortSignal ;
155182}
156183
157184// A process-lifetime local listener that tunnels each accepted connection into
@@ -201,7 +228,7 @@ export interface ProviderChangeOptions {
201228export interface EffectiveSettingView {
202229 value ?: SettingValue ;
203230 /** 'unspecified' | 'sandbox' | 'global'. */
204- scope : string ;
231+ scope : SettingScopeName ;
205232}
206233
207234export interface SandboxConfig {
@@ -212,7 +239,7 @@ export interface SandboxConfig {
212239 /** u64 rendered as a string. */
213240 configRevision : string ;
214241 /** 'unspecified' | 'sandbox' | 'global'. */
215- policySource : string ;
242+ policySource : PolicySourceName ;
216243 globalPolicyVersion : number ;
217244 /** u64 rendered as a string. */
218245 providerEnvRevision : string ;
@@ -237,17 +264,44 @@ export interface UpdateConfigResult {
237264
238265// ---- enum → lowercase string -----------------------------------------------
239266
240- function phaseName ( p : SandboxPhase ) : string {
241- return ( SandboxPhase [ p ] ?? 'UNSPECIFIED' ) . toLowerCase ( ) ;
267+ // Exported for the enum-name drift test only; not re-exported from index.ts, so
268+ // they are not part of the public package API.
269+ export const PHASE_NAMES : Record < SandboxPhase , SandboxPhaseName > = {
270+ [ SandboxPhase . UNSPECIFIED ] : 'unspecified' ,
271+ [ SandboxPhase . PROVISIONING ] : 'provisioning' ,
272+ [ SandboxPhase . READY ] : 'ready' ,
273+ [ SandboxPhase . ERROR ] : 'error' ,
274+ [ SandboxPhase . DELETING ] : 'deleting' ,
275+ [ SandboxPhase . UNKNOWN ] : 'unknown' ,
276+ } ;
277+ export const STATUS_NAMES : Record < ServiceStatus , HealthStatus > = {
278+ [ ServiceStatus . UNSPECIFIED ] : 'unspecified' ,
279+ [ ServiceStatus . HEALTHY ] : 'healthy' ,
280+ [ ServiceStatus . DEGRADED ] : 'degraded' ,
281+ [ ServiceStatus . UNHEALTHY ] : 'unhealthy' ,
282+ } ;
283+ export const SCOPE_NAMES : Record < SettingScope , SettingScopeName > = {
284+ [ SettingScope . UNSPECIFIED ] : 'unspecified' ,
285+ [ SettingScope . SANDBOX ] : 'sandbox' ,
286+ [ SettingScope . GLOBAL ] : 'global' ,
287+ } ;
288+ export const POLICY_SOURCE_NAMES : Record < PolicySource , PolicySourceName > = {
289+ [ PolicySource . UNSPECIFIED ] : 'unspecified' ,
290+ [ PolicySource . SANDBOX ] : 'sandbox' ,
291+ [ PolicySource . GLOBAL ] : 'global' ,
292+ } ;
293+
294+ function phaseName ( p : SandboxPhase ) : SandboxPhaseName {
295+ return PHASE_NAMES [ p ] ?? 'unspecified' ;
242296}
243- function statusName ( s : ServiceStatus ) : string {
244- return ( ServiceStatus [ s ] ?? 'UNSPECIFIED' ) . toLowerCase ( ) ;
297+ function statusName ( s : ServiceStatus ) : HealthStatus {
298+ return STATUS_NAMES [ s ] ?? 'unspecified' ;
245299}
246- function scopeName ( s : SettingScope ) : string {
247- return ( SettingScope [ s ] ?? 'UNSPECIFIED' ) . toLowerCase ( ) ;
300+ function scopeName ( s : SettingScope ) : SettingScopeName {
301+ return SCOPE_NAMES [ s ] ?? 'unspecified' ;
248302}
249- function policySourceName ( s : PolicySource ) : string {
250- return ( PolicySource [ s ] ?? 'UNSPECIFIED' ) . toLowerCase ( ) ;
303+ function policySourceName ( s : PolicySource ) : PolicySourceName {
304+ return POLICY_SOURCE_NAMES [ s ] ?? 'unspecified' ;
251305}
252306
253307function sandboxRef ( sandbox : Sandbox | undefined ) : SandboxRef {
@@ -307,7 +361,8 @@ function updateConfigResult(resp: UpdateConfigResponse): UpdateConfigResult {
307361}
308362
309363// Optimistic-concurrency version pin: absent/empty means 0n (server uses the
310- // current version, backward-compatible). A mismatch surfaces as Aborted → rpc.
364+ // current version, backward-compatible). A mismatch surfaces as Aborted →
365+ // SdkError code 'aborted'.
311366function versionPin ( value : string | undefined ) : bigint {
312367 return value ? BigInt ( value ) : 0n ;
313368}
@@ -560,16 +615,19 @@ export class SandboxClient {
560615 ) : AsyncGenerator < ExecStreamEvent , void , void > {
561616 try {
562617 // Resolve the sandbox id first, exactly like the gateway client.
563- const sandbox = await this . get ( name ) ;
564- const stream = this . grpc . execSandbox ( {
565- sandboxId : sandbox . id ,
566- command,
567- workdir : options ?. workdir ?? '' ,
568- environment : options ?. environment ?? { } ,
569- timeoutSeconds : options ?. timeoutSecs ?? 0 ,
570- stdin : options ?. stdin ? new Uint8Array ( options . stdin ) : new Uint8Array ( ) ,
571- tty : false ,
572- } ) ;
618+ const sandbox = await this . get ( name , options ?. signal ? { signal : options . signal } : undefined ) ;
619+ const stream = this . grpc . execSandbox (
620+ {
621+ sandboxId : sandbox . id ,
622+ command,
623+ workdir : options ?. workdir ?? '' ,
624+ environment : options ?. environment ?? { } ,
625+ timeoutSeconds : options ?. timeoutSecs ?? 0 ,
626+ stdin : options ?. stdin ? new Uint8Array ( options . stdin ) : new Uint8Array ( ) ,
627+ tty : false ,
628+ } ,
629+ { signal : options ?. signal } ,
630+ ) ;
573631
574632 let sawExit = false ;
575633 for await ( const event of stream ) {
@@ -630,7 +688,7 @@ export class SandboxClient {
630688 ) : Promise < ExecInteractiveSession > {
631689 let sandboxId : string ;
632690 try {
633- sandboxId = ( await this . get ( name ) ) . id ;
691+ sandboxId = ( await this . get ( name , options ?. signal ? { signal : options . signal } : undefined ) ) . id ;
634692 } catch ( e ) {
635693 throw e instanceof SdkError ? e : fromConnect ( e ) ;
636694 }
@@ -653,7 +711,7 @@ export class SandboxClient {
653711 } ,
654712 } ) ;
655713
656- const stream = this . grpc . execSandboxInteractive ( input ) ;
714+ const stream = this . grpc . execSandboxInteractive ( input , { signal : options ?. signal } ) ;
657715 let resolveDone ! : ( code : number ) => void ;
658716 let rejectDone ! : ( err : unknown ) => void ;
659717 const done = new Promise < number > ( ( resolve , reject ) => {
@@ -725,7 +783,7 @@ export class SandboxClient {
725783
726784 let sandboxId : string ;
727785 try {
728- const ref = await this . get ( name ) ;
786+ const ref = await this . get ( name , opts . signal ? { signal : opts . signal } : undefined ) ;
729787 if ( ref . phase !== 'ready' ) {
730788 throw new SdkError ( 'connect' , `sandbox '${ name } ' is not ready (phase: ${ ref . phase } )` ) ;
731789 }
@@ -763,16 +821,24 @@ export class SandboxClient {
763821 } ) ;
764822 } ) ;
765823
824+ const teardown = async ( ) : Promise < void > => {
825+ for ( const socket of sockets ) socket . destroy ( ) ;
826+ await new Promise < void > ( ( resolve ) => server . close ( ( ) => resolve ( ) ) ) ;
827+ } ;
828+
829+ // Caller cancellation tears the local listener down the same way close() does.
830+ if ( opts . signal ) {
831+ if ( opts . signal . aborted ) void teardown ( ) ;
832+ else opts . signal . addEventListener ( 'abort' , ( ) => void teardown ( ) , { once : true } ) ;
833+ }
834+
766835 const addr = server . address ( ) as AddressInfo | null ;
767836 return {
768837 localHost,
769838 localPort : addr ? addr . port : localPort ,
770839 targetHost,
771840 targetPort,
772- close : async ( ) : Promise < void > => {
773- for ( const socket of sockets ) socket . destroy ( ) ;
774- await new Promise < void > ( ( resolve ) => server . close ( ( ) => resolve ( ) ) ) ;
775- } ,
841+ close : teardown ,
776842 closed,
777843 } ;
778844 }
0 commit comments