labruntime

type ChangeAction string

type Config struct {
	Timeout   time.Duration
	Namespace string

	// KindLinkApplyMode resolves the default link apply mode ("live", "restart" or
	// "recreate") a node kind declares, as containerlab's node registry reports it. An
	// empty result means the kind is unknown and the conservative recreate default
	// applies. Lab runtimes use it to predict the node lifecycle impact of link changes.
	KindLinkApplyMode func(kind string) string
}

type DeployPlan struct {
	LabName   string           `json:"lab-name"`
	Namespace string           `json:"namespace"`
	Changes   []ResourceChange `json:"changes"`
}

type DeployRequest struct {
	Name               string
	Namespace          string
	Owner              string
	TopologyFile       string
	TopologyLabDir     string
	TopologyDefinition []byte
	Wait               bool
	Timeout            time.Duration
	// MaxWorkers limits concurrent independent operations performed by the runtime.
	MaxWorkers uint
	// NoTopologyCR deploys without a controller-owned topology object: the runtime compiles the
	// topology client-side and manages the individual lab resources directly.
	NoTopologyCR bool
	// ImagePullSecret names the same-namespace Docker-config Secret placed on device pods
	// through Pod.spec.imagePullSecrets. Empty means the lab references no pull secret at
	// all: public images and clusters whose runtime already holds credentials need none.
	ImagePullSecret string
	// ExposeType controls the Kubernetes Service type c9s creates for lab nodes. Empty uses the
	// c9s CRD default.
	ExposeType string
	// NoPersistence deploys the lab on ephemeral node storage. By default every node's
	// artifact volume is backed by a persistent claim so saved device configuration survives
	// Pod replacement, matching the local-runtime lab directory contract; opting out trades
	// that for not needing a dynamically provisionable storage class, and every Pod
	// replacement then resets the node to its declared configuration.
	NoPersistence bool
}

type DestroyRequest struct {
	Name       string
	Namespace  string
	Wait       bool
	Timeout    time.Duration
	MaxWorkers uint
}

type Event struct {
	Timestamp   time.Time
	Type        string
	Action      string
	ActorID     string
	ActorName   string
	ActorFullID string
	Attributes  map[string]string
}

type EventStreamRequest struct {
	Namespace             string
	AllNamespaces         bool
	IncludeInitialState   bool
	IncludeInterfaceStats bool
	StatsInterval         time.Duration
}

type ExecRequest struct {
	Name      string
	Namespace string
	NodeName  string
	Command   []string
}

type Initializer func(Config) (LabRuntime, error)

type InspectRequest struct {
	Name      string
	Namespace string
}

type LabExistenceChecker interface {
	LabExists(context.Context, InspectRequest) (bool, error)
}

type LabRuntime interface {
	Deploy(context.Context, DeployRequest) (*LabState, error)
	Destroy(context.Context, DestroyRequest) error
	Inspect(context.Context, InspectRequest) (*LabState, error)
	List(context.Context, ListRequest) ([]*LabState, error)
	Exec(context.Context, ExecRequest) (*clabexec.ExecResult, error)
	Start(context.Context, NodeRequest) error
	Stop(context.Context, NodeRequest) error
	Restart(context.Context, NodeRequest) error
	Save(context.Context, SaveRequest) (*SaveResult, error)
	StreamEvents(context.Context, EventStreamRequest) (<-chan Event, <-chan error, error)
}

type LabState struct {
	Name         string
	Namespace    string
	Owner        string
	TopologyPath string
	State        string
	Ready        bool
	Nodes        []NodeState
}

type ListRequest struct {
	Namespace     string
	AllNamespaces bool
}

type Manifest struct {
	APIVersion string
	Kind       string
	Namespace  string
	Name       string
	Object     map[string]any
}

type ManifestEmitter interface {
	Manifests(context.Context, DeployRequest) ([]Manifest, error)
}

type NodeRequest struct {
	Name      string
	Namespace string
	Nodes     []string
	Timeout   time.Duration
}

type NodeState struct {
	Name  string
	Kind  string
	Image string
	State string
	Ready bool
	// MgmtIPv4Address and MgmtIPv6Address are the node's allocated management addresses in
	// CIDR notation, when the runtime reports them.
	MgmtIPv4Address     string
	MgmtIPv6Address     string
	LoadBalancerAddress string
}

type ResourceChange struct {
	Action    ChangeAction `json:"action"`
	Kind      string       `json:"kind"`
	Namespace string       `json:"namespace,omitempty"`
	Name      string       `json:"name"`
}

type SaveRequest struct {
	Name      string
	Namespace string
	Nodes     []string
	Copy      bool
}

type SaveResult struct {
	Files []SavedFile
}

type SavedFile struct {
	NodeName   string
	Name       string
	Data       []byte
	Mode       int64
	LinkTarget string
}

type TopologyPlanner interface {
	Plan(context.Context, DeployRequest) (*DeployPlan, error)
}

type TopologyValidator interface {
	Validate(context.Context, DeployRequest) error
}