nethttp

type CallOptions struct {
	// QueryParams appends query string parameters to the URL.
	// Each value is validated against its registered [rest.QueryParam] codec (if any)
	// before the request is sent.
	QueryParams map[string]string

	// CookieParams adds cookies to the outgoing request.
	// Each value is validated against its registered [rest.CookieParam] codec (if any)
	// before the request is sent.
	CookieParams map[string]string

	// HeaderParams adds declared request headers to the outgoing request.
	// Each value is validated against its registered [rest.HeaderParam] codec (if any)
	// before the request is sent.
	//
	// Do not pass the Authorization header here — use [CallOptions.ExtraHeaders] or
	// [CallOptions.CredentialFunc] for security credentials.
	HeaderParams map[string]string

	// ExtraHeaders adds arbitrary HTTP headers to the outgoing request without
	// codec validation. Use for non-declared headers such as X-Request-ID,
	// User-Agent, or static Authorization values.
	ExtraHeaders http.Header

	// CredentialFunc, when non-nil, is called for routes that declare non-nil
	// Security requirements. It receives the effective security requirements and
	// must return headers to merge into the outgoing request (e.g. Authorization).
	// Return a non-nil error to abort the call before the request is sent.
	//
	// Use [CallOptions.ExtraHeaders] for simple static credentials;
	// use CredentialFunc for structured or dynamic credential injection —
	// it mirrors the server-side SecurityFunc pattern.
	CredentialFunc func(ctx context.Context, reqs []route.SecurityRequirement) (http.Header, error)

	// Observer, when non-nil, receives per-call lifecycle events.
	// [stats.Observer.RecordRequest] is called on every code path — including
	// early-exit validation failures — with the HTTP method, route path template
	// (not the concrete URL), HTTP status code, and total duration.
	// Status 0 is used when validation fails before any HTTP request is sent
	// (path var, query, cookie, or header codec failure; credential func error;
	// or request build error). This allows observers to count all call attempts,
	// including those that never reach the network.
	// Per-field validation errors are reported via [stats.Observer.RecordValidationError].
	// Defaults to [stats.NoopObserver] when nil.
	Observer stats.Observer
}

type CookieOptions struct {
	// Path is the cookie path. Defaults to "/" when empty.
	Path string

	// Domain scopes the cookie to a specific host. Defaults to the current host.
	Domain string

	// MaxAge is the cookie lifetime in seconds.
	// 0 means session cookie (deleted when browser closes).
	// Negative means delete the cookie immediately.
	MaxAge int

	// SameSite controls the cross-site request behaviour.
	// Defaults to [http.SameSiteStrictMode] when zero.
	SameSite http.SameSite

	// Insecure, when true, omits the Secure attribute.
	// Use only for non-TLS environments such as localhost development.
	// Default: false (Secure is always set).
	Insecure bool

	// AllowJS, when true, omits the HttpOnly attribute, making the cookie
	// accessible via document.cookie. Required for patterns such as
	// CSRF tokens that must be read by client-side JavaScript.
	// Default: false (HttpOnly is always set).
	AllowJS bool

	// Codec, when non-nil, validates value before the Set-Cookie header is
	// written. Use the same [codex.Codec] as the matching [rest.CookieParam]
	// for symmetric read/write validation from a single definition.
	// Set via [CookieOptions.WithCodec] to avoid address-of boilerplate.
	//
	// If validation fails, SetCookie returns [rest.CookieParamError] and does
	// NOT write the Set-Cookie header.
	Codec *codex.Codec[string]
}

type HandlerFunc[Req, Resp any] func(ctx context.Context, req Req) (Resp, error)

type Options struct {
	// ErrorHandler, when non-nil, is called instead of the default JSON error
	// envelope when a request fails. status is the suggested HTTP status code
	// (400 or 500). Implementations must write the response header and body.
	ErrorHandler func(w http.ResponseWriter, r *http.Request, status int, err error)

	// Observer, when non-nil, receives per-request lifecycle events: request
	// counts with latency and HTTP status, and per-field validation errors.
	// Defaults to [stats.NoopObserver] when nil.
	Observer stats.Observer

	// MaxBodyBytes limits the number of bytes read from the request body for
	// body-bearing methods (POST, PUT, PATCH). Zero means the default (1 MiB).
	// Requests exceeding the limit are rejected with 400 Bad Request.
	MaxBodyBytes int64

	// ContentType is the expected Content-Type for body-bearing methods (POST,
	// PUT, PATCH). When non-empty, requests whose Content-Type does not match
	// (ignoring parameters such as "; charset=utf-8") are rejected with
	// 415 Unsupported Media Type. Defaults to "application/json".
	ContentType string

	// MultiValueQueryParams, when true, passes the raw multi-value query map
	// (map[string][]string from r.URL.Query()) to [rest.RouteHandle.ValidateQueryMulti]
	// instead of the flat single-value map. Use when your routes use repeated query
	// keys such as "?tags=a&tags=b". When false (default), the first value per key
	// is validated via [rest.RouteHandle.ValidateQuery].
	MultiValueQueryParams bool

	// SecurityFunc, when non-nil, is called for routes that declare a non-nil
	// Security field (via [rest.RouteMeta.Security] or global security), after
	// parameter validation but before the handler fn.
	//
	// Return a non-nil error to reject the request with 401 Unauthorized.
	// reqs contains the route's declared security requirements (scheme names +
	// scopes). The adapter has already extracted and codec-validated the credential
	// from the request before calling SecurityFunc.
	//
	// Example — JWT bearer verification:
	//
	//	opts.SecurityFunc = func(ctx context.Context, r *http.Request, reqs []route.SecurityRequirement) error {
	//	    token := strings.TrimPrefix(r.Header.Get("Authorization"), "Bearer ")
	//	    return jwtlib.VerifyScopes(token, reqs)
	//	}
	SecurityFunc func(ctx context.Context, r *http.Request, reqs []route.SecurityRequirement) error
}

type PendingCookie struct {
	Name  string
	Value string
	Opts  CookieOptions
}

type RequestBuildError struct {
	// Err is the underlying error from [http.NewRequestWithContext].
	Err error
}

type RequestError struct {
	// Method is the HTTP method (e.g. "GET", "POST").
	Method string
	// Path is the route path template (e.g. "/users/{id}").
	Path string
	// Err is the underlying transport error from [http.Client.Do].
	Err error
}

type ResponseBodyError struct {
	// Err is the underlying error from reading the response body.
	Err error
}

type SSEHandlerFunc[Req, Event any] func(ctx context.Context, req Req, send func(Event) error) error

type UnexpectedStatusError struct {
	// Method is the HTTP method used for the request (e.g. "GET", "POST").
	Method string
	// Path is the route path template, not the concrete URL (e.g. "/users/{id}").
	// Use this for log grouping and metrics — it does not contain the base URL or
	// concrete path variable values.
	Path string
	// StatusCode is the HTTP response status code returned by the server.
	StatusCode int
	// Body is the raw response body returned by the server (may be nil or empty).
	Body []byte
}