refactor(flowcontrol): Migrate Fairness Policies to EPP Plugin System

[LukeAVanDrie]

What type of PR is this?
/kind feature
/kind cleanup

What this PR does / why we need it:
This PR refactors the experimental Flow Control layer to use the standard EPP Plugin Registry for Fairness Policies (formerly, Inter-Flow Dispatch Policies), replacing the previous hardcoded factory implementation.

Architectural Change:
Previously, policies were instantiated per-band using a custom factory. Now, policies are registered as Singletons in the global EPP registry to align with the wider project architecture.

To support stateful logic (like Round Robin cursors) for each Priority Band while using singleton plugins, we utilize the flyweight pattern:

1. Plugin: The Policy instance is a global stateless singleton (holding only immutable config).
2. State: Mutable state (e.g., the cursor) is created via NewState(ctx) and stored on the PriorityBand.
3. Execution: The Pick(ctx, band) method receives the specific state for that band at runtime.

Renaming & Standardization:

• InterFlowDispatchPolicy → FairnessPolicy: Aligns terminology with the "Fairness" tier in the dispatch hierarchy.
• BestHead → GlobalStrict: Renamed to better describe the behavior (strict global ordering ignoring flow boundaries) rather than the implementation.
• Documentation: Added pkg/epp/flowcontrol/framework/plugins/interflow/doc.go to document the 3-Tier Dispatch Hierarchy (Priority → Fairness → Ordering).

Reviewer Guide:
This PR includes a significant refactor (~1.5k lines changed), but the logic changes are localized. I recommend reviewing by commit:

1. Commit 1: Defines the new FairnessPolicy and Accessor interfaces.
2. Commit 2: Ports RoundRobin and GlobalStrict to the new interface.
3. Commit 3: Updates config/loader to validate/hydrate policies at startup.
4. Commit 4: Updates the Registry and Controller to use the new system.
5. Commit 5: Cleanups (deletes legacy factory and docs).

Relationship to Previous Proposals:
This implementation supersedes the "Transient Plugin Lifecycle" proposal (#1977 ).
Based on feedback from @shmuelk and @kfswain I have abandoned the "Transient/Factory" framework changes in favor of the simpler flyweight pattern.

Which issue(s) this PR fixes:
Part of #1715

Does this PR introduce a user-facing change?:

[Experimental] Flow Control: Fairness Policies (formerly, Inter-Flow Dispatch Policies) are now integrated with the standard EPP Plugin system; however, they are not yet configurable.

[k8s-ci-robot]

Hi @LukeAVanDrie. Thanks for your PR.

I'm waiting for a github.com member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[netlify]

✅ Deploy Preview for gateway-api-inference-extension ready!

Name	Link
🔨 Latest commit	6eaba6b
🔍 Latest deploy log	https://app.netlify.com/projects/gateway-api-inference-extension/deploys/696fd5710f98380008b4b553
😎 Deploy Preview	https://deploy-preview-2031--gateway-api-inference-extension.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[LukeAVanDrie]

Sorry for the large diff! I thought a lot about how to split this, but I ultimately opted for a single atomic PR for two architectural reasons:

1. Atomic Consistency: This is a binary state change. Moving from the legacy Factory pattern to the new Flyweight/Singleton pattern requires changing the interfaces, plugins, and registry wiring simultaneously. Splitting it would have required "bridge code" or dead interfaces, adding noise.
2. Contextual Completeness: The FairnessPolicy interface (Commit 1) is best understood alongside its implementation in RoundRobin (Commit 2) and its wiring in the Registry (Commit 3).

Review Strategy:
To mitigate the size, I structured the git history for a linear, commit-by-commit review

• Commits 2 & 4 contain the actual logic changes.
• Commits 3 & 5 are largely mechanical (config wiring and deleting legacy code).

I have also left inline reviewer comments to answer anticipated questions. Thanks!

[shmuelk]

This function iterates on the queues of a flow, why not say that in the name?

I think the name should be FlowQueuesIterator, again without the func suffix.

[LukeAVanDrie]

I see the point, but IterateQueuesFunc is deliberately named to map 1:1 with the
IterateQueues method in the PriorityBandAccessor interface it mocks. Changing the mock field name without changing the interface method name would reduce discoverability and consistency.

Renaming the interface method itself is something we can consider, but I'd prefer to handle that in a separate cleanup PR to keep this refactor focused.

[shmuelk]

Thank you for changing direction here and going with a style that is in-line with the other EPP plugins

I have only reviewed a small part of this PR.

I think it should have been broken up into at least two PRs. One that did the renames and second one that changed the flowcontrol extensions into proper EPP plugins.

[ahg-g]

/ok-to-test

[LukeAVanDrie]

I think it should have been broken up into at least two PRs. One that did the renames and second one that changed the flowcontrol extensions into proper EPP plugins.

Thanks! This is a fair point regarding BestHead -> GlobalStrict (which could have probably been deferred). The reason I didn't separate the InterFlow -> Fairness rename is that the interface signature also changed. The rename would have introduced some temporary code churn, and I felt it was cleaner to introduce the new interface correctly from the start in the context of the plugin migration. Given I had to update several references in go-docs, call sites, etc. it would have maybe been worthwhile despite this. I will keep this in mind when migrating IntraFlowDispatchPolicy (to be renamed OrderingPolicy) next.

[shmuelk]

Why is the FairnessPolicy (the old InterFlowDispatchPolicy) per priority in a shard? Shouldn't it be at the shard level?

This is unless I misunderstand that the FairnessPolicy is between priorities within a shard? While the IntraFlowDispatchPolicy is the ordering of things in a Priority.

[shmuelk]

While you're renaming things here, I really don't understand the use of the word band throughout the flow control layer.

Bands usually are ranges of things (to quote the AI part of a Google search "or a range of values (like a salary band)"). Here a band is for a single priority.

In the following code snippet it is clear that a PriorityBand is for a single priority.

type PriorityBandConfig struct {
	// Priority is the unique numerical priority level for this band.
	// Convention: Highest numeric value corresponds to highest priority (centered on 0).
	// Required.
	Priority int
         ...

[ahg-g]

General comment: Please focus only on aligning on the user facing names for now, names of internal structs/types can be changed separately as a followup.

[ahg-g]

I am ok with this, but for the future, this PR is massive, it could have been split in to two: the renaming and the architectural change for plugin creation

[LukeAVanDrie]

While you're renaming things here, I really don't understand the use of the word band throughout the flow control layer.

Bands usually are ranges of things (to quote the AI part of a Google search "or a range of values (like a salary band)"). Here a band is for a single priority.

Thanks for the feedback. In our domain model, a "Priority Band" represents the logical grouping of all state and resources associated with a specific priority level. While "band" often implies a range of values, here it refers to a "horizontal slice" of traffic entitlement.

To clarify this distinction and scope, I've updated the PriorityBandConfig struct documentation in config.go to explicitly define it: "A 'Band' is defined as the collection (or range) of all flows having the same priority level."

This terminology is used similarly in Linux Traffic Control if you want prior art here.

[ahg-g]

/lgtm
/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: ahg-g, LukeAVanDrie

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [ahg-g]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment