vatel is a REST framework built on fasthttp and fasthttp/router. An endpoint is a method, a path and a controller factory; vatel decodes path parameters, query string and JSON body into the controller, calls it, serializes the result to JSON and handles errors, logging (with masking of sensitive fields), metrics, authentication and authorization.
go get github.com/axkit/vatel@latestRequires Go 1.26, fasthttp v1.77.0+ and fasthttp/router v1.5.4+ and, for WebSocket, regorov/websocket v0.1.5+ (Go modules raise them in your project automatically). Errors are built with github.com/axkit/errors v1.1.0+. Upgrading from v0.14? See MIGRATION.md.
- Quick start
- Endpoints
- Controllers and carriers
- Input decoding and validation
- Middleware
- Authentication and authorization (
vatel/auth) - Errors
- Logging
- Masking sensitive data
- Request context, timeouts and shutdown
- HEAD, OPTIONS and CORS
- WebSocket
- Other options
A complete runnable application is in example/ (ADDR=:18080 go run ./example).
It verifies HS256 JWTs signed with the JWT_SECRET environment variable (without it, a
public development key is used and a warning is logged). To call the protected
endpoints, mint a development token (user 100, every permission, valid 24 hours) with the
same JWT_SECRET:
TOKEN=$(go run ./example token)
curl -H "Authorization: Bearer $TOKEN" localhost:18080/ordersgo run ./example token 2 mints the token for organization 2 (default 1). The order
endpoints serve only the orders of the token's organization: GET /orders lists them,
GET, PUT and DELETE of /orders/{id} give 404 for an order of another
organization, and POST /orders creates the order in the token's organization. The
example also serves WebSocket on /ws: send {"path":"updateAccessToken","data":{"mid":"<uuid>","at":"<token>"}}
within 10 seconds, then {"path":"orders.watch","data":{"id":1}} (see
Security context and closing connections).
The minimal version:
package main
import (
"context"
"os"
"os/signal"
"syscall"
"time"
"github.com/axkit/errors"
"github.com/axkit/vatel"
"github.com/axkit/vatel/auth"
"github.com/fasthttp/router"
"github.com/rs/zerolog"
)
type Order struct {
ID int `json:"id"`
Product string `json:"product"`
}
var errOrderNotFound = errors.Template("order not found").Code("APP-0001").StatusCode(404)
// GET /orders/{id}
type GetOrder struct {
vatel.PathParams[struct {
ID int `param:"id"`
}]
vatel.Output[Order]
}
func (c *GetOrder) Handle(ctx vatel.Context) error {
if c.Params.ID != 1 {
return errOrderNotFound.New().Set("id", c.Params.ID)
}
c.Out = Order{ID: 1, Product: "Widget"}
return nil
}
// POST /orders
type CreateOrderInput struct {
Product string `json:"product"`
}
// Validate is called by vatel after decoding, before Handle.
func (in *CreateOrderInput) Validate() error {
if in.Product == "" {
return vatel.ErrValidationFailed.New().Set("reason", "product is required")
}
return nil
}
type CreateOrder struct {
vatel.Body[CreateOrderInput]
vatel.Output[Order]
}
func (c *CreateOrder) Handle(ctx vatel.Context) error {
c.Out = Order{ID: 2, Product: c.In.Product}
return nil
}
func OrderEndpoints(cfg *auth.Config) vatel.Endpoints {
read := cfg.RequirePerms(map[string]uint{"orders:read": 0}) // name -> bit position
write := cfg.RequirePerms(map[string]uint{"orders:write": 1})
return vatel.Endpoints{
vatel.GET("/orders/{id}", func() vatel.Handler { return &GetOrder{} }, read),
vatel.POST("/orders", func() vatel.Handler { return &CreateOrder{} }, write,
vatel.WithSuccessStatusCode(201)),
vatel.GET("/healthcheck", vatel.Func(func(ctx vatel.Context) error {
ctx.SetStatusCode(204)
return nil
})),
}
}
func main() {
log := zerolog.New(os.Stdout).With().Timestamp().Logger()
authCfg := &auth.Config{
Decoder: &JWTDecoder{Secret: []byte(os.Getenv("JWT_SECRET"))}, // your vatel.TokenDecoder
Authorizer: &BitsetAuthorizer{}, // your auth.Authorizer
}
v := vatel.NewVatel(
vatel.WithDefaultLogOption(vatel.LogFullOnExit),
vatel.WithRequestID(),
vatel.WithClientErrorFields("reason"),
)
v.AddMiddleware(vatel.OnAuthentication, authCfg.Middleware())
v.Add(OrderEndpoints(authCfg))
mux := router.New()
if err := v.BuildHandlers(mux, &log); err != nil {
log.Fatal().Err(err).Msg("build handlers")
}
go func() {
// nil after Shutdown; ErrServerClosed if Shutdown ran first.
if err := v.ListenAndServe(":8080", mux, &log); err != nil && !errors.Is(err, vatel.ErrServerClosed) {
log.Fatal().Err(err).Msg("server stopped")
}
}()
quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
<-quit
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
if err := v.Shutdown(ctx); err != nil {
log.Error().Err(err).Msg("shutdown")
}
}JWTDecoder and BitsetAuthorizer are application types; see
example/claims.go for a sample implementation (HS256 signature
and exp check with the standard library; a JWT library such as
github.com/golang-jwt/jwt/v5 adds key rotation and other algorithms).
Responses:
GET /orders/1 (token with orders:read) -> 200 {"id":1,"product":"Widget"}
GET /orders/5 (token with orders:read) -> 404 {"msg":"order not found","severity":"unknown","code":"APP-0001","statusCode":404}
GET /orders/1 (no token) -> 401 {"msg":"authentication required","severity":"medium","code":"VTL-0004","statusCode":401}
POST /orders {"product":""} -> 400 {"msg":"validation failed","severity":"tiny","code":"VTL-0006","statusCode":400,"reason":"product is required"}
GET / (under WithUrlPrefix, if set) is registered automatically and returns an HTML
list of all endpoints, WS endpoints included. It is public and cannot be replaced: your
own GET / makes BuildHandlers fail. Keep in mind that it exposes the route list.
An endpoint is created with a builder function: method, path template, controller factory and options.
vatel.GET(path, ctrl, opts...) // also POST, PUT, PATCH, DELETE, HEAD, OPTIONS
vatel.WS(path, wsCtrl, opts...) // WebSocket message endpoint, see belowctrl is a func() vatel.Handler. It is called once per request, so each request gets
its own controller value, and once more during BuildHandlers to inspect the controller
type. Keep it cheap and free of side effects. vatel.Func(f) turns a plain
func(vatel.Context) error into a factory.
Path templates use fasthttp/router syntax: /orders/{id}, /files/{path:*},
/items/{id:[0-9]+}.
Group endpoints with vatel.Endpoints (a []Endpoint that implements Endpointer) or
with your own type that has an Endpoints() []vatel.Endpoint method, and register them
with v.Add(...).
| Option | Effect |
|---|---|
vatel.Perms(names...) |
Appends permission names to EndpointMeta.Perms. On HTTP endpoints this is metadata only; use auth.RequirePerms to enforce permissions. On WS endpoints non-empty Perms require WithWsAuthFunc. |
vatel.WithLogOption(lo) |
Log verbosity of the endpoint (see Logging). |
vatel.WithSuccessStatusCode(code) |
Status of a successful response (default 200). Overrides a status set by the handler. |
vatel.WithManualStatusCode() |
vatel does not set the success status; the handler calls ctx.SetStatusCode. |
vatel.WithContentType(ct) |
Content-Type of the Resulter body (default application/json; charset=utf-8); the body is still JSON-marshalled. A handler writing to ctx.BodyWriter() sets the type itself with ctx.SetContentType. |
vatel.WithCompress() |
Wraps the handler in fasthttp.CompressHandler. |
vatel.WithOptionalBody() |
POST/PUT/PATCH: an empty body is accepted (see below). |
vatel.WithTimeout(d) |
Timeout of the request context (see Request context). |
cfg.RequireAuth(), cfg.RequirePerms(...) |
From vatel/auth. |
An EndpointOption is a func(*vatel.Endpoint), so you can write your own; it may add
per-endpoint middleware with e.AddMiddleware(pos, f).
v.BuildHandlers(mux, &log) validates every endpoint and registers it with the router.
It returns an error for, among others: a path with {params} and a controller that is not
a Paramer (or the reverse; a vatel.Func handler may have {params} and reads them with
ctx.PathValue), a Param(), QueryInput() or GET/DELETE/HEAD/OPTIONS Input() that
does not return a pointer to a struct, a path that does not begin with /, a route the router
rejects (a duplicate or conflicting path, your own GET /), WithOptionalBody on
GET/DELETE/HEAD/OPTIONS, an unknown method, a WS endpoint without WithWebsocketSupport,
a duplicate WS path, WS Perms without WithWsAuthFunc. MustBuildHandlers panics
instead.
Add endpoints (v.Add) and middleware (v.AddMiddleware) before BuildHandlers: it
copies them, later additions have no effect.
BuildHandlers may be called once. Registration is not transactional: after a failed
build the router may hold part of the routes, so the Vatel is unusable; further
BuildHandlers/ListenAndServe calls return a "previous build failed" error. Create a new
Vatel and router.
v.ListenAndServe(addr, mux, &log) builds the handlers if that has not been done yet and
starts a fasthttp.Server with IdleTimeout = vatel.DefaultIdleTimeout (90 s) and
CloseOnShutdown. vatel.WithServerConfig(func(*fasthttp.Server)) changes it (e.g.
ReadTimeout, MaxRequestBodySize, MaxConnsPerIP, a ConnState hook; do not replace
Handler). After Shutdown it returns nil; called after
Shutdown, it returns vatel.ErrServerClosed. You can also serve mux.Handler with your
own server; then Shutdown only cancels request contexts and closes WebSocket
connections (waiting, within its ctx, until they have closed).
A controller implements Handle(vatel.Context) error. Capability interfaces tell vatel
what to decode and what to send back:
| Interface | Method | Purpose |
|---|---|---|
Paramer |
Param() any |
Pointer to a struct with param:"name" fields filled from path parameters. |
Querier |
QueryInput() any |
Pointer to a struct filled from the URL query string, for every HTTP method. |
Inputer |
Input() any |
GET/DELETE/HEAD/OPTIONS: filled from the query string; POST/PUT/PATCH: from the JSON body. |
Resulter |
Result() any |
Value serialized to the JSON response. nil (or a nil pointer) means no body. |
Validator |
Validate() error |
Implemented by an input type; called after decoding. |
The returned pointers must point into the controller (not to a local variable).
Instead of writing these methods, embed the generic carriers:
| Carrier | Field | Implements |
|---|---|---|
vatel.PathParams[T] |
Params T |
Paramer |
vatel.QueryParams[T] |
Query T |
Querier |
vatel.Body[T] |
In T |
Inputer |
vatel.Output[T] |
Out T |
Resulter (always writes a body) |
vatel.OptionalOutput[T] |
Out *T |
Resulter; leave Out nil for no body (204, 304) |
vatel.Upload |
Key, Header |
multipart upload helper, call BindFile(ctx) in Handle |
// POST /customers/{customerId}/orders/search?limit=50
type SearchFilter struct {
Limit int `param:"limit"`
}
type SearchOrders struct {
vatel.PathParams[struct {
CustomerID int `param:"customerId"`
}]
vatel.QueryParams[SearchFilter]
vatel.Body[struct {
Products []string `json:"products"`
}]
vatel.Output[[]Order]
}
func (c *SearchOrders) Handle(ctx vatel.Context) error {
// c.Params.CustomerID, c.Query.Limit, c.In.Products
return nil
}File upload:
type ImportController struct {
vatel.Upload
vatel.Output[ImportResult]
}
func (c *ImportController) Handle(ctx vatel.Context) error {
if err := c.BindFile(ctx); err != nil {
return err
}
f, err := c.Open() // or c.SaveTo(ctx, path), c.StreamTo(w)
if err != nil {
return err
}
defer f.Close()
// ...
return nil
}
vatel.POST("/import", func() vatel.Handler {
return &ImportController{Upload: vatel.Upload{Key: "file"}}
})BindFile returns 400 VTL-0007 (ErrInvalidRequestBody) with field field (the Key)
when the request is not a multipart form or has no such file field.
vatel.Context gives the handler access to the request and the response without exposing
fasthttp: Header, RequestBody, PathValue, QueryValue, FormFile, FormValue,
RemoteAddr (real IP), RequestTime, SetStatusCode, SetHeader, SetContentType,
BodyWriter, SetBodyStream, TokenPayload, Context (Go context), and a per-request
key-value store Set/Get. Values stored with Set are written to the request log.
SetBodyStream(r, size) sends a body that is read only while the response is written, so a
large file is not loaded into memory. size is the length (Content-Length) or -1 if
unknown (chunked encoding); r is closed after the response if it is an io.Closer. A
handler error, a panic or a non-nil Result() replaces the stream and closes it.
vatel.GET("/files/{id}", vatel.Func(func(ctx vatel.Context) error {
f, err := os.Open(pathOf(ctx.PathValue("id")))
if err != nil {
return err
}
st, err := f.Stat()
if err != nil {
f.Close()
return err
}
ctx.SetContentType([]byte("application/octet-stream"))
ctx.SetBodyStream(f, int(st.Size())) // f is closed after the response
return nil
}))SetValue(key, val any) stores a value under any comparable key, typically an unexported
typed key, for code that only gets the Go context: ctx.Context().Value(key) returns it.
A string key is the same as Set; a value under a non-string key is not returned by
Get and is not written to the log.
type patKey struct{}
// middleware (OnAuthorization, OnHandle, ...)
ctx.SetValue(patKey{}, patID)
// business code that receives ctx.Context()
func viaPAT(ctx context.Context) bool { _, ok := ctx.Value(patKey{}).(int64); return ok }The token payload set by the auth middleware is type-asserted to your claims type:
claims := ctx.TokenPayload().(*Claims)Order of steps for a request: path parameters (Paramer), query (Querier), query or
body (Inputer), then validation: Validate() of the Querier input, then Validate()
of the Inputer input. The first error rejects the request with 400.
- Path parameters and query:
int*,uint*,string,bool,float*fields, pointers to them,github.com/axkit/date.Dateand*date.Date; fields of nested structs (embedded or untagged) are flattened. A nested struct of a type already being flattened (a cycle such asParent *Filter) is skipped. A missing query variable leaves the field as is. - A value that cannot be parsed gives 400
VTL-0006(ErrValidationFailed) with fieldparam, and so does an empty date (?from=). So does an integer that does not fit the field (300for auint8,2147483648for anint32): integers are parsed at the size of the field, never truncated. Param(),QueryInput()and the GET/DELETE/HEAD/OPTIONSInput()must return a non-nil pointer to a struct; anything else, a typed nil included, is aBuildHandlerserror.- Body:
encoding/jsoninto theInputervalue. An empty or whitespace-only body gives 400VTL-0007"empty request body, JSON expected"; invalid JSON gives 400VTL-0007"request body is not valid JSON". For an input type withmasktags theencoding/jsonerror is not wrapped, because it may quote a value (a number that does not fit the field, atime.Time); the error carries only the fieldsfield,typeandoffset. - A request body on DELETE is not supported (RFC 9110 leaves its semantics undefined); use
query parameters (
QueryParams).
Declare Validate() on a named type. An anonymous struct (vatel.Body[struct{...}])
cannot have methods, so its Validate() never exists. The method may have a pointer
receiver; it may also set default values.
type SearchFilter struct {
Limit int `param:"limit"`
}
func (f *SearchFilter) Validate() error {
if f.Limit == 0 {
f.Limit = 20
}
if f.Limit > 100 {
return vatel.ErrValidationFailed.New().Set("reason", "limit must be <= 100")
}
return nil
}The client sees ErrValidationFailed: the message "validation failed", status 400 and
code VTL-0006. Any status of the returned error (409, 422, ...) is replaced by 400; the
code of a returned *errors.Error, if it has one, replaces VTL-0006, and its fields
are kept. A plain errors.New("...") text from Validate() reaches the client only with
verbose errors; to
show a reason, set an error field and list it in WithClientErrorFields (see
Errors). Validate() is called on Querier and Inputer input only, not on a
PathParams struct. On a WebSocket endpoint it is called on the Inputer input after the
message data is decoded.
By default POST/PUT/PATCH with an Inputer require a JSON body. With
vatel.WithOptionalBody() an empty or whitespace-only body is accepted: decoding is
skipped, the input stays zero and Validate() is not called, so a Validate() that
fills in defaults does not run. A non-empty body is decoded and validated as usual.
vatel.POST("/orders/{id}/ticket", func() vatel.Handler { return &CreateTicket{} },
vatel.WithOptionalBody())Middleware has the signature func(vatel.Context, vatel.EndpointMeta) error and runs at
a position in the pipeline:
| Position | When |
|---|---|
OnRequest |
First. Rate limiting by IP, CORS headers. |
OnAuthentication |
Decode the token, set the token payload (auth.Config.Middleware). |
OnAuthorization |
Check access (auth.RequireAuth, auth.RequirePerms). Runs before input decoding. |
OnHandle |
After input decoding and validation, before Handle. Per-user limits, audit. |
OnSuccessResponse |
After a successful response is written. The error is ignored: the response is not changed and later middleware still runs. |
OnErrorResponse |
After an error response is written. The error is ignored. |
Global middleware is added with v.AddMiddleware(pos, f...), per-endpoint middleware with
e.AddMiddleware(pos, f...) inside an EndpointOption. At each position global middleware
runs first, then per-endpoint, in the order added. An error returned at
OnRequest..OnHandle stops the request and is written as the error response.
EndpointMeta carries the endpoint's Method, Path (template, with URL prefix),
Perms and LogOptions; every position, including OnErrorResponse, receives it.
func audit(ctx vatel.Context, meta vatel.EndpointMeta) error {
if len(meta.Perms) > 0 {
ctx.Set("perms", meta.Perms) // written to the request log
}
return nil
}
v.AddMiddleware(vatel.OnHandle, audit)
// Per-endpoint middleware as an option.
func RateLimit(perMinute int) vatel.EndpointOption {
return func(e *vatel.Endpoint) {
e.AddMiddleware(vatel.OnHandle, func(ctx vatel.Context, meta vatel.EndpointMeta) error {
// ...
return nil
})
}
}vatel itself does not check tokens. The github.com/axkit/vatel/auth package provides
middleware for a JWT-like token with a bitset of permissions.
cfg := &auth.Config{
Decoder: myDecoder, // vatel.TokenDecoder: Decode([]byte) (vatel.Tokener, error)
Authorizer: myAuthorizer, // auth.Authorizer: IsAllowed(requestPerms []byte, bits ...uint) (bool, error)
RevokeCheck: myRevokeCheck, // optional vatel.RevokeTokenChecker
}
v.AddMiddleware(vatel.OnAuthentication, cfg.Middleware())
v.Add(vatel.Endpoints{
vatel.GET("/healthcheck", healthCtrl), // public
vatel.GET("/users/me", meCtrl, cfg.RequireAuth()), // any valid token
vatel.GET("/orders", listCtrl, cfg.RequirePerms(map[string]uint{"orders:read": 0})),
})Middleware()reads theAuthorizationheader, checks revocation, decodes the token and storesTokener.ApplicationPayload()withctx.SetTokenPayload. If the payload'sDebug()is true, verbose errors are enabled for the request. A missing, invalid, expired or revoked token does not fail the request here: public endpoints serve it as unauthenticated.RequireAuth()rejects a request without a valid token (401; the token error if the token was bad).RequirePerms(map[string]uint)maps permission names to bit positions. It rejects a request without a valid token (401) or without all bits (403VTL-0003). The names are appended, sorted, toEndpointMeta.Perms. A nilAuthorizergives 500 instead of a panic.Config.Decoderis required withMiddleware(). It andRevokeCheckreceive the rawAuthorizationheader value; nothing strips aBearerprefix, so strip it in the decoder. A nilDecoderor aRevokeCheckerror failsRequireAuth/RequirePermsendpoints with 500VTL-0005; public endpoints serve the request as unauthenticated. ADecoderreturning neither a token nor an error counts as a bad token (401).Config.Disabled = trueturns all checks off; it is read on every request without synchronisation, so set it before the server starts serving.
The payload must implement vatel.AuthPayload (Perms() []byte, Debug() bool; the
vatel core does not call them, vatel/auth does); handlers type-assert
ctx.TokenPayload() to the concrete type. vatel.Perms(...) alone does not
protect an HTTP endpoint.
Return any error from Handle, Validate or middleware. Errors from
github.com/axkit/errors carry an HTTP status, a code
and a severity:
var ErrOrderLocked = errors.Template("order is locked").
Code("APP-0042").StatusCode(409).Severity(errors.Medium)
return ErrOrderLocked.New().Set("orderId", id).Set("reason", "payment in progress")
return ErrOrderLocked.Wrap(err)The client receives the message, severity, code and status of the first *errors.Error
(or *errors.ErrorTemplate) in the error chain; a fmt.Errorf("...: %w", err) wrapper
keeps its status and the wrapper text is not sent:
{"msg":"order is locked","severity":"medium","code":"APP-0042","statusCode":409}Fields (Set), wrapped errors and the stack are written to the server log only. To show
selected fields to the client, list them once:
v := vatel.NewVatel(vatel.WithClientErrorFields("reason", "suggestedName"))
// -> {"msg":"order is locked",...,"statusCode":409,"reason":"payment in progress"}The listed fields are written at the root of the error JSON. Do not list fields that may contain internal data.
Verbose errors (stack, all fields, wrapped errors in the response) are enabled for all
requests by vatel.WithVerboseError(true), or per request by a token whose payload
Debug() returns true (or by middleware calling ctx.SetVerboseError(true)). Use them in
development only.
An error chain without *errors.Error (a driver error, errors.New, fmt.Errorf) may
carry internal text, so the client gets a generic error instead: {"msg":"internal error",...,"code":"VTL-0005","statusCode":500}, or "service unavailable" / "gateway
timeout" for 503/504. The original error is logged. With verbose errors the client gets
the original text.
Status of an error without its own status (a plain error, or an *errors.Error with
status 0): 504 if the chain contains context.DeadlineExceeded, 503 for
context.Canceled, 500 otherwise. An error with status 429 and a Retry-After field sets
the Retry-After header. Errors with status >= 500 are passed to the Alarmer
(vatel.WithAlarmer).
vatel recovers a panic anywhere in the pipeline of an HTTP request (middleware,
path/query/body decoding, the handler, response serialization, OnSuccessResponse and
OnErrorResponse middleware) and in a WebSocket message handler; the server keeps
running. The response written so far (status, headers, body) is dropped and the client
gets ErrInternalError: 500, VTL-0005, "internal error" (the panic value only with
verbose errors). The panic value is logged under panic and the stack under stack,
whatever the log level; the request is reported to the metrics once, the Alarmer is
called and OnErrorResponse middleware runs (not when the panic came from a middleware
that runs after the response is written). A WebSocket client gets the error frame and its
connection keeps serving messages. A panic in the WebSocket OnOpen or OnClose callback
is recovered too: it is logged (panic, stack, callback) and the Alarmer is called;
after an OnOpen panic the connection is closed with status 1011 (OnClose is still
called for it).
Predefined errors:
| Error | Code | Status |
|---|---|---|
ErrAuthorizationHeaderMissed |
VTL-0001 | 401 (deprecated: no longer returned, kept for compatibility) |
ErrAccessTokenRevoked |
VTL-0002 | 401 |
ErrForbidden |
VTL-0003 | 403 |
ErrUnauthorized |
VTL-0004 | 401 |
ErrInternalError |
VTL-0005 | 500 |
ErrValidationFailed |
VTL-0006 | 400 |
ErrInvalidRequestBody |
VTL-0007 | 400 |
ErrUnknownPath |
VTL-0008 | 404 (WebSocket message with an unknown path) |
ErrWsContextChanged |
VTL-0009 | 409 (WebSocket reply before closing with 4009, see WebSocket) |
ErrWsTokenConflict |
VTL-0010 | 409 (concurrent UpdateAccessToken for one connection) |
vatel logs with zerolog. Each endpoint logger carries
method, path and client (real IP); WithRequestID() adds reqId. path is the
path as registered, without the WithUrlPrefix prefix (EndpointMeta.Path and metrics
include it). The "new request" and exit lines are logged at debug level, so a logger at
info level hides them; errors are logged at error level.
What is logged is a bitmask (LogOption):
| Bit | Header value | Logs |
|---|---|---|
LogEnter |
enter |
a "new request" line when the request arrives |
LogExit |
exit |
a line when the request completes, with dur |
LogReqBody |
req-body |
request body as requestBody: compacted JSON, or, for an input type with mask tags, the decoded input marshalled and masked |
LogReqInput |
req-input |
decoded input as reqInput (Inputer) and reqQuery (Querier) |
LogRespBody |
resp-body |
response body as respBody |
LogRespOutput |
resp-out |
response as result, only when LogRespBody is not set (the same masked JSON is not logged twice) |
LogSilent |
silent |
nothing except 5xx errors; overrides all other bits |
Presets: LogFull (enter, exit, request body and input, response body), LogFullOnExit
(the same without enter), LogConfidential (exit only).
- The default level is 0: only errors are logged. Set a default with
vatel.WithDefaultLogOption(lo)and override it per endpoint withvatel.WithLogOption(lo). - Errors are logged at error level with the full error (fields, wrapped errors, stack),
the path and query parameters decoded so far and context values. With
LogSilentonly 5xx errors are logged. - Path and query parameters are logged by name; values stored with
ctx.Setare logged as well. A value stored withctx.Set("message", v)replaces the exit line message (a path parameter namedmessagedoes not). - The
X-Set-Log-Levelrequest header (X-Set-Log-Level: exit,req-body) replaces the endpoint level for that one request. It cannot switch offLogSilentof an endpoint;silentin the header silences the request.vatel.WithStaticLoggingLevel()ignores the header. Any client can send this header; useWithStaticLoggingLevel()in production unless every secret in request and response types is tagged withmask.
Tag fields with mask and they are masked in the log. The response sent to the client is
not changed.
type LoginInput struct {
Login string `json:"login"`
Password string `json:"password" mask:"-"` // removed from the log
Card string `json:"card" mask:"secret"` // "***"
Phone string `json:"phone" mask:"phone"` // custom function
}-
mask:"-"removes the field; any other value names a masking function. A name not registered withAddFuncgives"***"(jsonmask.DefaultMask). -
Without
vatel.WithJsonMaskera defaultjsonmask.New()is used, so tagged fields are always masked. Register functions with your own masker:jm := jsonmask.New() jm.AddFunc("phone", func(s string) string { if len(s) < 4 { return jsonmask.DefaultMask } return strings.Repeat("*", len(s)-4) + s[len(s)-4:] }) v := vatel.NewVatel(vatel.WithJsonMasker(jm))
-
Masked log keys:
requestBody,reqInput,reqQuery,respBody,result, including elements of arrays (Body[[]T],Output[[]T]) andOptionalOutput[T]. A result is masked by the rules of the typeResult()returns for the request. If masking fails only the error is logged (requestBodyMaskingFailed,reqInputMaskingFailed,respBodyMaskingFailedorresultMaskingFailed), never the unmasked value. -
The request body of an input type with
masktags is logged as the decoded input, not as the raw body:encoding/jsonalso decodes keys in another letter case ("Password") and the last of duplicate keys, which a path-based masker would miss. A body that cannot be decoded is then not logged (requestBodyLoggingFailed). -
Tags are honoured in nested structs,
*Struct,[]Struct,[]*Structand recursive types. A tagged field is a leaf: a tagged struct, pointer or slice (e.g.time.Time) is masked or removed as a whole. A tag on an embedded struct applies to each promoted field without a tag of its own. Maps andany(interface) values are not visited. Fields absent from the JSON (omitempty) are not added. -
Path and query parameters:
mask:"-"omits the parameter from the log, any other non-emptymasklogs"***". Masking functions are not applied to parameters. Amasktag on a nested struct of a query input applies to its fields without their own tag. An invalid value of a masked parameter gives 400 without the value in the error (not even in verbose responses). The same holds for a JSON body (HTTP or WSdata) of an input type withmasktags that cannot be decoded.
type ResetPassword struct {
vatel.PathParams[struct {
Token string `param:"token" mask:"secret"` // logged as "***"
}]
vatel.QueryParams[struct {
Email string `param:"email" mask:"-"` // not logged
}]
}Types without mask tags are logged unchanged.
ctx.Context() returns a Go context for the request; pass it to database and HTTP calls.
-
It is a child of a base context owned by the
Vatel.v.Shutdown(ctx):- starts closing WebSocket connections and stops accepting new connections;
- waits until no request is in flight and every WebSocket connection has closed:
requests being handled and requests still being received (headers or body) finish
normally, and their responses carry
Connection: close. Idle keep-alive connections do not hold it up: they are closed. A new connection that has sent nothing yet gets about 5 seconds to start its request (as in net/http), then it is closed too. A WebSocket message being handled is finished; - cancels the base context and returns nil.
When
ctxis done first, the base context is cancelled at once, so handlers still running getcontext.Canceled(503);Shutdownwaits up to one more second for them to finish and returnsctx.Err(); requests still running after that are not interrupted, and their connections are closed when they finish. Requests that start afterShutdownget a cancelled context. Without a server started byListenAndServe, the base context is cancelled at once andShutdownwaits, withinctx, only for the WebSocket connections. CallingShutdownagain, also concurrently, is safe: each call waits for the server with its ownctx. -
vatel.WithTimeout(d)(endpoint) andvatel.WithDefaultTimeout(d)(Vatel, for endpoints without their own timeout) add a deadline. Such a context is also cancelled when the request ends. -
The timeout does not interrupt the handler by itself. Only code that listens to the context stops (database drivers,
http.NewRequestWithContext,selectonDone()). -
A handler error whose chain contains
context.DeadlineExceededgives 504,context.Canceledgives 503, unless the error carries its own status. -
fasthttp does not report a client disconnect, so the context is not cancelled when the client goes away.
-
Value(key)returns the request values first (Set,SetValue, path params,reqId), then the values of the parent context, looked up at call time: a context obtained before a value is stored sees it. It is safe to call from another goroutine. After the request has ended it returns the parent values only (fasthttp reuses the request object for the next request). -
vatel.NewContext(fctx)(for tests) returns aContextwithcontext.Background().
func (c *Report) Handle(ctx vatel.Context) error {
rows, err := c.db.QueryContext(ctx.Context(), query)
if err != nil {
return err // DeadlineExceeded -> 504
}
defer rows.Close()
// ...
}
vatel.GET("/reports/sales", reportCtrl, vatel.WithTimeout(5*time.Second))vatel.HEAD and vatel.OPTIONS work like vatel.GET: an Inputer is filled from the
query string, WithOptionalBody is not allowed. On HEAD the fasthttp server drops the
response body, so only the status and headers reach the client.
For CORS preflight use the router's GlobalOPTIONS handler. The router calls it only for
registered paths (an unknown path gets 404) and sets the Allow header before calling it.
An explicit vatel.OPTIONS endpoint on a path replaces GlobalOPTIONS for that path.
Do not put RequireAuth/RequirePerms on an OPTIONS endpoint: browsers send the
preflight without the Authorization header.
mux := router.New()
mux.GlobalOPTIONS = func(fctx *fasthttp.RequestCtx) {
h := &fctx.Response.Header
h.Set("Access-Control-Allow-Origin", allowedOrigin(fctx.Request.Header.Peek("Origin")))
h.Set("Access-Control-Allow-Methods", string(h.Peek("Allow")))
h.Set("Access-Control-Allow-Headers", "Authorization, Content-Type")
h.Set("Access-Control-Max-Age", "600")
h.Add("Vary", "Origin")
fctx.SetStatusCode(fasthttp.StatusNoContent)
}
// Allow-Origin on actual responses, including errors.
v.AddMiddleware(vatel.OnRequest, func(ctx vatel.Context, _ vatel.EndpointMeta) error {
ctx.SetHeader([]byte("Access-Control-Allow-Origin"), []byte(allowedOrigin(ctx.Header("Origin"))))
ctx.SetHeader([]byte("Vary"), []byte("Origin"))
return nil
})See example/cors.go.
WebSocket endpoints share the endpoint model. A client sends JSON messages
{"path": "<endpoint path>", "data": {...}}; data is decoded into the handler's
Inputer, the Resulter value is sent back as JSON.
type Ping struct {
in struct {
Seq int `json:"seq"`
}
out struct {
Seq int `json:"seq"`
}
}
func (h *Ping) Input() any { return &h.in }
func (h *Ping) Result() any { return &h.out }
func (h *Ping) Handle(ctx vatel.WebsocketContext) error {
h.out.Seq = h.in.Seq
return nil
}
wv := vatel.NewWebsocketVatel(
vatel.WithTokenDecoder(myDecoder),
vatel.WithWsAuthFunc(func(ctx vatel.WebsocketContext, path string, perms []string) error {
if len(perms) > 0 && ctx.TokenPayload() == nil {
return vatel.ErrUnauthorized.New()
}
return nil // check perms against ctx.TokenPayload()
}),
)
wv.OnTokenUpdate(func(cid uint64, prev, next vatel.AuthPayload) error { return nil })
v := vatel.NewVatel(vatel.WithWebsocketSupport(wv))
v.Add(vatel.Endpoints{
vatel.WS("ping", func() vatel.WebsocketHandler { return &Ping{} }),
vatel.WS("orders.watch", watchCtrl, vatel.Perms("orders:read")),
})
mux := router.New()
mux.GET("/ws", wv.Upgrade) // the HTTP route that upgrades to WebSocket- The built-in endpoint
updateAccessToken(data:{"mid": "<uuid>", "at": "<token>"}) decodes the token withWithTokenDecoderand calls theOnTokenUpdatecallback with the payload stored so far (prev, nil for the first token) and the new one (next); unless the callback returns an error, it storesnextfor the connection. An error from the callback rejects the token (the connection keeps its previous payload) and is sent to the client; a token that cannot be decoded, or whose payload has expired (Expirer), gives 401VTL-0004. WithoutWithTokenDecoderit replies"Ok"and stores nothing. The stored payload is available asctx.TokenPayload()in later messages. See Security context and closing connections. WithWsAuthFuncis called for every message with the endpoint'sPerms; WS endpoints withPermsrequire it. HTTP middleware does not run for WS messages.- Invalid
datagives a 400VTL-0007error message. If theInputerinput implementsValidator,Validate()is called after decoding, beforeHandle; an error givesErrValidationFailed(400,VTL-0006) as in HTTP. Errors are sent, logged and reported to metrics and theAlarmerlike HTTP errors. - A message that is not valid JSON or has no
pathgives 400VTL-0007, an unknownpathgives 404VTL-0008(ErrUnknownPath). These errors are sent and logged like other errors (on theWithLoggerlogger, or theBuildHandlersone, with"method":"WS"), but not reported to metrics: no endpoint is known. - The metric size of a successful message is the size of the reply.
- WS handlers have no Go context:
WithTimeout,WithDefaultTimeoutand theShutdowncancellation do not apply.LogReqBody/LogReqInputare ignored.WithRequestIDlogsconnectionIdinstead ofreqId. vatel.WithLogger(l)sets the logger of WS endpoints (lines get"layer":"ws"); without it they log to the logger passed toBuildHandlers.OnOpenandOnCloseregister connection callbacks.v.Shutdowncloses all WebSocket connections with a "going away" status first and waits, within itsctx, until they have closed: their further messages are not served, the message being handled is finished, and a client that does not answer the close frame is disconnected after about one second (OnClosegets a nil error). A connection opened after that is closed at once, without the callbacks.wv.Shutdown()alone does not wait.- A write to
ctx.BodyWriter()after the connection is closed (byShutdownor the client) returnswebsocket.ErrConnClosedinstead of blocking. A write to a client that does not read blocks once the outbound queue (128 frames) is full; after the write timeout of a frame,vatel.WithWsWriteTimeout(d)(defaultvatel.DefaultWsWriteTimeout, 10 s; 0 means no limit), the write fails and the connection ends. - A message larger than 1 MB (the
MaxPayloadSizeofgithub.com/regorov/websocket), also when assembled from fragments, closes the connection with status 1009 (message too big).OnClosegets the client's close status as awebsocket.Errorwhen the client closed the connection. - A panic in a WS handler is recovered (see Panics): the client gets a 500
VTL-0005error frame and the connection keeps serving messages. A panic in theOnOpen/OnClosecallback is logged and alarmed; after anOnOpenpanic the connection is closed with status 1011. UpgradeWithID(ctx, id): the ID must be unique among live connections. A connection with the ID of a live one is closed at once with status 1008 (policy violation), without the callbacks; its messages are not served and it does not share the token payload of the live connection.
vatel does not know what an organization (tenant, workspace, ...) is: it gives the mechanism, the application compares the contexts. The recommended model is one connection = one security context (user + organization). A token of another context is not accepted on a live connection; the client opens a new connection with it.
wv.OnTokenUpdate(func(_ uint64, prev, next vatel.AuthPayload) error {
if prev == nil {
return nil // the first token of the connection sets its context
}
p, n := prev.(*Claims), next.(*Claims)
switch {
case p.UserID != n.UserID:
return vatel.NewWsCloseError(vatel.WsStatusForbidden, "user changed", nil)
case p.OrgID != n.OrgID:
return vatel.NewWsCloseError(vatel.WsStatusContextChanged, "organization changed", nil)
}
return nil // a refresh of the same context
})OnTokenUpdate(f func(cid uint64, prev, next AuthPayload) error)runs without a lock. If another payload is stored for the connection while it runs (a concurrentUpdateAccessTokenfor the samecid), or the connection closes or starts closing,UpdateAccessTokenreturnsErrWsTokenConflict(409,VTL-0010) and stores nothing; it does not retry, as the callback need not be idempotent. For a connection that is already closing it returnsErrWsTokenConflictwithout calling the callback.WsCloseError(vatel.NewWsCloseError(code, reason, err), fieldsCode,Reason,Err). When the handler of any WS message — includingupdateAccessToken(throughOnTokenUpdate) and theWithWsAuthFuncfunction — returns an error with a*WsCloseErrorin its chain (errors.As), the client first gets the usual error reply to that message, then the connection is closed withCodeandReason; its further messages are not served. The reply is built fromErrwhen it has an*errors.Errorwith a status (an*errors.Errorjoined or wrapped next to theWsCloseError, outsideErr, does not count); otherwise from the code: 4001 → 401ErrUnauthorized, 4003 → 403ErrForbidden, 4009 → 409ErrWsContextChanged(VTL-0009), any other code → 400. It is logged and reported to metrics, never passed to theAlarmer. A rejected token is not stored. An application that callswv.UpdateAccessTokenitself gets the error and closes the connection withCloseConn.Reasonis sent in the close frame, which holds at most 123 bytes of text: vatel cuts it on a UTF-8 character boundary (a longer text makes browsers drop the connection with 1006 and lose the code). It must not carry sensitive details: put them inErr(the log) or the error reply.wv.CloseConn(cid, code, reason) boolcloses a live connection, e.g. when its user was removed from the organization, logged out, or the token was revoked; it returns false if there is no such connection (or it is already closing). Its further messages are not served;OnCloseis called once it has closed.wv.VisitConns(func(cid uint64, tp vatel.AuthPayload) bool)walks the live connections with their payloads (nil before the first token), by ID, until the callback returns false. It runs on a snapshot without a lock, so the callback may callCloseConn, e.g. to close every connection of a user in an organization.- Token expiry. A payload that implements
vatel.Expirer(ExpiresAt() time.Time) with a non-zero time closes its connection with 4001 when it expires. Each acceptedupdateAccessTokenrestarts the timer, so the client sends a fresh token before the current one expires. A payload that has already expired is rejected with 401 and the connection keeps its previous payload. A payload stored withUpdateAccessTokenfor an ID before its connection opened (UpgradeWithID) that has expired by then is dropped: the connection opens without a payload (its next token is the first,prev == nil, and the authentication timeout applies). Once the payload of a connection has expired, the connection is over even if its timer has not fired yet: a message on it (includingupdateAccessToken) is not served and closes it with 4001 "token expired", a directUpdateAccessTokenfor it returnsErrWsTokenConflictwithout callingOnTokenUpdate, andVisitConnsleaves it out. A late token never extends an expired connection nor changes its security context: refresh the token before it expires. - Authentication timeout.
vatel.WithWsAuthTimeout(d)closes a connection with 4001 if no token was accepted withindafter it opened (a rejected token does not count). Default 0: no limit. It has no effect withoutWithTokenDecoder. - Timers stop when the connection closes and on
Shutdown.
Close codes (vatel uses the first three; applications may add their own in 4000–4999):
| Code | Constant | Client reaction |
|---|---|---|
| 4001 | vatel.WsStatusAuthRequired |
refresh the token, reconnect, send it |
| 4003 | vatel.WsStatusForbidden |
do not reconnect (access denied or another user) |
| 4009 | vatel.WsStatusContextChanged |
get a token of the needed context (organization), reconnect with it, subscribe again |
| 1001 | (Shutdown, "going away") |
reconnect, possibly to another instance |
Organizations. The organization of a message is taken only from the token payload
of the connection (ctx.TokenPayload()), never from the message data. A subscription
handler checks that the organization of the resource matches the organization of the
token (the example reports a resource of another organization as not found, so its
existence is not disclosed). The same holds for HTTP: the example's order endpoints take
the organization from ctx.TokenPayload() only, filter lists by it, check it before
reading, changing or deleting an order, and set it on created orders. The context
belongs to the connection, not to the user:
browser tabs working in different organizations use different connections.
Client contract. Send the token (updateAccessToken) right after connecting, and a
fresh one before it expires. To switch the organization, close the WebSocket yourself
(1000), open a new one with a token of the new organization and subscribe again. React to
the close codes as in the table above. A complete server is in example/ws.go.
Vatel option |
Effect |
|---|---|
WithUrlPrefix("/api/v1") |
Prefix joined to every HTTP endpoint path. |
WithRequestID() |
Log reqId (fasthttp request ID); also stored in the context as reqId. |
WithVerboseError(true) |
Stack, fields and wrapped errors in error responses. |
WithClientErrorFields(names...) |
Error fields shown to the client. |
WithDefaultLogOption(lo) |
Log level of endpoints without their own. |
WithStaticLoggingLevel() |
Ignore the X-Set-Log-Level header. |
WithDefaultTimeout(d) |
Request context timeout of endpoints without their own. |
WithJsonMasker(jm) |
Masker for logged JSON (default jsonmask.New()). |
WithMetricReporter(mr) |
ReportMetric(method, path, statusCode, durSeconds, size) per request; path is the template; size is 0 for HEAD; for SetBodyStream it is the declared size (0 if unknown), the stream is not read. |
WithAlarmer(a) |
Alarm(err) for errors with status >= 500. |
WithWebsocketSupport(wv) |
Enables WS endpoints. |
WithServerConfig(f) |
Configures the fasthttp.Server started by ListenAndServe. |
MIT, see LICENSE.