Documentation
¶
Overview ¶
Package response provides structured JSON response helpers with a consistent envelope format and generics support.
The standard response envelope:
{
"success": true,
"message": "User created",
"data": { ... },
"meta": { ... },
"timestamp": 1700000000
}
Usage with the builder:
response.New().
Status(201).
Message("User created").
Data(user).
Send(w)
Or with convenience functions:
response.OK(w, "Success", user) response.NotFound(w, "User not found") response.ValidationError(w, fields)
Index ¶
- func Accepted(w http.ResponseWriter, message string, data any)
- func BadRequest(w http.ResponseWriter, message string)
- func Conflict(w http.ResponseWriter, message string)
- func Created(w http.ResponseWriter, message string, data any)
- func CursorPaginated(w http.ResponseWriter, data any, meta CursorMeta)
- func Err(w http.ResponseWriter, err error)
- func Error(w http.ResponseWriter, statusCode int, code, message string)
- func ErrorWithFields(w http.ResponseWriter, statusCode int, code, message string, ...)
- func File(w http.ResponseWriter, filename string, data []byte, contentType string)
- func Forbidden(w http.ResponseWriter, message string)
- func HTML(w http.ResponseWriter, statusCode int, html string)
- func Handle(fn HandlerFunc) http.HandlerFunc
- func HandleWith(fn HandlerFunc, ...) http.HandlerFunc
- func IndentedJSON(w http.ResponseWriter, statusCode int, data any)
- func InternalServerError(w http.ResponseWriter, message string)
- func JSON(w http.ResponseWriter, statusCode int, data any)
- func JSONP(w http.ResponseWriter, r *http.Request, statusCode int, data any)
- func NoContent(w http.ResponseWriter)
- func NotFound(w http.ResponseWriter, message string)
- func OK(w http.ResponseWriter, message string, data any)
- func Paginated(w http.ResponseWriter, data any, meta PageMeta)
- func PaginatedWithMessage(w http.ResponseWriter, message string, data any, meta PageMeta)
- func PureJSON(w http.ResponseWriter, statusCode int, data any)
- func Raw(w http.ResponseWriter, statusCode int, contentType string, data []byte)
- func Reader(w http.ResponseWriter, statusCode int, contentType string, contentLength int64, ...)
- func Redirect(w http.ResponseWriter, r *http.Request, url string, code int)
- func ServiceUnavailable(w http.ResponseWriter, message string)
- func SetLinkHeader(w http.ResponseWriter, baseURL string, page, perPage, total int)
- func Stream(w http.ResponseWriter, fn func(send func(event, data string) error) error)
- func StreamJSON(w http.ResponseWriter, fn func(send func(event string, data any) error) error)
- func Text(w http.ResponseWriter, statusCode int, text string)
- func TooManyRequests(w http.ResponseWriter, message string)
- func Unauthorized(w http.ResponseWriter, message string)
- func ValidationError(w http.ResponseWriter, fields map[string]string)
- func XML(w http.ResponseWriter, statusCode int, data any)
- type Builder
- func (b *Builder) CursorPagination(nextCursor string, hasMore bool, total int) *Builder
- func (b *Builder) Data(data any) *Builder
- func (b *Builder) Err(code, message string) *Builder
- func (b *Builder) ErrDetails(details map[string]any) *Builder
- func (b *Builder) ErrFields(fields map[string]string) *Builder
- func (b *Builder) Header(key, value string) *Builder
- func (b *Builder) JSON() ([]byte, error)
- func (b *Builder) Message(msg string) *Builder
- func (b *Builder) Meta(meta any) *Builder
- func (b *Builder) MustJSON() []byte
- func (b *Builder) Pagination(page, perPage, total int) *Builder
- func (b *Builder) Send(w http.ResponseWriter)
- func (b *Builder) Status(code int) *Builder
- type CursorMeta
- type Envelope
- type ErrorBody
- type HandlerFunc
- type PageMeta
- type TypedEnvelope
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Accepted ¶
func Accepted(w http.ResponseWriter, message string, data any)
Accepted writes a 202 response.
func BadRequest ¶
func BadRequest(w http.ResponseWriter, message string)
BadRequest writes a 400 response.
func Conflict ¶
func Conflict(w http.ResponseWriter, message string)
Conflict writes a 409 response.
func Created ¶
func Created(w http.ResponseWriter, message string, data any)
Created writes a 201 response.
func CursorPaginated ¶
func CursorPaginated(w http.ResponseWriter, data any, meta CursorMeta)
CursorPaginated writes a cursor-paginated response.
response.CursorPaginated(w, events, response.CursorMeta{
NextCursor: "eyJpZCI6MTAwfQ==",
HasMore: true,
Total: 500,
})
func Err ¶
func Err(w http.ResponseWriter, err error)
Err writes an error response from an *errors.Error. This is the primary way to send error responses, bridging the errors package.
if err != nil {
response.Err(w, err)
return
}
func Error ¶
func Error(w http.ResponseWriter, statusCode int, code, message string)
Error writes a custom error response.
func ErrorWithFields ¶
func ErrorWithFields(w http.ResponseWriter, statusCode int, code, message string, fields map[string]string)
ErrorWithFields writes an error response with field-level errors.
func File ¶
func File(w http.ResponseWriter, filename string, data []byte, contentType string)
File sends a file as a download.
func Forbidden ¶
func Forbidden(w http.ResponseWriter, message string)
Forbidden writes a 403 response.
func HTML ¶
func HTML(w http.ResponseWriter, statusCode int, html string)
HTML writes an HTML response.
func Handle ¶
func Handle(fn HandlerFunc) http.HandlerFunc
Handle wraps a HandlerFunc into a standard http.HandlerFunc. If the handler returns an error:
- *errors.Error → sends the appropriate status code and error body
- Standard error → sends 500 with a generic message (original error NOT exposed)
func HandleWith ¶
func HandleWith(fn HandlerFunc, onError func(w http.ResponseWriter, r *http.Request, err error)) http.HandlerFunc
HandleWith wraps a HandlerFunc with a custom error handler.
func IndentedJSON ¶ added in v0.5.0
func IndentedJSON(w http.ResponseWriter, statusCode int, data any)
IndentedJSON writes a pretty-printed JSON response (no envelope). Useful for debug endpoints or human-readable API responses.
func InternalServerError ¶
func InternalServerError(w http.ResponseWriter, message string)
InternalServerError writes a 500 response.
func JSON ¶
func JSON(w http.ResponseWriter, statusCode int, data any)
JSON writes a success response with the given status code and data.
func JSONP ¶ added in v0.5.0
JSONP writes a JSONP response for cross-domain callbacks. The callback name is read from the "callback" query parameter. If no callback is provided, it falls back to a regular JSON response.
func NoContent ¶
func NoContent(w http.ResponseWriter)
NoContent writes a 204 response with no body.
func NotFound ¶
func NotFound(w http.ResponseWriter, message string)
NotFound writes a 404 response.
func Paginated ¶
func Paginated(w http.ResponseWriter, data any, meta PageMeta)
Paginated writes a paginated response with offset-based metadata.
response.Paginated(w, users, response.PageMeta{
Page: 1, PerPage: 20, Total: 150, TotalPages: 8,
})
func PaginatedWithMessage ¶
func PaginatedWithMessage(w http.ResponseWriter, message string, data any, meta PageMeta)
PaginatedWithMessage writes a paginated response with a message.
func PureJSON ¶ added in v0.5.0
func PureJSON(w http.ResponseWriter, statusCode int, data any)
PureJSON writes a JSON response without HTML escaping of <, >, and &. Standard json.Encoder escapes these characters for safe embedding in HTML; PureJSON preserves them as-is for clients that consume raw JSON.
func Raw ¶
func Raw(w http.ResponseWriter, statusCode int, contentType string, data []byte)
Raw writes raw bytes with a custom content type. Use this for non-JSON responses like HTML, XML, plain text, etc.
func Reader ¶ added in v0.5.0
func Reader(w http.ResponseWriter, statusCode int, contentType string, contentLength int64, reader io.Reader)
Reader streams data from an io.Reader to the response. Useful for proxying responses or sending large files without loading them into memory.
func ServiceUnavailable ¶
func ServiceUnavailable(w http.ResponseWriter, message string)
ServiceUnavailable writes a 503 response.
func SetLinkHeader ¶ added in v0.2.0
func SetLinkHeader(w http.ResponseWriter, baseURL string, page, perPage, total int)
SetLinkHeader sets an RFC 5988 Link header for paginated responses.
response.SetLinkHeader(w, "https://api.example.com/users", 2, 20, 100) // Link: <https://api.example.com/users?page=3&per_page=20>; rel="next", // <https://api.example.com/users?page=1&per_page=20>; rel="prev", // <https://api.example.com/users?page=1&per_page=20>; rel="first", // <https://api.example.com/users?page=5&per_page=20>; rel="last"
func Stream ¶
func Stream(w http.ResponseWriter, fn func(send func(event, data string) error) error)
Stream provides Server-Sent Events (SSE) streaming.
response.Stream(w, func(send func(event, data string) error) error {
for msg := range messages {
if err := send("message", msg); err != nil {
return err
}
}
return nil
})
func StreamJSON ¶
StreamJSON is like Stream but sends JSON-encoded data.
func Text ¶
func Text(w http.ResponseWriter, statusCode int, text string)
Text writes a plain text response.
func TooManyRequests ¶
func TooManyRequests(w http.ResponseWriter, message string)
TooManyRequests writes a 429 response.
func Unauthorized ¶
func Unauthorized(w http.ResponseWriter, message string)
Unauthorized writes a 401 response.
func ValidationError ¶
func ValidationError(w http.ResponseWriter, fields map[string]string)
ValidationError writes a 422 response with field errors.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder provides a fluent interface for constructing responses.
response.New().
Status(http.StatusCreated).
Message("User created").
Data(user).
Header("X-Resource-ID", user.ID).
Send(w)
func New ¶
func New() *Builder
New creates a new response Builder with defaults (200 OK, success=true).
func (*Builder) CursorPagination ¶
CursorPagination sets cursor-based pagination metadata.
func (*Builder) ErrDetails ¶
ErrDetails adds arbitrary error metadata.
func (*Builder) Pagination ¶
Pagination sets offset-based pagination metadata.
func (*Builder) Send ¶
func (b *Builder) Send(w http.ResponseWriter)
Send writes the response to the http.ResponseWriter. The timestamp is set at send time to reflect the actual response time.
type CursorMeta ¶
type CursorMeta struct {
NextCursor string `json:"next_cursor,omitempty"`
HasMore bool `json:"has_more"`
Total int `json:"total,omitempty"`
}
CursorMeta represents cursor-based pagination metadata.
type Envelope ¶
type Envelope struct {
Success bool `json:"success"`
Message string `json:"message,omitempty"`
Data any `json:"data,omitempty"`
Error *ErrorBody `json:"error,omitempty"`
Meta any `json:"meta,omitempty"`
Timestamp int64 `json:"timestamp"`
}
Envelope is the standard API response envelope. All API responses are wrapped in this structure.
type ErrorBody ¶
type ErrorBody struct {
Code string `json:"code"`
Message string `json:"message"`
Fields map[string]string `json:"fields,omitempty"`
Details map[string]any `json:"details,omitempty"`
}
ErrorBody is the error portion of the response envelope.
type HandlerFunc ¶
type HandlerFunc func(w http.ResponseWriter, r *http.Request) error
HandlerFunc is an HTTP handler that returns an error. When the handler returns a non-nil error, it is automatically converted to a structured JSON response.
mux.HandleFunc("GET /users/{id}", response.Handle(getUser))
func getUser(w http.ResponseWriter, r *http.Request) error {
id := request.PathParam(r, "id")
user, err := db.FindUser(id)
if err != nil {
return errors.NotFound("User")
}
response.OK(w, "Success", user)
return nil
}
type PageMeta ¶
type PageMeta struct {
Page int `json:"page"`
PerPage int `json:"per_page"`
Total int `json:"total"`
TotalPages int `json:"total_pages"`
HasNext bool `json:"has_next"`
HasPrevious bool `json:"has_previous"`
}
PageMeta represents offset-based pagination metadata.
func NewPageMeta ¶
NewPageMeta creates a PageMeta from page, perPage, and total count. TotalPages, HasNext, and HasPrevious are computed automatically. If perPage is <= 0, TotalPages defaults to 0.
type TypedEnvelope ¶
type TypedEnvelope[T any] struct { Success bool `json:"success"` Message string `json:"message,omitempty"` Data T `json:"data,omitempty"` Error *ErrorBody `json:"error,omitempty"` Meta any `json:"meta,omitempty"` Timestamp int64 `json:"timestamp"` }
TypedEnvelope is a generic version of Envelope for type-safe responses. Useful when you want compile-time type checking on the data field.
Source Files