CallBudget
Grants permits under a provider's rate windows and lane shares, pauses on server signals and, when a store is supplied, holds a hard daily stop across a restart.
The contract an implementation (the supplied WindowedCallBudget, CallBudget.Unlimited, a consumer's own budget or a fake) meets:
Charged at the grant. A granted permit has been charged to the budget's counts; the budget holds no lock, semaphore or lease for it. A permit never completed is simply spent.
Fail fast. acquire returns
Result.failure(HttpFailure.BudgetExhausted(wait, reason, window))when the wait the call would need exceedsmaxWait(Duration.INFINITE waits as long as the plan needs; zero fails unless the call fits now), charging nothing.waitis the wait the call would have had; Duration.INFINITE forCostExceedsLimit.First come first served within a lane. A call that would wait is queued behind the lane's earlier waiters.
Cancellation. The caller's own cancellation is thrown as
CancellationException; a cancelled wait is refunded and the waiters behind it are re-planned. A caller that is already cancelled gets itsCancellationExceptioneven after close, and never receives a permit.Closing. After close, acquire and every call waiting return
Result.failure(HttpFailure.Closed("budget"))as a value, never as a thrown cancellation. close is idempotent, non-suspending, never throws and may be called from any thread. After it, flush, utilisation andcomplete()/release()on permits granted before the close keep working.Permits. Permit.complete,
complete(signals)and Permit.release are idempotent and run underNonCancellable, so they take effect from a cancelled coroutine.Utilisation. utilisation is a snapshot of the current window of each rate window, the pause remaining and the number of waiting calls.
Flush. flush writes the exact counts to the budget's store and returns the failure instead of a success when it could not. The default body succeeds.
Programmer errors. A
costbelow 1 and a negativemaxWaitthrowIllegalArgumentException.Concurrency. Every member may be called concurrently from any thread and any number of coroutines.
Experimental (implement). Implementing needs @OptIn(ExperimentalForInheritanceWebToolsApi::class); calling the port, passing it, and the supplied WindowedCallBudget and Unlimited are Stable Core.