pluginhost

README

togo-framework/plugin-host

Database-driven runtime plugin registry for togo — host, toggle & configure plugins live, and compose capabilities over the workflow plugin.

Install

togo install togo-framework/plugin-host

Where a compiled togo plugin is wired at build time, plugin-host adds a runtime layer (the sentra-style plugins table): an admin can enable/disable a hosted plugin, change its config, and reorder navigation — live, persisted through a pluggable store, no restart. Each hosted plugin can contribute capabilities that call other togo plugins or trigger a workflow as step management.

Concepts

• Hosted plugin record — Plugin{Slug, Kind, Enabled, Config, Nav, Sort, LabelEN, LabelAR} stored via the Store interface (in-memory default; back it with a DB plugins table).
• Runtime toggle — Enable/Disable/Configure + Refresh() apply state without recompiling.
• Capabilities — RegisterCapability(slug, fn); RunCapability(ctx, slug, input) runs it, gated by the owning plugin's enabled state.
• Workflow composition — WorkflowCapability(k, "name") returns a capability that triggers a workflow (uses the workflow plugin's steps).

Usage

ph, _ := pluginhost.FromKernel(k)

// Host a plugin (persisted), shown in nav, sorted.
ph.Register(pluginhost.Plugin{Slug: "newsletter", Kind: "capability", Enabled: true, Nav: true, Sort: 10, LabelEN: "Newsletter"})

// Toggle / configure at runtime — no restart.
ph.Disable("newsletter")
ph.Configure("newsletter", map[string]any{"from": "news@acme.io", "double_optin": true})
ph.Enable("newsletter")

// Contribute a capability that composes other plugins…
ph.RegisterCapability("newsletter.send", func(ctx context.Context, in map[string]any) (any, error) {
    // call mail / notifications / billing plugins here
    return nil, nil
})

// …or compose the workflow plugin as step management.
ph.RegisterCapability("onboard", pluginhost.WorkflowCapability(k, "onboarding"))
out, err := ph.RunCapability(ctx, "onboard", map[string]any{"user_id": 42})

nav := ph.Nav() // enabled + nav-visible plugins, in sort order (for a sidebar)

REST API

Method	Path	Description
GET	/api/plugin-host/plugins	list hosted plugins (sorted)
GET	/api/plugin-host/dashboard	plugins + nav + capabilities
POST	/api/plugin-host/plugins/{slug}/toggle	enable/disable
POST	/api/plugin-host/plugins/{slug}/configure	merge config (JSON body)
GET	/api/plugin-host/capabilities	list capability slugs
POST	/api/plugin-host/capabilities/{slug}/run	run a capability (JSON input)

Configuration

No required env. Storage defaults to a bounded in-memory store; implement the Store interface (Upsert/Get/All/Delete) and call ph.WithStore(db) to host plugins in a database plugins table for true runtime, multi-instance control.

---

Premium sponsors

ID8 Media  ·  One Studio

_{Support togo — become a sponsor.}

Documentation

Overview

Package pluginhost is a database-driven runtime plugin/capability registry for togo (the sentra-style "plugins table"): host plugins over a data store, enable/disable/configure them at runtime without a restart, and let each hosted plugin contribute capabilities/steps that compose other togo plugins — including the workflow plugin as step management.

Where a compiled togo plugin is wired at build time, plugin-host adds a *runtime* layer: an admin can toggle a plugin on/off, change its config, and reorder navigation live, all persisted through a pluggable Store.

Index

• type CapabilityFunc
  • func WorkflowCapability(k *togo.Kernel, workflowName string) CapabilityFunc
• type Plugin
• type Service
  • func FromKernel(k *togo.Kernel) (*Service, bool)
  • func (s *Service) Capabilities() []string
  • func (s *Service) ConfigValue(slug, key string) (any, bool)
  • func (s *Service) Configure(slug string, cfg map[string]any) error
  • func (s *Service) Disable(slug string) error
  • func (s *Service) Enable(slug string) error
  • func (s *Service) Get(slug string) (Plugin, bool)
  • func (s *Service) IsEnabled(slug string) bool
  • func (s *Service) List() []Plugin
  • func (s *Service) Nav() []Plugin
  • func (s *Service) Refresh()
  • func (s *Service) Register(p Plugin)
  • func (s *Service) RegisterCapability(slug string, fn CapabilityFunc)
  • func (s *Service) RunCapability(ctx context.Context, slug string, input map[string]any) (any, error)
  • func (s *Service) WithStore(store Store) *Service
• type Store

Types

type CapabilityFunc

type CapabilityFunc func(ctx context.Context, input map[string]any) (any, error)

CapabilityFunc is a runtime capability a hosted plugin contributes. It can call other togo plugins or trigger a workflow.

func WorkflowCapability

func WorkflowCapability(k *togo.Kernel, workflowName string) CapabilityFunc

WorkflowCapability builds a CapabilityFunc that triggers a named workflow via the workflow plugin — this is how a hosted plugin uses workflow as step management. Register it with RegisterCapability.

s.RegisterCapability("onboard", pluginhost.WorkflowCapability(k, "onboarding"))

type Plugin

type Plugin struct {
	Slug    string         `json:"slug"`
	Kind    string         `json:"kind"` // e.g. capability, source, integration, ui
	Enabled bool           `json:"enabled"`
	Config  map[string]any `json:"config,omitempty"`
	Nav     bool           `json:"nav"`  // show in navigation
	Sort    int            `json:"sort"` // nav/order weight
	LabelEN string         `json:"label_en,omitempty"`
	LabelAR string         `json:"label_ar,omitempty"`
}

Plugin is a hosted plugin/capability record (the row in the plugins table).

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service is the plugin-host runtime stored on the kernel (k.Get("plugin-host")).

func FromKernel

func FromKernel(k *togo.Kernel) (*Service, bool)

FromKernel returns the plugin-host Service.

func (*Service) Capabilities

func (s *Service) Capabilities() []string

Capabilities lists registered capability slugs.

func (*Service) ConfigValue

func (s *Service) ConfigValue(slug, key string) (any, bool)

ConfigValue returns a single config value for a plugin.

func (*Service) Configure

func (s *Service) Configure(slug string, cfg map[string]any) error

Configure merges config into a plugin's record (typed values).

func (*Service) Disable

func (s *Service) Disable(slug string) error

func (*Service) Enable

func (s *Service) Enable(slug string) error

Enable / Disable toggle a plugin at runtime (persisted + applied immediately).

func (*Service) Get

func (s *Service) Get(slug string) (Plugin, bool)

Get returns one hosted plugin.

func (*Service) IsEnabled

func (s *Service) IsEnabled(slug string) bool

IsEnabled reports whether a plugin is currently enabled.

func (*Service) List

func (s *Service) List() []Plugin

List returns hosted plugins sorted by Sort then Slug.

func (*Service) Nav

func (s *Service) Nav() []Plugin

Nav returns the enabled, nav-visible plugins in sort order (for a sidebar).

func (*Service) Refresh

func (s *Service) Refresh()

Refresh re-reads the store and applies the enabled-state cache. Call after a store mutation made outside this Service (the "no restart" reload).

func (*Service) Register

func (s *Service) Register(p Plugin)

Register adds or updates a hosted plugin record, then refreshes runtime state.

func (*Service) RegisterCapability

func (s *Service) RegisterCapability(slug string, fn CapabilityFunc)

RegisterCapability registers a runtime capability under a slug.

func (*Service) RunCapability

func (s *Service) RunCapability(ctx context.Context, slug string, input map[string]any) (any, error)

RunCapability invokes a capability. It errors if the owning plugin is disabled, so toggling a plugin gates its capabilities at runtime.

func (*Service) WithStore

func (s *Service) WithStore(store Store) *Service

WithStore swaps the backing store (e.g. a DB-backed plugins table).

type Store

type Store interface {
	Upsert(p Plugin)
	Get(slug string) (Plugin, bool)
	All() []Plugin
	Delete(slug string)
}

Store persists hosted plugins (swap the in-memory default for a DB store).