admin

Documentation

Overview

Package admin is Gombit's runtime generic admin (ADMIN-1 through ADMIN-3 / ADR-013).

Feature packages register models explicitly:

admin.Register(app, Product{}, admin.Options{Slug: "products", ...})

framework.New mounts the Huma introspection and data-plane routes, and the /admin/ SPA, only when cookie session auth is on (cfg.Auth.Mode == cookie). JWT-only apps do not get admin routes. Admin requests enforce the registered permission keys; auth.User.IsSuperuser bypasses those checks.

Options is the source of truth. After Register returns, handlers read stored values and GORM constructors — they do not reflect over arbitrary Go types. FieldsFrom and the empty-Fields default may use reflect only inside Register; both are registration-time conveniences.

Index

• Constants
• func Mount(host Host) error
• func Register[T any](host Host, model T, opts Options) error
• type Actions
• type AuthMeta
• type Capabilities
• type Catalog
• type CatalogAux
• type Field
  • func FieldsFrom(model any) ([]Field, error)
• type FieldMeta
• type FieldType
• type Host
• type ModelMeta
• type Options
• type Permissions
• type Relation

Constants

const (
	RelBelongsTo = "belongs_to"
	RelHasMany   = "has_many"
)

Relation kinds for v1. Many-to-many is deferred.

const (
	ImplicitCreatedAt = "created_at"
	ImplicitUpdatedAt = "updated_at"
)

Implicit timestamp names allowed in List and Ordering even when omitted from Fields. They are GORM's default created_at / updated_at columns.

Functions

func Mount

func Mount(host Host) error

Mount registers the admin Huma routes on host.API() when cookie auth is on. The catalog is empty until Register is called. framework.New calls Mount automatically in cookie mode; JWT-only apps must not call it.

func Register

func Register[T any](host Host, model T, opts Options) error

Register adds model T to the host's admin registry.

host is typically *framework.App. Missing or duplicate Slug is an error. Cookie auth must already be on (framework.New mounts the empty admin routes in that mode). After Register returns, the registry holds concrete Options values plus constructors for T; request handlers do not walk arbitrary Go types.

Types

type Actions

type Actions struct {
	List   bool `json:"list"`
	Detail bool `json:"detail"`
	Create bool `json:"create"`
	Update bool `json:"update"`
	Delete bool `json:"delete"`
}

Actions names which data-plane operations are enabled for a model.

type AuthMeta

type AuthMeta struct {
	Mode      string `json:"mode"`
	Bootstrap string `json:"bootstrap"`
}

AuthMeta tells the SPA which authorization rule guards the catalog.

type Capabilities

type Capabilities struct {
	View   bool `json:"view"`
	Create bool `json:"create"`
	Update bool `json:"update"`
	Delete bool `json:"delete"`
}

Capabilities are the current user's enabled actions for one model.

type Catalog

type Catalog struct {
	Models []ModelMeta `json:"models"`
}

Catalog is the GET /admin/meta success data object.

type CatalogAux

type CatalogAux struct {
	Auth *AuthMeta `json:"auth,omitempty"`
}

CatalogAux is optional envelope meta on the catalog.

type Field

type Field struct {
	Name     string    `json:"name"`
	Type     FieldType `json:"type"`
	Required bool      `json:"required"`
	ReadOnly bool      `json:"readonly"`
	Related  *Relation `json:"related,omitempty"`
	// Column is the GORM/SQL column name. Empty means Name == JSON key ==
	// column (the v1 default). Not emitted in meta.
	Column string `json:"-"`
}

Field describes one registered admin field.

Name is the JSON object key used in meta and in data-plane row payloads. For v1, Name is also the GORM/SQL column unless Column is set (when the Go exported name or GORM column differs from the JSON key).

func FieldsFrom

func FieldsFrom(model any) ([]Field, error)

FieldsFrom derives a default []Field from model at registration time. It may use reflect on this one type. Do not call it from request handlers.

Name comes from the json tag when present, otherwise the GORM column / snake_case of the exported field name. Type is inferred from the Go type. Primary keys are readonly. GORM created_at / updated_at are included when present on the struct.

type FieldMeta

type FieldMeta struct {
	Name     string    `json:"name"`
	Type     FieldType `json:"type"`
	Required bool      `json:"required"`
	ReadOnly bool      `json:"readonly"`
	Related  *Relation `json:"related,omitempty"`
}

FieldMeta is the introspection shape of a field (no Column).

type FieldType

type FieldType string

FieldType is a closed admin field type string.

const (
	TypeString   FieldType = "string"
	TypeText     FieldType = "text"
	TypeInteger  FieldType = "integer"
	TypeFloat    FieldType = "float"
	TypeDecimal  FieldType = "decimal"
	TypeBoolean  FieldType = "boolean"
	TypeDateTime FieldType = "datetime"
	TypeDate     FieldType = "date"
	TypeUUID     FieldType = "uuid"
	TypeJSON     FieldType = "json"
	TypeRelation FieldType = "relation"
)

Closed field-type set for v1 (ADR-013). ADMIN-1 may add members with a docs bump; do not invent a parallel type system.

type Host

type Host interface {
	API() huma.API
	DB() *gorm.DB
	Config() config.Config
}

Host is satisfied by *framework.App. It is defined here so this package does not import framework (framework.New calls Mount).

type ModelMeta

type ModelMeta struct {
	Slug        string       `json:"slug"`
	Singular    string       `json:"singular"`
	Plural      string       `json:"plural"`
	PK          string       `json:"pk"`
	Fields      []FieldMeta  `json:"fields"`
	List        []string     `json:"list"`
	Search      []string     `json:"search"`
	Filter      []string     `json:"filter"`
	Ordering    []string     `json:"ordering"`
	Actions     Actions      `json:"actions"`
	Permissions Permissions  `json:"permissions"`
	Can         Capabilities `json:"can"`
}

ModelMeta is one registered model in the introspection API.

type Options

type Options struct {
	// Slug is the URL key (products). Required, lowercase, unique per app.
	Slug string
	// Singular and Plural are UI labels. Empty values are derived at Register
	// from the Go type name and slug.
	Singular string
	Plural   string
	// PK is the JSON/field name of the primary key. Empty means derive the
	// GORM primary key at Register and store it.
	PK string
	// Fields is the concrete field list handlers read. Empty means derive a
	// default from the struct once, inside Register (see FieldsFrom).
	Fields []Field
	// List is the list-view column order.
	List []string
	// Search is the list of field names the search query param applies to.
	Search []string
	// Filter is the list of field names that may appear as list query keys.
	Filter []string
	// Ordering is the list of field names the ordering query param may use.
	// created_at and updated_at may appear here even if omitted from Fields.
	Ordering []string
	// Actions enables list / detail / create / update / delete. The zero
	// value (all false) defaults to all enabled.
	Actions Actions
	// Permissions are authorization keys enforced by the admin handlers.
	// Empty values default to admin.{slug}.{action}.
	Permissions Permissions
}

Options is the source of truth for one registered admin model.

type Permissions

type Permissions struct {
	View   string `json:"view"`
	Create string `json:"create"`
	Update string `json:"update"`
	Delete string `json:"delete"`
}

Permissions holds the keys enforced for each admin operation.

type Relation

type Relation struct {
	Slug       string `json:"slug"`
	Kind       string `json:"kind"`
	LabelField string `json:"label_field"`
}

Relation describes a belongs_to or has_many field. belongs_to is stored as the foreign key on create/update. has_many is meta-only in ADMIN-1: the data plane does not nest related collections.