Documentation
¶
Overview ¶
Package httpx is the kernel's HTTP response envelope: the one wire format every module writes. It is byte-identical to internal/api/response by contract — the compat suite in the main module diffs both writers — so clients cannot tell whether a route is served by core or by a module.
Modules import this package instead of internal code they cannot reach. The kernel never imports net/http handlers or routers here; it only serializes envelopes.
Index ¶
- Constants
- Variables
- func DecodeCursor(cursor string) (int, error)
- func EncodeCursor(id int) string
- func Error(w http.ResponseWriter, statusCode int, code, message string, details any)
- func ParseListLimit(r *http.Request) int
- func SendJSON(w http.ResponseWriter, statusCode int, resp Response)
- func Success(w http.ResponseWriter, data any)
- func SuccessList(w http.ResponseWriter, items any, meta any)
- type ErrorInfo
- type ListMeta
- type Pagination
- type Response
Constants ¶
const ( DefaultListLimit = 50 MinListLimit = 1 MaxListLimit = 100 )
List limit bounds shared by all cursor-paginated list endpoints.
Variables ¶
var ErrInvalidCursor = errors.New("invalid cursor")
ErrInvalidCursor is the single failure returned by DecodeCursor for any unparseable, non-numeric, or non-positive cursor token. List handlers map it to 400 VALIDATION_ERROR without disclosing why the token was bad.
Functions ¶
func DecodeCursor ¶
DecodeCursor inverts EncodeCursor. An empty cursor means "first page" → (0, nil). Any token that fails base64 decoding, is not a decimal integer, or decodes to id <= 0 is rejected with ErrInvalidCursor.
func EncodeCursor ¶
EncodeCursor produces an opaque, URL-safe keyset token for the given id using unpadded base64 (RawURLEncoding) so the token contains no `=` padding — clients can drop it into a query string verbatim without worrying about padding being trimmed or mis-encoded by intermediaries. Clients must echo the token verbatim and never construct it. Opacity is for contract stability, not secrecy — the token is NOT signed; tamper-evidence is a post-MVP concern. The underlying value is the decimal id, so id DESC paging is stable across concurrent inserts/deletes (a new row lands on page 1; a deleted row never shifts later pages).
func Error ¶
func Error(w http.ResponseWriter, statusCode int, code, message string, details any)
Error sends an error response with structured error info.
func ParseListLimit ¶
ParseListLimit clamps the ?limit query param into [MinListLimit, MaxListLimit] with a default of DefaultListLimit. Missing/invalid/negative → default; over-max → max.
func SendJSON ¶
func SendJSON(w http.ResponseWriter, statusCode int, resp Response)
SendJSON sends a JSON response with the given status code.
func Success ¶
func Success(w http.ResponseWriter, data any)
Success sends a successful response with data.
func SuccessList ¶
func SuccessList(w http.ResponseWriter, items any, meta any)
SuccessList sends a list response whose Data is never omitted (so empty lists render as "data":[]).
Types ¶
type ErrorInfo ¶
type ErrorInfo struct {
Code string `json:"code"`
Message string `json:"message"`
Details any `json:"details,omitempty"`
}
ErrorInfo represents structured error information.
type ListMeta ¶
type ListMeta struct {
Pagination Pagination `json:"pagination"`
}
ListMeta wraps pagination metadata under the canonical "pagination" key.
type Pagination ¶
type Pagination struct {
NextCursor string `json:"nextCursor,omitempty"`
HasMore bool `json:"hasMore"`
Total *int `json:"total,omitempty"`
Limit *int `json:"limit,omitempty"`
Offset *int `json:"offset,omitempty"`
}
Pagination is the list-pagination metadata carried in a list response's meta. Cursor endpoints populate NextCursor; offset endpoints populate Total/Limit/Offset.
Source Files