Documentation
¶
Overview ¶
Package modelregistry is the shared catalogue of the Go model structs that the ResolveSpec front ends (resolvespec, restheadspec, websocketspec, mqttspec, resolvemcp, ...) expose as database entities.
A registry maps a model name ("schema.entity") to a struct type and holds:
- ModelRules: which operations (read/create/update/delete, public or not) are allowed, and whether security checks are disabled.
- ModelInfo: optional documentation (description, purpose, tags, per-column descriptions) meant for humans and AI agents. It never affects queries or permissions.
Register models on a registry created with NewModelRegistry, or through the package-level functions that use the default registry:
reg := modelregistry.NewModelRegistry()
_ = reg.RegisterModelWithRules("public.users", User{}, modelregistry.DefaultModelRules())
reg.SetModelInfo("public.users", modelregistry.ModelInfo{
Description: "Application accounts",
Purpose: "Look up who a person is; never store credentials here",
Columns: map[string]string{"email": "Login address, unique"},
})
Descriptions come from, in priority order:
- ModelInfo set with SetModelInfo or loaded from an external JSON map with LoadModelInfoFile (the map can be maintained outside the Go code).
- The model's Describer (ModelDescription() string) for the description.
- Struct tags, read per column by FieldComment: comment, note, desc or description tags, then "comment:" inside the gorm or bun tag.
Models must be non-pointer structs; pointers, slices and arrays of structs are unwrapped on registration. All registry methods are safe for concurrent use.
Index ¶
- Variables
- func AddRegistry(registry *DefaultModelRegistry)
- func FieldComment(sf reflect.StructField) string
- func GetModelByName(name string) (interface{}, error)
- func GetModels() []interface{}
- func IterateModels(fn func(name string, model interface{}))
- func RegisterModel(model interface{}, name string) error
- func RegisterModelWithRules(model interface{}, name string, rules ModelRules) error
- func SetDefaultRegistry(registry *DefaultModelRegistry)
- func SetModelRules(name string, rules ModelRules) error
- type DefaultModelRegistry
- func (r *DefaultModelRegistry) GetAllModels() map[string]interface{}
- func (r *DefaultModelRegistry) GetModel(name string) (interface{}, error)
- func (r *DefaultModelRegistry) GetModelByEntity(schema, entity string) (interface{}, error)
- func (r *DefaultModelRegistry) GetModelInfo(name string) (ModelInfo, bool)
- func (r *DefaultModelRegistry) GetModelRules(name string) (ModelRules, error)
- func (r *DefaultModelRegistry) LoadModelInfo(src io.Reader) (int, error)
- func (r *DefaultModelRegistry) LoadModelInfoFile(path string) (int, error)
- func (r *DefaultModelRegistry) RegisterModel(name string, model interface{}) error
- func (r *DefaultModelRegistry) RegisterModelWithInfo(name string, model interface{}, info ModelInfo) error
- func (r *DefaultModelRegistry) RegisterModelWithRules(name string, model interface{}, rules ModelRules) error
- func (r *DefaultModelRegistry) ResolveModelInfo(name string) ModelInfo
- func (r *DefaultModelRegistry) SetModelInfo(name string, info ModelInfo)
- func (r *DefaultModelRegistry) SetModelRules(name string, rules ModelRules) error
- type Describer
- type ModelInfo
- type ModelRules
Constants ¶
This section is empty.
Variables ¶
var ( ErrModelNotFound = errors.New("model not found") ErrModelExists = errors.New("model already registered") ErrInvalidModel = errors.New("invalid model") )
Sentinel errors so callers (notably the security layer) can distinguish "not registered" from every other failure with errors.Is.
Functions ¶
func AddRegistry ¶ added in v0.0.34
func AddRegistry(registry *DefaultModelRegistry)
AddRegistry adds a registry to the global list of registries Registries are searched in the order they were added
func FieldComment ¶ added in v1.3.6
func FieldComment(sf reflect.StructField) string
FieldComment returns the description of a struct field from its tags. Order: standalone comment/note/desc/description tags, then a "comment:" entry inside the gorm tag (semicolon separated), then inside the bun tag (comma separated). It returns "" when the field carries none.
func GetModelByName ¶
GetModelByName retrieves a model by searching through all registries in order Returns the first match found
func GetModels ¶
func GetModels() []interface{}
GetModels returns a list of all models from all registries. Only the first occurrence of each model name is included.
func IterateModels ¶
func IterateModels(fn func(name string, model interface{}))
IterateModels iterates over all models in the default global registry. It iterates over a snapshot, so fn may safely call back into the registry. A panic in fn is recovered and logged with the model name, and iteration continues with the remaining models.
func RegisterModel ¶
RegisterModel registers a model with the default global registry
func RegisterModelWithRules ¶ added in v0.0.108
func RegisterModelWithRules(model interface{}, name string, rules ModelRules) error
RegisterModelWithRules registers a model with specific rules in the default registry
func SetDefaultRegistry ¶ added in v0.0.35
func SetDefaultRegistry(registry *DefaultModelRegistry)
SetDefaultRegistry replaces the default registry. A nil registry is ignored.
func SetModelRules ¶ added in v0.0.108
func SetModelRules(name string, rules ModelRules) error
SetModelRules sets the rules for a specific model in the default registry
Types ¶
type DefaultModelRegistry ¶
type DefaultModelRegistry struct {
// contains filtered or unexported fields
}
DefaultModelRegistry implements ModelRegistry interface
func GetDefaultRegistry ¶ added in v0.0.88
func GetDefaultRegistry() *DefaultModelRegistry
GetDefaultRegistry returns the current default registry.
func NewModelRegistry ¶
func NewModelRegistry() *DefaultModelRegistry
NewModelRegistry creates a new model registry
func (*DefaultModelRegistry) GetAllModels ¶
func (r *DefaultModelRegistry) GetAllModels() map[string]interface{}
func (*DefaultModelRegistry) GetModel ¶
func (r *DefaultModelRegistry) GetModel(name string) (interface{}, error)
func (*DefaultModelRegistry) GetModelByEntity ¶
func (r *DefaultModelRegistry) GetModelByEntity(schema, entity string) (interface{}, error)
func (*DefaultModelRegistry) GetModelInfo ¶ added in v1.3.6
func (r *DefaultModelRegistry) GetModelInfo(name string) (ModelInfo, bool)
GetModelInfo returns the documentation stored with SetModelInfo (or loaded from a descriptions file), without any fallback.
func (*DefaultModelRegistry) GetModelRules ¶ added in v0.0.108
func (r *DefaultModelRegistry) GetModelRules(name string) (ModelRules, error)
GetModelRules retrieves the rules for a specific model Returns default rules if model exists but rules are not set
func (*DefaultModelRegistry) LoadModelInfo ¶ added in v1.3.6
func (r *DefaultModelRegistry) LoadModelInfo(src io.Reader) (int, error)
LoadModelInfo reads an external descriptions map from r and applies it. The JSON is an object keyed by model name:
{"public.users": {"description": "...", "purpose": "...", "tags": ["x"],
"columns": {"email": "Login address"}}}
Entries replace any existing info for the same name and take precedence over the model's Describer and its struct-tag comments. It returns the number of models loaded.
func (*DefaultModelRegistry) LoadModelInfoFile ¶ added in v1.3.6
func (r *DefaultModelRegistry) LoadModelInfoFile(path string) (int, error)
LoadModelInfoFile is LoadModelInfo reading from a JSON file.
func (*DefaultModelRegistry) RegisterModel ¶
func (r *DefaultModelRegistry) RegisterModel(name string, model interface{}) error
func (*DefaultModelRegistry) RegisterModelWithInfo ¶ added in v1.3.6
func (r *DefaultModelRegistry) RegisterModelWithInfo(name string, model interface{}, info ModelInfo) error
RegisterModelWithInfo registers a model together with its documentation.
func (*DefaultModelRegistry) RegisterModelWithRules ¶ added in v0.0.108
func (r *DefaultModelRegistry) RegisterModelWithRules(name string, model interface{}, rules ModelRules) error
RegisterModelWithRules registers a model with specific rules atomically
func (*DefaultModelRegistry) ResolveModelInfo ¶ added in v1.3.6
func (r *DefaultModelRegistry) ResolveModelInfo(name string) ModelInfo
ResolveModelInfo returns the effective documentation for a registered model. Stored/loaded info wins; an empty Description falls back to the model's Describer. Column descriptions are not resolved here: use the stored map and fall back to FieldComment per field.
func (*DefaultModelRegistry) SetModelInfo ¶ added in v1.3.6
func (r *DefaultModelRegistry) SetModelInfo(name string, info ModelInfo)
SetModelInfo stores documentation for a model name ("schema.entity"). The model does not have to be registered yet, so descriptions can be loaded before or after registration. Any previous info for the name is replaced.
func (*DefaultModelRegistry) SetModelRules ¶ added in v0.0.108
func (r *DefaultModelRegistry) SetModelRules(name string, rules ModelRules) error
SetModelRules sets the rules for a specific model
type Describer ¶ added in v1.3.6
type Describer interface {
ModelDescription() string
}
Describer can be implemented by a model to document itself. It is the fallback used when no ModelInfo description was registered or loaded. (The method is not called Description so models may keep a Description field.)
type ModelInfo ¶ added in v1.3.6
type ModelInfo struct {
// Description says what the model/table holds.
Description string `json:"description,omitempty"`
// Purpose says why it exists / when an agent should use it.
Purpose string `json:"purpose,omitempty"`
// Tags are free-form labels (e.g. "billing", "pii").
Tags []string `json:"tags,omitempty"`
// Columns maps a JSON column name to its description.
Columns map[string]string `json:"columns,omitempty"`
}
ModelInfo is human/AI-facing documentation for a registered model: what it is for and what its columns mean. It is optional and has no effect on permissions or queries.
type ModelRules ¶ added in v0.0.108
type ModelRules struct {
CanPublicRead bool // Whether the model can be read (GET operations)
CanPublicUpdate bool // Whether the model can be updated (PUT/PATCH operations)
CanPublicCreate bool // Whether the model can be created (POST operations)
CanPublicDelete bool // Whether the model can be deleted (DELETE operations)
CanRead bool // Whether the model can be read (GET operations)
CanUpdate bool // Whether the model can be updated (PUT/PATCH operations)
CanCreate bool // Whether the model can be created (POST operations)
CanDelete bool // Whether the model can be deleted (DELETE operations)
SecurityDisabled bool // Whether security checks are disabled for this model
}
ModelRules defines the permissions and security settings for a model
func DefaultModelRules ¶ added in v0.0.108
func DefaultModelRules() ModelRules
DefaultModelRules returns the default rules for a model (all operations allowed, security enabled)
func GetModelRules ¶ added in v0.0.108
func GetModelRules(name string) (ModelRules, error)
GetModelRules retrieves the rules for a specific model from the default registry
func GetModelRulesByName ¶ added in v0.0.108
func GetModelRulesByName(name string) (ModelRules, error)
GetModelRulesByName retrieves the rules for a model by searching through all registries in order Returns the first match found. The error wraps ErrModelNotFound when no registry has the model.
Source Files