Demonstrate component result handoff
This commit is contained in:
@@ -1,6 +1,6 @@
|
|||||||
# Implementation plan: typed result values and focused inspection
|
# Implementation plan: typed result values and focused inspection
|
||||||
|
|
||||||
Status: implementation in progress; Stages 1–6 complete.
|
Status: implementation in progress; Stages 1–7 complete.
|
||||||
|
|
||||||
## Scope and working instructions
|
## Scope and working instructions
|
||||||
|
|
||||||
@@ -267,6 +267,8 @@ concurrent-mutation contract.
|
|||||||
|
|
||||||
## Stage 7 — Demonstrate one-library handoff
|
## Stage 7 — Demonstrate one-library handoff
|
||||||
|
|
||||||
|
**Complete.**
|
||||||
|
|
||||||
Add a maintained example and focused test under `examples/consumers/`, for example
|
Add a maintained example and focused test under `examples/consumers/`, for example
|
||||||
`result_component.go` and `result_component_test.go`, using representative small
|
`result_component.go` and `result_component_test.go`, using representative small
|
||||||
library-owned settings rather than adding an actual PromptKit dependency.
|
library-owned settings rather than adding an actual PromptKit dependency.
|
||||||
|
|||||||
121
examples/consumers/result_component.go
Normal file
121
examples/consumers/result_component.go
Normal file
@@ -0,0 +1,121 @@
|
|||||||
|
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"`
|
||||||
|
}
|
||||||
|
|
||||||
|
// 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)
|
||||||
|
}
|
||||||
53
examples/consumers/result_component_test.go
Normal file
53
examples/consumers/result_component_test.go
Normal file
@@ -0,0 +1,53 @@
|
|||||||
|
package consumers
|
||||||
|
|
||||||
|
import (
|
||||||
|
"bytes"
|
||||||
|
"strings"
|
||||||
|
"testing"
|
||||||
|
"testing/fstest"
|
||||||
|
|
||||||
|
configkit "go.maximumdirect.net/configkit"
|
||||||
|
)
|
||||||
|
|
||||||
|
func TestComponentHandoff(t *testing.T) {
|
||||||
|
filesystem := configkit.NewFilesystem("application", fstest.MapFS{
|
||||||
|
"config/main.yml": &fstest.MapFile{Data: []byte("component: {name: ' example ', resource: asset.txt, token: disposable-canary}\n")},
|
||||||
|
"config/asset.txt": &fstest.MapFile{Data: []byte("resource data")},
|
||||||
|
})
|
||||||
|
result, err := LoadComponentApplication(filesystem.File("config/main.yml"))
|
||||||
|
if err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
runtime, err := NewComponent(result)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
if runtime.Settings.Name != "example" || len(runtime.Settings.Entries) != 1 || runtime.Settings.Entries[0].ID != "default" || string(runtime.Resource) != "resource data" {
|
||||||
|
t.Fatalf("component runtime = %#v", runtime)
|
||||||
|
}
|
||||||
|
entries, found := result.Metadata().Lookup(configkit.Keys("component", "entries"))
|
||||||
|
if !result.Metadata().IsExplicit(configkit.Keys("component", "resource")) || !found || entries.Origin.Layer != configkit.LayerUnderlay {
|
||||||
|
t.Fatal("presence did not retain source distinction")
|
||||||
|
}
|
||||||
|
view, ok := InspectComponent(result)
|
||||||
|
if !ok {
|
||||||
|
t.Fatal("component view unavailable")
|
||||||
|
}
|
||||||
|
var output bytes.Buffer
|
||||||
|
if err := view.WriteEffective(&output); err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
if strings.Contains(output.String(), "disposable-canary") || !strings.Contains(output.String(), "example") {
|
||||||
|
t.Fatalf("unsafe report: %s", output.String())
|
||||||
|
}
|
||||||
|
if _, ok := view.Explain(configkit.Keys("component", "resource")); !ok {
|
||||||
|
t.Fatal("resource explanation unavailable")
|
||||||
|
}
|
||||||
|
if diff, err := view.Diff(view); err != nil || len(diff) != 0 {
|
||||||
|
t.Fatalf("view diff = %#v, %v", diff, err)
|
||||||
|
}
|
||||||
|
_, err = LoadComponentApplication(configkit.Bytes("invalid.yml", []byte("component: {name: ' '}\n")))
|
||||||
|
if err == nil {
|
||||||
|
t.Fatal("component validation did not fail")
|
||||||
|
}
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user