Documentation
¶
Index ¶
- func AutoSummary(method, path string) string
- func AutoTags(path string) []string
- func HandleAction[T any](h ActionFunc[T], opts ...HandleOption) gin.HandlerFunc
- func HandleList[T any](lister QueryLister[T], opts ...HandleOption) gin.HandlerFunc
- func HandleRequest[T any, R any](h HandlerFunc[T, R], opts ...HandleOption) gin.HandlerFunc
- func IndexRoutes(engine *gin.Engine)
- func WriteResponse(c *gin.Context, code int, data any, err error)
- type ActionFunc
- type Binder
- type ErrorResponse
- type HandleOption
- type HandlerFunc
- type HandlerMeta
- type ListResult
- type QueryLister
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AutoSummary ¶
AutoSummary derives a summary from the HTTP method and path.
POST /api/v1/posts → "Create posts" GET /api/v1/posts → "List posts" GET /api/v1/posts/:rid → "Get posts" PUT /api/v1/posts/:rid → "Update posts" DELETE /api/v1/posts/:rid → "Delete posts"
func AutoTags ¶
AutoTags derives tags from the path — the last non-parameter segment.
/api/v1/posts → ["posts"] /api/v1/posts/:rid → ["posts"]
func HandleAction ¶
func HandleAction[T any](h ActionFunc[T], opts ...HandleOption) gin.HandlerFunc
HandleAction creates a gin.HandlerFunc for actions (no response body, 204 by default).
func HandleList ¶
func HandleList[T any](lister QueryLister[T], opts ...HandleOption) gin.HandlerFunc
HandleList creates a gin handler that parses page/size/order/filter from URL query parameters and returns a paginated ListResult.
Supported query params (parsed by where.FromQuery):
page — page number (default 1) size — items per page (default 20) order — "field:asc" or "field:desc" <field> — equality filter (field must be in WithQueryFields)
Usage:
rg.GET("/posts", handler.HandleList(postStore))
func HandleRequest ¶
func HandleRequest[T any, R any](h HandlerFunc[T, R], opts ...HandleOption) gin.HandlerFunc
HandleRequest creates a gin.HandlerFunc with multi-source binding. Tag analysis happens once at construction time (Setup phase).
func IndexRoutes ¶
IndexRoutes re-indexes handler metadata by method+path from gin routes. Call once after all routes are registered (typically at swagger populate time). After this call, LookupRoute is the preferred lookup path, and metaStore is pruned to drop closure-addr entries — the map is otherwise append-only and would leak in long-running tests that build and discard many Apps. Clearing happens after the re-index so nothing referenced by routeIndex is lost.
func WriteResponse ¶
WriteResponse writes a success or error JSON response.
Success: HTTP {code}, body = data. Error: HTTP {apierr.Code}, body = ErrorResponse with request_id from ctx.
No-op when the response has already been written (e.g. a timeout middleware already wrote 504). Without this guard, a recovered panic in a later handler would trigger "http: superfluous response.WriteHeader call" warnings and produce a garbled body.
Types ¶
type ActionFunc ¶
ActionFunc is a typed handler that returns only an error (no response body).
func ValidatedAction ¶
func ValidatedAction[T any](h ActionFunc[T], validators ...validate.Func[T]) ActionFunc[T]
ValidatedAction wraps an ActionFunc with additional validation functions. Same error wrapping as Validated.
type Binder ¶
type Binder interface {
// Tag returns the struct tag this binder handles (e.g., "uri", "form", "json").
Tag() string
// Bind maps values from the request into the target struct.
Bind(c *gin.Context, target any) error
}
Binder binds a specific source (URI params, query string, JSON body, etc.) into struct fields tagged with the corresponding struct tag. Bind must NOT run validation — validation runs once after all binders complete.
type ErrorResponse ¶
type ErrorResponse struct {
Code int `json:"code"`
Reason string `json:"reason"`
Message string `json:"message"`
RequestID string `json:"request_id,omitempty"`
Metadata map[string]any `json:"metadata,omitempty"`
}
ErrorResponse is the JSON body for error responses.
type HandleOption ¶
type HandleOption func(*handleConfig)
HandleOption controls handler behavior.
func WithBinders ¶
func WithBinders(binders ...Binder) HandleOption
WithBinders appends additional binders to the default set (uri, query, json). Custom binders run after the built-in ones, in the order provided.
func WithMaxBodySize ¶
func WithMaxBodySize(n int64) HandleOption
WithMaxBodySize overrides the default 4 MiB request-body cap for this handler. Use for upload endpoints or webhook receivers that legitimately accept larger payloads. Non-positive values are ignored (default kept).
func WithPublic ¶
func WithPublic() HandleOption
WithPublic marks this handler as not requiring authentication. In OpenAPI output, the route omits the security requirement so clients know no Bearer token is needed (e.g. login, register).
func WithSuccessCode ¶
func WithSuccessCode(code int) HandleOption
WithSuccessCode overrides the default success HTTP status code.
func WithSummary ¶
func WithSummary(s string) HandleOption
WithSummary sets the OpenAPI summary for this handler (optional). If not set, auto-derived from HTTP method + path.
func WithTags ¶
func WithTags(tags ...string) HandleOption
WithTags sets the OpenAPI tags for this handler (optional). If not set, auto-derived from path resource name.
type HandlerFunc ¶
HandlerFunc is a typed handler that returns a response and error.
func Validated ¶
func Validated[T any, R any](h HandlerFunc[T, R], validators ...validate.Func[T]) HandlerFunc[T, R]
Validated wraps a HandlerFunc with additional validation functions. If a validator returns a plain error (not *apierr.Error), it is automatically wrapped as ErrInvalidArgument so it always produces a 4xx response.
type HandlerMeta ¶
type HandlerMeta struct {
ReqType reflect.Type // request struct type (nil for HandleList)
RespType reflect.Type // response type (nil for ActionFunc)
Code int // success HTTP status code
Summary string // user-provided or auto-derived
Tags []string // user-provided or auto-derived
IsList bool // true for HandleList
Public bool // true = no auth required (omits security in OpenAPI)
}
HandlerMeta stores type and documentation metadata for a chok handler. Registered automatically by HandleRequest, HandleAction, and HandleList.
func LookupMeta ¶
func LookupMeta(fn gin.HandlerFunc) *HandlerMeta
LookupMeta returns the metadata for a gin handler by closure address. Retained for backward compatibility; prefer LookupRoute after IndexRoutes.
func LookupRoute ¶
func LookupRoute(method, path string) *HandlerMeta
LookupRoute returns metadata by HTTP method and path. Available after IndexRoutes has been called. Preferred over LookupMeta for stable key identity that does not depend on function pointer addresses.
type ListResult ¶
type ListResult[T any] struct { Items []T `json:"items"` Total int64 `json:"total"` Page int `json:"page,omitempty"` Size int `json:"size,omitempty"` HasMore bool `json:"has_more"` }
ListResult is the standard paginated response wrapper. When page/size are parsed from the query, Page and Size are populated so clients can compute total pages without extra logic.
Source Files