Handlers and routes
The handler pattern
Every handler embeds httpx.Kit, so an action reads like a Laravel controller method:
type Handler struct { service *Service checker *authz.Checker httpx.Kit // Bind, Validate, PathID, Data, Error, NoContent, Paginated, Cursor, Message}
func NewHandler(service *Service, checker *authz.Checker, kit httpx.Kit) *Handler { return &Handler{service: service, checker: checker, Kit: kit}}
func (h *Handler) update(w http.ResponseWriter, r *http.Request) { id, ok := h.PathID(w, r, "id") // positive int64 from {id}; writes the 400 itself if !ok { return } var req InsertUpdateRequest if !h.Bind(w, r, &req) { // decode JSON + run `validate` tags; writes 400/415/422 return } branch, err := h.service.Update(r.Context(), tenancy.From(r), authn.UserID(r), id, req.toInput()) if err != nil { h.Error(w, r, err) // *apperr.Error → RFC 9457 problem return } h.Data(w, r, http.StatusOK, NewResponse(*branch))}The kit is built once in internal/app/wiring.go (httpx.NewKit(binder, validator, responder)) and handed to every NewHandler — the developer dashboard’s handler included.
| Helper | Does |
|---|---|
h.Bind(w, r, &req) |
strict JSON decode + validation; on failure writes the problem and returns false |
h.Validate(w, r, &req) |
validation only — for query-string or multipart structs you filled yourself |
h.PathID(w, r, "id") |
reads a positive integer route parameter, 400 otherwise |
h.Data(w, r, status, v) |
{"data": v} |
h.Paginated(w, r, status, data, meta, links) |
{"data": [...], "links": {...}, "meta": {...}} |
h.Cursor(w, r, status, data, meta, links) |
cursor-paginated lists |
h.Message(w, r, status, "Done.") |
{"message": "Done."} |
h.NoContent(w) |
204 |
h.Error(w, r, err) |
the right problem response for any error |
authn.UserID(r) |
the signed-in user (auth()->id()) |
tenancy.From(r) |
the resolved tenant scope |
Routes and permissions
A module registers its routes in routes.go, and each route declares its permission — the
equivalent of Laravel’s ->middleware('can:...'):
func (h *Handler) RegisterRoutes(r chi.Router) { r.With(h.can(authz.PermBranchViewAll)).Get("/branch", h.index) r.With(h.can(authz.PermBranchView)).Get("/branch/{id}", h.show) r.With(h.can(authz.PermBranchCreate)).Post("/branch", h.store) r.With(h.can(authz.PermBranchUpdate)).Patch("/branch/{id}", h.update) r.With(h.can(authz.PermBranchDelete)).Delete("/branch/{id}", h.destroy)}
// can is route middleware requiring a permission.func (h *Handler) can(permission string) func(http.Handler) http.Handler { return authz.Require(h.checker, permission, h.Responder)}Only when the permission depends on the payload — sending roles while creating a user needs
user.role.assign — does a handler check inside the action:
if len(req.Roles) > 0 { if err := h.checker.MustCan(r.Context(), authn.UserID(r), authz.PermUserRoleAssign); err != nil { h.Error(w, r, err) return }}Why permissions live at the edge
CLI commands, queue jobs and scheduled tasks are trusted code and don’t re-check permissions — exactly like artisan commands and queued jobs. Services stay permission-free. What services always enforce, whoever calls them, is tenant scoping and business invariants. See Permissions.
The module’s RegisterRoutes is mounted into a route group in internal/app/routes.go; the group
decides authentication and tenancy (see How it works).
Pagination
Management lists use page-based pagination:
page, perPage, offset := httpx.PageParams(r) // ?page=, ?per_page= (default 10, max 100)orderBy, orderDir := httpx.OrderParams(r, "id", "name", "created_at") // whitelisted ?order_by=&order_direction=items, total, err := h.service.List(r.Context(), tenancy.From(r), ListFilter{ Search: r.URL.Query().Get("search"), OrderBy: orderBy, OrderDir: orderDir, Limit: int32(perPage), Offset: int32(offset),})meta, links := httpx.NewPagination(r, page, perPage, total)h.Paginated(w, r, http.StatusOK, data, meta, links)Feeds and streams (notifications, activity, dashboard telemetry) use cursor pagination:
?limit= (default 20–25, max 100) and ?cursor=, answered with h.Cursor and links from
httpx.CursorURL.
order_by is always whitelisted per endpoint — an unknown column falls back to the default,
so user input never reaches ORDER BY.
The response envelope
| Response | Shape |
|---|---|
| a resource | {"data": {...}} |
| a list | {"data": [...], "links": {first, last, prev, next}, "meta": {current_page, per_page, total, …}} |
| a message | {"message": "…"} |
| deleted / logged out | 204 No Content |
| any error | application/problem+json (RFC 9457) — see Validation & errors |
Timestamps are RFC 3339 in UTC. Money is an integer in minor units (paisa). IDs are 64-bit integers.