[FLINK-40326][core] Do not over-grant permits in GatedRateLimiter

[Savonitar]

What is the purpose of the change

The decrement in acquire() was generalized from a constant 1 to numberOfEvents as part of FLIP-535, but the gate was left closing only at capacityLeft <= 0, so a cycle can admit more events than capacityPerCycle. The gate is now closed unless the capacity left covers the whole request.

Brief change log

• Close the gate in GatedRateLimiter#acquire(int) unless the capacity left covers the whole request, rather than only once it has reached zero
• Reject a non-positive numberOfEvents
• Initialize gatingFuture eagerly, so notifyCheckpointComplete before the first acquire() no longer throws a NullPointerException
• Correct the class Javadoc

Verifying this change

This change added the following tests:

• Added four tests to GatedRateLimiterTest, one per defect, each fails against the unfixed code

Does this pull request potentially affect one of the following parts:

• Dependencies (does it add or upgrade a dependency): (no)
• The public API, i.e., is any changed class annotated with @Public(Evolving): (yes, but Javadoc only )
• The serializers: (no, a transient modifier is dropped, but GatedRateLimiter does not implement Serializable (only RateLimiterStrategy does), so it had no effect.)
• The runtime per-record code paths (performance sensitive): (yes, acquire(int) is called once per input record when rate limiting is enabled.)
• Anything that affects deployment or recovery: JobManager (and its components), Checkpointing, Kubernetes/Yarn, ZooKeeper: (no)
• The S3 file system connector: (no)

Documentation

• Does this pull request introduce a new feature? (no)
• If yes, how is the feature documented? (not applicable)

---

Was generative AI tooling used to co-author this PR?

• Yes (please specify the tool below)

Generated-by: [Tool Name and Version]

[flinkbot]

CI report:

• 0988ec0 Azure: SUCCESS

Bot commands

The @flinkbot bot supports the following commands:

• @flinkbot run azure re-run the last Azure build

[1996fanrui]

Thanks for the fix. Two questions:

1. The gate now closes while capacity is still unused, so a cycle always emits less than capacityPerCycle and never reaches it — with capacityPerCycle=100 and 6 events per request, every cycle stops at 96.

2. A single request larger than the cycle capacity still exceeds it: with capacityPerCycle=100 and acquire(10000), the first cycle emits nothing and then every following checkpoint releases the whole 10000, since notifyCheckpointComplete resets capacityLeft and drops the negative balance.

So we neither reach capacityPerCycle in the first case nor stay within it in the second. How do you think we should handle this?

Fine with me if this is the accepted behaviour.

[Savonitar]

@1996fanrui thanks for the questions and feedback.

Two questions:
The gate now closes while capacity is still unused, so a cycle always emits less than capacityPerCycle and never reaches it — with capacityPerCycle=100 and 6 events per request, every cycle stops at 96.

1. Yes, it undershoots now instead of overshooting, but isn't that the direction a rate limiter should err in? With capacityPerCycle=100, a single acquire(1000) was granted immediately and in full before this PR, because 100 <= 0 is false. Also, doesn't it seem strange to use negative value for capacity(which can happen in pre-PR code)?

A single request larger than the cycle capacity still exceeds it: with capacityPerCycle=100 and acquire(10000), the first cycle emits nothing and then every following checkpoint releases the whole 10000, since notifyCheckpointComplete resets capacityLeft and drops the negative balance.

2.That one is pre-existing, not introduced here: before the PR it produced [10000, 10000, ...], now it produces [0, 10000, ...].

So this is an iterative improvement rather than a complete fix, a strict cap would need a redesign. This PR fixes three separate things: the gate, an NPE when a checkpoint completes before the first acquire(), and a missing argument check. I'm happy to drop the gate change and keep the overshoot if you think that's better by design. WDYT?