ratelimit

type Capacity struct {
	// Resource is the unique identifier for the rate-limited resource.
	Resource string

	// Available is the current number of available tokens.
	Available int

	// Total is the maximum capacity (tokens per window).
	Total int

	// Window is the refill period.
	Window time.Duration

	// InFlight tracks requests currently in progress (if Release is used).
	InFlight int
}

type CapacityUpdate struct {
	// Resource that changed.
	Resource string `json:"resource"`

	// AgentID that sent the update.
	AgentID string `json:"agent_id"`

	// NewCapacity is the suggested new total capacity.
	NewCapacity int `json:"new_capacity"`

	// Reason for the change.
	Reason string `json:"reason"`

	// Timestamp of the update.
	Timestamp time.Time `json:"timestamp"`
}

type DistributedConfig struct {
	// Bus is the message bus for coordination.
	Bus bus.MessageBus

	// AgentID is the unique identifier for this agent.
	AgentID string

	// ReduceFactor is the multiplier when reducing capacity (0-1).
	// Default: 0.5 (reduce by 50%)
	ReduceFactor float64

	// RecoveryInterval is how often to attempt capacity recovery.
	// Default: 30 seconds
	RecoveryInterval time.Duration

	// RecoveryFactor is the multiplier when recovering capacity (>1).
	// Default: 1.1 (increase by 10%)
	RecoveryFactor float64

	// MaxRecovery caps recovery at original capacity.
	// Default: true
	MaxRecovery bool
}

type DistributedLimiter struct {
	// contains filtered or unexported fields
}

type MemoryLimiter struct {
	// contains filtered or unexported fields
}

type OnCapacityChange func(update *CapacityUpdate)

type RateLimiter interface {
	// Acquire blocks until a token is available for the resource.
	// Returns context.Canceled or context.DeadlineExceeded if context ends.
	// Returns ErrResourceUnknown if the resource has no configured capacity.
	Acquire(ctx context.Context, resource string) error

	// TryAcquire attempts to acquire a token without blocking.
	// Returns true if a token was acquired, false otherwise.
	TryAcquire(resource string) bool

	// Release returns a token to the resource bucket.
	// This is optional and useful for tracking in-flight requests.
	// Has no effect if the resource is unknown or already at capacity.
	Release(resource string)

	// SetCapacity configures the rate limit for a resource.
	// capacity is the number of tokens per window.
	// window is the time period for refill (e.g., time.Minute).
	SetCapacity(resource string, capacity int, window time.Duration)

	// AnnounceReduced broadcasts that capacity should be reduced.
	// reason describes why (e.g., "received 429 response").
	// For distributed limiters, this notifies other agents.
	// For local limiters, this is a no-op.
	AnnounceReduced(resource string, reason string)

	// GetCapacity returns the current capacity info for a resource.
	// Returns nil if the resource is unknown.
	GetCapacity(resource string) *Capacity

	// Close shuts down the limiter and releases resources.
	Close() error
}

type WatchOption func(*watchConfig)