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/domain/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 } // Manifests returns the registered modules' manifests sorted by id. It is the // read side of the running set: a live load reports what is loaded from here. func (h *Host) Manifests() []Manifest { h.mu.RLock() defer h.mu.RUnlock() out := make([]Manifest, 0, len(h.modules)) for _, entry := range h.modules { out = append(out, entry.manifest.clone()) } slices.SortFunc(out, func(a, b Manifest) int { return strings.Compare(a.ID, b.ID) }) 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 }