api

type BindOptions struct {
	// HostPath is the absolute path on the host filesystem.
	HostPath string
	// CreateHostPath indicates whether the host path should be created if it doesn't exist.
	// If false, deployment will fail if the path doesn't exist.
	CreateHostPath bool              `json:",omitempty"`
	Propagation    mount.Propagation `json:",omitempty"`
	Recursive      string            `json:",omitempty"`
}

type CaddySpec struct {
	// Config contains the Caddy config (Caddyfile) content. It must not conflict with the Caddy configs
	// of other services.
	Config string
}

type Client interface {
	ContainerClient
	DNSClient
	ImageClient
	MachineClient
	ServiceClient
	VolumeClient
}

type ConfigMount struct {
	// ConfigName references a config defined in ServiceSpec.Configs by its Name field
	ConfigName string
	// ContainerPath is the absolute path where the config is mounted in the container
	ContainerPath string `json:",omitempty"`
	// Uid for the mounted config file
	Uid string `json:",omitempty"`
	// Gid for the mounted config file
	Gid string `json:",omitempty"`
	// Mode (file permissions) for the mounted config file
	Mode *os.FileMode `json:",omitempty"`
}

type ConfigSpec struct {
	Name string

	// Content of the config when specified inline
	Content []byte `json:",omitempty"`
}

type Container struct {
	container.InspectResponse
	// contains filtered or unexported fields
}

type ContainerClient interface {
	CreateContainer(
		ctx context.Context, serviceID string, spec ServiceSpec, machineID string,
	) (container.CreateResponse, 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)
}

type ContainerLogEntry struct {
	Stream    LogStreamType
	Timestamp time.Time
	Message   []byte
	// Err indicates that an error occurred while streaming logs from a container.
	// Other fields are not set if Err is not nil.
	Err error
}

type ContainerResources struct {
	// CPU is the maximum amount of CPU nanocores (1000000000 = 1 CPU core) the container can use.
	CPU int64
	// Memory is the maximum amount of memory (in bytes) the container can use.
	Memory int64
	// MemoryReservation is the minimum amount of memory (in bytes) the container needs to run efficiently.
	// TODO: implement a placement constraint that checks available memory on machines.
	MemoryReservation int64
	// Device reservations/requests for access to things like GPUs
	DeviceReservations []container.DeviceRequest
}

type ContainerSpec struct {
	// Command overrides the default CMD of the image to be executed when running a container.
	Command []string
	// Entrypoint overrides the default ENTRYPOINT of the image.
	Entrypoint []string
	// Env defines the environment variables to set inside the container.
	Env   EnvVars
	Image string
	// Run a custom init inside the container. If nil, use the daemon's configured settings.
	Init *bool
	// LogDriver overrides the default logging driver for the container. Each Docker daemon can have its own default.
	LogDriver *LogDriver
	// Privileged gives extended privileges to the container. This is a security risk and should be used with caution.
	Privileged bool
	// PullPolicy determines when to pull the image from the registry or use the image already available in the cluster.
	// Default is PullPolicyMissing if empty.
	PullPolicy string
	// Resource allocation for the container.
	Resources ContainerResources
	// User overrides the default user of the image used to run the container. Format: user|UID[:group|GID].
	User string
	// VolumeMounts specifies how volumes are mounted into the container filesystem.
	// Each mount references a volume defined in ServiceSpec.Volumes.
	VolumeMounts []VolumeMount
	// ConfigMounts specifies how configs are mounted into the container filesystem.
	// Each mount references a config defined in ServiceSpec.Configs.
	ConfigMounts []ConfigMount
	// Volumes is list of data volumes to mount into the container.
	// TODO(lhf): delete all usage, has been replaced with []VolumeMounts.
	Volumes []string
}

type DNSClient interface {
	GetDomain(ctx context.Context) (string, error)
}

