Documentation
¶
Index ¶
- Constants
- func LoadDescriptors(descriptors []EntityDescriptor)
- func Register(d EntityDescriptor)
- func Reset()
- func UpdateDescriptor(kind string, updateFn func(*EntityDescriptor))
- func Validate()
- func ValidateEntityConditions(entities []EntityDescriptor, descriptor EntityDescriptor) error
- func ValidateSpecSchemas(schemaExists func(string) bool)
- type ConditionMappingRule
- type EntityDescriptor
- func All() []EntityDescriptor
- func ChildrenOf(parentKind string) []EntityDescriptor
- func Get(entityKind string) (EntityDescriptor, bool)
- func MustGet(entityKind string) EntityDescriptor
- func Validated(entityKind string) (EntityDescriptor, *errors.ServiceError)
- func WithSpecSchema() []EntityDescriptor
- type MappingExpression
- type MappingOutput
- type OnParentDeletePolicy
- type ReferenceDescriptor
Constants ¶
const ( MaxConditionTypeLength = 100 MaxConditionReasonLength = 256 MaxConditionMessageLength = 2048 )
Field length constraints
Variables ¶
This section is empty.
Functions ¶
func LoadDescriptors ¶ added in v0.3.1
func LoadDescriptors(descriptors []EntityDescriptor)
LoadDescriptors registers entity descriptors loaded from the application config. Called during startup after config is parsed and before services/routes are built.
func Register ¶
func Register(d EntityDescriptor)
Register adds a descriptor to the global registry. Panics on empty Kind or duplicate Kind.
func UpdateDescriptor ¶ added in v0.3.1
func UpdateDescriptor(kind string, updateFn func(*EntityDescriptor))
UpdateDescriptor modifies an existing descriptor in-place. Panics if kind not found. Used by tests to temporarily override descriptor fields.
func Validate ¶
func Validate()
Validate checks registry integrity. Panics on:
- empty Kind or Plural on any descriptor
- any ParentKind that references an unregistered kind
- cycles in the ParentKind ownership chain
- duplicate Plural values across descriptors
- ReferenceDescriptor with TargetKind that doesn't resolve
- duplicate RefType within a single entity's References
- Max < Min (when Max > 0)
- NameMaxLen > 0 && NameMinLen > NameMaxLen
- circular required references (Min > 0 cycle between two or more kinds)
func ValidateEntityConditions ¶ added in v0.3.1
func ValidateEntityConditions(entities []EntityDescriptor, descriptor EntityDescriptor) error
ValidateEntityConditions validates condition mappings for a single entity descriptor Used by registry.Validate() to check conditions inline in entity descriptors
entities: all registered entity descriptors (needed to compute per-adapter synthesized types) descriptor: the specific entity descriptor being validated
func ValidateSpecSchemas ¶ added in v0.3.1
ValidateSpecSchemas checks descriptors that set RequireSpecSchema and panics if their SpecSchemaName is absent from the OpenAPI spec. Entities without RequireSpecSchema are left to buildSchemasMap, which warns and skips them. See also Validate, which checks registry structural integrity.
Types ¶
type ConditionMappingRule ¶ added in v0.3.1
type ConditionMappingRule struct {
Type string `mapstructure:"type" json:"type" validate:"required"`
When MappingExpression `mapstructure:"when" json:"when" validate:"required"`
Output MappingOutput `mapstructure:"output" json:"output" validate:"required"`
}
ConditionMappingRule defines a single condition mapping rule
type EntityDescriptor ¶
type EntityDescriptor struct {
// discriminator value stored in Resource.Kind
Kind string `mapstructure:"kind" json:"kind"`
// URL path segment, e.g. "channels"
Plural string `mapstructure:"plural" json:"plural"`
// "" for top-level entities
ParentKind string `mapstructure:"parent_kind" json:"parent_kind,omitempty"`
// OpenAPI component name for spec validation
SpecSchemaName string `mapstructure:"spec_schema_name" json:"spec_schema_name,omitempty"`
// only meaningful when ParentKind != ""
OnParentDelete OnParentDeletePolicy `mapstructure:"on_parent_delete" json:"on_parent_delete,omitempty"`
// adapters that must finalize before hard-delete
RequiredAdapters []string `mapstructure:"required_adapters" json:"required_adapters,omitempty"`
// non-ownership associations to other entity types (HYPERFLEET-1156)
References []ReferenceDescriptor `mapstructure:"references" json:"references,omitempty"`
// CEL-based condition mapping rules for this entity type
Conditions []ConditionMappingRule `mapstructure:"conditions" json:"conditions,omitempty"`
// minimum name length (0 = no constraint)
NameMinLen int `mapstructure:"name_min_len" json:"name_min_len,omitempty"`
// maximum name length (0 = no constraint)
NameMaxLen int `mapstructure:"name_max_len" json:"name_max_len,omitempty"`
// panic at startup if SpecSchemaName missing from spec
RequireSpecSchema bool `mapstructure:"require_spec_schema" json:"require_spec_schema,omitempty"`
}
EntityDescriptor defines everything specific to a HyperFleet entity type. Descriptors are loaded from the application config YAML at startup via LoadDescriptors.
func ChildrenOf ¶
func ChildrenOf(parentKind string) []EntityDescriptor
ChildrenOf returns descriptors whose ParentKind matches the given kind.
func Get ¶
func Get(entityKind string) (EntityDescriptor, bool)
Get returns a descriptor by Kind, or (zero, false) if not found.
func MustGet ¶
func MustGet(entityKind string) EntityDescriptor
MustGet returns a descriptor by Kind. Panics if not found.
func Validated ¶ added in v0.3.1
func Validated(entityKind string) (EntityDescriptor, *errors.ServiceError)
Validated returns a descriptor by Kind, or a 400 ServiceError if kind is unregistered. Shared by callers (services, handlers) that need to turn an unknown kind into a client-facing validation error rather than a panic or a bare bool.
func WithSpecSchema ¶ added in v0.3.1
func WithSpecSchema() []EntityDescriptor
WithSpecSchema returns descriptors that declare an OpenAPI spec schema name.
type MappingExpression ¶ added in v0.3.1
type MappingExpression struct {
Expression string `mapstructure:"expression" json:"expression" validate:"required"`
}
MappingExpression wraps a CEL expression string
type MappingOutput ¶ added in v0.3.1
type MappingOutput struct {
Status MappingExpression `mapstructure:"status" json:"status" validate:"required"`
Reason MappingExpression `mapstructure:"reason" json:"reason" validate:"required"`
Message MappingExpression `mapstructure:"message" json:"message" validate:"required"`
}
MappingOutput defines the output expressions for a mapped condition
type OnParentDeletePolicy ¶
type OnParentDeletePolicy string
OnParentDeletePolicy determines child behavior when its parent is deleted.
const ( OnParentDeleteRestrict OnParentDeletePolicy = "restrict" OnParentDeleteCascade OnParentDeletePolicy = "cascade" )
type ReferenceDescriptor ¶ added in v0.3.1
type ReferenceDescriptor struct {
// key in the references map on the Resource API type, e.g. "wif_config"
RefType string `mapstructure:"ref_type" json:"ref_type"`
// Kind of the referenced entity, e.g. "WifConfig"
TargetKind string `mapstructure:"target_kind" json:"target_kind"`
// minimum references of this type (0 = optional)
Min int `mapstructure:"min" json:"min,omitempty"`
// maximum references of this type (0 = unlimited)
Max int `mapstructure:"max" json:"max,omitempty"`
}
ReferenceDescriptor declares a non-ownership association from one entity type to another. See HYPERFLEET-1156 for the full resource references implementation.
Source Files