response

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 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 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 OK ¶

func OK(w http.ResponseWriter, message string, data any)

OK writes a 200 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 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 Redirect ¶

func Redirect(w http.ResponseWriter, r *http.Request, url string, code int)

Redirect sends an HTTP redirect.

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 ¶

func StreamJSON(w http.ResponseWriter, fn func(send func(event string, data any) error) error)

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.

func Wrap ¶

func Wrap(fn http.HandlerFunc) http.HandlerFunc

Wrap wraps a standard http.HandlerFunc so that any error passed to Err or the error convenience helpers is automatically written as a structured JSON response. Use this when you prefer the standard handler signature with no return type.

mux.HandleFunc("GET /users/{id}", response.Wrap(getUser))

func getUser(w http.ResponseWriter, r *http.Request) {
    id := request.PathParam(r, "id")
    user, err := db.FindUser(id)
    if err != nil {
        response.Err(w, errors.NotFound("User"))
        return
    }
    response.OK(w, "Success", user)
}

Wrap is a thin pass-through today, but it future-proofs your handlers for middleware features like response capture or panic recovery.