kubernetes

type ExecRequest struct {
	Namespace string
	PodName   string
	// ContainerName picks a container in the pod. Empty means the
	// pod's first container — matches `kubectl exec`'s default.
	ContainerName string
	// Cmd is the argv passed to the container. Caller is responsible
	// for shell wrapping.
	Cmd []string
	// User and WorkDir don't have a clean apiserver-exec equivalent
	// (kubectl exec doesn't take -u or --workdir), so they're
	// translated into a `cd <workdir>; exec setpriv ... or su -c
	// ...` shell wrapper. Empty values are no-ops.
	User    string
	WorkDir string
	// Env is layered on top of the container's environment for this
	// exec via a leading `env K=V K=V <cmd>`. Empty is a no-op.
	Env map[string]string
	// TTY allocates a pseudo-terminal.
	TTY bool
	// Stdin / Stdout / Stderr are forwarded to/from the exec session.
	// Any of them may be nil; nil stdin sends EOF immediately, nil
	// stdout/stderr captures into the returned ExecResult.
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
}

type ExecResult struct {
	// ExitCode is best-effort: the apiserver's exec stream surfaces
	// non-zero exits as a wrapped error rather than a structured
	// status, so a non-nil err from Exec means ExitCode is "unknown
	// non-zero". For matching docker semantics we return ExitCode = 1
	// in that case.
	ExitCode int
	Stdout   []byte
	Stderr   []byte
}

type ForwardedPort struct {
	Local  uint16
	Remote uint16
}

type Host struct {
	// contains filtered or unexported fields
}

type Options struct {
	// Logger receives informational messages. nil discards.
	Logger func(format string, args ...any)
	// Stdout / Stderr default to nil (silent). Lifecycle command output
	// is written to these unless the per-call request overrides.
	Stdout io.Writer
	Stderr io.Writer
	// Namespace is the default namespace for Up / Inspect / Delete /
	// Exec when the per-call request leaves it empty. Empty here means
	// "default".
	Namespace string
	// ReadyTimeout bounds Up's wait for the pod to reach Ready before
	// running lifecycle commands. Defaults to 5 minutes.
	ReadyTimeout time.Duration
	// DeleteGracePeriod bounds Delete's terminationGracePeriodSeconds
	// override. Defaults to the pod's own
	// TerminationGracePeriodSeconds (typically 30s).
	DeleteGracePeriod time.Duration
}

type PodInfo struct {
	Namespace     string
	Name          string
	UID           string
	NodeName      string
	Phase         corev1.PodPhase
	PodIP         string
	Ready         bool
	StartedAt     string
	CreatedAt     string
	Labels        map[string]string
	Annotations   map[string]string
	ContainerName string
	Image         string
}

type PortForwardRequest struct {
	Namespace string
	PodName   string
	// Ports is one or more "LOCAL:REMOTE" specs (e.g. "0:8080" lets
	// the kernel pick a local port for remote 8080). Same syntax as
	// kubectl port-forward.
	Ports []string
	// Addresses are the local interfaces to bind. Empty defaults to
	// ["localhost"] (matches kubectl's default).
	Addresses []string
	// Out / ErrOut receive port-forward's startup banners
	// ("Forwarding from 127.0.0.1:1234 -> 8080"). nil discards both.
	Out    io.Writer
	ErrOut io.Writer
	// Ready, when non-nil, is closed by the forwarder once it's
	// listening locally. Embedders that need to know when it's safe
	// to dial the local port should pass a channel and wait on it.
	Ready chan struct{}
}

type PortForwardSession struct {
	// LocalPorts is populated once the forwarder is Ready. Each entry
	// is "LOCAL:REMOTE" with the actual local port the kernel
	// assigned (useful for "0:N" specs).
	LocalPorts func() ([]ForwardedPort, error)
	// Stop tears the session down. Safe to call multiple times.
	Stop func()
	// Done is closed when the forwarder goroutine exits, either
	// because Stop was called or because of an unrecoverable error.
	Done <-chan error
}

type UpRequest struct {
	// Spec is the parsed devcontainer.json. Required.
	Spec *spec.DevContainer
	// SpecPath is the host-side path the spec was loaded from. Stored
	// in the AnnotationConfigFile annotation so downstream tooling
	// can reverse-look-up the source file.
	SpecPath string
	// LocalWorkspace is the host-side workspace folder (absolute).
	// Required: it's the discovery key (the LabelLocalFolderHash label
	// is sha256(LocalWorkspace)) and the default HostPath source for
	// the workspace volume.
	LocalWorkspace string
	// ContainerWorkspace is the path inside the container where the
	// workspace is mounted. When empty, falls back to spec
	// workspaceFolder, then "/workspaces/<basename>".
	ContainerWorkspace string
	// Image is the already-built image reference (use pkg/builder to
	// produce one).
	Image string
	// Features as resolved by pkg/features. Their containerEnv,
	// init/privileged/capAdd/securityOpt, and mounts merge into the
	// pod the same way pkg/projection/kubernetes merges them.
	Features []features.Resolved
	// LocalEnv is the host environment used for ${localEnv:VAR}
	// substitution. Pass an empty map (not nil) for no host env.
	LocalEnv map[string]string
	// IDLabels seeds ${devcontainerId} substitution. The
	// AnnotationLocalFolder + AnnotationConfigFile pair is always
	// included; supply additional entries here if you want them folded
	// into the id hash.
	IDLabels map[string]string

	// Namespace overrides Options.Namespace for this call. Empty falls
	// back to Options.Namespace, then "default".
	Namespace string
	// Name is the metadata.name written onto the projected Pod. Empty
	// is allowed: Up will fall back to "devcontainer-<localFolderHash>"
	// which is stable across reruns and matches the discovery key.
	Name string
	// ContainerName overrides the projected container's name. Empty
	// means pkg/projection/kubernetes.DefaultContainerName.
	ContainerName string
	// Labels and Annotations seed the projected Pod's metadata. The
	// host adds AnnotationLocalFolder, AnnotationConfigFile, and
	// LabelLocalFolderHash on top.
	Labels      map[string]string
	Annotations map[string]string
	// WorkspaceVolumeSource overrides the default HostPath workspace
	// volume. See pkg/projection/kubernetes.ProjectRequest.
	WorkspaceVolumeSource *corev1.VolumeSource
	// ReadyTimeout overrides Options.ReadyTimeout for this call.
	ReadyTimeout time.Duration
}

type UpResult struct {
	Namespace       string
	Name            string
	ContainerName   string
	UID             string
	CreatedThisCall bool
	// PhasesRun lists the lifecycle phases that actually ran (markers
	// may have skipped some).
	PhasesRun []lifecycle.Hook
}