type EnvVars map[string]string

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:"-"`
}

type ImageClient interface {
	InspectImage(ctx context.Context, id string) ([]MachineImage, error)
	InspectRemoteImage(ctx context.Context, id string) ([]MachineRemoteImage, error)
}

type ImageFilter struct {
	// Machines filters images to those present on the specified machines (names or IDs).
	// If empty, it matches images on all machines.
	Machines []string
	// Name filters images by name (with or without tag). Accepts a wildcard pattern.
	// If empty, it matches all image names.
	Name string
}

type LogDriver struct {
	// Name of the logging driver to use.
	Name string
	// Options is the configuration options to pass to the logging driver.
	Options map[string]string
}

type LogStreamType int

type MachineClient interface {
	InspectMachine(ctx context.Context, id string) (*pb.MachineMember, error)
	ListMachines(ctx context.Context, filter *MachineFilter) (MachineMembersList, error)
	UpdateMachine(ctx context.Context, req *pb.UpdateMachineRequest) (*pb.MachineInfo, error)
	RenameMachine(ctx context.Context, nameOrID, newName string) (*pb.MachineInfo, error)
}

type MachineFilter struct {
	// Available filters machines that are not DOWN.
	Available bool
	// NamesOrIDs filters machines by their names or IDs.
	NamesOrIDs []string
}

type MachineImage struct {
	Metadata *pb.Metadata
	Image    image.InspectResponse
}

type MachineImages struct {
	Metadata *pb.Metadata
	// Images is a list of images present on the machine.
	Images []image.Summary
	// ContainerdStore indicates whether Docker on the machine uses the containerd image store
	// (containerd-snapshotter feature).
	ContainerdStore bool
}

type MachineMembersList []*pb.MachineMember

type MachineRemoteImage struct {
	Metadata *pb.Metadata
	Image    RemoteImage
}

type MachineServiceContainer struct {
	MachineID string
	Container ServiceContainer
}

type MachineVolume struct {
	// MachineID is the ID of the machine where the volume exists.
	MachineID string
	// MachineName is the name of the machine where the volume exists.
	MachineName string
	// Volume is the Docker volume model.
	Volume volume.Volume
}

type Placement struct {
	// Machines is a list of machine names or IDs where service containers are allowed to be deployed.
	// If empty, containers can be deployed to any available machine in the cluster.
	Machines []string `json:",omitempty"`
}

type PortSpec struct {
	// Hostname specifies the DNS name that will route to this service. Only valid in ingress mode.
	Hostname string
	// HostIP is the host IP to bind the PublishedPort to. Only valid in host mode.
	HostIP netip.Addr
	// PublishedPort is the port number exposed outside the container.
	// In ingress mode, this is the load balancer port. In host mode, this is the port bound on the host.
	PublishedPort uint16
	// ContainerPort is the port inside the container that the service listens on.
	ContainerPort uint16
	// Protocol specifies the network protocol.
	Protocol string
	// Mode specifies how the port is published.
	Mode string
}

type RemoteImage struct {
	Reference     reference.Canonical
	IndexManifest *v1.Index
	ImageManifest *v1.Manifest
}

type RunServiceResponse struct {
	ID   string
	Name string
}

type Service struct {
	ID         string
	Name       string
	Mode       string
	Containers []MachineServiceContainer
}

type ServiceClient interface {
	RunService(ctx context.Context, spec ServiceSpec) (RunServiceResponse, error)
	InspectService(ctx context.Context, id string) (Service, error)
	RemoveService(ctx context.Context, id string) error
	StopService(ctx context.Context, id string, opts container.StopOptions) error
	StartService(ctx context.Context, id string) error
}

type ServiceContainer struct {
	Container
	ServiceSpec ServiceSpec
}

type ServiceLogEntry struct {
	// Metadata may not be set if an error occurred (Err is not nil).
	Metadata ServiceLogEntryMetadata
	ContainerLogEntry
}

type ServiceLogEntryMetadata struct {
	ServiceID   string
	ServiceName string
	ContainerID string
	MachineID   string
	MachineName string
}

type ServiceLogsOptions struct {
	Follow bool
	Tail   int
	Since  string
	Until  string
	// Machines filters logs to only include containers running on the specified machines (names or IDs).
	// If empty, logs from all machines are included.
	Machines []string
}

type ServiceSpec struct {
	// Caddy is the optional Caddy reverse proxy configuration for the service.
	// Caddy and Ports cannot be specified simultaneously.
	Caddy *CaddySpec `json:",omitempty"`
	// Container defines the desired state of each container in the service.
	Container ContainerSpec
	// Mode is the replication mode of the service. Default is ServiceModeReplicated if empty.
	Mode string
	Name string
	// Placement defines the placement constraints for the service.
	Placement Placement
	// Ports defines what service ports to publish to make the service accessible outside the cluster.
	// Caddy and Ports cannot be specified simultaneously.
	Ports []PortSpec
	// Replicas is the number of containers to run for the service. Only valid for a replicated service.
	Replicas uint `json:",omitempty"`
	// Volumes is list of data volumes that can be mounted into the container.
	Volumes []VolumeSpec
	// Configs is list of configuration objects that can be mounted into the container.
	Configs []ConfigSpec
}

type VolumeClient interface {
	CreateVolume(ctx context.Context, machineNameOrID string, opts volume.CreateOptions) (MachineVolume, error)
	ListVolumes(ctx context.Context, filter *VolumeFilter) ([]MachineVolume, error)
	RemoveVolume(ctx context.Context, machineNameOrID, volumeName string, force bool) error
}

type VolumeFilter struct {
	// Driver filters volumes by storage driver name.
	Driver string
	// Labels filters volumes by label key-value pairs. Volumes must match all labels.
	Labels map[string]string
	// Machines filters volumes to those on the specified machines (names or IDs).
	Machines []string
	// Names filters volumes by name. Volumes must match one of the names.
	Names []string
}

type VolumeMount struct {
	// VolumeName references a volume defined in ServiceSpec.Volumes by its Name field.
	VolumeName string
	// ContainerPath is the absolute path where the volume is mounted in the container.
	ContainerPath string
	// ReadOnly indicates whether the volume should be mounted read-only.
	// If false (default), the volume is mounted read-write.
	ReadOnly bool `json:",omitempty"`
}

type VolumeOptions struct {
	// Driver specifies the volume driver and its options for volume creation.
	// TODO: It seems we don't really need Driver and Labels if we only support externally managed volumes.
	//  However we may need them in the future if we add support for isolated container-scoped volumes.
	Driver *mount.Driver `json:",omitempty"`
	// Labels are key-value metadata to apply to the volume if creating a new volume.
	Labels map[string]string `json:",omitempty"`
	// Name of the named Docker volume to use. If not specified, defaults to the VolumeSpec.Name.
	Name string `json:",omitempty"`
	// NoCopy prevents automatic copying of data from the container mount path to the volume.
	NoCopy bool `json:",omitempty"`
	// SubPath is the path within the volume to mount instead of its root.
	SubPath string `json:",omitempty"`
}

type VolumeSpec struct {
	// Name is the volume name used to reference this volume in container mounts.
	Name          string
	Type          string
	BindOptions   *BindOptions        `json:",omitempty"`
	TmpfsOptions  *mount.TmpfsOptions `json:",omitempty"`
	VolumeOptions *VolumeOptions      `json:",omitempty"`
}