Documentation
¶
Overview ¶
Package scheduler implements periodic withdrawal of accumulated lease fees and credit-depletion monitoring.
WithdrawScheduler ¶
WithdrawScheduler runs two coupled loops:
A timer-driven withdrawal at a fixed interval (`withdraw_interval`, default 1h). Each tick pages MsgWithdraw through all of the provider's active leases — threading the chain's opaque next_key cursor until it is empty, bounded by `max_withdraw_iterations` — to drain accumulated fees into the provider's account.
A credit-depletion check that runs after each withdrawal. It samples tenant credit balances, estimates depletion time, and schedules an earlier follow-up withdrawal if any tenant would deplete before the next scheduled tick.
The estimator extrapolates depletion time from the rate of credit consumption observed between two withdrawals; the check runs `depletionCheckBuffer` (10 seconds) before the estimated depletion to ensure we catch it.
When credit is exhausted, MsgCloseLease is submitted for each affected lease and the provisioner's normal lease_closed event flow handles the cleanup.
External triggers ¶
TriggerWithdraw can be called by other components (notably the watcher, for cross-provider credit-depletion events) to force an immediate withdrawal between scheduled ticks.
Failure handling ¶
Transient chain errors are retried with exponential backoff up to `maxRetries` (3) and `maxBackoff` (10s). Per-tenant credit-query errors are tracked as `consecutiveErrs` in the tenant's state; once that count reaches `credit_check_error_threshold` (default 3), the scheduler treats the failures as potentially transient: it does not close the tenant's leases on the still-failing data, but does schedule an earlier follow-up run after `credit_check_retry_interval` (default 30s). A successful query resets the counter.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ChainClient ¶
type ChainClient interface {
GetProviderWithdrawable(ctx context.Context, providerUUID string) (sdktypes.Coins, error)
WithdrawByProvider(ctx context.Context, providerUUID string, key []byte) (string, *billingtypes.MsgWithdrawResponse, error)
GetActiveLeasesByProvider(ctx context.Context, providerUUID string) ([]billingtypes.Lease, error)
GetCreditAccount(ctx context.Context, tenant string) (*billingtypes.CreditAccount, sdktypes.Coins, error)
CloseLeases(ctx context.Context, leaseUUIDs []string, reason string) (uint64, []string, error)
}
ChainClient defines the interface for chain operations needed by the scheduler.
type WithdrawScheduler ¶
type WithdrawScheduler struct {
// contains filtered or unexported fields
}
WithdrawScheduler periodically withdraws funds from active leases and auto-closes leases for tenants with depleted credit.
func NewWithdrawScheduler ¶
func NewWithdrawScheduler(client ChainClient, cfg WithdrawSchedulerConfig) *WithdrawScheduler
NewWithdrawScheduler creates a new withdrawal scheduler.
func (*WithdrawScheduler) Start ¶
func (s *WithdrawScheduler) Start(ctx context.Context) error
Start begins the periodic withdrawal and credit checking process. Note: Call WithdrawOnce() before Start() if you need an initial withdrawal that must complete before other operations.
Context inheritance: Start() creates an internal context derived from the passed ctx. When ctx is canceled, the internal context is also canceled, which stops any TriggerWithdraw goroutines that were spawned during operation.
func (*WithdrawScheduler) Stop ¶
func (s *WithdrawScheduler) Stop()
Stop cancels the scheduler's internal context, stopping all operations. This is useful for testing or for cases where you want to stop the scheduler without canceling the parent context passed to Start(). After Stop() is called, TriggerWithdraw() calls will be ignored.
func (*WithdrawScheduler) TriggerWithdraw ¶
func (s *WithdrawScheduler) TriggerWithdraw()
TriggerWithdraw triggers an immediate withdrawal cycle. This can be called from event handlers when cross-provider credit depletion is detected. Uses the scheduler's context so it can be canceled on shutdown.
func (*WithdrawScheduler) WithdrawOnce ¶
func (s *WithdrawScheduler) WithdrawOnce(ctx context.Context) error
WithdrawOnce performs a single withdrawal and credit check cycle. This should be called at startup before Start() to ensure the transaction completes before other startup transactions (like lease acknowledgment).
type WithdrawSchedulerConfig ¶
type WithdrawSchedulerConfig struct {
ProviderUUID string
WithdrawInterval time.Duration // paid-withdraw cadence
CreditCheckInterval time.Duration // credit-check / wake cadence; 0 => = WithdrawInterval
MaxWithdrawIterations int
CreditCheckErrorThreshold int
CreditCheckRetryInterval time.Duration
}
WithdrawSchedulerConfig holds configuration for the withdrawal scheduler.
Source Files