// Package common contains cross-cutting HTTP helpers: contract errors, JSON // binding, validation, cursor pagination and timestamp formatting. package common import ( "errors" "net/http" "github.com/gofiber/fiber/v3" "github.com/gofiber/fiber/v3/middleware/requestid" ) const ( ErrorCodeInvalidRequest = "invalid_request" ErrorCodeUnauthorized = "unauthorized" ErrorCodeNotFound = "not_found" ErrorCodeConflict = "conflict" ErrorCodePayloadTooLarge = "payload_too_large" ErrorCodeUnsupportedMedia = "unsupported_media_type" ErrorCodeRateLimited = "rate_limited" ErrorCodeUnavailable = "unavailable" ErrorCodeInternal = "internal_error" ) type APIErrorResponse struct { Error APIError `json:"error"` } type APIError struct { Code string `json:"code"` Message string `json:"message"` RequestID string `json:"request_id"` } func NewError(code, message, requestID string) APIErrorResponse { return APIErrorResponse{ Error: APIError{ Code: code, Message: message, RequestID: requestID, }, } } // AppError is the single contract error type. Handlers and the store return it; // the Fiber error handler is the only place that turns it into a response. type AppError struct { Status int Code string Message string Challenge string // WWW-Authenticate value, set for 401 responses } func (e *AppError) Error() string { return e.Message } func NewAppError(status int, code, message string) *AppError { return &AppError{ Status: status, Code: code, Message: message, } } func BadRequest(message string) *AppError { return NewAppError(http.StatusBadRequest, ErrorCodeInvalidRequest, message) } func NotFound(message string) *AppError { return NewAppError(http.StatusNotFound, ErrorCodeNotFound, message) } func Conflict(message string) *AppError { return NewAppError(http.StatusConflict, ErrorCodeConflict, message) } func UnsupportedMedia(message string) *AppError { return NewAppError(http.StatusUnsupportedMediaType, ErrorCodeUnsupportedMedia, message) } func PayloadTooLarge(message string) *AppError { return NewAppError(http.StatusRequestEntityTooLarge, ErrorCodePayloadTooLarge, message) } func Internal() *AppError { return NewAppError(http.StatusInternalServerError, ErrorCodeInternal, "Internal server error") } func Unavailable(message string) *AppError { return NewAppError(http.StatusServiceUnavailable, ErrorCodeUnavailable, message) } // NewChallenge builds the 401 that carries a WWW-Authenticate header. func NewChallenge(challenge, message string) *AppError { return &AppError{ Status: http.StatusUnauthorized, Code: ErrorCodeUnauthorized, Message: message, Challenge: challenge, } } // IsCode reports whether err is an AppError with the given contract code. func IsCode(err error, code string) bool { appErr, ok := errors.AsType[*AppError](err) return ok && appErr.Code == code } func ErrorCodeFromStatus(status int) string { switch status { case http.StatusBadRequest: return ErrorCodeInvalidRequest case http.StatusUnauthorized: return ErrorCodeUnauthorized case http.StatusNotFound: return ErrorCodeNotFound case http.StatusConflict: return ErrorCodeConflict case http.StatusRequestEntityTooLarge: return ErrorCodePayloadTooLarge case http.StatusUnsupportedMediaType: return ErrorCodeUnsupportedMedia case http.StatusTooManyRequests: return ErrorCodeRateLimited case http.StatusServiceUnavailable: return ErrorCodeUnavailable default: return ErrorCodeInternal } } func getRequestID(c fiber.Ctx) string { if id := string(c.Response().Header.Peek("X-Request-Id")); id != "" { return id } return requestid.FromContext(c) } func SendError(c fiber.Ctx, status int, code, message string) error { return c.Status(status).JSON(NewError(code, message, getRequestID(c))) }