feat: add WaitContainerHealthy client method and health check utilities

pkg/api/client.go

@@ -21,11 +21,14 @@ type ContainerClient interface {
 	CreateContainer(
 		ctx context.Context, serviceID string, spec ServiceSpec, machineID string,
 	) (container.CreateResponse, error)
+	ExecContainer(ctx context.Context, serviceNameOrID, containerNameOrID string, config ExecOptions) (int, error)
 	InspectContainer(ctx context.Context, serviceNameOrID, containerNameOrID string) (MachineServiceContainer, error)
-	RemoveContainer(ctx context.Context, serviceNameOrID, containerNameOrID string, opts container.RemoveOptions) error
 	StartContainer(ctx context.Context, serviceNameOrID, containerNameOrID string) error
 	StopContainer(ctx context.Context, serviceNameOrID, containerNameOrID string, opts container.StopOptions) error
-	ExecContainer(ctx context.Context, serviceNameOrID, containerNameOrID string, config ExecOptions) (int, error)
+	RemoveContainer(ctx context.Context, serviceNameOrID, containerNameOrID string, opts container.RemoveOptions) error
+	WaitContainerHealthy(
+		ctx context.Context, serviceNameOrID, containerNameOrID string, opts WaitContainerHealthyOptions,
+	) error
 }
 
 type DNSClient interface {
@@ -57,3 +60,8 @@ type VolumeClient interface {
 	ListVolumes(ctx context.Context, filter *VolumeFilter) ([]MachineVolume, error)
 	RemoveVolume(ctx context.Context, machineNameOrID, volumeName string, force bool) error
 }
+
+// AsPtr returns a pointer to the given value. Useful for optional fields in API structs.
+func AsPtr[T any](v T) *T {
+	return &v
+}

pkg/api/container.go

@@ -3,7 +3,10 @@ package api
 import (
 	"encoding/json"
 	"fmt"
+	"io"
 	"net/netip"
+	"os"
+	"strconv"
 	"strings"
 	"time"
 
@@ -41,6 +44,19 @@ func (c *Container) CreatedTime() time.Time {
 	return c.created
 }
 
+// HasHealthcheck returns true if the container has a health check configured.
+func (c *Container) HasHealthcheck() bool {
+	hc := c.Config.Healthcheck
+	if hc == nil {
+		return false
+	}
+
+	if len(hc.Test) > 0 && hc.Test[0] == "NONE" {
+		return false
+	}
+	return true
+}
+
 // Healthy determines if the container is running and healthy.
 // A running container with no health check configured is considered healthy.
 func (c *Container) Healthy() bool {
@@ -244,3 +260,60 @@ func (c *ServiceContainer) UnmarshalJSON(data []byte) error {
 
 	return nil
 }
+
+// DefaultHealthMonitorPeriod is the default duration to wait before checking that the container is still running
+// and not restarting. Can be overridden with the UNCLOUD_DEFAULT_HEALTH_MONITOR_PERIOD_MS environment variable.
+var DefaultHealthMonitorPeriod = defaultHealthMonitorPeriod()
+
+func defaultHealthMonitorPeriod() time.Duration {
+	if v, ok := os.LookupEnv("UNCLOUD_DEFAULT_HEALTH_MONITOR_PERIOD_MS"); ok {
+		if ms, err := strconv.Atoi(v); err == nil {
+			return time.Duration(ms) * time.Millisecond
+		}
+	}
+
+	return 5 * time.Second
+}
+
+// WaitContainerHealthyOptions configures the behaviour of WaitContainerHealthy.
+type WaitContainerHealthyOptions struct {
+	// MonitorPeriod is how long to wait before checking that the container is still running and not restarting.
+	// Containers with a health check that become healthy before the period ends succeed early.
+	// nil means use the default DefaultHealthMonitorPeriod.
+	// Zero skips the monitoring and checks the container's health immediately after starting.
+	MonitorPeriod *time.Duration
+}
+
+// ExecOptions contains configuration for executing a command in a container.
+type ExecOptions struct {
+	// Command is the command to run in the container.
+	Command []string
+	// AttachStdin attaches the stdin stream to the exec session.
+	AttachStdin bool
+	// AttachStdout attaches the stdout stream to the exec session.
+	AttachStdout bool
+	// AttachStderr attaches the stderr stream to the exec session.
+	AttachStderr bool
+	// Tty allocates a pseudo-TTY for the exec session.
+	Tty bool
+	// Detach runs the command in the background without attaching to streams.
+	Detach bool
+
+	//// Not yet implemented fields
+	// User specifies the user to run the command as.
+	User string
+	// Privileged runs the command in privileged mode.
+	Privileged bool
+	// WorkingDir sets the working directory for the command.
+	WorkingDir string
+	// Env sets environment variables for the command.
+	Env []string
+
+	// Client-side only fields (not serialized, not sent to server)
+	// Stdin is the input stream. Defaults to os.Stdin if nil.
+	Stdin io.Reader `json:"-"`
+	// Stdout is the output stream. Defaults to os.Stdout if nil.
+	Stdout io.Writer `json:"-"`
+	// Stderr is the error stream. Defaults to os.Stderr if nil.
+	Stderr io.Writer `json:"-"`
+}

pkg/api/container_exec.go

@@ -1,37 +0,0 @@
-package api
-
-import "io"
-
-// ExecOptions contains configuration for executing a command in a container.
-type ExecOptions struct {
-	// Command is the command to run in the container.
-	Command []string
-	// AttachStdin attaches the stdin stream to the exec session.
-	AttachStdin bool
-	// AttachStdout attaches the stdout stream to the exec session.
-	AttachStdout bool
-	// AttachStderr attaches the stderr stream to the exec session.
-	AttachStderr bool
-	// Tty allocates a pseudo-TTY for the exec session.
-	Tty bool
-	// Detach runs the command in the background without attaching to streams.
-	Detach bool
-
-	//// Not yet implemented fields
-	// User specifies the user to run the command as.
-	User string
-	// Privileged runs the command in privileged mode.
-	Privileged bool
-	// WorkingDir sets the working directory for the command.
-	WorkingDir string
-	// Env sets environment variables for the command.
-	Env []string
-
-	// Client-side only fields (not serialized, not sent to server)
-	// Stdin is the input stream. Defaults to os.Stdin if nil.
-	Stdin io.Reader `json:"-"`
-	// Stdout is the output stream. Defaults to os.Stdout if nil.
-	Stdout io.Writer `json:"-"`
-	// Stderr is the error stream. Defaults to os.Stderr if nil.
-	Stderr io.Writer `json:"-"`
-}

pkg/api/container_health.go

@@ -1,11 +0,0 @@
-package api
-
-import "time"
-
-const (
-	// defaultDockerHealthcheckInterval is the default Docker interval between health check runs.
-	defaultDockerHealthcheckInterval = 30 * time.Second
-	// defaultDockerHealthcheckRetries is the default Docker number of consecutive failures needed
-	// to consider the container unhealthy.
-	defaultDockerHealthcheckRetries = 3
-)