ipam

type AllocationResult struct {
	// IP is the allocated IP
	IP netip.Addr

	// IPPoolName is the IPAM pool from which the above IP was allocated from
	IPPoolName Pool

	// CIDRs is a list of all CIDRs to which the IP has direct access to.
	// This is primarily useful if the IP has been allocated out of a VPC
	// subnet range and the VPC provides routing to a set of CIDRs in which
	// the IP is routable.
	CIDRs []netip.Prefix

	// PrimaryMAC is the MAC address of the primary interface. This is useful
	// when the IP is a secondary address of an interface which is
	// represented on the node as a Linux device and all routing of the IP
	// must occur through that master interface. It is unset for the IPAM
	// modes which have no master interface.
	PrimaryMAC mac.MAC

	// GatewayIP is the IP of the gateway which must be used for this IP.
	// If the allocated IP is derived from a VPC, then the gateway
	// represented the gateway of the VPC or VPC subnet.
	GatewayIP netip.Addr

	// ExpirationUUID is the UUID of the expiration timer. This field is
	// only set if AllocateNextWithExpiration is used.
	ExpirationUUID string

	// InterfaceNumber is a field for generically identifying an interface.
	// This is only useful in ENI mode.
	InterfaceNumber string

	// SkipMasquerade indicates whether the datapath should avoid masquerading connections from this IP when the cluster is in tunneling mode.
	SkipMasquerade bool
}

type Allocator interface {
	// Allocate allocates a specific IP or fails
	Allocate(addr netip.Addr, owner string, pool Pool) (*AllocationResult, error)

	// AllocateWithoutSyncUpstream allocates a specific IP without syncing
	// upstream or fails
	AllocateWithoutSyncUpstream(addr netip.Addr, owner string, pool Pool) (*AllocationResult, error)

	// Release releases a previously allocated IP or fails
	Release(addr netip.Addr, pool Pool) error

	// AllocateNext allocates the next available IP or fails if no more IPs
	// are available
	AllocateNext(owner string, pool Pool) (*AllocationResult, error)

	// AllocateNextWithoutSyncUpstream allocates the next available IP without syncing
	// upstream or fails if no more IPs are available
	AllocateNextWithoutSyncUpstream(owner string, pool Pool) (*AllocationResult, error)

	// Dump returns a map of all allocated IPs per pool with the IP represented as key in the
	// map. Dump must also provide a status one-liner to represent the overall status, e.g.
	// number of IPs allocated and overall health information if available.
	Dump() (map[Pool]map[string]string, string)

	// Capacity returns the total IPAM allocator capacity (not the current
	// available).
	Capacity() uint64

	// RestoreFinished marks the status of restoration as done
	RestoreFinished()
}

type CloudProvider interface {
	// Mode returns the IPAM mode this provider handles.
	Mode() string

	// PoolSpecAccessors returns how allocated CIDRs are read from and written
	// back to the CiliumNode for this cloud.
	PoolSpecAccessors() PoolSpecAccessors

	// Initialize performs the cloud-specific startup work that must not block:
	// registering the provider's CiliumNode observers and whatever jobs it needs
	// to configure the node. It is called once, before the multi-pool manager is
	// constructed, and returns the resolver the allocators enrich their results
	// with.
	Initialize() (RoutingMetadataResolver, error)

	// WaitReady blocks until the state the jobs registered by Initialize set in
	// motion has converged and the agent is allowed to serve allocations. A
	// provider with nothing to converge on returns nil immediately.
	//
	// It returns an error if ctx is cancelled first.
	WaitReady(ctx context.Context) error
}

type CloudProviderOut struct {
	cell.Out

	Provider CloudProvider `group:"ipam-cloud-providers"`
}

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

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

type Family string

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

