package provider

import (
	"context"
	"errors"
	"time"
)

var (
	ErrInvalidCoordination     = errors.New("invalid provider coordination")
	ErrCoordinationUnavailable = errors.New("provider coordination unavailable")
	ErrLeadershipLost          = errors.New("provider leadership lost")
	ErrLeaderWorkStopped       = errors.New("provider leader work stopped")
)

type CoordinationLimits struct {
	RequestInterval    time.Duration
	MaxInFlight        int
	MaxAttemptDuration time.Duration
	MaxTotal           int64
}

type Fence struct {
	Generation string
	Epoch      uint64
}

type Coordinator interface {
	// RunLeader waits for leadership and runs work only while its fencing lease
	// is valid. The work context is canceled before a known lease expiry.
	RunLeader(context.Context, string, CoordinationLimits, func(context.Context, LeaderSession) error) error
}

type LeaderSession interface {
	Fence() Fence
	AcquireFetch(context.Context, int) (RequestPermit, bool, error)
}

type RequestPermit interface {
	// Complete atomically releases in-flight capacity and charges the actual
	// successful candidate count. Repeated calls are idempotent.
	Complete(context.Context, int) error
	// Cancel releases a reservation that is known not to have consumed Provider
	// quota. A crashed or abandoned reservation is conservatively charged.
	Cancel(context.Context) error
}