pfs

Documentation

Index

• Constants
• Variables
• func LoadComposableKindDef(fsys fs.FS, rt *thema.Runtime, defpath string) (kindsys.Def[kindsys.ComposableProperties], error)
• func NewDeclParser(rt *thema.Runtime, skip map[string]bool) *declParser
• type ParsedPlugin
  • func ParsePluginFS(fsys fs.FS, rt *thema.Runtime) (ParsedPlugin, error)
• type PluginDecl
  • func EmptyPluginDecl(path string, meta plugindef.PluginDef) *PluginDecl
  • func (decl *PluginDecl) HasSchema() bool

Constants

const PackageName = "grafanaplugin"

PackageName is the name of the CUE package that Grafana will load when looking for a Grafana plugin's kind declarations.

Variables

var ErrComposableNotExpected = errors.New("plugin type should not produce composable kind for schema interface")

ErrComposableNotExpected indicates that a plugin has a composable kind for a schema interface that is not expected, given the type of the plugin. (For example, a datasource plugin has a panelcfg composable kind)

var ErrDisallowedCUEImport = errors.New("CUE import is not allowed")

ErrDisallowedCUEImport indicates that a plugin's grafanaplugin cue package contains that are not on the allowlist.

var ErrEmptyFS = errors.New("provided fs.FS is empty")

ErrEmptyFS indicates that the fs.FS provided to ParsePluginFS was empty.

var ErrExpectedComposable = errors.New("plugin type should produce composable kind for schema interface")

ErrExpectedComposable indicates that a plugin lacks a composable kind implementation for a schema interface that is expected for that plugin's type. (For example, a datasource plugin lacks a queries composable kind)

var ErrInvalidGrafanaPluginInstance = errors.New("grafanaplugin cue instance is invalid")

ErrInvalidGrafanaPluginInstance indicates a plugin's set of .cue grafanaplugin package files are invalid with respect to the GrafanaPlugin spec.

var ErrInvalidLineage = errors.New("invalid lineage")

ErrInvalidLineage indicates that the plugin contains an invalid lineage declaration, according to Thema's validation rules in ["github.com/grafana/thema".BindLineage].

var ErrInvalidRootFile = errors.New("plugin.json is invalid")

ErrInvalidRootFile indicates that the root plugin.json file is invalid.

var ErrNoRootFile = errors.New("no plugin.json at root of fs.fS")

ErrNoRootFile indicates that no root plugin.json file exists.

var PermittedCUEImports = cuectx.PermittedCUEImports

PermittedCUEImports returns the list of import paths that may be used in a plugin's grafanaplugin cue package.

Functions

func LoadComposableKindDef

func LoadComposableKindDef(fsys fs.FS, rt *thema.Runtime, defpath string) (kindsys.Def[kindsys.ComposableProperties], error)

LoadComposableKindDef loads and validates a composable kind definition. On success, it returns a [Def] which contains the entire contents of the kind definition.

defpath is the path to the directory containing the composable kind definition, relative to the root of the caller's repository.

NOTE This function will be deprecated in favor of a more generic loader when kind providers will be implemented.

func NewDeclParser

func NewDeclParser(rt *thema.Runtime, skip map[string]bool) *declParser

Types

type ParsedPlugin

type ParsedPlugin struct {
	// Properties contains the plugin's definition, as declared in plugin.json.
	Properties plugindef.PluginDef

	// ComposableKinds is a map of all the composable kinds declared in this plugin.
	// Keys are the name of the [kindsys.SchemaInterface] implemented by the value.
	//
	// Composable kind defs are only populated in this map by [ParsePluginFS] if
	// they are implementations of a known schema interface, or are for
	// an unknown schema interface.
	ComposableKinds map[string]kindsys.Composable

	// CUEImports lists the CUE import statements in the plugin's grafanaplugin CUE
	// package, if any.
	CUEImports []*ast.ImportSpec
}

ParsedPlugin represents everything knowable about a single plugin from static analysis of its filesystem tree contents, as performed by ParsePluginFS.

Guarantees described in the below comments only exist for instances of this struct returned from ParsePluginFS.

func ParsePluginFS

func ParsePluginFS(fsys fs.FS, rt *thema.Runtime) (ParsedPlugin, error)

ParsePluginFS takes a virtual filesystem and checks that it contains a valid set of files that statically define a Grafana plugin.

The fsys must contain a plugin.json at the root, which must be valid according to the plugindef schema. If any .cue files exist in the grafanaplugin package, these will also be loaded and validated according to the GrafanaPlugin specification. This includes the validation of any custom or composable kinds and their contained lineages, via thema.BindLineage.

This function parses exactly one plugin. It does not descend into subdirectories to search for additional plugin.json or .cue files.

Calling this with a nil thema.Runtime (the singleton returned from cuectx.GrafanaThemaRuntime is used) will memoize certain CUE operations. Prefer passing nil unless a different thema.Runtime is specifically required.

type PluginDecl

type PluginDecl struct {
	SchemaInterface *kindsys.SchemaInterface
	Lineage         thema.Lineage
	Imports         []*ast.ImportSpec
	PluginPath      string
	PluginMeta      plugindef.PluginDef
	KindDecl        kindsys.Def[kindsys.ComposableProperties]
}

func EmptyPluginDecl

func EmptyPluginDecl(path string, meta plugindef.PluginDef) *PluginDecl

func (*PluginDecl) HasSchema

func (decl *PluginDecl) HasSchema() bool