Documentation
¶
Overview ¶
Package httpx provides small, framework-neutral helpers for JSON HTTP handlers: a standard error envelope, safe error responses that never echo internal error strings to clients, bounded JSON decoding, and clamped pagination parsing. Everything operates on net/http types; framework veneers (e.g. Gin) wrap these.
Index ¶
- Constants
- func DecodeJSON(w http.ResponseWriter, r *http.Request, dst any) error
- func WriteError(w http.ResponseWriter, status int, message string)
- func WriteErrorCode(w http.ResponseWriter, status int, message, code string)
- func WriteInternalError(w http.ResponseWriter)
- func WriteJSON(w http.ResponseWriter, status int, v any)
- type ErrorBody
- type Page
Examples ¶
Constants ¶
const ( DefaultPageLimit = 20 MaxPageLimit = 100 )
Pagination defaults; override per call with PaginationWith.
const MaxJSONBody = 1 << 20 // 1 MiB
MaxJSONBody is the default request-body cap for DecodeJSON.
Variables ¶
This section is empty.
Functions ¶
func DecodeJSON ¶
DecodeJSON decodes the request body into dst, capping the body at MaxJSONBody and rejecting trailing garbage. The returned error is safe to show to clients.
func WriteError ¶
func WriteError(w http.ResponseWriter, status int, message string)
WriteError writes the standard error envelope. The message is sent to the client verbatim, so it must be a public-safe description — never pass err.Error() from an internal error here; use WriteInternalError instead.
Example ¶
WriteError sends a client-facing message. Internal error text never reaches the response body: use WriteInternalError for that, which logs the cause and tells the client nothing beyond the status.
package main
import (
"fmt"
"net/http"
"net/http/httptest"
"github.com/dobrevit/svckit/httpx"
)
func main() {
w := httptest.NewRecorder()
httpx.WriteError(w, http.StatusNotFound, "order not found")
fmt.Println(w.Code)
fmt.Println(w.Body.String())
}
Output: 404 {"error":"order not found"}
func WriteErrorCode ¶
func WriteErrorCode(w http.ResponseWriter, status int, message, code string)
WriteErrorCode writes the standard error envelope with a machine-readable code.
func WriteInternalError ¶
func WriteInternalError(w http.ResponseWriter)
WriteInternalError writes the canonical 500 response without exposing any internal detail. Log the underlying error at the call site.
Types ¶
type ErrorBody ¶
type ErrorBody struct {
Error string `json:"error"`
Code string `json:"code,omitempty"`
Details any `json:"details,omitempty"`
}
ErrorBody is the standard JSON error envelope.
type Page ¶
Page is a parsed, clamped limit/offset pair.
func Pagination ¶
Pagination parses the "limit" and "offset" query parameters with the package defaults: limit defaults to DefaultPageLimit and is clamped to [1, MaxPageLimit]; offset defaults to 0 and is clamped to >= 0.
Example ¶
Pagination clamps the caller's request into a range the handler can serve, so an unbounded ?limit= cannot ask for the whole table.
package main
import (
"fmt"
"net/http"
"net/http/httptest"
"github.com/dobrevit/svckit/httpx"
)
func main() {
r := httptest.NewRequest(http.MethodGet, "/orders?limit=100000&offset=40", nil)
page := httpx.Pagination(r)
fmt.Printf("limit=%d offset=%d\n", page.Limit, page.Offset)
}
Output: limit=100 offset=40
Source Files