Files
configkit/examples/consumers/result_component.go

123 lines
4.7 KiB
Go

package consumers
import (
"errors"
"io"
"io/fs"
"path"
"slices"
"strings"
configkit "go.maximumdirect.net/configkit"
)
// ComponentSettings is a library-owned configuration type embedded by an application.
type ComponentSettings struct {
Name string `yaml:"name"`
Resource string `yaml:"resource"`
Token string `yaml:"token"`
Entries []ComponentItem `yaml:"entries"`
}
// ComponentItem is one identified library setting.
type ComponentItem struct {
ID string `yaml:"id"`
Resource string `yaml:"resource"`
}
// ComponentApplication is the application-owned root for this example.
type ComponentApplication struct {
Component ComponentSettings `yaml:"component"`
}
// ComponentResult is the small interface required by the library at handoff.
type ComponentResult interface {
Value(configkit.Path) (any, bool)
Metadata() configkit.Metadata
SourceContext(string) (configkit.ResourceContext, bool)
}
// ComponentRuntime contains settings and captured resource data owned by the library.
type ComponentRuntime struct {
Settings ComponentSettings
Resource []byte
}
// ComponentDefinition registers library behavior through an application field selector.
func ComponentDefinition[T any](selectSettings func(*T) *ComponentSettings) configkit.Definition[T] {
component := configkit.Keys("component")
return configkit.Definition[T]{
SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(component.Key("entries"), "id")},
Resolve: func(root *T, resolution *configkit.Resolution) error {
settings := selectSettings(root)
configkit.Default(resolution, component.Key("name"), &settings.Name, "default component", "use component default")
configkit.Normalize(resolution, component.Key("name"), &settings.Name, strings.TrimSpace(settings.Name), "trim component name")
return nil
},
Validate: func(root *T, validation *configkit.Validation) {
if selectSettings(root).Name == "" {
validation.Error(component.Key("name"), "component name is required")
}
},
Sensitive: func(path configkit.Path) bool { return path.String() == "/component/token" },
}
}
// LoadComponentApplication assembles one application load with bundled underlay defaults.
func LoadComponentApplication(source configkit.Source) (*configkit.Result[ComponentApplication], error) {
return configkit.LoadLayered(configkit.Input{Source: source}, configkit.LayeredOptions[ComponentApplication]{
Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{Source: configkit.Bytes("component defaults", []byte("component: {entries: [{id: default}]}\n"))}}}},
Definition: ComponentDefinition(func(root *ComponentApplication) *ComponentSettings { return &root.Component }),
})
}
// NewComponent accepts the entire result, selects library settings, and captures
// a resource relative to the effective field's original source.
func NewComponent(result ComponentResult) (ComponentRuntime, error) {
value, ok := result.Value(configkit.Keys("component"))
settings, typed := value.(ComponentSettings)
if !ok || !typed {
return ComponentRuntime{}, errors.New("component settings unavailable")
}
settings.Entries = slices.Clone(settings.Entries)
info, ok := result.Metadata().Lookup(configkit.Keys("component", "resource"))
if !ok || len(info.Origin.Locations) != 1 {
return ComponentRuntime{}, errors.New("component resource origin unavailable")
}
context, ok := result.SourceContext(info.Origin.Locations[0].SourceID)
if !ok {
return ComponentRuntime{}, errors.New("component resource context unavailable")
}
data, err := fs.ReadFile(context.FS, path.Join(context.BaseDir, settings.Resource))
if err != nil {
return ComponentRuntime{}, err
}
return ComponentRuntime{Settings: settings, Resource: data}, nil
}
// ComponentInspection is a library-owned facade over one selected reporting view.
type ComponentInspection struct{ view configkit.Inspection }
// InspectComponent selects the library's conventional reporting scope once.
func InspectComponent(result interface {
InspectSubtree(configkit.Path) (configkit.Inspection, bool)
}) (ComponentInspection, bool) {
view, ok := result.InspectSubtree(configkit.Keys("component"))
return ComponentInspection{view: view}, ok
}
// WriteEffective renders the frozen component safely.
func (i ComponentInspection) WriteEffective(output io.Writer) error {
return i.view.WriteEffective(output)
}
// Explain forwards native application paths without changing their meaning.
func (i ComponentInspection) Explain(path configkit.Path) (configkit.Explanation, bool) {
return i.view.Explain(path)
}
// Diff compares two frozen component views.
func (i ComponentInspection) Diff(other ComponentInspection) ([]configkit.Difference, error) {
return i.view.Diff(other.view)
}