public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

kindsys: Change "Meta" to "Properties" (#59852)

Browse Source
This commit is contained in:
sam boyer
2022-12-05 14:48:47 -05:00
committed by GitHub
parent 4e0f95dc31
commit 46143b0764
17 changed files with 237 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files
pkg/kindsys/kind.go
+17 -7
View File
@@ -41,15 +41,25 @@ func (m Maturity) Less(om Maturity) bool {
return maturityIdx(m) < maturityIdx(om)
}
// TODO docs
// Interface describes a Grafana kind object: a Go representation of the definition of
// one of Grafana's categories of kinds.
type Interface interface {
// TODO docs
// Props returns a [kindsys.SomeKindProps], representing the properties
// of the kind as declared in the .cue source. The underlying type is
// determined by the category of kind.
//
// This method is largely for convenience, as all actual kind categories are
// expected to implement one of the other interfaces, each of which contain
// a Decl() method through which these same properties are accessible.
Props() SomeKindProperties
// TODO remove, unnecessary with Props()
Name() string
// TODO docs
// TODO remove, unnecessary with Props()
MachineName() string
// TODO docs
// TODO remove, unnecessary with Props()
Maturity() Maturity // TODO unclear if we want maturity for raw kinds
}
@@ -58,7 +68,7 @@ type Raw interface {
Interface
// TODO docs
Decl() *Decl[RawMeta]
Decl() *Decl[RawProperties]
}
type Structured interface {
@@ -68,7 +78,7 @@ type Structured interface {
Lineage() thema.Lineage
// TODO docs
Decl() *Decl[CoreStructuredMeta] // TODO figure out how to reconcile this interface with CustomStructuredMeta
Decl() *Decl[CoreStructuredProperties] // TODO figure out how to reconcile this interface with CustomStructuredProperties
}
// type Composable interface {
@@ -78,5 +88,5 @@ type Structured interface {
// Lineage() thema.Lineage
//
// // TODO docs
// Meta() CoreStructuredMeta // TODO figure out how to reconcile this interface with CustomStructuredMeta
// Properties() CoreStructuredProperties // TODO figure out how to reconcile this interface with CustomStructuredProperties
// }
pkg/kindsys/kindmetas.go
+50 -35
View File
@@ -2,8 +2,8 @@ package kindsys
import "github.com/grafana/thema"
// CommonMeta contains the metadata common to all categories of kinds.
type CommonMeta struct {
// CommonProperties contains the metadata common to all categories of kinds.
type CommonProperties struct {
Name string `json:"name"`
PluralName string `json:"pluralName"`
MachineName string `json:"machineName"`
@@ -12,63 +12,78 @@ type CommonMeta struct {
Maturity Maturity `json:"maturity"`
}
// TODO generate from type.cue
type RawMeta struct {
CommonMeta
// RawProperties represents the static properties in a #Raw kind declaration that are
// trivially representable with basic Go types.
//
// When a .cue #Raw declaration is loaded through the standard [LoadCoreKind],
// func, it is fully validated and populated according to all rules specified
// in CUE for #Raw kinds.
type RawProperties struct {
CommonProperties
Extensions []string `json:"extensions"`
}
func (m RawMeta) _private() {}
func (m RawMeta) Common() CommonMeta {
return m.CommonMeta
func (m RawProperties) _private() {}
func (m RawProperties) Common() CommonProperties {
return m.CommonProperties
}
// TODO
type CoreStructuredMeta struct {
CommonMeta
// CoreStructuredProperties represents the static properties in the declaration of a
// #CoreStructured kind that are representable with basic Go types. This
// excludes Thema schemas.
//
// When a .cue #CoreStructured declaration is loaded through the standard [LoadCoreKind],
// func, it is fully validated and populated according to all rules specified
// in CUE for #CoreStructured kinds.
type CoreStructuredProperties struct {
CommonProperties
CurrentVersion thema.SyntacticVersion `json:"currentVersion"`
}
func (m CoreStructuredMeta) _private() {}
func (m CoreStructuredMeta) Common() CommonMeta {
return m.CommonMeta
func (m CoreStructuredProperties) _private() {}
func (m CoreStructuredProperties) Common() CommonProperties {
return m.CommonProperties
}
// TODO
type CustomStructuredMeta struct {
CommonMeta
// CustomStructuredProperties represents the static properties in the declaration of a
// #CustomStructured kind that are representable with basic Go types. This
// excludes Thema schemas.
type CustomStructuredProperties struct {
CommonProperties
CurrentVersion thema.SyntacticVersion `json:"currentVersion"`
}
func (m CustomStructuredMeta) _private() {}
func (m CustomStructuredMeta) Common() CommonMeta {
return m.CommonMeta
func (m CustomStructuredProperties) _private() {}
func (m CustomStructuredProperties) Common() CommonProperties {
return m.CommonProperties
}
// TODO
type ComposableMeta struct {
CommonMeta
// ComposableProperties represents the static properties in the declaration of a
// #Composable kind that are representable with basic Go types. This
// excludes Thema schemas.
type ComposableProperties struct {
CommonProperties
CurrentVersion thema.SyntacticVersion `json:"currentVersion"`
}
func (m ComposableMeta) _private() {}
func (m ComposableMeta) Common() CommonMeta {
return m.CommonMeta
func (m ComposableProperties) _private() {}
func (m ComposableProperties) Common() CommonProperties {
return m.CommonProperties
}
// SomeKindMeta is an interface type to abstract over the different kind
// metadata struct types: [RawMeta], [CoreStructuredMeta],
// [CustomStructuredMeta].
// SomeKindProperties is an interface type to abstract over the different kind
// property struct types: [RawProperties], [CoreStructuredProperties],
// [CustomStructuredProperties], [ComposableProperties].
//
// It is the traditional interface counterpart to the generic type constraint
// KindMetas.
type SomeKindMeta interface {
// KindProperties.
type SomeKindProperties interface {
_private()
Common() CommonMeta
Common() CommonProperties
}
// KindMetas is a type parameter that comprises the base possible set of
// KindProperties is a type parameter that comprises the base possible set of
// kind metadata configurations.
type KindMetas interface {
RawMeta | CoreStructuredMeta | CustomStructuredMeta | ComposableMeta
type KindProperties interface {
RawProperties | CoreStructuredProperties | CustomStructuredProperties | ComposableProperties
}
pkg/kindsys/load.go
+30 -30
View File
@@ -83,52 +83,52 @@ func CUEFramework(ctx *cue.Context) cue.Value {
// ToKindMeta takes a cue.Value expected to represent a kind of the category
// specified by the type parameter and populates the Go type from the cue.Value.
func ToKindMeta[T KindMetas](v cue.Value) (T, error) {
meta := new(T)
func ToKindMeta[T KindProperties](v cue.Value) (T, error) {
props := new(T)
if !v.Exists() {
return *meta, ErrValueNotExist
return *props, ErrValueNotExist
}
fw := CUEFramework(v.Context())
var kdef cue.Value
anymeta := any(*meta).(SomeKindMeta)
switch anymeta.(type) {
case RawMeta:
anyprops := any(*props).(SomeKindProperties)
switch anyprops.(type) {
case RawProperties:
kdef = fw.LookupPath(cue.MakePath(cue.Def("Raw")))
case CoreStructuredMeta:
case CoreStructuredProperties:
kdef = fw.LookupPath(cue.MakePath(cue.Def("CoreStructured")))
case CustomStructuredMeta:
case CustomStructuredProperties:
kdef = fw.LookupPath(cue.MakePath(cue.Def("CustomStructured")))
case ComposableMeta:
case ComposableProperties:
kdef = fw.LookupPath(cue.MakePath(cue.Def("Composable")))
default:
// unreachable so long as all the possibilities in KindMetas have switch branches
// unreachable so long as all the possibilities in KindProperties have switch branches
panic("unreachable")
}
item := v.Unify(kdef)
if err := item.Validate(cue.Concrete(false), cue.All()); err != nil {
return *meta, ewrap(item.Err(), ErrValueNotAKind)
return *props, ewrap(item.Err(), ErrValueNotAKind)
}
if err := item.Decode(meta); err != nil {
if err := item.Decode(props); err != nil {
// Should only be reachable if CUE and Go framework types have diverged
panic(errors.Details(err, nil))
}
return *meta, nil
return *props, nil
}
// SomeDecl represents a single kind declaration, having been loaded
// and validated by a func such as [LoadCoreKind].
//
// The underlying type of the Meta field indicates the category of
// The underlying type of the Properties field indicates the category of
// kind.
type SomeDecl struct {
// V is the cue.Value containing the entire Kind declaration.
V cue.Value
// Meta contains the kind's metadata settings.
Meta SomeKindMeta
// Properties contains the kind's declared properties.
Properties SomeKindProperties
}
// BindKindLineage binds the lineage for the kind declaration. nil, nil is returned
@@ -140,10 +140,10 @@ func (decl *SomeDecl) BindKindLineage(rt *thema.Runtime, opts ...thema.BindOptio
if rt == nil {
rt = cuectx.GrafanaThemaRuntime()
}
switch decl.Meta.(type) {
case RawMeta:
switch decl.Properties.(type) {
case RawProperties:
return nil, nil
case CoreStructuredMeta, CustomStructuredMeta, ComposableMeta:
case CoreStructuredProperties, CustomStructuredProperties, ComposableProperties:
return thema.BindLineage(decl.V.LookupPath(cue.MakePath(cue.Str("lineage"))), rt, opts...)
default:
panic("unreachable")
@@ -152,25 +152,25 @@ func (decl *SomeDecl) BindKindLineage(rt *thema.Runtime, opts ...thema.BindOptio
// IsRaw indicates whether the represented kind is a raw kind.
func (decl *SomeDecl) IsRaw() bool {
_, is := decl.Meta.(RawMeta)
_, is := decl.Properties.(RawProperties)
return is
}
// IsCoreStructured indicates whether the represented kind is a core structured kind.
func (decl *SomeDecl) IsCoreStructured() bool {
_, is := decl.Meta.(CoreStructuredMeta)
_, is := decl.Properties.(CoreStructuredProperties)
return is
}
// IsCustomStructured indicates whether the represented kind is a custom structured kind.
func (decl *SomeDecl) IsCustomStructured() bool {
_, is := decl.Meta.(CustomStructuredMeta)
_, is := decl.Properties.(CustomStructuredProperties)
return is
}
// IsComposable indicates whether the represented kind is a composable kind.
func (decl *SomeDecl) IsComposable() bool {
_, is := decl.Meta.(ComposableMeta)
_, is := decl.Properties.(ComposableProperties)
return is
}
@@ -178,18 +178,18 @@ func (decl *SomeDecl) IsComposable() bool {
// and validated by a func such as [LoadCoreKind].
//
// Its type parameter indicates the category of kind.
type Decl[T KindMetas] struct {
type Decl[T KindProperties] struct {
// V is the cue.Value containing the entire Kind declaration.
V cue.Value
// Meta contains the kind's metadata settings.
Meta T
// Properties contains the kind's declared properties.
Properties T
}
// Some converts the typed Decl to the equivalent typeless SomeDecl.
func (decl *Decl[T]) Some() *SomeDecl {
return &SomeDecl{
V: decl.V,
Meta: any(decl.Meta).(SomeKindMeta),
V: decl.V,
Properties: any(decl.Properties).(SomeKindProperties),
}
}
@@ -210,7 +210,7 @@ func (decl *Decl[T]) Some() *SomeDecl {
// This is a low-level function, primarily intended for use in code generation.
// For representations of core kinds that are useful in Go programs at runtime,
// see ["github.com/grafana/grafana/pkg/registry/corekind"].
func LoadCoreKind[T RawMeta | CoreStructuredMeta](declpath string, ctx *cue.Context, overlay fs.FS) (*Decl[T], error) {
func LoadCoreKind[T RawProperties | CoreStructuredProperties](declpath string, ctx *cue.Context, overlay fs.FS) (*Decl[T], error) {
vk, err := cuectx.BuildGrafanaInstance(ctx, declpath, "kind", overlay)
if err != nil {
return nil, err
@@ -218,7 +218,7 @@ func LoadCoreKind[T RawMeta | CoreStructuredMeta](declpath string, ctx *cue.Cont
decl := &Decl[T]{
V: vk,
}
decl.Meta, err = ToKindMeta[T](vk)
decl.Properties, err = ToKindMeta[T](vk)
if err != nil {
return nil, err
}