contracts

type ActiveFlowConnection interface {
	// GetDataPlane returns the FlowRegistryDataPlane this connection is pinned to.
	GetDataPlane() FlowRegistryDataPlane
	// FlowKey returns the immutable identity of the flow this connection is pinned to.
	FlowKey() flowcontrol.FlowKey
}

type AggregateStats struct {
	// TotalCapacityBytes is the globally configured maximum total byte size limit across all priority bands.
	TotalCapacityBytes uint64
	// TotalCapacityRequests is the globally configured maximum total request count limit across all priority bands.
	TotalCapacityRequests uint64
	// TotalByteSize is the total byte size of all items currently queued across the entire system.
	TotalByteSize uint64
	// TotalLen is the total number of items currently queued across the entire system.
	TotalLen uint64
	// PerPriorityBandStats maps each configured priority level to its globally aggregated statistics.
	PerPriorityBandStats map[int]PriorityBandStats
}

type EndpointCandidates interface {
	// Locate returns a list of endpoint candidate metrics that match the criteria defined in the request metadata.
	Locate(ctx context.Context, requestMetadata map[string]any) []fwkdl.Endpoint
}

type FlowRegistry interface {
	FlowRegistryObserver
	FlowRegistryDataPlane
	PriorityBandControlPlane
	FlowRegistryBackground
}

type FlowRegistryBackground interface {
	PriorityBandUpdateChannel() <-chan map[int]struct{}
	FlowGCTimeout() time.Duration
	ApplyDesiredPriorities(desired map[int]struct{})
	ExecuteGCCycle()
}

type FlowRegistryDataPlane interface {
	// WithConnection manages a scoped, leased session for a given flow.
	// It is the primary and sole entry point for interacting with the data path.
	//
	// This method handles the entire lifecycle of a flow connection:
	// 1. Flow Registration: If the flow for the given FlowKey does not exist, it is created and registered
	//    automatically. Priority bands must be provisioned by the control plane before use.
	// 2. Lease Acquisition: It acquires a lifecycle lease, protecting the flow from garbage collection.
	// 3. Callback Execution: It invokes the provided function `fn`, passing in a temporary `ActiveFlowConnection` handle.
	// 4. Guaranteed Lease Release: It ensures the lease is safely released when the callback function returns.
	//
	// This functional, callback-based approach makes resource leaks impossible, as the caller is not responsible for
	// manually closing the connection.
	//
	// Errors returned by the callback `fn` are propagated up.
	// Returns `ErrFlowIDEmpty` if the provided key has an empty ID.
	WithConnection(key flowcontrol.FlowKey, fn func(conn ActiveFlowConnection) error) error

	// ManagedQueue retrieves the managed queue for the given, unique FlowKey. This is the primary method for accessing
	// a specific flow's queue for either enqueueing or dispatching requests.
	//
	// Returns an error wrapping ErrPriorityBandNotFound if the priority specified in the key is not configured, or
	// ErrFlowInstanceNotFound if no instance exists for the given key.
	ManagedQueue(key flowcontrol.FlowKey) (ManagedQueue, error)

	// FairnessPolicy retrieves the FairnessPolicy singleton configured for the specified priority band.
	// This method provides access to the immutable logic component that governs inter-flow contention.
	// The registry guarantees that a non-nil policy is returned for any active priority band.
	//
	// Returns:
	//   - FairnessPolicy: The active policy instance.
	//   - error: A wrapped ErrPriorityBandNotFound if the priority level is not configured.
	FairnessPolicy(priority int) (flowcontrol.FairnessPolicy, error)

	// PriorityBandAccessor retrieves the read-only view of the "Flow Group" for a specific priority level.
	// This accessor provides the state of all contending flows within the band and serves as the
	// primary input for FairnessPolicy execution.
	//
	// Returns an error wrapping ErrPriorityBandNotFound if the priority level is not configured.
	PriorityBandAccessor(priority int) (flowcontrol.PriorityBandAccessor, error)

	// AllOrderedPriorityLevels returns all configured priority levels, sorted in descending
	// numerical order. This order corresponds to highest priority (highest numeric value) to lowest priority (lowest
	// numeric value).
	// The returned slice provides a definitive, ordered list of priority levels for iteration, for example, by a
	// `controller.FlowController` worker's dispatch loop.
	AllOrderedPriorityLevels() []int
}

type FlowRegistryObserver interface {
	// Stats returns a near-consistent snapshot globally aggregated statistics for the entire `FlowRegistry`.
	Stats() AggregateStats
}

type ManagedQueue interface {
	// Add attempts to enqueue an item.
	Add(item flowcontrol.QueueItemAccessor) error

	// Remove atomically finds and removes an item from the underlying queue using its handle.
	Remove(handle flowcontrol.QueueItemHandle) (flowcontrol.QueueItemAccessor, error)

	// Cleanup removes all items from the underlying queue that satisfy the predicate.
	Cleanup(predicate PredicateFunc) []flowcontrol.QueueItemAccessor

	// Drain removes all items from the underlying queue.
	Drain() []flowcontrol.QueueItemAccessor

	// FlowQueueAccessor returns a read-only, flow-aware accessor for this queue, used by policy plugins.
	// Conformance: This method MUST NOT return nil.
	FlowQueueAccessor() flowcontrol.FlowQueueAccessor
}

type PredicateFunc func(item flowcontrol.QueueItemAccessor) bool

type PriorityBandControlPlane interface {
	// SubmitDesiredPriorities queues the set of priority levels that should remain provisioned.
	// Dynamic bands not in this set become eligible for removal once idle.
	SubmitDesiredPriorities(desired map[int]struct{})
}

type PriorityBandStats struct {
	// Priority is the numerical priority level this struct describes.
	Priority int
	// CapacityBytes is the configured maximum total byte size for this priority band.
	// When viewed via `AggregateStats`, this is the global limit.
	// The `controller.FlowController` enforces this limit.
	// A default non-zero value is guaranteed if not configured.
	CapacityBytes uint64
	// CapacityRequests is the configured maximum total request count for this priority band.
	CapacityRequests uint64
	// ByteSize is the total byte size of items currently queued in this priority band.
	ByteSize uint64
	// Len is the total number of items currently queued in this priority band.
	Len uint64
}

type SafeQueue interface {
	flowcontrol.QueueInspectionMethods

	// Add enqueues an item. It must associate a new, unique QueueItemHandle with the item by calling
	// item.SetHandle().
	// Contract: The caller MUST NOT provide a nil item.
	Add(item flowcontrol.QueueItemAccessor)

	// Remove atomically finds and removes the item identified by the given handle.
	// On success, implementations MUST invalidate the provided handle by calling handle.Invalidate().
	// Returns the removed item.
	// Returns ErrInvalidQueueItemHandle if the handle is invalid.
	// Returns ErrQueueItemNotFound if the handle is valid but the item is not in the queue.
	Remove(handle flowcontrol.QueueItemHandle) (removedItem flowcontrol.QueueItemAccessor, err error)

	// Cleanup iterates through the queue and atomically removes all items for which the predicate returns true,
	// returning them in a slice.
	// The handle for each removed item MUST be invalidated.
	Cleanup(predicate PredicateFunc) (cleanedItems []flowcontrol.QueueItemAccessor)

	// Drain atomically removes all items from the queue and returns them in a slice.
	// The handle for all removed items MUST be invalidated. The queue MUST be empty after this operation.
	Drain() (drainedItems []flowcontrol.QueueItemAccessor)
}