network

type Allocation struct {
	NetworkID  string `yaml:"network_id"`
	InstanceID string `yaml:"instance_id"`
	IP         string `yaml:"ip"`
	MAC        string `yaml:"mac"`

	// InstanceName and TAPDevice are derived when the allocation is read
	// and not stored.
	InstanceName string `yaml:"-"`
	TAPDevice    string `yaml:"-"`
}

type AttachOptions struct {
	// StaticIP is the address the instance takes. Empty takes a free one.
	StaticIP string
	// Bandwidth limits what the instance's guest sends and receives.
	Bandwidth Bandwidth
	// Ports are the host ports forwarded to the instance's address.
	Ports []PortMapping
	// Disconnected keeps the instance's TAP device off the network's bridge
	// until ConnectInstance, so that nothing the guest sends reaches the
	// network. A fork needs this: it wakes with the address of the instance
	// it is a copy of.
	Disconnected bool
}

type Attachment struct {
	Allocation Allocation
	// TAPDevice is the host's end of the guest's network interface.
	TAPDevice string
	// Nameservers are the nameservers the guest asks: the gateway while the
	// network's DNS server runs, and its upstream nameservers otherwise.
	Nameservers []string
}

type Bandwidth struct {
	UploadBytesPerSecond   int64
	DownloadBytesPerSecond int64
}

type Config struct {
	// Dir is the directory the allocation tables are kept in.
	Dir string
	// Store keeps the network definitions. Creating, deleting and listing
	// networks need it, and allocating addresses does not.
	Store Store
	// Host sets up the networks' bridges and the instances' TAP devices
	// and published ports, and says which subnets a new network may not
	// overlap. Nil leaves the host alone and skips that check.
	Host Host
	// DNSServers serve each network's guests their nameserver. Nil serves
	// none.
	DNSServers DNSServers
	// Events records what happens to networks. Nil records nothing.
	Events Recorder
	// Logger is where the Manager logs. Nil is slog.Default().
	Logger *slog.Logger
}

type DNSServers interface {
	// Serve starts serving a network, unless it already is. The network's
	// bridge must be up.
	Serve(ctx context.Context, nw Network) error
	// Stop stops serving a network.
	Stop(network string)
	// Serving reports whether a network is served.
	Serving(network string) bool
}

type Host interface {
	// SetupBridge sets up a network's bridge, or makes sure it is as it
	// should be when it is already there.
	SetupBridge(ctx context.Context, nw *Network) error
	// TeardownBridge removes a network's bridge, logging what it cannot.
	TeardownBridge(ctx context.Context, nw *Network)
	// Subnets returns the subnets the host's interfaces are on, which a new
	// network may not overlap.
	Subnets() ([]netip.Prefix, error)

	// CreateTAP creates an instance's TAP device, limited to bandwidth and
	// off the network's bridge. On failure the device may be left behind
	// for RemoveTAP.
	CreateTAP(ctx context.Context, nw *Network, instanceID string, bandwidth Bandwidth) error
	// ConnectTAP puts an instance's TAP device on the network's bridge.
	ConnectTAP(ctx context.Context, nw *Network, instanceID string) error
	// RemoveTAP removes an instance's TAP device, logging what it cannot.
	RemoveTAP(ctx context.Context, nw *Network, instanceID string)

	// PublishPorts forwards host ports to the instance's address, replacing
	// any it already published.
	PublishPorts(ctx context.Context, nw *Network, allocation *Allocation, ports []PortMapping) error
	// UnpublishPorts removes every port the instance published, logging
	// what it cannot.
	UnpublishPorts(ctx context.Context, instanceID string)
}

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

type Network struct {
	ID          string   `yaml:"id"`
	Name        string   `yaml:"name"`
	Gateway     string   `yaml:"gateway"`
	Subnet      string   `yaml:"subnet"`
	Bridge      string   `yaml:"bridge"`
	Nameservers []string `yaml:"nameservers,omitempty"`
	MTU         int      `yaml:"mtu,omitempty"`
	Isolated    bool     `yaml:"isolated,omitempty"`
	// Internal stops the network's instances reaching anything beyond it:
	// the outside, other networks, the host's services and upstream
	// nameservers.
	Internal  bool      `yaml:"internal,omitempty"`
	CreatedAt time.Time `yaml:"created_at"`
	UpdatedAt time.Time `yaml:"updated_at"`

	// TotalIPs and FreeIPs count the addresses for instances. They are
	// computed when the network is read and not stored.
	TotalIPs int64 `yaml:"-"`
	FreeIPs  int64 `yaml:"-"`
}

type PortMapping struct {
	// HostIP is the host address to publish on. Empty means every
	// non-loopback address.
	HostIP    string `yaml:"host_ip,omitempty" json:"host_ip,omitempty"`
	HostPort  uint16 `yaml:"host_port" json:"host_port"`
	GuestPort uint16 `yaml:"guest_port" json:"guest_port"`

	// Protocol is tcp or udp. Empty means tcp.
	Protocol string `yaml:"protocol,omitempty" json:"protocol,omitempty"`
}

type Recorder interface {
	Record(e event.Event)
}

type Spec struct {
	Name        string
	Subnet      string
	Gateway     string
	MTU         int
	Nameservers []string
	Isolated    bool
	Internal    bool
}

type Store interface {
	CreateNetwork(n Network) error
	Network(nameOrID string) (Network, error)
	Networks() []Network
	// DeleteNetwork refuses a network an instance or snapshot is on.
	DeleteNetwork(nameOrID string) error
}