package port

import (
	"context"

	"github.com/orchard9/rdev/internal/domain"
)

// RateLimiter defines operations for rate limiting API requests.
type RateLimiter interface {
	// CheckLimit checks if a request is allowed under the rate limit.
	// Returns the result including whether allowed, remaining counts, and retry timing.
	CheckLimit(ctx context.Context, keyID string) (*domain.RateLimitResult, error)

	// RecordRequest records that a request was made for the given API key.
	// This should be called after CheckLimit returns Allowed=true.
	RecordRequest(ctx context.Context, keyID string) error

	// GetLimits retrieves the rate limit configuration for an API key.
	// Returns default limits if the key doesn't have custom limits set.
	GetLimits(ctx context.Context, keyID string) (*domain.RateLimitConfig, error)

	// Cleanup removes expired rate limit state entries.
	// This should be called periodically to prevent table bloat.
	Cleanup(ctx context.Context) error
}