httpx

package
v2.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 2, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package httpx provides HTTP utilities, including RFC 9457 Problem Details helpers.

Index

Constants

View Source 
const (
	TypeBadRequest         = "bad-request"
	TypeValidation         = "validation-error"
	TypeUnauthorized       = "unauthorized"
	TypeForbidden          = "forbidden"
	TypeNotFound           = "not-found"
	TypeConflict           = "conflict"
	TypePayloadTooLarge    = "payload-too-large"
	TypeRateLimited        = "rate-limit-exceeded"
	TypeServiceUnavailable = "service-unavailable"
	TypeInternal           = "internal-error"
)

Standard problem type slugs.

View Source 
const DefaultTypeBase = "https://api-toolkit.dev/problems"

DefaultTypeBase is the canonical base URI for toolkit problem types.

View Source 
const ValidationErrorsKey = "validation"

ValidationErrorsKey is the canonical extension key for field errors.

Variables

View Source 
var (
	ErrUnauthorized    = errors.New("unauthorized")
	ErrForbidden       = errors.New("forbidden")
	ErrTooManyRequests = errors.New("rate limit exceeded")
)

Sentinel errors for common HTTP categories.

View Source 
var (
	ErrHeaderBytesExceeded = errors.New("request headers exceed max bytes")
	ErrHeaderCountExceeded = errors.New("request headers exceed max count")
)
View Source 
var (
	HeaderLimitsStrict   = HeaderLimits{MaxBytes: 32 << 10, MaxCount: 40}
	HeaderLimitsBalanced = HeaderLimits{MaxBytes: 64 << 10, MaxCount: 100}
	HeaderLimitsRelaxed  = HeaderLimits{MaxBytes: 1 << 20, MaxCount: 200}
)

Functions

func DefaultTypeForStatus 

func DefaultTypeForStatus(status int) string

DefaultTypeForStatus returns the standard type URI for a status code.

func DefaultTypeURI 

func DefaultTypeURI(slug string) string

DefaultTypeURI resolves a standard type slug to a full URI.

func HeaderBytes 

func HeaderBytes(h http.Header) int

HeaderBytes returns an approximate size for header names and values.

func HeaderCount 

func HeaderCount(h http.Header) int

HeaderCount returns the total number of header values.

func TypeURI 

func TypeURI(base, slug string) string

TypeURI builds a type URI from base and slug.

func WriteError 

func WriteError(w http.ResponseWriter, err error)

WriteError maps an error to a Problem Details response.

func WriteErrorStrict 

func WriteErrorStrict(w http.ResponseWriter, err error)

WriteErrorStrict maps an error to a Problem Details response with redaction.

func WriteErrorWithOptions 

func WriteErrorWithOptions(w http.ResponseWriter, err error, opts ErrorOptions)

WriteErrorWithOptions maps an error to Problem Details using custom options.

func WriteJSON 

func WriteJSON(w http.ResponseWriter, status int, v any)

WriteJSON writes a JSON response with a buffered marshal to avoid partial writes.

func WriteProblem 

func WriteProblem(w http.ResponseWriter, status int, p Problem)

WriteProblem writes a problem details response with the provided status code. It merges extension fields after the standard members, per RFC 9457.

func WriteProblemWithFieldErrors 

func WriteProblemWithFieldErrors(w http.ResponseWriter, status int, p Problem, errs fielderrors.FieldErrors)

WriteProblemWithFieldErrors writes problem details with field errors attached.

func WriteSimpleProblem 

func WriteSimpleProblem(w http.ResponseWriter, status int, title, detail string)

WriteSimpleProblem is a convenience for common cases.

Types

type ErrorMode 

type ErrorMode int

ErrorMode controls how problems are produced from errors. 

const (
	// ErrorModeDefault preserves details for non-internal errors.
	ErrorModeDefault ErrorMode = iota
	// ErrorModeStrict redacts details for 5xx responses.
	ErrorModeStrict
)

type ErrorOptions 

type ErrorOptions struct {
	Mode         ErrorMode
	TypeRegistry *TypeRegistry
}

