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 ClientSource struct {
	// Trusted are the proxies whose X-Forwarded-For field tells the
	// client's address.
	Trusted []netip.Prefix
	// Header is a field, in canonical form, that the platform in front of
	// the API overwrites with the client's address; it replaces Trusted.
	Header string
}

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 KeyRequestOptions struct {
	// Requests mails the links and redeems them; nil answers both routes
	// with a 503.
	Requests KeyRequester
	// Origin is the site's origin, the only one CORS allows; empty allows
	// none.
	Origin string
	// Verifier checks the anti-abuse token of each link request; nil
	// answers them with a 503.
	Verifier ChallengeVerifier
	// Limit limits the requests of each client address to both routes;
	// nil applies config.DefaultRateLimitKeyRequest a minute.
	Limit Limiter
	// AddressLimit limits the links mailed to each email address; nil
	// applies config.DefaultRateLimitKeyRequestAddress an hour. Over it, a
	// request is answered as any other, and no link is mailed.
	AddressLimit Limiter
}

type KeyRequester interface {
	// RequestLink mails a login link to to.
	RequestLink(ctx context.Context, to domain.Email) error
	// Redeem issues a key for the login link of token, or fails with
	// app.ErrLoginLinkInvalid.
	Redeem(ctx context.Context, token string) (domain.APIKey, domain.KeyRecord, error)
}

type Limiter interface {
	// Allow spends one request of key.
	Allow(key string) ratelimit.Decision
	// AllowN spends n requests of key, or none when it has fewer.
	AllowN(key string, n int) 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
	// ClientIPHeader is the field the platform overwrites with the
	// client's address, replacing TrustedProxies:
	// config.Config.ClientIPHeader.
	ClientIPHeader string
	// Demo configures POST /v1/demo/check.
	Demo DemoOptions
	// Keys configures POST /v1/keys/request and POST /v1/keys/redeem.
	Keys KeyRequestOptions
	// MCP serves the remote MCP endpoint, POST /mcp, behind the API key
	// and the quota of the check routes; nil leaves the route out.
	MCP http.Handler
}

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
}