Skip to content

Handlers

A handler in Kori is a function that processes an HTTP request and returns an error.

The standard library defines a handler as a function that writes to a ResponseWriter and returns nothing:

func listUsers(w http.ResponseWriter, r *http.Request) {
users, err := db.All()
if err != nil {
http.Error(w, "internal server error", http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusOK)
json.NewEncoder(w).Encode(users)
}

Error handling is manual. Every path that fails requires writing a response and returning early. Forgetting either is a silent bug.

Kori defines its own handler type:

type Handler func(w http.ResponseWriter, r *http.Request) error

The signature is identical to http.HandlerFunc except for the error return. Kori wraps the handler internally and catches any non-nil error before it reaches the client.

func listUsers(w http.ResponseWriter, r *http.Request) error {
users, err := db.All()
if err != nil {
return kori.InternalServerError("could not fetch users")
}
return kori.JSON(w, http.StatusOK, users)
}

Handlers are registered on any chi.Router:

kori.GET(r, "/users", listUsers)

When a handler returns an error, Kori passes it to the configured error handler. The default behavior is:

Returned value Response
nil No action — you already wrote the response
*kori.HTTPError JSON with the error’s status code
Any other error 500 Internal Server Error

Kori provides constructors for common status codes:

return kori.BadRequest("invalid input") // 400
return kori.Unauthorized("missing token") // 401
return kori.Forbidden("insufficient permissions") // 403
return kori.NotFound("user not found") // 404
return kori.Conflict("email already in use") // 409
return kori.UnprocessableEntity("invalid data") // 422
return kori.InternalServerError("unexpected err") // 500

For custom status codes, use kori.NewError:

return kori.NewError(http.StatusTooManyRequests, "rate limit exceeded", map[string]int{
"retry_after": 60,
})

The second argument is optional structured details, included in the JSON response under "details".

Kori provides helpers for writing responses. Each returns the write error so it can propagate up:

kori.JSON(w, http.StatusOK, payload) // application/json
kori.RawJSON(w, http.StatusOK, rawBytes) // pre-encoded JSON bytes
kori.Text(w, http.StatusOK, "hello") // text/plain
kori.NoContent(w) // 204
kori.Redirect(w, r, http.StatusFound, "/new") // redirect
Helper Content-Type Writes
JSON(w, status, v) application/json v encoded as JSON
RawJSON(w, status, data) application/json data written as-is, without re-encoding
Text(w, status, s) text/plain s as plain text
NoContent(w) — 204 No Content, no body
Redirect(w, r, status, url) — A redirect to url with the given status

RawJSON writes bytes that are already valid JSON, skipping a second encode. Use it for cached payloads or JSON produced elsewhere:

cached, err := cache.Get(ctx, key) // []byte, already JSON
if err != nil {
return err
}
return kori.RawJSON(w, http.StatusOK, cached)

Redirect wraps http.Redirect and returns nil, so it composes with the error-returning handler signature. Pass the status explicitly — http.StatusFound (302), http.StatusMovedPermanently (301), or http.StatusSeeOther (303) after a successful POST:

return kori.Redirect(w, r, http.StatusSeeOther, "/posts/"+post.ID)

Explicit error flow. Errors bubble up naturally. There is no way to accidentally swallow an error without explicitly ignoring the return value.

Centralized handling. One SetErrorHandler call configures how all errors are rendered. You can swap the entire error format — JSON, Problem Details, XML — in one place:

kori.SetErrorHandler(func(w http.ResponseWriter, r *http.Request, err error) {
var he *kori.HTTPError
if !errors.As(err, &he) {
he = kori.InternalServerError("internal server error")
}
w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.WriteHeader(he.Status)
json.NewEncoder(w).Encode(he)
})

Less boilerplate. Route logic stays focused on the happy path. Early returns propagate errors up without writing responses inline.

Compatible with net/http. Standard Chi handlers and Kori handlers coexist on the same router. Migration is incremental.