httpapi

package
v0.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 23, 2026 License: AGPL-3.0 Imports: 12 Imported by: 0

Documentation

Overview

Package httpapi contains HTTP trust-boundary primitives shared by handlers.

Index

Constants

View Source
const Redacted = "[REDACTED]"

Variables

This section is empty.

Functions

func NewRequestID

func NewRequestID() (string, error)

NewRequestID returns a cryptographically random lowercase UUIDv4.

func RedactText

func RedactText(text string, secrets ...Secret) string

RedactText removes explicit secret values and supported token/session syntax.

func StatusCode

func StatusCode(err error) int

StatusCode maps a classified error to its stable HTTP status.

func StrictJSON

func StrictJSON[T any](body io.Reader, maxBytes int64, next func(T) error) error

StrictJSON bounds and strictly decodes one object before invoking next. The callback is never invoked for malformed, duplicate-key, unknown-field, or type-invalid input.

func WriteError

func WriteError(w http.ResponseWriter, requestID string, err error)

WriteError emits one deterministic DANS error response.

Types

type APIError

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

APIError retains an internal cause while exposing only a stable public kind.

func NewDetailedError

func NewDetailedError(kind ErrorKind, cause error, details ...string) *APIError

NewDetailedError adds already-sanitized public validation details.

func NewError

func NewError(kind ErrorKind, cause error) *APIError

NewError classifies cause without exposing its text to clients.

func (*APIError) Error

func (e *APIError) Error() string

func (*APIError) Unwrap

func (e *APIError) Unwrap() error

Unwrap preserves the internal cause for server-side inspection.

type ErrorKind

type ErrorKind string

ErrorKind is a stable class of DANS-originated failure.

const (
	KindBadRequest      ErrorKind = "bad_request"
	KindInvalidRequest  ErrorKind = "invalid_request"
	KindUnauthenticated ErrorKind = "unauthenticated"
	KindForbidden       ErrorKind = "forbidden"
	KindNotFound        ErrorKind = "not_found"
	KindConflict        ErrorKind = "conflict"
	KindBodyTooLarge    ErrorKind = "body_too_large"
	// KindRateLimited is a retryable throttle: a bucket lacks tokens now.
	KindRateLimited ErrorKind = "rate_limited"
	// KindRateLimitCapacity is not retryable: the request cost exceeds a
	// bucket's capacity, so it can never be admitted as sent.
	KindRateLimitCapacity ErrorKind = "rate_limit_capacity"
	KindUnavailable       ErrorKind = "unavailable"
	KindBadGateway        ErrorKind = "bad_gateway"
	KindGatewayTimeout    ErrorKind = "gateway_timeout"
	KindInternal          ErrorKind = "internal"
)

type ErrorResponse

type ErrorResponse struct {
	Error  string   `json:"error"`
	Errors []string `json:"errors,omitzero"`
}

ErrorResponse is the PowerDNS-compatible body for a DANS-originated error.

func ErrorBody

func ErrorBody(err error) ErrorResponse

ErrorBody maps a classified error to a secret-safe public response.

type Secret

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

Secret wraps a value so common diagnostic encoders redact it by default.

func NewSecret

func NewSecret(value string) Secret

NewSecret marks value as secret-bearing data.

func (Secret) GoString

func (Secret) GoString() string

func (Secret) LogValue

func (Secret) LogValue() slog.Value

LogValue prevents structured slog handlers from recording the value.

func (Secret) MarshalJSON

func (Secret) MarshalJSON() ([]byte, error)

MarshalJSON prevents accidental secret disclosure in JSON diagnostics.

func (Secret) String

func (Secret) String() string

func (Secret) Value

func (s Secret) Value() string

Value explicitly unwraps a secret for its intended protocol use.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL