labruntime

type AttachRequest struct {
	// Name is the lab name.
	Name      string
	Namespace string
	// NodeName is the node to attach to, as the topology or the runtime names it.
	NodeName string
	// Container overrides the node's primary device container.
	Container string
	// Command runs in the container; empty runs "sh".
	Command []string
	// TTY allocates a terminal. Stdout then carries the combined output, and Resize applies.
	TTY      bool
	Identity Identity
}

type AttachStreams struct {
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
	// Resize delivers terminal size changes of a TTY session; closing it stops resizing.
	Resize <-chan TerminalSize
}

type CaptureGap struct {
	Node       string
	Interfaces []string
	// From and To bound the gap on the node's clock; To is zero when it is unknown.
	From   time.Time
	To     time.Time
	Reason string
}

type CaptureInterface struct {
	// Node is the node name as the topology spells it.
	Node string `json:"node"`
	// Interface is the interface name inside the node, which capture output carries.
	Interface string `json:"interface"`
	// Alias is the name the topology used for the interface when the node kind maps it (for
	// example ethernet-1/1 for SR Linux e1-1). Capture targets accept either name.
	Alias string `json:"alias,omitempty"`
	// PeerNode is the node at the other end of the link, "host" for a host endpoint, or empty
	// when the runtime cannot name it.
	PeerNode string `json:"peer_node"`
	// PeerInterface is the peer's interface as the topology wrote it.
	PeerInterface string `json:"peer_interface"`
}

type CaptureRequest struct {
	// Name is the lab name.
	Name      string
	Namespace string
	Targets   []CaptureTarget
	// Duration ends the capture; zero captures until the context ends.
	Duration time.Duration
	// PacketLimit ends the capture after that many packets across all targets; zero means no
	// limit.
	PacketLimit int
	// SnapLength is the number of bytes kept of each packet; zero uses the runtime default.
	SnapLength int
	// OnGap is called when the capture missed traffic, for example because a chained capture
	// did not start in time. Without it, gaps are logged as warnings.
	OnGap    func(CaptureGap)
	Identity Identity
}

type CaptureTarget struct {
	Node      string
	Interface string
}

type ChangeAction string

type CommandExitError struct {
	Code int
}

type Config struct {
	Timeout   time.Duration
	Namespace string
	// Identity is the identity of every call that does not set its own.
	Identity Identity

	// 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
	// Identity overrides the runtime's configured identity for this call.
	Identity Identity
}

type DestroyRequest struct {
	Name       string
	Namespace  string
	Wait       bool
	Timeout    time.Duration
	MaxWorkers uint
	// Cleanup also deletes the lab's persistent node storage (saved configuration). Without
	// it the storage is kept, like the lab directory of a local runtime, and a later deploy
	// of the lab boots from it.
	Cleanup bool
	// Identity overrides the runtime's configured identity for this call.
	Identity Identity
}

type Event struct {
	Timestamp   time.Time
	Type        string
	Action      string
	ActorID     string
	ActorName   string
	ActorFullID string
	// Attributes are the runtime's own attributes. Event consumers add the attributes the
	// container runtimes report from Lab, Node and Interface.
	Attributes map[string]string
	// Lab and Node are the lab node a container or interface event is about, as Inspect
	// reports it. containerlab's events command describes the node from them the same way
	// inspect does, so both agree and match what the container runtimes report.
	Lab  *LabState
	Node *NodeState
	// Interface is the interface an interface event reports.
	Interface *InterfaceEventData
}

type EventStreamRequest struct {
	Name                  string
	Namespace             string
	AllNamespaces         bool
	IncludeInitialState   bool
	IncludeInterfaceStats bool
	StatsInterval         time.Duration
	// Identity overrides the runtime's configured identity for this call.
	Identity Identity
}

type ExecRequest struct {
	Name      string
	Namespace string
	NodeName  string
	Command   []string
	// Identity overrides the runtime's configured identity for this call.
	Identity Identity
}

type ExposedPort = clabtypes.ExposedPort

type Identity struct {
	User   string
	Groups []string
}

type Initializer func(Config) (LabRuntime, error)

type InspectRequest struct {
	Name      string
	Namespace string
	// Identity overrides the runtime's configured identity for this call.
	Identity Identity
}

type InterfaceEventData struct {
	// Name is the interface name inside the node.
	Name string
	// Alias is the name the topology gave the interface when the node kind maps it (for
	// example ethernet-1/1 for SR Linux e1-1).
	Alias string
	Index int
	MTU   int
	MAC   string
	// OperState is the operational state in netlink's vocabulary: up, down, lower-layer-down,
	// dormant, testing, not-present or unknown.
	OperState string
	// Type is the link type in netlink's vocabulary, such as veth or device (loopback).
	Type string
	// Stats are set on stats events.
	Stats *InterfaceStats
}

