limits

type ErrorRateLimited struct {
	Key string

	Scope  settings.Scope
	Tenant string

	N int

	Err error
}

type ErrorResourceLimited[N Number] struct {
	Key string

	Scope  settings.Scope
	Tenant string

	Used, Limit, Amount N
}

type ErrorTimeLimited struct {
	Key string

	Scope  settings.Scope
	Tenant string

	Timeout time.Duration
}

type Factory struct {
	// Settings is a source of dynamic limit and burst updates.
	// [settings.Getter.GetScoped] will be polled for updates, unless Settings is also a settings.Registry, in which case
	// the channel based [settings.Registry.SubscribeScoped] will be used instead.
	Settings settings.Getter // optional

	// Meter is an optional way to emit Open Telemetry metrics.
	Meter metric.Meter // optional

	// Logger is used when parsing fails and a limit falls back to the default value.
	Logger logger.Logger // optional
}

type Limiter interface {
	io.Closer // Limiters spawn background goroutines and must be closed.
}

type MultiRateLimiter []RateLimiter

type MultiResourcePoolLimiter[N Number] []ResourcePoolLimiter[N]

type Number interface {
	constraints.Integer | constraints.Float
}

type RateLimiter interface {
	Limiter

	// Allow reports whether an event may happen now.
	Allow(ctx context.Context) bool
	// AllowN reports whether n events may happen at time t.
	// Use this method if you intend to drop / skip events that exceed the rate limit.
	// Otherwise, use Reserve or Wait.
	AllowN(ctx context.Context, t time.Time, n int) bool
	// AllowErr is like Allow, but returns an error.
	AllowErr(ctx context.Context) error
	// AllowNErr is like AllowN, but returns an error.
	AllowNErr(ctx context.Context, t time.Time, n int) error

	// Reserve is shorthand for ReserveN(time.Now(), 1).
	Reserve(ctx context.Context) (Reservation, error)
	// ReserveN returns a Reservation that indicates how long the caller must wait before n events happen.
	// The Limiter takes this Reservation into account when allowing future events.
	// The returned Reservation’s OK() method returns false if n exceeds the Limiter's burst size.
	// Usage example:
	//
	//	r := lim.ReserveN(time.Now(), 1)
	//	if !r.OK() {
	//	  // Not allowed to act! Did you remember to set lim.burst to be > 0 ?
	//	  return
	//	}
	//	time.Sleep(r.Delay())
	//	Act()
	//
	// Use this method if you wish to wait and slow down in accordance with the rate limit without dropping events.
	// If you need to respect a deadline or cancel the delay, use Wait instead.
	// To drop or skip events exceeding rate limit, use Allow instead.
	ReserveN(ctx context.Context, t time.Time, n int) (Reservation, error)

	// Wait is shorthand for WaitN(ctx, 1).
	Wait(ctx context.Context) (err error)
	// WaitN blocks until lim permits n events to happen.
	// It returns an error if n exceeds the Limiter's burst size, the Context is
	// canceled, or the expected wait time exceeds the Context's Deadline.
	WaitN(ctx context.Context, n int) (err error)
}

type Reservation interface {
	OK() bool
	Delay() time.Duration
	DelayFrom(time.Time) time.Duration
	Cancel()
	CancelAt(time.Time)

	// Allow returns true if no Delay is required.
	Allow() bool
	// AllowErr is like Allow but includes a detailed error.
	AllowErr() error
}

type ResourceLimiter[N Number] interface {
	Limiter
	// Use increases the resource count by amount, or returns an error if the limit is reached.
	// It does not block. Use a ResourcePoolLimiter for blocking semantics.
	Use(ctx context.Context, amount N) error
	// Free is the counterpart to Use and releases amount of resources from use.
	Free(ctx context.Context, amount N) error
}

type ResourcePoolLimiter[N Number] interface {
	ResourceLimiter[N]
	// Wait is like Use, but blocks until resources are available, or context has expired. The free func must be
	// called and should be deferred immediately when possible. It effectively calls Free to release N resources.
	Wait(context.Context, N) (free func(), err error)
}

type TimeLimiter interface {
	Limiter
	// WithTimeout is like context.WithTimeout, but automatically applies the timeout
	// from this TimeLimiter, and returns a done func() that must be called to signal completion.
	WithTimeout(context.Context) (ctx context.Context, done func(), err error)
}