httpapi

type Authenticator interface {
	// Authenticate returns the record of the key raw. A malformed,
	// unknown or revoked key is refused with domain.ErrInvalidAPIKey,
	// app.ErrKeyNotFound or app.ErrKeyRevoked; any other error means the
	// key could not be checked.
	Authenticate(ctx context.Context, raw string) (domain.KeyRecord, error)
}

type ChallengeVerifier interface {
	// Verify reports whether token is valid; a token is valid once. An
	// error means it could not be checked.
	Verify(ctx context.Context, token string) (bool, error)
}

type Checker interface {
	// Check returns the report of in; a source it could not consult is
	// reported unavailable, never an error.
	Check(ctx context.Context, in domain.Input) domain.Report
	// CheckAll returns the report of each input, in the order of ins.
	CheckAll(ctx context.Context, ins []domain.Input) []domain.Report
}

type DemoOptions struct {
	// Origin is the site's origin, the only one CORS allows; empty allows
	// none.
	Origin string
	// Verifier checks the anti-abuse token of each request; nil answers
	// every request with a 503.
	Verifier ChallengeVerifier
	// Limit limits the demo checks of each client address; nil applies
	// config.DefaultRateLimitDemo a minute.
	Limit Limiter
	// GlobalLimit limits the demo checks of every client together; nil
	// applies config.DefaultRateLimitDemoGlobal a minute.
	GlobalLimit Limiter
}

type Limiter interface {
	// Allow spends one request of key.
	Allow(key string) ratelimit.Decision
	// Policy returns the policy applied to each key.
	Policy() ratelimit.Policy
	// Refund gives back one request of key, spent by Allow.
	Refund(key string)
}

type Options struct {
	// Ready backs /readyz.
	Ready Readiness
	// Check backs /v1/check and /v1/check/batch.
	Check Checker
	// Auth checks the API key of /v1/check and /v1/check/batch; nil
	// answers them all with a 503.
	Auth Authenticator
	// Sources backs /v1/sources.
	Sources SourceLister
	// Logger receives the access log and the recovered panics.
	Logger *slog.Logger
	// NewID makes a request identifier when the client sent no valid one;
	// nil means crypto/rand.Text.
	NewID func() string
	// ProblemBase is the URL of the documentation of the problems, ending
	// with a slash: the type of a problem is its code under it.
	ProblemBase string
	// BatchMaxItems is the most items POST /v1/check/batch accepts, at
	// least one: config.Config.BatchMaxItems.
	BatchMaxItems int
	// KeyLimit limits the requests of each API key to the check routes;
	// nil applies config.DefaultRateLimitKey a minute.
	KeyLimit Limiter
	// IPLimit limits the requests of each client address to the routes
	// needing no key; nil applies config.DefaultRateLimitIP a minute.
	IPLimit Limiter
	// AuthLimit limits the refused API keys of each client address on the
	// check routes: an address it refuses is answered 429 before its key is
	// looked up. nil applies config.DefaultRateLimitAuth a minute.
	AuthLimit RefusalLimiter
	// TrustedProxies are the proxies whose X-Forwarded-For field tells the
	// client's address: config.Config.TrustedProxies.
	TrustedProxies []netip.Prefix
	// Demo configures POST /v1/demo/check.
	Demo DemoOptions
}

type Readiness interface {
	// Ready reports whether every snapshot is loaded.
	Ready() bool
}

type RefusalLimiter interface {
	// Peek returns whether key may be refused once more, spending nothing.
	Peek(key string) ratelimit.Decision
	// Charge spends one refusal of key, even one it does not have.
	Charge(key string)
	// Policy returns the policy applied to each key.
	Policy() ratelimit.Policy
}

type SourceLister interface {
	// Sources returns every source and the state of its data in service.
	Sources() []app.ListedSource
}