// Package module is the Module position of the EDA playbook engine: operator- // installed, in-process, daemon-privileged action implementations, interpreted // via Yaegi (same trust tier as PluginDir and SecretEngineDir -- NOT // repository-supplied task code). // // Each module kind has a fixed signature and generated symbol table: load the // installed source, resolve its typed entrypoint, then call it through the // panic-safe interpreter boundary. // // Per docs/prds/module-position.md, there is deliberately no generic Module // interface with an any payload. Each action kind is its own tiny package // with its own generated contract (internal/domain/eda/module/), and // the registry's internal storage is the only place type erasure appears. package module import ( "context" "fmt" "os" "path/filepath" "reflect" "sort" "strings" "github.com/traefik/yaegi/interp" "github.com/samcharles93/archie-core/internal/domain/eda/module/log" "github.com/samcharles93/archie-core/internal/domain/eda/module/log/logextract" "github.com/samcharles93/archie-core/internal/yaegiutil" ) // Kind is a resolved module implementation: how to load a Yaegi file against // this kind's generated contract, and how to invoke it. type Kind struct { // loadSymbols returns the kind's generated Yaegi symbol table. loadSymbols func() map[string]map[string]reflect.Value // exportPath is the fixed exported function name the interpreted file // must define (e.g. "main.Run"). exportPath string // argsType and resultType are the kind's hand-written Args and Result // struct types. They are the schema the playbook loader declares to CEL // so an arg key or result field typo is a load failure rather than a // dispatch failure (multi-action-playbooks.md, D4). argsType reflect.Type resultType reflect.Type } // registry maps kind name to its one typed contract. Adding a new kind is a // new entry here plus its own schema package -- no generic interface grows. var registry = map[string]Kind{ "log": { loadSymbols: func() map[string]map[string]reflect.Value { return logextract.Symbols }, exportPath: "main.Run", argsType: reflect.TypeFor[log.Args](), resultType: reflect.TypeFor[log.Result](), }, } // ModuleRegistry maps kind names to their resolved, type-erased invokers. // It is not a service locator: it owns one capability family (Module action // kinds) and exposes Register/Invoke only. type ModuleRegistry struct { // kinds holds the resolved invoker per kind. Erasure is internal-only: // the kind's interpreted contract remains fully typed. kinds map[string]invoker } // invoker is the type-erased callable the registry stores: it decodes raw // args, invokes the interpreted function, and marshals the typed result. type invoker func(ctx context.Context, rawArgs map[string]any) (map[string]any, error) // New returns an empty registry. func New() *ModuleRegistry { return &ModuleRegistry{kinds: make(map[string]invoker)} } // Kinds returns the known action-kind names, sorted for determinism. Only // kinds with a registered contract can be loaded; the log kind is the // shipped proof-of-concept (t2db.13). func Kinds() []string { names := make([]string, 0, len(registry)) for name := range registry { names = append(names, name) } sort.Strings(names) return names } // Len returns how many kinds were successfully registered (loaded). func (r *ModuleRegistry) Len() int { return len(r.kinds) } // KindSchema reports the hand-written Args and Result struct types for a // known kind. A kind is known when it has a registered contract in this // package's built-in registry (the log kind is the shipped kind), independent // of whether a module instance is currently loaded from a module directory. // It is the narrow schema source the playbook loader consumes to type-check // an action playbook's args and result references at load. func (r *ModuleRegistry) KindSchema(kind string) (reflect.Type, reflect.Type, bool) { k, ok := registry[kind] if !ok { return nil, nil, false } return k.argsType, k.resultType, true } // Register discovers /.go, interprets it against the kind's // generated symbols, resolves its fixed export, and stores the invoker. // A missing file, an unreadable file, a resolve failure, or an unknown kind // is a reported error -- the daemon aborts startup on a broken module // directory per the established routing-file pattern. func (r *ModuleRegistry) Register(kind, dir string) error { k, ok := registry[kind] if !ok { return fmt.Errorf("module: unknown kind %q", kind) } path := filepath.Join(dir, kind+".go") src, err := os.ReadFile(path) if err != nil { return fmt.Errorf("module: read %s: %w", path, err) } inv, err := resolveInvoker(kind, path, string(src), k) if err != nil { return err } r.kinds[kind] = inv return nil } // resolveInvoker builds the type-erased invoker for one kind from its // interpreted source. Each kind has its own typed decode/invoke path below; // this switch is the only place the per-kind types are named. func resolveInvoker(kind, label, src string, k Kind) (invoker, error) { switch kind { case "log": return logInvoker(label, src, k) default: return nil, fmt.Errorf("module: no invoker for kind %q", kind) } } // logInvoker resolves a log kind's main.Run func(log.Args) log.Result, // decoding rawArgs strictly into log.Args first (a shape mismatch is a // reported failure, never a silent zero-value fill). func logInvoker(label, src string, k Kind) (invoker, error) { inv, err := yaegiutil.Safe(label, func() (invoker, error) { i, err := yaegiutil.New(interp.Options{}, k.loadSymbols()) if err != nil { return nil, err } run, err := yaegiutil.Resolve[func(log.Args) log.Result](i, src, k.exportPath) if err != nil { return nil, fmt.Errorf("%s: %w", label, err) } return func(ctx context.Context, rawArgs map[string]any) (map[string]any, error) { return runLog(ctx, label, run, rawArgs) }, nil }) return inv, err } // runLog decodes rawArgs into log.Args, invokes the interpreted Run, and // marshals the typed Result back to map[string]any. ctx is accepted for // interface symmetry with future kinds that need cancellation; the log kind // is side-effect-free and does not use it. func runLog(_ context.Context, label string, run func(log.Args) log.Result, rawArgs map[string]any) (map[string]any, error) { args, err := decodeLogArgs(rawArgs) if err != nil { return nil, err } res, err := yaegiutil.Safe(label, func() (log.Result, error) { return run(args), nil }) if err != nil { return nil, err } return map[string]any{ "written": res.Written, "level": res.Level, }, nil } // decodeLogArgs strictly decodes rawArgs into log.Args: a wrong-typed field // or an unknown key is a reported error, never a silent zero-value fill -- // the "schema defines the accepted message" rule. func decodeLogArgs(rawArgs map[string]any) (log.Args, error) { var args log.Args if rawArgs == nil { return args, nil } if msg, ok := rawArgs["message"]; ok { s, ok := msg.(string) if !ok { return args, fmt.Errorf("module log: args.message is %T, want string", msg) } args.Message = s } if lvl, ok := rawArgs["level"]; ok { s, ok := lvl.(string) if !ok { return args, fmt.Errorf("module log: args.level is %T, want string", lvl) } args.Level = s } for key := range rawArgs { if key != "message" && key != "level" { return args, fmt.Errorf("module log: unknown arg %q", key) } } return args, nil } // Invoke calls the registered kind with rawArgs and returns the marshaled // result. An unregistered kind is a reported error. Invoke is deliberately // schema-agnostic: it returns the flat map[string]any the kind produces and // does not re-apply the Result schema. DecodeResult is the single conversion // site that re-applies it for the typed CEL environment. func (r *ModuleRegistry) Invoke(ctx context.Context, kind string, rawArgs map[string]any) (map[string]any, error) { inv, ok := r.kinds[kind] if !ok { return nil, fmt.Errorf("module: kind %q is not registered", kind) } res, err := inv(ctx, rawArgs) if err != nil { return nil, fmt.Errorf("module %s: %w", kind, err) } return res, nil } // DecodeResult converts Invoke's flat result map into the kind's registered // Result struct. Invoke stays schema-agnostic and returns map[string]any; this // method is the one place the Result schema is re-applied so the value a later // CEL expression reads is the same Go struct the expression environment typed // (`actions..result.`). The map is keyed by the lower-cased Go // field name, the same spelling expr registers as the CEL field name. An // unknown field or a wrong-typed value is a reported error. func (r *ModuleRegistry) DecodeResult(kind string, raw map[string]any) (any, error) { k, ok := registry[kind] if !ok { return nil, fmt.Errorf("module: unknown kind %q", kind) } return decodeResultStruct(kind, k.resultType, raw) } // decodeResultStruct marshals raw into a new value of the kind's Result // struct type, keyed by the lower-cased Go field name -- the same spelling // expr registers as the CEL field name. func decodeResultStruct(kind string, t reflect.Type, raw map[string]any) (any, error) { if t == nil { return nil, fmt.Errorf("module %s: result schema is not set", kind) } if t.Kind() == reflect.Pointer { t = t.Elem() } if t.Kind() != reflect.Struct { return nil, fmt.Errorf("module %s: result type %s is not a struct", kind, t) } out := reflect.New(t).Elem() fields := make(map[string]reflect.Value, t.NumField()) for i := 0; i < t.NumField(); i++ { f := t.Field(i) if !out.Field(i).CanSet() { continue } fields[strings.ToLower(f.Name)] = out.Field(i) } for key, val := range raw { fv, ok := fields[key] if !ok { return nil, fmt.Errorf("module %s: unknown result field %q", kind, key) } if err := setResultField(kind, key, fv, val); err != nil { return nil, err } } return out.Interface(), nil } // setResultField assigns val to fv, converting compatible Go types. A nil or // incompatible value is a reported error, never a silent zero-value fill. func setResultField(kind, field string, fv reflect.Value, val any) error { if val == nil { return fmt.Errorf("module %s: result.%s is nil, want %s", kind, field, fv.Type()) } rv := reflect.ValueOf(val) if rv.Type().AssignableTo(fv.Type()) { fv.Set(rv) return nil } if rv.Type().ConvertibleTo(fv.Type()) { fv.Set(rv.Convert(fv.Type())) return nil } return fmt.Errorf("module %s: result.%s is %T, want %s", kind, field, val, fv.Type()) }