Documentation
¶
Overview ¶
Package httpapi provides the HTTP transport and middleware adapters.
Index ¶
- Constants
- func ErrorHandler(mapper ErrorMapper) v1.ErrorHandler
- func RequestID(ctx context.Context) (string, bool)
- func TracerProvider(provider trace.TracerProvider) trace.TracerProvider
- func ValidateJSONUnicode(next http.Handler) http.Handler
- func Wrap(next http.Handler, options Options) (http.Handler, error)
- type AccessLogOptions
- type ApplicationError
- type ApplicationErrorClassifier
- type Error
- type ErrorMapper
- type Middleware
- type Next
- type Options
- type Request
- type Response
- type Security
Constants ¶
const ( // RequestIDHeader is the only request correlation header owned by the server. RequestIDHeader = "X-PowerContext-Request-ID" // SelectionDigestHeader and ReportDigestHeader carry canonical report identities. SelectionDigestHeader = "X-PowerContext-Selection-Digest" ReportDigestHeader = "X-PowerContext-Report-Digest" )
Variables ¶
This section is empty.
Functions ¶
func ErrorHandler ¶
func ErrorHandler(mapper ErrorMapper) v1.ErrorHandler
ErrorHandler returns the error adapter used by the generated server. Decode failures are deliberately normalized to FastAPI's 422 contract and raw error strings are never returned to clients.
func RequestID ¶
RequestID returns the server-owned identifier for the current ingress request. Caller-provided correlation headers are deliberately ignored.
func TracerProvider ¶
func TracerProvider(provider trace.TracerProvider) trace.TracerProvider
TracerProvider wraps the provider passed to ogen so request IDs are bound as soon as ogen creates its ingress span. Unlike ogen middleware, this also runs for requests rejected during security or decoding.
func ValidateJSONUnicode ¶
ValidateJSONUnicode rejects malformed UTF-8 and unpaired JSON surrogate escapes before Go's JSON decoder replaces them with U+FFFD. Pydantic rejects the same input at the Python transport boundary; preserving that distinction also prevents malformed private input from reaching application handlers.
Types ¶
type AccessLogOptions ¶
type ApplicationError ¶
type ApplicationErrorClassifier ¶
type ApplicationErrorClassifier func(error) ApplicationError
type Error ¶
type Error struct {
Code string `json:"code"`
Message string `json:"message"`
Details map[string]any `json:"details"`
}
Error is the stable wire-level error detail. Details is encoded as JSON null when absent, matching the frozen Python envelope.
type ErrorMapper ¶
ErrorMapper maps application/domain errors at the transport boundary. The bool is false when the mapper does not recognize an error.
type Middleware ¶
type Middleware = middleware.Middleware
These aliases keep the request-ID middleware signature readable without introducing a transport abstraction parallel to ogen.
func LogApplicationFailures ¶
func LogApplicationFailures(logger *slog.Logger, classify ApplicationErrorClassifier) Middleware
LogApplicationFailures records decoded application failures and cancellations. Successful operations are already represented by metrics and spans and intentionally remain silent, matching the frozen Python behavior.
func TraceApplication ¶
func TraceApplication(provider trace.TracerProvider) Middleware
TraceApplication records the decoded application operation as a child of ogen's transport span. Decode/security failures therefore remain transport failures and never masquerade as entered application work.
type Next ¶
type Next = middleware.Next
These aliases keep the request-ID middleware signature readable without introducing a transport abstraction parallel to ogen.
type Options ¶
type Options struct {
BearerToken string
HandoffReportRoutes bool
Access *AccessLogOptions
}
Options configures transport-only behavior around the generated server.
type Request ¶
type Request = middleware.Request
These aliases keep the request-ID middleware signature readable without introducing a transport abstraction parallel to ogen.
type Response ¶
type Response = middleware.Response
These aliases keep the request-ID middleware signature readable without introducing a transport abstraction parallel to ogen.
func BindSpanRequestID ¶
BindSpanRequestID is an ogen middleware. ogen starts the ingress span before invoking middleware, so this is the first point where its final span ID is available. The outer response writer reads the same requestState when it commits headers.
func ValidatePowerContextContract ¶
ValidatePowerContextContract supplements ogen's OpenAPI 3.0 validation with the few cross-field rules that the schema format cannot encode. Requests are rejected before application telemetry and endpoint dispatch; invalid responses are treated as server failures.
type Security ¶
type Security struct {
// contains filtered or unexported fields
}
Security satisfies ogen's optional OpenAPI bearer scheme. Enforcement is performed by Wrap because authentication also covers metrics, MCP and the Dashboard; keeping this handler permissive when disabled preserves the contract's anonymous alternative.
func NewSecurity ¶
func (*Security) HandleBearerAuth ¶
func (s *Security) HandleBearerAuth(ctx context.Context, _ v1.OperationName, auth v1.BearerAuth) (context.Context, error)
Source Files