Documentation
¶
Overview ¶
Package web provides HTTP integration, declarative routing, and middleware support for the Helix framework, built on top of Fiber.
Index ¶
- Constants
- Variables
- func ApplyGlobalGuard(server HTTPServer, guard Guard) error
- func Forbidden(message string) error
- func GlobalErrorHandlerRegistry() *internal.ErrorHandlerRegistry
- func GlobalRouteRegistry() *internal.RouteRegistry
- func RegisterController(server HTTPServer, controller any) error
- func RegisterErrorHandler(server HTTPServer, handler any) error
- func RegisterGuard(server HTTPServer, name string, guard Guard) error
- func RegisterGuardFactory(server HTTPServer, name string, factory GuardFactory) error
- func RegisterInterceptor(server HTTPServer, name string, interceptor Interceptor) error
- func RegisterInterceptorFactory(server HTTPServer, name string, factory InterceptorFactory) error
- func Unauthorized(message string) error
- type Context
- type ErrorDetail
- type ErrorResponse
- type FieldError
- type Guard
- type GuardFactory
- type GuardFunc
- type HTTPController
- type HTTPServer
- type HandlerFunc
- type Interceptor
- type InterceptorFactory
- type InterceptorFunc
- type Option
- type RequestError
- type RouteObservation
- type RouteObserver
- type ValidationErrorResponse
Constants ¶
const ( // DefaultMaxCacheEntries is the default maximum number of entries in the cache. DefaultMaxCacheEntries = 1000 // DefaultEvictionStrategy is the default eviction strategy (LRU). DefaultEvictionStrategy = "lru" // DefaultSweepInterval is the default interval for proactive cache sweep. DefaultSweepInterval = 30 * time.Second // MaxCacheBodySize is the maximum response body size allowed in the cache (1MB). MaxCacheBodySize = 1024 * 1024 )
Variables ¶
var ErrInvalidController = errors.New("web: invalid controller")
ErrInvalidController is returned when a controller cannot be registered.
var ErrInvalidDirective = errors.New("web: invalid directive")
ErrInvalidDirective is returned when a Helix directive comment cannot be parsed.
var ErrInvalidErrorHandler = errors.New("web: invalid error handler")
ErrInvalidErrorHandler is returned when a centralized error handler cannot be registered.
var ErrInvalidRequest = errors.New("web: invalid request")
ErrInvalidRequest is returned when request binding or validation fails before a controller handler can be called.
var ErrInvalidRoute = errors.New("web: invalid route")
ErrInvalidRoute is returned when a route cannot be registered.
var ErrUnsupportedHandler = errors.New("web: unsupported handler")
ErrUnsupportedHandler is returned when a controller method signature cannot be adapted to HandlerFunc.
Functions ¶
func ApplyGlobalGuard ¶
func ApplyGlobalGuard(server HTTPServer, guard Guard) error
ApplyGlobalGuard registers a global guard that runs before any handler.
func GlobalErrorHandlerRegistry ¶
func GlobalErrorHandlerRegistry() *internal.ErrorHandlerRegistry
GlobalErrorHandlerRegistry returns the global error handler registry for accessing pre-generated handlers. This is primarily used for testing and accessing generated handler metadata.
func GlobalRouteRegistry ¶
func GlobalRouteRegistry() *internal.RouteRegistry
GlobalRouteRegistry returns the global route registry for accessing pre-generated routes. This is primarily used for testing and accessing generated route metadata.
func RegisterController ¶
func RegisterController(server HTTPServer, controller any) error
RegisterController registers conventional REST routes for a marked controller. Routes are registered on the provided server before Start().
func RegisterErrorHandler ¶
func RegisterErrorHandler(server HTTPServer, handler any) error
RegisterErrorHandler registers centralized error mappings on a Helix server.
func RegisterGuard ¶
func RegisterGuard(server HTTPServer, name string, guard Guard) error
RegisterGuard registers a named guard on a Helix server.
func RegisterGuardFactory ¶
func RegisterGuardFactory(server HTTPServer, name string, factory GuardFactory) error
RegisterGuardFactory registers a named guard factory on a Helix server.
func RegisterInterceptor ¶
func RegisterInterceptor(server HTTPServer, name string, interceptor Interceptor) error
RegisterInterceptor registers a named interceptor on a Helix server.
func RegisterInterceptorFactory ¶
func RegisterInterceptorFactory(server HTTPServer, name string, factory InterceptorFactory) error
RegisterInterceptorFactory registers a named interceptor factory on a Helix server.
func Unauthorized ¶
Unauthorized returns a structured 401 error for guards.
Types ¶
type Context ¶
type Context interface {
Method() string
Path() string
OriginalURL() string
Param(key string) string
Query(key string) string
Header(key string) string
IP() string
Body() []byte
Status(code int)
SetHeader(key, value string)
Send(body []byte) error
JSON(body any) error
// Context returns the request context.
Context() context.Context
// Locals stores or retrieves a request-scoped value by key.
// Call with one value argument to set; call with no value argument to get.
Locals(key string, value ...any) any
}
Context exposes request data to Helix handlers without leaking the underlying HTTP framework context.
type ErrorDetail ¶
type ErrorDetail struct {
Type string `json:"type"`
Message string `json:"message"`
Field string `json:"field"`
Code string `json:"code"`
}
ErrorDetail contains a single machine-readable request error.
type ErrorResponse ¶
type ErrorResponse struct {
Error ErrorDetail `json:"error"`
}
ErrorResponse is the structured JSON error envelope returned by Helix.
type FieldError ¶
FieldError represents a single validation error for a field.
type GuardFactory ¶
GuardFactory creates a guard from a directive argument.
type GuardFunc ¶
GuardFunc adapts a function to Guard.
func (GuardFunc) CanActivate ¶
CanActivate runs f for a request.
type HTTPController ¶
type HTTPController interface{}
HTTPController is the marker interface for Helix controller components. It is an empty interface used as a type constraint for auto-discovery — components registered in the DI container that satisfy this interface are automatically registered with the HTTP server.
A struct satisfies HTTPController when it embeds helix.Controller:
type UserController struct {
helix.Controller
}
The embed provides no methods — the framework detects the helix.Controller field via struct reflection inside RegisterController.
type HTTPServer ¶
type HTTPServer interface {
Start(addr string) error
Stop(ctx context.Context) error
RegisterRoute(method, path string, handler HandlerFunc) error
// ServeHTTP executes a request against the server without starting a
// network listener. Intended for use in tests and tooling.
ServeHTTP(req *http.Request) (*http.Response, error)
// IsGeneratedOnly returns true if the server is configured to only use
// pre-generated route and error handler metadata.
IsGeneratedOnly() bool
}
HTTPServer exposes Helix's minimal HTTP server contract.
func NewServer ¶
func NewServer(opts ...Option) HTTPServer
NewServer creates an HTTP server backed by an internal Fiber adapter.
type HandlerFunc ¶
HandlerFunc handles a request through the Helix HTTP abstraction.
type Interceptor ¶
type Interceptor interface {
Intercept(Context, HandlerFunc) error
}
Interceptor wraps request handling around a route handler.
type InterceptorFactory ¶
type InterceptorFactory func(argument string) (Interceptor, error)
InterceptorFactory creates an interceptor from a directive argument.
type InterceptorFunc ¶
type InterceptorFunc func(Context, HandlerFunc) error
InterceptorFunc adapts a function to Interceptor.
func (InterceptorFunc) Intercept ¶
func (f InterceptorFunc) Intercept(ctx Context, next HandlerFunc) error
Intercept runs f for a request.
type Option ¶
type Option func(*serverOptions)
Option configures an HTTP server.
func WithGeneratedOnly ¶
func WithGeneratedOnly() Option
WithGeneratedOnly disables AST-parsing fallback for route and error handler discovery, requiring all directives to be pre-generated.
func WithRouteObserver ¶
func WithRouteObserver(observer RouteObserver) Option
WithRouteObserver installs a RouteObserver that receives an observation for every HTTP request handled by the server. A nil or typed-nil observer is silently ignored.
func WithTracerProvider ¶
func WithTracerProvider(tp trace.TracerProvider) Option
WithTracerProvider installs an OpenTelemetry TracerProvider that automatically creates a span for every incoming HTTP request and propagates the W3C trace context via traceparent/tracestate headers. A nil provider is silently ignored — tracing is disabled.
type RequestError ¶
type RequestError struct {
// contains filtered or unexported fields
}
RequestError carries an HTTP status and structured response for request binding failures. It is intentionally small until the central error handler story introduces global customization.
func (*RequestError) ErrorCode ¶
func (e *RequestError) ErrorCode() string
ErrorCode returns the machine-readable error code.
func (*RequestError) ErrorField ¶
func (e *RequestError) ErrorField() string
ErrorField returns the field associated with this error, when any.
func (*RequestError) ErrorType ¶
func (e *RequestError) ErrorType() string
ErrorType returns the structured error type name.
func (*RequestError) ResponseBody ¶
func (e *RequestError) ResponseBody() any
ResponseBody returns the JSON body to encode for this error.
func (*RequestError) StatusCode ¶
func (e *RequestError) StatusCode() int
StatusCode returns the HTTP status code to write.
func (*RequestError) Unwrap ¶
func (e *RequestError) Unwrap() error
Unwrap keeps request errors compatible with errors.Is(err, ErrInvalidRequest).
type RouteObservation ¶
RouteObservation carries the observed data for a single handled HTTP request.
type RouteObserver ¶
type RouteObserver interface {
Observe(RouteObservation)
}
RouteObserver receives observations about handled HTTP requests.
type ValidationErrorResponse ¶
type ValidationErrorResponse struct {
Errors []FieldError `json:"errors"`
}
ValidationErrorResponse is the JSON envelope for multiple validation errors.
Source Files
Directories