Files
archie/internal/tools/provider/provider.go
T
2026-08-29 00:20:05 +10:00

603 lines
17 KiB
Go

// Package provider defines the typed tool-provider capability family.
package provider
import (
"context"
"errors"
"fmt"
"reflect"
"slices"
"strings"
"sync"
"time"
"github.com/samcharles93/archie-core/internal/plugin"
"github.com/samcharles93/archie-core/internal/tools"
)
var (
// ErrDuplicateProvider is returned when a manifest ID is already registered.
ErrDuplicateProvider = errors.New("duplicate tool provider")
// ErrRegistryStarted is returned when registration occurs after lifecycle start.
ErrRegistryStarted = errors.New("tool provider registry already started")
)
const toolCapability plugin.CapabilityKind = "tools"
const cleanupTimeout = 10 * time.Second
// Engine is one lifecycle-managed source of executable tools.
type Engine interface {
plugin.Module
Discover(context.Context) ([]tools.ToolEntry, error)
}
type registryState uint8
const (
stateIdle registryState = iota
stateStarting
stateRunning
stateStopping
stateStopped
stateFailed
)
type registration struct {
engine Engine
manifest plugin.Manifest
// optional marks a provider the daemon can run without. Atomicity is
// right for a provider archied requires; it is wrong for an external
// MCP server pulled from a registry at runtime, which is exactly the
// category that is allowed to be absent.
optional bool
}
// SkippedProvider is an optional provider that could not be started, and why.
type SkippedProvider struct {
ID string
Err error
}
type runningProvider struct {
registration registration
toolNames []string
}
// Registry owns tool-provider registration, lifecycle, and central indexing.
// The capability host starts and stops the Registry as one typed family module;
// the Registry, in turn, owns provider ordering and atomic tool availability.
type Registry struct {
opMu sync.Mutex
mu sync.RWMutex
index *tools.Registry
providers map[string]registration
running []runningProvider
// skipped records optional providers excluded from the running set.
// Health reports it: a silent degradation is how one broken npm package
// went unnoticed until the daemon crash-looped.
skipped []SkippedProvider
state registryState
}
// NewRegistry creates a provider registry backed by the central tool index.
func NewRegistry(index *tools.Registry) *Registry {
if index == nil {
index = tools.NewRegistry()
}
return &Registry{
index: index,
providers: make(map[string]registration),
}
}
// Register adds an engine the daemon requires. Its failure to start or
// discover fails the whole family, as before.
func (r *Registry) Register(engine Engine) error {
return r.register(engine, false)
}
// RegisterOptional adds an engine the daemon can run without.
//
// An optional provider that fails to start or discover is logged, excluded
// from the running set, and does not roll the family back or stop the daemon.
// Required/optional is a deployment decision, not a property of the code, so
// it is stated by the registrar rather than declared in the engine's own
// manifest.
func (r *Registry) RegisterOptional(engine Engine) error {
return r.register(engine, true)
}
func (r *Registry) register(engine Engine, optional bool) error {
if isNilEngine(engine) {
return errors.New("tool provider is nil")
}
manifest, err := safeManifest(engine)
if err != nil {
return err
}
if err := manifest.Validate(); err != nil {
return fmt.Errorf("tool provider manifest: %w", err)
}
if !slices.Contains(manifest.Capabilities, toolCapability) {
return fmt.Errorf("tool provider %q does not declare %q capability", manifest.ID, toolCapability)
}
manifest = cloneManifest(manifest)
r.mu.Lock()
defer r.mu.Unlock()
if r.state != stateIdle {
return ErrRegistryStarted
}
if _, exists := r.providers[manifest.ID]; exists {
return fmt.Errorf("%w: %q", ErrDuplicateProvider, manifest.ID)
}
r.providers[manifest.ID] = registration{engine: engine, manifest: manifest, optional: optional}
return nil
}
// Skipped returns the optional providers excluded from the running set.
func (r *Registry) Skipped() []SkippedProvider {
r.mu.RLock()
defer r.mu.RUnlock()
return append([]SkippedProvider(nil), r.skipped...)
}
// Get returns a registered engine by manifest ID.
func (r *Registry) Get(id string) (Engine, bool) {
r.mu.RLock()
defer r.mu.RUnlock()
registration, ok := r.providers[id]
return registration.engine, ok
}
// Manifest identifies the tool-provider family to the capability host.
func (r *Registry) Manifest() plugin.Manifest {
return plugin.Manifest{
ID: "archie.tools",
Name: "Tool providers",
Version: "1.0.0",
APIVersion: plugin.HostAPIVersion,
Capabilities: []plugin.CapabilityKind{toolCapability},
}
}
// Start starts and discovers registered providers in dependency order. A
// provider's tools become visible as one atomic batch only after Start and
// Discover both succeed. Any failure rolls the complete family back.
func (r *Registry) Start(ctx context.Context) error {
r.opMu.Lock()
defer r.opMu.Unlock()
r.mu.Lock()
switch r.state {
case stateRunning:
r.mu.Unlock()
return nil
case stateIdle:
r.state = stateStarting
default:
state := r.state
r.mu.Unlock()
return fmt.Errorf("tool provider registry cannot start from state %d", state)
}
providers := cloneRegistrations(r.providers)
r.mu.Unlock()
order, err := dependencyOrder(providers)
if err != nil {
r.setFailed(nil)
return err
}
started := make([]runningProvider, 0, len(order))
var skipped []SkippedProvider
unavailable := make(map[string]struct{})
for _, id := range order {
reg := providers[id]
// A provider whose dependency was skipped cannot run either. If it
// is required, that is a hard failure: it declared it cannot work
// without something now absent, so running it anyway would be worse
// than not starting.
if missing, blocked := firstUnavailable(reg, unavailable); blocked {
cause := fmt.Errorf("tool provider %q depends on unavailable provider %q", id, missing)
if !reg.optional {
return r.failFamily(ctx, started, cause)
}
unavailable[id] = struct{}{}
skipped = append(skipped, SkippedProvider{ID: id, Err: cause})
continue
}
rp, err := r.startProvider(ctx, reg, started)
if err == nil {
started = append(started, rp)
continue
}
if !reg.optional {
// failProvider has already rolled back and set the failed state.
return err
}
// Optional: the provider is out, the family carries on.
unavailable[id] = struct{}{}
skipped = append(skipped, SkippedProvider{ID: id, Err: err})
}
r.mu.Lock()
r.running = started
r.skipped = skipped
r.state = stateRunning
r.mu.Unlock()
return nil
}
// firstUnavailable reports the first dependency of reg that was skipped.
func firstUnavailable(reg registration, unavailable map[string]struct{}) (string, bool) {
for _, dependency := range reg.manifest.Dependencies {
if _, missing := unavailable[dependency]; missing {
return dependency, true
}
}
return "", false
}
// failFamily rolls back everything started so far and marks the registry
// failed, for a failure that is not attributable to one provider's own Start.
func (r *Registry) failFamily(ctx context.Context, started []runningProvider, cause error) error {
cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), cleanupTimeout)
defer cancel()
rollbackFailed, rollbackErr := rollback(cleanupCtx, r.index, started)
r.setFailed(rollbackFailed)
return errors.Join(cause, rollbackErr)
}
// Health reports aggregate provider health.
func (r *Registry) Health(ctx context.Context) plugin.Health {
r.mu.RLock()
state := r.state
running := append([]runningProvider(nil), r.running...)
skipped := append([]SkippedProvider(nil), r.skipped...)
r.mu.RUnlock()
switch state {
case stateFailed:
return plugin.Health{Status: plugin.HealthUnhealthy, Message: "tool-provider registry failed"}
case stateRunning:
default:
return plugin.Health{Status: plugin.HealthUnknown, Message: "tool-provider registry is not running"}
}
aggregate := plugin.Health{Status: plugin.HealthHealthy}
var messages []string
// An excluded optional provider is a degradation, not a clean start.
// Reporting healthy here is what let one broken npm package go unnoticed
// until the daemon crash-looped.
for _, s := range skipped {
aggregate.Status = plugin.HealthDegraded
message := s.ID + ": unavailable"
if s.Err != nil {
message = s.ID + ": " + s.Err.Error()
}
messages = append(messages, message)
}
for _, provider := range running {
health := safeHealth(ctx, provider.registration.engine)
switch health.Status {
case plugin.HealthHealthy:
case plugin.HealthDegraded:
if aggregate.Status == plugin.HealthHealthy {
aggregate.Status = plugin.HealthDegraded
}
case plugin.HealthUnhealthy:
aggregate.Status = plugin.HealthUnhealthy
default:
aggregate.Status = plugin.HealthUnhealthy
health.Message = fmt.Sprintf("invalid health status %q", health.Status)
}
if health.Message != "" {
messages = append(messages, provider.registration.manifest.ID+": "+health.Message)
}
}
aggregate.Message = strings.Join(messages, "; ")
return aggregate
}
// Stop removes all provider-owned tools before stopping providers in reverse
// startup order. It continues after provider failures and joins their errors.
func (r *Registry) Stop(ctx context.Context) error {
r.opMu.Lock()
defer r.opMu.Unlock()
r.mu.Lock()
switch r.state {
case stateStopped:
r.mu.Unlock()
return nil
case stateRunning:
r.state = stateStopping
case stateFailed:
if len(r.running) == 0 {
r.state = stateStopped
r.mu.Unlock()
return nil
}
r.state = stateStopping
case stateIdle:
r.running = nil
r.state = stateStopped
r.mu.Unlock()
return nil
default:
state := r.state
r.mu.Unlock()
return fmt.Errorf("tool provider registry cannot stop from state %d", state)
}
running := append([]runningProvider(nil), r.running...)
r.mu.Unlock()
var errs []error
var failed []runningProvider
for _, current := range slices.Backward(running) {
r.index.Unregister(current.toolNames...)
if err := safeStop(ctx, current.registration.engine); err != nil {
failed = append(failed, current)
errs = append(errs, fmt.Errorf(
"stop tool provider %q: %w",
current.registration.manifest.ID,
err,
))
}
}
r.mu.Lock()
r.running = reverseRunning(failed)
if len(failed) == 0 {
r.state = stateStopped
} else {
r.state = stateFailed
}
r.mu.Unlock()
return errors.Join(errs...)
}
func (r *Registry) setFailed(running []runningProvider) {
r.mu.Lock()
r.running = append([]runningProvider(nil), running...)
r.state = stateFailed
r.mu.Unlock()
}
// startProvider starts, discovers, and indexes one provider.
//
// A required provider's failure rolls back previously-started providers and
// returns a joined error. An optional provider's failure stops only itself
// and returns the cause, leaving the family running -- Start decides which,
// since only the registrar knows whether the daemon needs this provider.
func (r *Registry) startProvider(ctx context.Context, reg registration, started []runningProvider) (runningProvider, error) {
id := reg.manifest.ID
fail := func(cause error, startedOK bool) (runningProvider, error) {
if reg.optional {
return runningProvider{}, r.abandonProvider(ctx, id, reg, cause, startedOK)
}
return runningProvider{}, r.failProvider(ctx, id, reg, started, cause)
}
if err := safeStart(ctx, reg.engine); err != nil {
// Start failed, so there may or may not be anything to stop. Stop is
// still attempted: a provider that half-started (spawned a child
// process, opened a pipe) and then errored would otherwise leak it
// for the daemon's lifetime.
return fail(fmt.Errorf("start tool provider %q: %w", id, err), true)
}
entries, err := safeDiscover(ctx, reg.engine)
if err != nil {
return fail(fmt.Errorf("discover tools from provider %q: %w", id, err), true)
}
if err := r.index.RegisterBatch(entries); err != nil {
return fail(fmt.Errorf("index tools from provider %q: %w", id, err), true)
}
return runningProvider{
registration: reg,
toolNames: namesOf(entries),
}, nil
}
// abandonProvider stops one failed optional provider and returns why it was
// excluded. Nothing else is touched: the rest of the family keeps running.
func (r *Registry) abandonProvider(ctx context.Context, id string, reg registration, cause error, stop bool) error {
if !stop {
return cause
}
cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), cleanupTimeout)
defer cancel()
return errors.Join(cause, wrapCleanupError(id, safeStop(cleanupCtx, reg.engine)))
}
// failProvider stops the failing provider, rolls back previously-started
// providers, and returns a joined error.
func (r *Registry) failProvider(ctx context.Context, id string, reg registration, started []runningProvider, cause error) error {
cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), cleanupTimeout)
defer cancel()
cleanupErr := safeStop(cleanupCtx, reg.engine)
rollbackFailed, rollbackErr := rollback(cleanupCtx, r.index, started)
if cleanupErr != nil {
rollbackFailed = append(rollbackFailed, runningProvider{registration: reg})
}
r.setFailed(rollbackFailed)
return errors.Join(cause, wrapCleanupError(id, cleanupErr), rollbackErr)
}
func cloneRegistrations(source map[string]registration) map[string]registration {
clone := make(map[string]registration, len(source))
for id, value := range source {
value.manifest = cloneManifest(value.manifest)
clone[id] = value
}
return clone
}
func dependencyOrder(providers map[string]registration) ([]string, error) {
ids := make([]string, 0, len(providers))
for id := range providers {
ids = append(ids, id)
}
slices.Sort(ids)
indegree := make(map[string]int, len(providers))
dependents := make(map[string][]string, len(providers))
for _, id := range ids {
for _, dependency := range providers[id].manifest.Dependencies {
if _, exists := providers[dependency]; !exists {
return nil, fmt.Errorf("tool provider %q depends on missing provider %q", id, dependency)
}
indegree[id]++
dependents[dependency] = append(dependents[dependency], id)
}
}
var ready []string
for _, id := range ids {
if indegree[id] == 0 {
ready = append(ready, id)
}
}
var order []string
for len(ready) > 0 {
id := ready[0]
ready = ready[1:]
order = append(order, id)
slices.Sort(dependents[id])
for _, dependent := range dependents[id] {
indegree[dependent]--
if indegree[dependent] == 0 {
ready = append(ready, dependent)
slices.Sort(ready)
}
}
}
if len(order) != len(providers) {
return nil, errors.New("tool provider dependency cycle")
}
return order, nil
}
func rollback(
ctx context.Context,
index *tools.Registry,
started []runningProvider,
) ([]runningProvider, error) {
var errs []error
var failed []runningProvider
for _, current := range slices.Backward(started) {
index.Unregister(current.toolNames...)
if err := safeStop(ctx, current.registration.engine); err != nil {
failed = append(failed, current)
errs = append(errs, fmt.Errorf(
"rollback tool provider %q: %w",
current.registration.manifest.ID,
err,
))
}
}
return reverseRunning(failed), errors.Join(errs...)
}
func reverseRunning(values []runningProvider) []runningProvider {
out := append([]runningProvider(nil), values...)
slices.Reverse(out)
return out
}
func wrapCleanupError(id string, err error) error {
if err == nil {
return nil
}
return fmt.Errorf("clean up failed tool provider %q: %w", id, err)
}
func namesOf(entries []tools.ToolEntry) []string {
names := make([]string, len(entries))
for i, entry := range entries {
names[i] = entry.Name
}
return names
}
func cloneManifest(manifest plugin.Manifest) plugin.Manifest {
clone := manifest
clone.Capabilities = append([]plugin.CapabilityKind(nil), manifest.Capabilities...)
clone.Dependencies = append([]string(nil), manifest.Dependencies...)
clone.Permissions = append([]plugin.Permission(nil), manifest.Permissions...)
clone.ConfigSchema = append([]byte(nil), manifest.ConfigSchema...)
return clone
}
func isNilEngine(engine Engine) bool {
if engine == nil {
return true
}
value := reflect.ValueOf(engine)
switch value.Kind() {
case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice:
return value.IsNil()
default:
return false
}
}
func safeManifest(engine Engine) (manifest plugin.Manifest, err error) {
defer func() {
if recovered := recover(); recovered != nil {
err = fmt.Errorf("tool provider manifest panic: %v", recovered)
}
}()
return engine.Manifest(), nil
}
func safeStart(ctx context.Context, engine Engine) (err error) {
defer func() {
if recovered := recover(); recovered != nil {
err = fmt.Errorf("panic: %v", recovered)
}
}()
return engine.Start(ctx)
}
func safeDiscover(ctx context.Context, engine Engine) (entries []tools.ToolEntry, err error) {
defer func() {
if recovered := recover(); recovered != nil {
err = fmt.Errorf("panic: %v", recovered)
}
}()
return engine.Discover(ctx)
}
func safeHealth(ctx context.Context, engine Engine) (health plugin.Health) {
defer func() {
if recovered := recover(); recovered != nil {
health = plugin.Health{
Status: plugin.HealthUnhealthy,
Message: fmt.Sprintf("health panic: %v", recovered),
}
}
}()
return engine.Health(ctx)
}
func safeStop(ctx context.Context, engine Engine) (err error) {
defer func() {
if recovered := recover(); recovered != nil {
err = fmt.Errorf("panic: %v", recovered)
}
}()
return engine.Stop(ctx)
}