type InterfaceInspector interface {
	InspectInterfaces(
		ctx context.Context,
		req NodeRequest,
	) ([]*clabtypes.ContainerInterfaces, error)
}

type InterfaceStats struct {
	RxBytes   uint64
	TxBytes   uint64
	RxPackets uint64
	TxPackets uint64
	RxBps     float64
	TxBps     float64
	RxPps     float64
	TxPps     float64
	Interval  time.Duration
}

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 is the absolute path of the topology file the lab was deployed from, on the
	// machine that deployed it. A lab the runtime did not deploy from a file reports where the
	// runtime keeps its definition instead (for c9s k8s://<namespace>/topologies/<lab>).
	TopologyPath string
	State        string
	Ready        bool
	Nodes        []NodeState
}

type ListRequest struct {
	Namespace     string
	AllNamespaces bool
	// Identity overrides the runtime's configured identity for this call.
	Identity Identity
}

type LogRequest struct {
	// Name is the lab name.
	Name      string
	Namespace string
	// NodeName is the node whose log is streamed, as the topology or the runtime names it.
	NodeName string
	// Container overrides the node's primary device container.
	Container string
	// Tail limits the output to the last lines of the log; nil writes the whole log.
	Tail *int64
	// Follow keeps streaming new log lines until the context ends.
	Follow bool
	// Timestamps prefixes every line with its timestamp.
	Timestamps bool
	Identity   Identity
}

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 NodeAttacher interface {
	Attach(ctx context.Context, req AttachRequest, streams AttachStreams) error
}

type NodeLocation struct {
	// NodeName is the node name the runtime carries (the sanitized name).
	NodeName  string
	Namespace string
	Pod       string
	// Container is the node's primary device container in Pod.
	Container string
	// NodeUID identifies the runtime's node resource (the clabernetes Node UID).
	NodeUID string
	// ExposedPorts are the node ports the runtime publishes through a Service.
	ExposedPorts        []ExposedPort
	LoadBalancerAddress string
}

type NodeLocator interface {
	LocateNode(ctx context.Context, req NodeRequest) ([]NodeLocation, error)
}

type NodeLogStreamer interface {
	StreamLogs(ctx context.Context, req LogRequest, w io.Writer) error
}

type NodePortForwarder interface {
	DialPort(ctx context.Context, req NodeRequest, port int) (net.Conn, error)
}

type NodeRequest struct {
	Name      string
	Namespace string
	Nodes     []string
	Timeout   time.Duration
	// Identity overrides the runtime's configured identity for this call.
	Identity Identity
}

type NodeState struct {
	Name string
	// TopologyName is the node name as the topology file spells it, when the runtime had to
	// carry the node under another name (Name). Empty means Name.
	TopologyName string
	Kind         string
	Image        string
	// Type and Group are the node's type and group when the topology set them.
	Type  string
	Group string
	// State is the runtime's own view of the node, such as the clabernetes Node readiness, or
	// stopped.
	State string
	Ready bool
	// ContainerState is the node's state in container runtime terms: created, running or
	// exited (the ContainerState* constants). Empty when the runtime does not report one.
	ContainerState string
	// Health is the device health of a running node in container runtime terms: healthy or
	// starting. Empty when the node does not run.
	Health string
	// MgmtIPv4Address and MgmtIPv6Address are the node's allocated management addresses in
	// CIDR notation, when the runtime reports them.
	MgmtIPv4Address     string
	MgmtIPv6Address     string
	LoadBalancerAddress string
	// Pod is the pod that runs the node. Nodes that share a network namespace share a pod.
	Pod string
	// Container is the node's primary device container in Pod.
	Container string
	// NodeUID identifies the runtime's node resource (the clabernetes Node UID).
	NodeUID string
	// ExposedPorts are the node ports the runtime publishes through a Service.
	ExposedPorts []ExposedPort
}

type NodeStats struct {
	NodeName  string
	Namespace string
	Pod       string
	// CPUMilliCores is the CPU usage of the node's device containers, in thousandths of a core.
	CPUMilliCores int64
	// MemoryBytes is the memory working set of the node's device containers.
	MemoryBytes int64
	// Timestamp and Window describe the sampling interval the usage was measured over.
	Timestamp time.Time
	Window    time.Duration
}

type NodeStatsSampler interface {
	SampleStats(ctx context.Context, req InspectRequest) ([]NodeStats, error)
}

type PacketCapturer interface {
	CaptureInterfaces(ctx context.Context, req NodeRequest) ([]CaptureInterface, error)
	Capture(ctx context.Context, req CaptureRequest, w io.Writer) error
}

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
	// Identity overrides the runtime's configured identity for this call.
	Identity Identity
}

type SaveResult struct {
	Files []SavedFile
}

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

type SupportChecker interface {
	CheckSupport(ctx context.Context, identity Identity) error
}

type TerminalSize struct {
	Width  uint16
	Height uint16
}

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

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