Documentation
¶
Overview ¶
Package response provides the v2 response handler with a centralized error handler registry and pluggable renderers.
The error handler registry allows applications to register per-status-code handlers for customized error responses. The v2 response handler delegates to the v1 github.com/hmmftg/requestCore/response.WebHanlder for the actual Splunk transaction pipeline and localization, adding only the registry layer on top.
Index ¶
- func DefaultErrorHandlers() map[int]v2wf.ErrorHandler
- func DefaultStatusResolver(err error) int
- func DispatchError(h *Handler, ctx *v2wf.RequestContext, err error)
- func EnsureErrorResponse(req *v2wf.RequestContext, status int, renderer renderers.Renderer, body any) error
- func EnsureJSONErrorResponse(req *v2wf.RequestContext, status int, code, description string) error
- func FallbackInternalServerError(ctx *v2wf.RequestContext)
- func LegacyFallback(legacyHandler legacyResponse.WebHanlder) v2wf.ErrorHandler
- func MarshalErrorResponse(body ErrorResponse) ([]byte, error)
- func SanitizeError(err error) error
- type DefaultRegistry
- func (r *DefaultRegistry) Freeze()
- func (r *DefaultRegistry) Handle(req *webFramework.RequestContext, err error) error
- func (r *DefaultRegistry) Register(status int, handler webFramework.ErrorHandler) error
- func (r *DefaultRegistry) Resolve(err error) int
- func (r *DefaultRegistry) SetFallback(handler webFramework.ErrorHandler) error
- type ErrorResponse
- type ErrorResponseEntry
- type Handler
- func (h *Handler) DefaultRenderer() renderers.Renderer
- func (h *Handler) Error(req *v2wf.RequestContext, err error) error
- func (h *Handler) LegacyHandler() legacyResponse.WebHanlder
- func (h *Handler) NoContent(req *v2wf.RequestContext) error
- func (h *Handler) OK(req *v2wf.RequestContext, data any) error
- func (h *Handler) OKTyped[Resp any](req *v2wf.RequestContext, resp Resp) error
- func (h *Handler) OKWithRenderer(req *v2wf.RequestContext, renderer renderers.Renderer, data any) error
- func (h *Handler) OKWithStatus(req *v2wf.RequestContext, status int, data any) error
- func (h *Handler) OKWithStatusAndRenderer(req *v2wf.RequestContext, status int, renderer renderers.Renderer, data any) error
- func (h *Handler) OKWithStatusTyped[Resp any](req *v2wf.RequestContext, status int, resp Resp) error
- func (h *Handler) Redirect(req *v2wf.RequestContext, status int, url string) error
- func (h *Handler) Registry() Registry
- type Registry
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultErrorHandlers ¶
func DefaultErrorHandlers() map[int]v2wf.ErrorHandler
DefaultErrorHandlers returns a map of default error handlers for common HTTP status codes. These are opt-in presets; applications can register them individually or override with custom handlers.
Each handler writes a structured JSON error response using the JSONRenderer and emits a mandatory webFramework.AddLog failure entry so the error flows into the Splunk transaction pipeline.
func DefaultStatusResolver ¶
DefaultStatusResolver resolves the HTTP status code from an error by inspecting known error types in order:
- libError.ErrorData via Action().Status
- response.ErrorState via GetStatus()
- Any type implementing interface{ HTTPStatus() int }
- Fallback to 500 Internal Server Error
func DispatchError ¶
func DispatchError(h *Handler, ctx *v2wf.RequestContext, err error)
DispatchError is the shared adapter error-dispatch helper. It routes an error through the v2 response handler's registry if one is configured, emits mandatory AddLog failure entries, and falls back to a sanitized 500 JSON response if the registry fails or is unset.
All framework adapters (Gin, Fiber, chi, net/http) should call this instead of duplicating hard-coded fallback logic.
func EnsureErrorResponse ¶
func EnsureErrorResponse(req *v2wf.RequestContext, status int, renderer renderers.Renderer, body any) error
EnsureErrorResponse sends a structured error response using the given renderer.
func EnsureJSONErrorResponse ¶
func EnsureJSONErrorResponse(req *v2wf.RequestContext, status int, code, description string) error
EnsureJSONErrorResponse is a helper that encodes an error response as JSON and sends it through the v2 parser. It is used by custom error handlers that need to send structured error responses.
func FallbackInternalServerError ¶
func FallbackInternalServerError(ctx *v2wf.RequestContext)
FallbackInternalServerError writes a hard-coded 500 JSON response and marks the context committed. It is used when no response handler is configured.
func LegacyFallback ¶
func LegacyFallback(legacyHandler legacyResponse.WebHanlder) v2wf.ErrorHandler
LegacyFallback creates a fallback error handler that delegates to the v1 response.WebHanlder.Error method. This preserves the existing localization, sanitization, and Splunk transaction pipeline behavior.
The legacyHandler must be non-nil. The legacyWebFramework is extracted from the RequestContext.
func MarshalErrorResponse ¶
func MarshalErrorResponse(body ErrorResponse) ([]byte, error)
MarshalErrorResponse encodes an ErrorResponse to JSON bytes. Useful for testing.
func SanitizeError ¶
SanitizeError converts an arbitrary error into a libError.ErrorData with InternalServerError status if it is not already a known error type. This is used by fallback handlers to avoid leaking raw error strings.
Types ¶
type DefaultRegistry ¶
type DefaultRegistry struct {
// contains filtered or unexported fields
}
DefaultRegistry is the default Registry implementation.
func NewRegistry ¶
func NewRegistry(resolver webFramework.StatusResolver) *DefaultRegistry
NewRegistry creates a new DefaultRegistry with the given status resolver. If resolver is nil, DefaultStatusResolver is used.
func (*DefaultRegistry) Freeze ¶
func (r *DefaultRegistry) Freeze()
Freeze prevents further registration.
func (*DefaultRegistry) Handle ¶
func (r *DefaultRegistry) Handle(req *webFramework.RequestContext, err error) error
Handle invokes the appropriate error handler for the given error.
func (*DefaultRegistry) Register ¶
func (r *DefaultRegistry) Register(status int, handler webFramework.ErrorHandler) error
Register associates a handler with an HTTP status code.
func (*DefaultRegistry) Resolve ¶
func (r *DefaultRegistry) Resolve(err error) int
Resolve determines the HTTP status code for an error.
func (*DefaultRegistry) SetFallback ¶
func (r *DefaultRegistry) SetFallback(handler webFramework.ErrorHandler) error
SetFallback sets the fallback error handler.
type ErrorResponse ¶
type ErrorResponse struct {
Errors []ErrorResponseEntry `json:"errors"`
}
ErrorResponse is the standard v2 error response body.
type ErrorResponseEntry ¶
type ErrorResponseEntry struct {
Code string `json:"code"`
Description string `json:"description"`
}
ErrorResponseEntry represents a single error in a structured error response.
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler is the v2 response handler. It provides renderer-based response methods and delegates error handling to the error handler registry.
Unlike the v1 ResponseHandler interface, the v2 Handler takes *webFramework.RequestContext (which carries both v1 and v2 framework objects). It does not implement the v1 ResponseHandler interface because the context types differ. Use LegacyHandler() to obtain the underlying v1 WebHanlder for code that expects the v1 interface.
func NewHandler ¶
func NewHandler(registry Registry, defaultRenderer renderers.Renderer, legacyHandler legacyResponse.WebHanlder) *Handler
NewHandler creates a v2 response Handler with the given registry, default renderer, and legacy handler for fallback.
func (*Handler) DefaultRenderer ¶
DefaultRenderer returns the default renderer.
func (*Handler) Error ¶
func (h *Handler) Error(req *v2wf.RequestContext, err error) error
Error handles an error through the error handler registry.
func (*Handler) LegacyHandler ¶
func (h *Handler) LegacyHandler() legacyResponse.WebHanlder
LegacyHandler returns the v1 WebHanlder for fallback/delegation.
func (*Handler) NoContent ¶
func (h *Handler) NoContent(req *v2wf.RequestContext) error
NoContent sends a 204 No Content response.
func (*Handler) OK ¶
func (h *Handler) OK(req *v2wf.RequestContext, data any) error
OK sends a successful response with the default renderer at HTTP 200.
func (*Handler) OKTyped ¶
func (h *Handler) OKTyped[Resp any](req *v2wf.RequestContext, resp Resp) error
OKTyped renders a typed response with the default renderer at HTTP 200. This is a convenience wrapper around OK that preserves compile-time type information at the call site, eliminating the `any` parameter.
func (*Handler) OKWithRenderer ¶
func (h *Handler) OKWithRenderer(req *v2wf.RequestContext, renderer renderers.Renderer, data any) error
OKWithRenderer sends a successful response with the given renderer at HTTP 200.
func (*Handler) OKWithStatus ¶
OKWithStatus sends a successful response with the default renderer at the given status.
func (*Handler) OKWithStatusAndRenderer ¶
func (h *Handler) OKWithStatusAndRenderer(req *v2wf.RequestContext, status int, renderer renderers.Renderer, data any) error
OKWithStatusAndRenderer sends a successful response with the given renderer and status.
func (*Handler) OKWithStatusTyped ¶
func (h *Handler) OKWithStatusTyped[Resp any](req *v2wf.RequestContext, status int, resp Resp) error
OKWithStatusTyped renders a typed response with the default renderer at the given status. This preserves compile-time type information.
type Registry ¶
type Registry interface {
// Register associates a handler with an HTTP status code.
// Returns an error if the status code is invalid or the registry is frozen.
Register(status int, handler webFramework.ErrorHandler) error
// SetFallback sets the fallback handler invoked when no handler is
// registered for a given status code. The default fallback delegates
// to the v1 WebHanlder.Error method.
SetFallback(handler webFramework.ErrorHandler) error
// Resolve determines the HTTP status code for an error.
Resolve(err error) int
// Handle invokes the appropriate error handler for the given error.
// It resolves the status, looks up a registered handler (or fallback),
// and invokes it. If the handler fails to write a response, the
// fallback is invoked exactly once.
Handle(req *webFramework.RequestContext, err error) error
// Freeze prevents further registration. Called after startup.
Freeze()
}
Registry is the error handler registry interface. It is mutable during startup and frozen before serving.
Source Files