A step is id/type/settings with when and on_failure; the five kinds become
the types agent.run (inline mission), connector.action, approval.wait,
run.notify and workflow.sleep. Documents declare inputs, repository,
instructions, identity and profile; references are {{ task|inputs|steps }}
checked at save. Any number of approval steps, each asking only about what
was held since; actions still held at the end are put to people before the
run finishes. Triggers are refused for a workflow they can't start, and the
workflows API lists, reads and saves documents beside a step-type catalog.
Copied from internal/domain/workflow: definition.go, step_refs.go,
step_flow.go's checks, control_steps.go's when parser, vocabulary.go and
task/interface.go. stableid moves to internal/platform.
449 lines
11 KiB
Go
449 lines
11 KiB
Go
package plugin
|
|
|
|
import (
|
|
"context"
|
|
"encoding/json"
|
|
"errors"
|
|
"fmt"
|
|
"regexp"
|
|
"slices"
|
|
"strconv"
|
|
"strings"
|
|
"sync"
|
|
"time"
|
|
|
|
"github.com/samcharles93/archie-core/internal/domain/lifecycle"
|
|
"github.com/samcharles93/archie-core/internal/platform/stableid"
|
|
)
|
|
|
|
// HostAPIVersion is the capability-host contract version understood by this
|
|
// archied binary.
|
|
const HostAPIVersion = "1.0.0"
|
|
|
|
var semanticVersion = regexp.MustCompile(
|
|
`^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$`,
|
|
)
|
|
|
|
const rollbackTimeout = 10 * time.Second
|
|
|
|
// CapabilityKind identifies one typed capability family contributed by a
|
|
// module, such as "tools", "channels", or "delivery".
|
|
type CapabilityKind string
|
|
|
|
// Permission identifies one host permission requested by a module.
|
|
type Permission string
|
|
|
|
// Manifest declares module identity, compatibility, dependencies, and the
|
|
// capability families it contributes. It contains metadata only.
|
|
type Manifest struct {
|
|
ID string
|
|
Name string
|
|
Version string
|
|
APIVersion string
|
|
Capabilities []CapabilityKind
|
|
Dependencies []string
|
|
Permissions []Permission
|
|
ConfigSchema json.RawMessage
|
|
}
|
|
|
|
// Validate checks manifest identity, compatibility, declarations, and schema.
|
|
func (m Manifest) Validate() error {
|
|
if !stableid.Valid(m.ID) {
|
|
return fmt.Errorf("plugin manifest id %q is not a stable identifier", m.ID)
|
|
}
|
|
if strings.TrimSpace(m.Name) == "" {
|
|
return errors.New("plugin manifest name is required")
|
|
}
|
|
if _, err := parseSemver(m.Version); err != nil {
|
|
return fmt.Errorf("plugin manifest version: %w", err)
|
|
}
|
|
apiVersion, err := parseSemver(m.APIVersion)
|
|
if err != nil {
|
|
return fmt.Errorf("plugin manifest api_version: %w", err)
|
|
}
|
|
hostVersion, err := parseSemver(HostAPIVersion)
|
|
if err != nil {
|
|
return fmt.Errorf("plugin host api version: %w", err)
|
|
}
|
|
if apiVersion.major != hostVersion.major || apiVersion.minor > hostVersion.minor {
|
|
return fmt.Errorf(
|
|
"plugin manifest api_version %q is incompatible with host API %q",
|
|
m.APIVersion,
|
|
HostAPIVersion,
|
|
)
|
|
}
|
|
if err := validateIdentifiers("capability", capabilityStrings(m.Capabilities), true); err != nil {
|
|
return err
|
|
}
|
|
if err := validateIdentifiers("dependency", m.Dependencies, false); err != nil {
|
|
return err
|
|
}
|
|
if slices.Contains(m.Dependencies, m.ID) {
|
|
return fmt.Errorf("plugin manifest %q depends on itself", m.ID)
|
|
}
|
|
if err := validateIdentifiers("permission", permissionStrings(m.Permissions), false); err != nil {
|
|
return err
|
|
}
|
|
if len(m.ConfigSchema) > 0 {
|
|
var schema map[string]json.RawMessage
|
|
if err := json.Unmarshal(m.ConfigSchema, &schema); err != nil {
|
|
return fmt.Errorf("plugin manifest config schema: %w", err)
|
|
}
|
|
if schema == nil {
|
|
return errors.New("plugin manifest config schema must be a JSON object")
|
|
}
|
|
}
|
|
return nil
|
|
}
|
|
|
|
func (m Manifest) clone() Manifest {
|
|
clone := m
|
|
clone.Capabilities = append([]CapabilityKind(nil), m.Capabilities...)
|
|
clone.Dependencies = append([]string(nil), m.Dependencies...)
|
|
clone.Permissions = append([]Permission(nil), m.Permissions...)
|
|
clone.ConfigSchema = append(json.RawMessage(nil), m.ConfigSchema...)
|
|
return clone
|
|
}
|
|
|
|
type semver struct {
|
|
major int
|
|
minor int
|
|
}
|
|
|
|
func parseSemver(value string) (semver, error) {
|
|
matches := semanticVersion.FindStringSubmatch(value)
|
|
if matches == nil {
|
|
return semver{}, fmt.Errorf("%q is not semantic version syntax", value)
|
|
}
|
|
if prerelease := matches[4]; prerelease != "" {
|
|
for identifier := range strings.SplitSeq(prerelease, ".") {
|
|
if len(identifier) > 1 && identifier[0] == '0' && isASCIIDigits(identifier) {
|
|
return semver{}, fmt.Errorf(
|
|
"%q has a numeric prerelease identifier with a leading zero",
|
|
value,
|
|
)
|
|
}
|
|
}
|
|
}
|
|
major, err := strconv.Atoi(matches[1])
|
|
if err != nil {
|
|
return semver{}, fmt.Errorf("parse major version: %w", err)
|
|
}
|
|
minor, err := strconv.Atoi(matches[2])
|
|
if err != nil {
|
|
return semver{}, fmt.Errorf("parse minor version: %w", err)
|
|
}
|
|
return semver{major: major, minor: minor}, nil
|
|
}
|
|
|
|
func isASCIIDigits(value string) bool {
|
|
for _, char := range value {
|
|
if char < '0' || char > '9' {
|
|
return false
|
|
}
|
|
}
|
|
return value != ""
|
|
}
|
|
|
|
func capabilityStrings(values []CapabilityKind) []string {
|
|
out := make([]string, len(values))
|
|
for i, value := range values {
|
|
out[i] = string(value)
|
|
}
|
|
return out
|
|
}
|
|
|
|
func permissionStrings(values []Permission) []string {
|
|
out := make([]string, len(values))
|
|
for i, value := range values {
|
|
out[i] = string(value)
|
|
}
|
|
return out
|
|
}
|
|
|
|
func validateIdentifiers(kind string, values []string, required bool) error {
|
|
if required && len(values) == 0 {
|
|
return fmt.Errorf("plugin manifest requires at least one %s", kind)
|
|
}
|
|
seen := make(map[string]struct{}, len(values))
|
|
for _, value := range values {
|
|
if !stableid.Valid(value) {
|
|
return fmt.Errorf("plugin manifest %s %q is not a stable identifier", kind, value)
|
|
}
|
|
if _, exists := seen[value]; exists {
|
|
return fmt.Errorf("plugin manifest has duplicate %s %q", kind, value)
|
|
}
|
|
seen[value] = struct{}{}
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// Module is the capability host's metadata and lifecycle contract. Domain
|
|
// operations belong to typed capability-family interfaces, not here.
|
|
type Module interface {
|
|
Manifest() Manifest
|
|
Start(context.Context) error
|
|
Stop(context.Context) error
|
|
}
|
|
|
|
type hostState uint8
|
|
|
|
const (
|
|
hostIdle hostState = iota
|
|
hostStarting
|
|
hostRunning
|
|
hostStopping
|
|
hostStopped
|
|
hostFailed
|
|
)
|
|
|
|
type registeredModule struct {
|
|
module Module
|
|
manifest Manifest
|
|
}
|
|
|
|
// Host validates module manifests and coordinates cross-family lifecycle.
|
|
// It deliberately exposes no service lookup or domain callback registration.
|
|
type Host struct {
|
|
opMu sync.Mutex
|
|
mu sync.RWMutex
|
|
|
|
modules map[string]*registeredModule
|
|
registration []string
|
|
started []string
|
|
state hostState
|
|
}
|
|
|
|
// NewHost creates an empty capability host.
|
|
func NewHost() *Host {
|
|
return &Host{modules: make(map[string]*registeredModule)}
|
|
}
|
|
|
|
// Register adds a module to the host. Registration is allowed only before the
|
|
// first Start call.
|
|
func (h *Host) Register(module Module) error {
|
|
h.opMu.Lock()
|
|
defer h.opMu.Unlock()
|
|
|
|
manifest, err := prepareModule(module)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
|
|
h.mu.Lock()
|
|
defer h.mu.Unlock()
|
|
h.ensureModulesLocked()
|
|
if h.state != hostIdle {
|
|
return errors.New("plugin host no longer accepts registrations")
|
|
}
|
|
if _, exists := h.modules[manifest.ID]; exists {
|
|
return fmt.Errorf("plugin module %q is already registered", manifest.ID)
|
|
}
|
|
h.modules[manifest.ID] = ®isteredModule{
|
|
module: module,
|
|
manifest: manifest,
|
|
}
|
|
h.registration = append(h.registration, manifest.ID)
|
|
return nil
|
|
}
|
|
|
|
// Start starts registered modules in dependency order. A failed start stops
|
|
// every module already started by this call in reverse order.
|
|
func (h *Host) Start(ctx context.Context) error {
|
|
h.opMu.Lock()
|
|
defer h.opMu.Unlock()
|
|
|
|
h.mu.Lock()
|
|
if h.state == hostRunning {
|
|
h.mu.Unlock()
|
|
return nil
|
|
}
|
|
if h.state != hostIdle {
|
|
state := h.state
|
|
h.mu.Unlock()
|
|
return fmt.Errorf("plugin host cannot start from state %d", state)
|
|
}
|
|
order, err := h.startOrderLocked()
|
|
if err != nil {
|
|
h.mu.Unlock()
|
|
return err
|
|
}
|
|
h.state = hostStarting
|
|
h.mu.Unlock()
|
|
|
|
started := make([]string, 0, len(order))
|
|
for _, id := range order {
|
|
module := h.module(id)
|
|
if err := safeStart(ctx, id, module); err != nil {
|
|
rollback := append(append([]string(nil), started...), id)
|
|
rollbackCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), rollbackTimeout)
|
|
failedStops, rollbackErr := h.stopIDs(rollbackCtx, reverseClone(rollback))
|
|
cancel()
|
|
h.mu.Lock()
|
|
h.started = reverseClone(failedStops)
|
|
h.state = hostFailed
|
|
h.mu.Unlock()
|
|
return errors.Join(err, rollbackErr)
|
|
}
|
|
started = append(started, id)
|
|
}
|
|
|
|
h.mu.Lock()
|
|
h.started = append([]string(nil), started...)
|
|
h.state = hostRunning
|
|
h.mu.Unlock()
|
|
return nil
|
|
}
|
|
|
|
// Stop stops started modules in reverse dependency order. It attempts every
|
|
// stop even when one module returns an error or panics.
|
|
func (h *Host) Stop(ctx context.Context) error {
|
|
h.opMu.Lock()
|
|
defer h.opMu.Unlock()
|
|
|
|
h.mu.Lock()
|
|
if len(h.started) == 0 {
|
|
h.state = hostStopped
|
|
h.mu.Unlock()
|
|
return nil
|
|
}
|
|
h.state = hostStopping
|
|
order := reverseClone(h.started)
|
|
h.mu.Unlock()
|
|
|
|
failedStops, err := h.stopIDs(ctx, order)
|
|
h.mu.Lock()
|
|
h.started = reverseClone(failedStops)
|
|
if len(failedStops) == 0 {
|
|
h.state = hostStopped
|
|
} else {
|
|
h.state = hostFailed
|
|
}
|
|
h.mu.Unlock()
|
|
return err
|
|
}
|
|
|
|
func (h *Host) startOrderLocked() ([]string, error) {
|
|
const (
|
|
unvisited uint8 = iota
|
|
visiting
|
|
visited
|
|
)
|
|
visitState := make(map[string]uint8, len(h.modules))
|
|
order := make([]string, 0, len(h.modules))
|
|
var visit func(string) error
|
|
visit = func(id string) error {
|
|
switch visitState[id] {
|
|
case visiting:
|
|
return fmt.Errorf("plugin dependency cycle includes %q", id)
|
|
case visited:
|
|
return nil
|
|
}
|
|
entry, exists := h.modules[id]
|
|
if !exists {
|
|
return fmt.Errorf("plugin dependency %q is not registered", id)
|
|
}
|
|
visitState[id] = visiting
|
|
for _, dependency := range entry.manifest.Dependencies {
|
|
if err := visit(dependency); err != nil {
|
|
return fmt.Errorf("plugin %q: %w", id, err)
|
|
}
|
|
}
|
|
visitState[id] = visited
|
|
order = append(order, id)
|
|
return nil
|
|
}
|
|
for _, id := range h.registration {
|
|
if err := visit(id); err != nil {
|
|
return nil, err
|
|
}
|
|
}
|
|
return order, nil
|
|
}
|
|
|
|
func (h *Host) stopIDs(ctx context.Context, ids []string) ([]string, error) {
|
|
var errs []error
|
|
var failed []string
|
|
for _, id := range ids {
|
|
if err := safeStop(ctx, id, h.module(id)); err != nil {
|
|
failed = append(failed, id)
|
|
errs = append(errs, err)
|
|
continue
|
|
}
|
|
}
|
|
return failed, errors.Join(errs...)
|
|
}
|
|
|
|
func (h *Host) module(id string) Module {
|
|
h.mu.RLock()
|
|
defer h.mu.RUnlock()
|
|
return h.modules[id].module
|
|
}
|
|
|
|
func (h *Host) ensureModulesLocked() {
|
|
if h.modules == nil {
|
|
h.modules = make(map[string]*registeredModule)
|
|
}
|
|
}
|
|
|
|
func isNilModule(module Module) bool {
|
|
return lifecycle.IsNil(module)
|
|
}
|
|
|
|
func safeManifest(module Module) (manifest Manifest, err error) {
|
|
defer func() {
|
|
if recovered := recover(); recovered != nil {
|
|
err = fmt.Errorf("plugin manifest panic: %v", recovered)
|
|
}
|
|
}()
|
|
return module.Manifest(), nil
|
|
}
|
|
|
|
func safeStart(ctx context.Context, id string, module Module) (err error) {
|
|
defer func() {
|
|
if recovered := recover(); recovered != nil {
|
|
err = fmt.Errorf("plugin module %q start panic: %v", id, recovered)
|
|
}
|
|
}()
|
|
if err := module.Start(ctx); err != nil {
|
|
return fmt.Errorf("start plugin module %q: %w", id, err)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
func safeStop(ctx context.Context, id string, module Module) (err error) {
|
|
defer func() {
|
|
if recovered := recover(); recovered != nil {
|
|
err = fmt.Errorf("plugin module %q stop panic: %v", id, recovered)
|
|
}
|
|
}()
|
|
if err := module.Stop(ctx); err != nil {
|
|
return fmt.Errorf("stop plugin module %q: %w", id, err)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
func reverseClone(values []string) []string {
|
|
out := append([]string(nil), values...)
|
|
for left, right := 0, len(out)-1; left < right; left, right = left+1, right-1 {
|
|
out[left], out[right] = out[right], out[left]
|
|
}
|
|
return out
|
|
}
|
|
|
|
// prepareModule validates a module and returns its cloned manifest, the
|
|
// validation Register, Add and Replace all share.
|
|
func prepareModule(module Module) (Manifest, error) {
|
|
if isNilModule(module) {
|
|
return Manifest{}, errors.New("plugin module is nil")
|
|
}
|
|
manifest, err := safeManifest(module)
|
|
if err != nil {
|
|
return Manifest{}, err
|
|
}
|
|
if err := manifest.Validate(); err != nil {
|
|
return Manifest{}, err
|
|
}
|
|
return manifest.clone(), nil
|
|
}
|