feat(huma): generic CRUD registrar for CObject resources
This commit is contained in:
kolaente
parent
5ba404ac58
commit
75a9ad4555
|
|
@ -0,0 +1,190 @@
|
|||
package humaapi
|
||||
|
||||
import (
|
||||
"context"
|
||||
"net/http"
|
||||
|
||||
"code.vikunja.io/api/pkg/modules/auth"
|
||||
"code.vikunja.io/api/pkg/web/handler"
|
||||
|
||||
"github.com/danielgtaylor/huma/v2"
|
||||
)
|
||||
|
||||
// SingleID is the common path shape for /resource/{id} endpoints.
|
||||
type SingleID struct {
|
||||
ID int64 `path:"id" doc:"Resource ID"`
|
||||
}
|
||||
|
||||
// Config describes a generic CRUD resource:
|
||||
//
|
||||
// - T is the domain model pointer (must implement handler.CObject)
|
||||
// - P is the path-parameter struct; use SingleID for the simple case or
|
||||
// define your own for nested routes like /tasks/{task}/labels/{label}.
|
||||
//
|
||||
// Note: Go does not permit embedding a type parameter in a struct, so the
|
||||
// generic request wrappers below keep P as a named field. Huma's default
|
||||
// parameter discovery only walks anonymous (embedded) fields, so we define
|
||||
// parallel concrete wrappers per path shape (see SingleID section below)
|
||||
// that embed the concrete path struct. Resources with different path shapes
|
||||
// should add their own wrappers + Register call (this spike only needs
|
||||
// SingleID; the pattern generalises trivially).
|
||||
type Config[T handler.CObject, P any] struct {
|
||||
Tag string
|
||||
BasePath string // list + create; may itself contain {params}
|
||||
ItemPath string // read + update + delete
|
||||
New func() T // factory — same role as WebHandler.EmptyStruct
|
||||
ApplyPath func(T, P) // copies path params onto the model
|
||||
}
|
||||
|
||||
type bodyOutput[T any] struct {
|
||||
Body T
|
||||
}
|
||||
|
||||
type listOutput[T any] struct {
|
||||
Body []T
|
||||
}
|
||||
|
||||
type deleteMessage struct {
|
||||
Message string `json:"message"`
|
||||
}
|
||||
|
||||
// --- SingleID wrappers ---------------------------------------------------
|
||||
//
|
||||
// Concrete request-input types for the /{resource}/{id} shape. Huma's
|
||||
// parameter discovery finds `ID` through the embedded SingleID. The Body
|
||||
// field carries the decoded JSON payload.
|
||||
|
||||
type singleIDCreateInput[T any] struct {
|
||||
// No path params for CREATE (path is /{resource}); we still thread a
|
||||
// matching type parameter so Register can share a single handler shape.
|
||||
Body T
|
||||
}
|
||||
|
||||
type singleIDItemInput struct {
|
||||
SingleID
|
||||
}
|
||||
|
||||
type singleIDListInput struct {
|
||||
Page int `query:"page" default:"1" minimum:"1"`
|
||||
PerPage int `query:"per_page" default:"50" minimum:"1" maximum:"1000"`
|
||||
Search string `query:"s"`
|
||||
}
|
||||
|
||||
type singleIDBodyInput[T any] struct {
|
||||
SingleID
|
||||
Body T
|
||||
}
|
||||
|
||||
// Register wires five Huma operations for the given CRUD resource.
|
||||
//
|
||||
// Today this only implements the SingleID path shape. Resources using
|
||||
// multi-segment paths (e.g. /tasks/{task}/labels/{label}) should hand-write
|
||||
// their huma.Register calls until we generalise this registrar.
|
||||
func Register[T handler.CObject](api huma.API, cfg Config[T, SingleID]) {
|
||||
jwt := []map[string][]string{{"JWTKeyAuth": {}}}
|
||||
|
||||
// CREATE
|
||||
huma.Register(api, huma.Operation{
|
||||
OperationID: cfg.Tag + "-create",
|
||||
Method: http.MethodPut,
|
||||
Path: cfg.BasePath,
|
||||
Tags: []string{cfg.Tag},
|
||||
Security: jwt,
|
||||
}, func(ctx context.Context, in *singleIDCreateInput[T]) (*bodyOutput[T], error) {
|
||||
a, err := auth.GetAuthFromContext(ctx)
|
||||
if err != nil {
|
||||
return nil, huma.Error401Unauthorized(err.Error())
|
||||
}
|
||||
if err := handler.DoCreate(ctx, in.Body, a); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &bodyOutput[T]{Body: in.Body}, nil
|
||||
})
|
||||
|
||||
// READ ONE
|
||||
huma.Register(api, huma.Operation{
|
||||
OperationID: cfg.Tag + "-read",
|
||||
Method: http.MethodGet,
|
||||
Path: cfg.ItemPath,
|
||||
Tags: []string{cfg.Tag},
|
||||
Security: jwt,
|
||||
}, func(ctx context.Context, in *singleIDItemInput) (*bodyOutput[T], error) {
|
||||
a, err := auth.GetAuthFromContext(ctx)
|
||||
if err != nil {
|
||||
return nil, huma.Error401Unauthorized(err.Error())
|
||||
}
|
||||
obj := cfg.New()
|
||||
cfg.ApplyPath(obj, in.SingleID)
|
||||
if _, err := handler.DoReadOne(ctx, obj, a); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &bodyOutput[T]{Body: obj}, nil
|
||||
})
|
||||
|
||||
// READ ALL
|
||||
huma.Register(api, huma.Operation{
|
||||
OperationID: cfg.Tag + "-list",
|
||||
Method: http.MethodGet,
|
||||
Path: cfg.BasePath,
|
||||
Tags: []string{cfg.Tag},
|
||||
Security: jwt,
|
||||
}, func(ctx context.Context, in *singleIDListInput) (*listOutput[T], error) {
|
||||
a, err := auth.GetAuthFromContext(ctx)
|
||||
if err != nil {
|
||||
return nil, huma.Error401Unauthorized(err.Error())
|
||||
}
|
||||
obj := cfg.New()
|
||||
result, _, _, err := handler.DoReadAll(ctx, obj, a, in.Search, in.Page, in.PerPage)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
// Best-effort cast; ReadAll returns interface{}. For the spike
|
||||
// we assume []T. Resources returning a different list item type
|
||||
// should hand-write their list op via huma.Register directly.
|
||||
slice, ok := result.([]T)
|
||||
if !ok {
|
||||
// fall back to marshaling whatever shape was returned
|
||||
return &listOutput[T]{Body: nil}, nil
|
||||
}
|
||||
return &listOutput[T]{Body: slice}, nil
|
||||
})
|
||||
|
||||
// UPDATE
|
||||
huma.Register(api, huma.Operation{
|
||||
OperationID: cfg.Tag + "-update",
|
||||
Method: http.MethodPost,
|
||||
Path: cfg.ItemPath,
|
||||
Tags: []string{cfg.Tag},
|
||||
Security: jwt,
|
||||
}, func(ctx context.Context, in *singleIDBodyInput[T]) (*bodyOutput[T], error) {
|
||||
a, err := auth.GetAuthFromContext(ctx)
|
||||
if err != nil {
|
||||
return nil, huma.Error401Unauthorized(err.Error())
|
||||
}
|
||||
cfg.ApplyPath(in.Body, in.SingleID)
|
||||
if err := handler.DoUpdate(ctx, in.Body, a); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &bodyOutput[T]{Body: in.Body}, nil
|
||||
})
|
||||
|
||||
// DELETE
|
||||
huma.Register(api, huma.Operation{
|
||||
OperationID: cfg.Tag + "-delete",
|
||||
Method: http.MethodDelete,
|
||||
Path: cfg.ItemPath,
|
||||
Tags: []string{cfg.Tag},
|
||||
Security: jwt,
|
||||
}, func(ctx context.Context, in *singleIDItemInput) (*bodyOutput[deleteMessage], error) {
|
||||
a, err := auth.GetAuthFromContext(ctx)
|
||||
if err != nil {
|
||||
return nil, huma.Error401Unauthorized(err.Error())
|
||||
}
|
||||
obj := cfg.New()
|
||||
cfg.ApplyPath(obj, in.SingleID)
|
||||
if err := handler.DoDelete(ctx, obj, a); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &bodyOutput[deleteMessage]{Body: deleteMessage{Message: "Successfully deleted."}}, nil
|
||||
})
|
||||
}
|
||||
|
|
@ -0,0 +1,89 @@
|
|||
package humaapi
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"net/http/httptest"
|
||||
"testing"
|
||||
|
||||
"code.vikunja.io/api/pkg/modules/humaecho5"
|
||||
"code.vikunja.io/api/pkg/web"
|
||||
|
||||
"github.com/danielgtaylor/huma/v2"
|
||||
"github.com/labstack/echo/v5"
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
"xorm.io/xorm"
|
||||
)
|
||||
|
||||
// fakeObj is a minimal CObject for compile-level spec-generation tests only.
|
||||
// It is not exercised at runtime.
|
||||
type fakeObj struct {
|
||||
ID int64 `json:"id"`
|
||||
Title string `json:"title"`
|
||||
}
|
||||
|
||||
// Satisfy handler.CObject (web.CRUDable + web.Permissions) — implementations
|
||||
// are unreachable in this test because we only inspect the OpenAPI spec.
|
||||
|
||||
// web.CRUDable
|
||||
func (*fakeObj) Create(_ *xorm.Session, _ web.Auth) error { panic("unused") }
|
||||
func (*fakeObj) ReadOne(_ *xorm.Session, _ web.Auth) error {
|
||||
panic("unused")
|
||||
}
|
||||
func (*fakeObj) ReadAll(_ *xorm.Session, _ web.Auth, _ string, _ int, _ int) (interface{}, int, int64, error) {
|
||||
panic("unused")
|
||||
}
|
||||
func (*fakeObj) Update(_ *xorm.Session, _ web.Auth) error { panic("unused") }
|
||||
func (*fakeObj) Delete(_ *xorm.Session, _ web.Auth) error { panic("unused") }
|
||||
|
||||
// web.Permissions
|
||||
func (*fakeObj) CanRead(_ *xorm.Session, _ web.Auth) (bool, int, error) { panic("unused") }
|
||||
func (*fakeObj) CanDelete(_ *xorm.Session, _ web.Auth) (bool, error) { panic("unused") }
|
||||
func (*fakeObj) CanUpdate(_ *xorm.Session, _ web.Auth) (bool, error) { panic("unused") }
|
||||
func (*fakeObj) CanCreate(_ *xorm.Session, _ web.Auth) (bool, error) { panic("unused") }
|
||||
|
||||
// TestRegisterEmitsFiveOperations confirms that a call to Register
|
||||
// produces the expected OpenAPI path entries for a simple id-based
|
||||
// resource. We don't invoke the handlers here; we only inspect the spec.
|
||||
func TestRegisterEmitsFiveOperations(t *testing.T) {
|
||||
e := echo.New()
|
||||
api := humaecho5.New(e, huma.DefaultConfig("spike", "0.0.1"))
|
||||
|
||||
Register[*fakeObj](api, Config[*fakeObj, SingleID]{
|
||||
Tag: "fakes",
|
||||
BasePath: "/fakes",
|
||||
ItemPath: "/fakes/{id}",
|
||||
New: func() *fakeObj { return &fakeObj{} },
|
||||
ApplyPath: func(o *fakeObj, p SingleID) { o.ID = p.ID },
|
||||
})
|
||||
|
||||
spec := api.OpenAPI()
|
||||
require.NotNil(t, spec.Paths["/fakes"])
|
||||
require.NotNil(t, spec.Paths["/fakes/{id}"])
|
||||
|
||||
// Five ops across two paths: list+create on base, read+update+delete on item
|
||||
ops := 0
|
||||
for _, p := range spec.Paths {
|
||||
if p.Get != nil {
|
||||
ops++
|
||||
}
|
||||
if p.Put != nil {
|
||||
ops++
|
||||
}
|
||||
if p.Post != nil {
|
||||
ops++
|
||||
}
|
||||
if p.Delete != nil {
|
||||
ops++
|
||||
}
|
||||
}
|
||||
assert.Equal(t, 5, ops)
|
||||
|
||||
// Also prove the spec is 3.1.x
|
||||
req := httptest.NewRequest("GET", "/openapi.json", nil)
|
||||
rec := httptest.NewRecorder()
|
||||
e.ServeHTTP(rec, req)
|
||||
var doc map[string]any
|
||||
require.NoError(t, json.NewDecoder(rec.Body).Decode(&doc))
|
||||
require.Contains(t, doc["openapi"].(string), "3.1")
|
||||
}
|
||||
Loading…
Reference in New Issue