type K8sEventRegister interface {
	// K8sEventReceived is called to do metrics accounting for received
	// Kubernetes events, as well as calculating timeouts for k8s watcher
	// cache sync.
	K8sEventReceived(apiGroupResourceName string, scope string, action string, valid, equal bool)

	// K8sEventProcessed is called to do metrics accounting for each processed
	// Kubernetes event.
	K8sEventProcessed(scope string, action string, status bool)
}

type Metadata interface {
	GetIPPoolForPod(owner string, family Family) (pool string, err error)
}

type MtuConfiguration interface {
	GetDeviceMTU() int
}

type MultiPoolAllocatorParams struct {
	Logger *slog.Logger

	IPv4Enabled          bool
	IPv6Enabled          bool
	CiliumNodeUpdateRate time.Duration
	PreAllocPools        map[string]string

	Node           agentK8s.LocalCiliumNodeResource
	LocalNodeStore *node.LocalNodeStore
	CNClient       cilium_v2.CiliumNodeInterface
	JobGroup       job.Group

	DB                        *statedb.DB
	PodIPPools                statedb.Table[podippool.LocalPodIPPool]
	OnlyMasqueradeDefaultPool bool
}

type MultiPoolManagerParams struct {
	Logger *slog.Logger

	IPv4Enabled          bool
	IPv6Enabled          bool
	CiliumNodeUpdateRate time.Duration
	PreallocMap          preAllocatePerPool

	Node     agentK8s.LocalCiliumNodeResource
	CNClient cilium_v2.CiliumNodeInterface
	JobGroup job.Group

	PoolSpecAccessors PoolSpecAccessors

	SkipMasqueradeForPool SkipMasqueradeForPoolFn

	// LinearPreAlloc uses a simple inUse + preAlloc formula for demand
	// computation instead of the multi-pool's neededIPCeil rounding. This
	// matches the CRD allocator's calculateNeededIPs behavior and allows
	// the operator to recover exact usage from the demand signal.
	LinearPreAlloc bool
}

type NewIPAMParams struct {
	Logger         *slog.Logger
	NodeAddressing node.Addressing
	AgentConfig    *option.DaemonConfig
	NodeDiscovery  Owner
	LocalNodeStore *node.LocalNodeStore
	K8sEventReg    K8sEventRegister
	NodeResource   agentK8s.LocalCiliumNodeResource
	MTUConfig      MtuConfiguration
	Clientset      client.Clientset
	Metadata       Metadata
	Sysctl         sysctl.Sysctl
	IPMasqAgent    *ipmasq.IPMasqAgent

	JobGroup job.Group

	DB                        *statedb.DB
	PodIPPools                statedb.Table[podippool.LocalPodIPPool]
	OnlyMasqueradeDefaultPool bool

	// CloudProviders holds the registered cloud providers, keyed by the IPAM
	// mode each one handles.
	CloudProviders map[string]CloudProvider
}

type Owner interface {
	// UpdateCiliumNodeResource is called to create/update the CiliumNode
	// resource. The function must block until the custom resource has been
	// created.
	UpdateCiliumNodeResource()
}

type Pool string

type PoolSpecAccessors struct {
	// FromResource returns the IPAM Pool specs from the CiliumNode
	FromResource func(*ciliumv2.CiliumNode) types.IPAMPoolSpec

	// ToResource writes the IPAM Pool specs to the CiliumNode.
	// It returns true if the pools have been updated, false otherwise.
	ToResource func(*ciliumv2.CiliumNode, types.IPAMPoolSpec) bool
}

type RoutingMetadataResolver interface {
	// ResolveRoutingMetadata returns the cloud-specific routing metadata of
	// addr (PrimaryMAC, GatewayIP, CIDRs, InterfaceNumber), reported as the
	// AllocationResult the allocator hands to its caller.
	//
	// Returning an error makes an allocating caller release the reservation
	// that the underlying allocation already took.
	ResolveRoutingMetadata(node *ciliumv2.CiliumNode, addr netip.Addr, pool Pool) (*AllocationResult, error)
}

type SkipMasqueradeForPoolFn func(Pool) (bool, error)