ErrorOptions customizes how errors are mapped to problems.

type HTTPError 

type HTTPError struct {
	Status int
	Title  string
	Detail string
	Type   string
	Err    error
}

HTTPError carries an explicit HTTP status and response detail.

func NewHTTPError 

func NewHTTPError(status int, detail string) *HTTPError

NewHTTPError constructs an HTTPError with status and detail.

func (*HTTPError) Error 

func (e *HTTPError) Error() string

func (*HTTPError) Unwrap 

func (e *HTTPError) Unwrap() error

type HeaderLimits 

type HeaderLimits struct {
	// MaxBytes caps the approximate header bytes (name + value + separators).
	MaxBytes int
	// MaxCount caps the total number of header values.
	MaxCount int
}

HeaderLimits defines request header size/count limits.

func (HeaderLimits) ApplyServer 

func (l HeaderLimits) ApplyServer(s *http.Server)

ApplyServer sets MaxHeaderBytes using the configured limit.

func (HeaderLimits) Check 

func (l HeaderLimits) Check(r *http.Request) error

Check validates the request headers against configured limits.

type Problem 

type Problem struct {
	Type     string         `json:"type,omitempty"`     // "https://example.com/validation-error"`
	Title    string         `json:"title,omitempty"`    // "Bad Request"`
	Status   int            `json:"status,omitempty"`   // 400
	Detail   string         `json:"detail,omitempty"`   // "name is required"
	Instance string         `json:"instance,omitempty"` // "/api/v1/foo/123"
	Ext      map[string]any `json:"-"`
}

Problem represents an RFC 9457 problem details response body. RFC 9457 obsoletes RFC 7807. See: https://www.rfc-editor.org/rfc/rfc9457.html

func ProblemFromError 

func ProblemFromError(err error) (Problem, int)

ProblemFromError maps errors to a Problem and HTTP status code.

func ProblemFromErrorStrict 

func ProblemFromErrorStrict(err error) (Problem, int)

ProblemFromErrorStrict redacts 5xx details to avoid internal leakage.

func ProblemFromErrorWithOptions 

func ProblemFromErrorWithOptions(err error, opts ErrorOptions) (Problem, int)

ProblemFromErrorWithOptions maps errors to a Problem using custom options.

func WithFieldErrors 

func WithFieldErrors(p Problem, errs fielderrors.FieldErrors) Problem

WithFieldErrors attaches field-level errors to a problem payload.

func WithValidationErrors 

func WithValidationErrors(p Problem, errs fielderrors.FieldErrors) Problem

WithValidationErrors attaches canonical validation errors to a problem payload.

func (*Problem) With 

func (p *Problem) With(key string, value any) *Problem

With adds an extension field to the problem payload.

type TypeRegistry 

type TypeRegistry struct {
	// contains filtered or unexported fields
}

TypeRegistry helps build consistent problem type URIs.

func DefaultTypeRegistry 

func DefaultTypeRegistry() *TypeRegistry

DefaultTypeRegistry returns a registry with the toolkit's standard type slugs.

func NewTypeRegistry 

func NewTypeRegistry(base string, slugs ...string) *TypeRegistry

NewTypeRegistry registers slugs against a base URI.

func (*TypeRegistry) Register 

func (r *TypeRegistry) Register(slug string) string

Register adds a slug to the registry and returns its URI.

func (*TypeRegistry) Types 

func (r *TypeRegistry) Types() map[string]string

Types returns a copy of the registered type map.

func (*TypeRegistry) URI 

func (r *TypeRegistry) URI(slug string) string

URI returns the full URI for a slug, falling back to base + slug.

type ValidationErrors 

type ValidationErrors struct {
	Fields fielderrors.FieldErrors `json:"fields,omitempty"`
}

ValidationErrors wraps field-level validation errors for Problem extensions.

Source Files

View all Source files

Directories

Path Synopsis
Package identity provides identity utilities.
 Package identity provides identity utilities.
Package recover provides recover utilities.
 Package recover provides recover utilities.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.