Watch CVM State

Monitor CVM state changes in real-time using Server-Sent Events (SSE) with Go channels.

The WatchCVMState method streams CVM state changes in real-time using Server-Sent Events (SSE). It returns a Go channel that emits events as the CVM transitions between states, making it natural to use with for range loops.

​

WatchCVMState

GET /cvms/{cvmId}/state (SSE stream)

Opens an SSE connection and delivers events through a channel. A valid complete event ends the watch. The channel also closes on a terminal error or context cancellation.

func (c *Client) WatchCVMState(ctx context.Context, cvmID string, opts *WatchCVMStateOptions) (<-chan CVMStateEvent, error)

Parameters:

Field	Type	Required	Description
cvmID	string	Yes	CVM identifier
opts	*WatchCVMStateOptions	Yes	Stream options, including the required target

WatchCVMStateOptions fields:

Field	Type	Default	Description
Target	string	None	Required target state (e.g., "running", "stopped")
Interval	int	5	Polling interval in seconds (5-30)
Timeout	int	300	Server-side per-attempt timeout in seconds (10-600)
MaxRetries	*int	nil (unlimited)	Max reconnection attempts; nil = unlimited, 0 = no retries
RetryDelay	time.Duration	5s	Delay between reconnection attempts

Returns: <-chan CVMStateEvent — a receive-only channel of state events.

​

CVMStateEvent

Each event received from the channel has this structure:

type CVMStateEvent struct {
    Event string                 // Event type: "state", "complete", "error", "timeout"
    Data  map[string]any         // Event payload (parsed from JSON)
    Error error                  // Non-nil if this is an error event
}

The Event field indicates what happened:

Event	Meaning
"state"	A state update; Data contains the raw state
"complete"	Completion event with a nonempty status; the stream closes
"error"	An SSE or terminal request error; inspect Error
"timeout"	Server-side attempt timed out; the watcher may reconnect

​

Basic Usage

The simplest pattern is ranging over the channel until it closes:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()

ch, err := client.WatchCVMState(ctx, "my-app", &phala.WatchCVMStateOptions{
    Target:   "running",
    Interval: 5,
    Timeout:  300,
})
if err != nil {
    log.Fatal(err)
}

for event := range ch {
    if event.Error != nil {
        log.Printf("Error: %v", event.Error)
        continue
    }
    fmt.Printf("[%s] %v\n", event.Event, event.Data)
}
fmt.Println("Stream ended")

​

Cancellation with Context

Use context cancellation as the Go equivalent of JavaScript’s AbortController. Cancelling the context closes the SSE connection and the channel.

ctx, cancel := context.WithCancel(context.Background())

ch, err := client.WatchCVMState(ctx, "my-app", &phala.WatchCVMStateOptions{
    Target: "running",
})
if err != nil {
    log.Fatal(err)
}

// Cancel from another goroutine after some condition
go func() {
    time.Sleep(30 * time.Second)
    cancel() // Stops the SSE stream
}()

for event := range ch {
    fmt.Printf("State: %s\n", event.Event)
}

Always use a context with a timeout or deadline to avoid watching indefinitely. The server-side Timeout option is a safety net, but client-side context timeouts give you more control.

​

Retry Behavior

By default, the watcher reconnects indefinitely after a timeout or a stream ending before completion. Configure retries to limit this behavior. An SSE error event can be followed by more events; it does not itself close the stream.

// Retry up to 3 times
ch, err := client.WatchCVMState(ctx, "my-app", &phala.WatchCVMStateOptions{
    Target:     "running",
    MaxRetries: phala.Int(3),
    RetryDelay: 5 * time.Second,
})

// No retries — fail immediately on disconnect
ch, err := client.WatchCVMState(ctx, "my-app", &phala.WatchCVMStateOptions{
    Target:     "running",
    MaxRetries: phala.Int(0),
})

When retries are exhausted, the channel receives a final CVMStateEvent with Event: "error" and the underlying error in Error. An incomplete EOF produces a *WatchStreamError that unwraps to io.ErrUnexpectedEOF. A permanent HTTP failure produces a terminal *APIError without retrying.

The default watch client does not apply the ordinary 60-second total HTTP timeout. Explicit WithTimeout or WithHTTPClient settings still apply. Use a context deadline to limit total waiting time.

​

Wait for Deployment

A common pattern is to provision a CVM and then watch it until it reaches the "running" state:

// Provision and commit...
cvm, err := client.CommitCVMProvision(ctx, &phala.CommitCVMProvisionRequest{
    AppID:       provision.AppID,
    ComposeHash: provision.ComposeHash,
})
if err != nil {
    log.Fatal(err)
}

// Watch until running
watchCtx, cancel := context.WithTimeout(ctx, 10*time.Minute)
defer cancel()

ch, err := client.WatchCVMState(watchCtx, cvm.CvmID(), &phala.WatchCVMStateOptions{
    Target:     "running",
    Interval:   5,
    Timeout:    600,
    MaxRetries: phala.Int(5),
})
if err != nil {
    log.Fatal(err)
}

for event := range ch {
    switch event.Event {
    case "complete":
        fmt.Println("CVM is running!")
    case "error":
        log.Printf("Watch error: %v", event.Error)
    case "timeout":
        log.Println("Watch attempt timed out; retry may follow")
    default:
        fmt.Printf("State update: %v\n", event.Data)
    }
}

The Timeout option controls the server-side SSE stream timeout, not the overall watch duration. For long-running watches, set a generous server timeout and use the Go context for client-side control.