http

type AuthAttempt struct {
	// Reason is "initial" (first call, or after TTL expiry) or
	// "unauthorized" (after a 401 response).
	Reason string
	// Failures is the number of consecutive prior failures of this hook.
	Failures int
	// PreviousStatus is the HTTP status of the response that triggered
	// this re-evaluation. 0 on the initial call.
	PreviousStatus int
}

type AuthBackoff struct {
	InitialDelay time.Duration
	MaxDelay     time.Duration
	Factor       float64
}

type AuthEvaluator func(attempt AuthAttempt) (AuthResult, error)

type AuthHandler interface {
	// ClientName returns the name of the client this handler belongs
	// to. Used by verb functions to manage the reentrancy marker.
	ClientName() string

	// Expression returns the HCL expression that should be evaluated to
	// produce the Authorization header value. The verb function uses it
	// to build the AuthEvaluator closure.
	Expression() hcl.Expression

	// Get returns a cached or freshly-evaluated Authorization header.
	//
	// If reentrancy suppression applies (the client's name is in the
	// marker set on ctx), Get returns ("", nil) — the verb function
	// must send the request with no Authorization header.
	//
	// If the cache holds a value that has not expired, Get returns it
	// without calling eval.
	//
	// If the cache is empty or expired, Get calls eval under a
	// singleflight mutex (concurrent callers wait on the same
	// evaluation). The reason argument seeds AuthAttempt.Reason; pass
	// "initial" for the normal first-time / TTL-expired case and
	// "unauthorized" for a re-eval after a 401.
	//
	// If the handler is in failed state (consecutive failures exceeded
	// MaxFailures and the backoff has not yet elapsed), Get returns an
	// error without calling eval.
	Get(ctx context.Context, reason string, previousStatus int, eval AuthEvaluator) (string, error)

	// Invalidate marks the cached value as stale. The next call to Get
	// will re-evaluate. Used after a 401 response to force a fresh
	// credential on the next attempt.
	Invalidate()

	// RecordResult updates the consecutive-failure counter based on the
	// status of a request that consumed the handler's value:
	//   - 401 → failure (eligible for failed-state entry)
	//   - any other status → success, counter reset
	//
	// Note: 401 caused by a hook *evaluation* error is recorded
	// internally by Get itself — RecordResult is for wire results.
	RecordResult(status int)

	// Snapshot returns a copy of the handler's internal counters for
	// observability and tests. Implementations should make this safe to
	// call concurrently with other methods.
	Snapshot() AuthSnapshot
}

type AuthResult struct {
	Value     string
	ExpiresIn time.Duration
}

type AuthSnapshot struct {
	HasCachedValue      bool
	ConsecutiveFailures int
	InFailedState       bool
}

type HTTPCallable interface {
	GetName() string
	BaseURL() *url.URL
	DefaultHeaders() http.Header
	DefaultRequestTimeout() time.Duration
	DefaultRedirectPolicy() RedirectPolicy
	DefaultRetryPolicy() RetryPolicy

	// AuthHandler returns the auth cache and configuration for this
	// client, or nil if no `auth` expression was configured. Mock
	// implementations may return nil to opt out of auth entirely.
	AuthHandler() AuthHandler

	// ParentEvalCtx returns the HCL evaluation context the client was
	// registered against, or nil for synthetic clients (e.g. mocks, the
	// shared null client). Verb functions need it to evaluate lazy
	// expressions like retry.on_response that were stored at config time.
	ParentEvalCtx() *hcl.EvalContext

	// Do sends a request using the implementation's default redirect policy.
	Do(req *http.Request) (*http.Response, error)

	// DoWithRedirectPolicy sends a request using the supplied per-call
	// redirect policy in place of the default. Mock implementations that do
	// not actually follow redirects may delegate to Do(req).
	DoWithRedirectPolicy(req *http.Request, pol RedirectPolicy) (*http.Response, error)
}

type HTTPClient struct {
	cfg.BaseClient
	// contains filtered or unexported fields
}

type RedirectPolicy struct {
	Follow   bool
	Max      int
	KeepAuth bool
}

type RetryPolicy struct {
	MaxAttempts        int
	InitialDelay       time.Duration
	MaxDelay           time.Duration
	BackoffFactor      float64
	Jitter             bool
	RetryOn            map[int]struct{}
	RespectRetryAfter  bool
	AllowNonIdempotent bool

	// OnResponse is an HCL expression evaluated by the verb function
	// after each attempt that returned a response. nil means no hook
	// is configured. The expression has access to ctx.response (the
	// in-flight response) and ctx.attempt (1-indexed) and may return
	// null/false (stop), true (retry with normal backoff), or a
	// number/duration (wait that long, then retry).
	OnResponse hcl.Expression
}