Files
summercms/modules/party/registry.go
Jakub Zych ea1befdd6c feat(party): give every application its own plugin instances (quick-261118-lbt)
- Register keeps a pristine shallow copy of each pointer-to-struct plugin;
  every Activate hands its application a fresh copy, so a second
  application no longer rebinds the first one's plugins
- value plugins and pointers to non-struct types are used as is
- party.RegisterFactory for plugins whose init builds maps or pointers
- activate() and its tests are unchanged
- README and plugin/lifecycle docs describe the per-application rule
2026-11-18 15:37:06 +01:00

308 lines
8.7 KiB
Go

package party
import (
"fmt"
"reflect"
"strings"
"sync"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/pact"
"git.golem15.com/golem15/summercms/modules/phrasebook"
"git.golem15.com/golem15/summercms/modules/postcard"
"git.golem15.com/golem15/summercms/modules/signpost"
)
// Plugin is the required descriptor every compiled plugin implements.
type Plugin interface {
ID() string
Requires() []string
Register(app *backpack.App) error
Boot(app *backpack.App) error
}
// Activated is the ordered plugin list published by Activate. Commands look
// it up at Run time with app.Lookup[Activated](). The plugins in it are the
// application's own instances (see Activate).
type Activated []Plugin
// registration is one entry of the process-wide registry: a pristine copy of
// a pointer-to-struct plugin, a plugin used as is, or a factory.
type registration struct {
plugin Plugin
copyable bool
id string
factory func() Plugin
}
var (
mu sync.Mutex
plugins []registration
)
// Register adds a plugin to the process-wide registry. Plugins call this
// from init() after a blank import; Activate selects and orders them.
//
// A pointer to a struct (the usual &Plugin{}) is copied: Register keeps a
// pristine shallow copy and every Activate hands its application a fresh
// copy of it, so a plugin keeps per-application state on its struct, never
// in package variables. The value passed here is never handed to an
// application. Fields set in the literal carry over; a map or pointer set
// there is shared by every application, so a plugin that needs its own maps
// or pointers per application uses RegisterFactory. A value plugin or a
// pointer to a non-struct type is used as is. A nil plugin is ignored.
func Register(p Plugin) {
if p == nil {
return
}
entry := registration{plugin: p}
if v := reflect.ValueOf(p); v.Kind() == reflect.Pointer && !v.IsNil() && v.Elem().Kind() == reflect.Struct {
pristine := reflect.New(v.Elem().Type())
pristine.Elem().Set(v.Elem())
if cp, ok := pristine.Interface().(Plugin); ok {
entry = registration{plugin: cp, copyable: true}
}
}
mu.Lock()
defer mu.Unlock()
plugins = append(plugins, entry)
}
// RegisterFactory adds a plugin built by fn to the process-wide registry. fn
// is called on every Activate, so each application gets the plugin fn
// returns; use it for plugins whose init builds maps or pointers that must
// not be shared between applications. The returned plugin's ID must be id;
// a nil result or another ID fails Activate. A nil fn is ignored.
func RegisterFactory(id string, fn func() Plugin) {
if fn == nil {
return
}
mu.Lock()
defer mu.Unlock()
plugins = append(plugins, registration{id: id, factory: fn})
}
// snapshot returns one fresh instance per registration, in registration
// order: a new copy of each pristine pointer-to-struct plugin, the result of
// each factory, and the as-is plugins.
func snapshot() ([]Plugin, error) {
mu.Lock()
entries := make([]registration, len(plugins))
copy(entries, plugins)
mu.Unlock()
out := make([]Plugin, 0, len(entries))
for _, e := range entries {
switch {
case e.factory != nil:
p := e.factory()
if p == nil {
return nil, fmt.Errorf("party: factory for %q returned nil", e.id)
}
if got := p.ID(); got != e.id {
return nil, fmt.Errorf("party: factory for %q returned plugin %q", e.id, got)
}
out = append(out, p)
case e.copyable:
src := reflect.ValueOf(e.plugin)
fresh := reflect.New(src.Elem().Type())
fresh.Elem().Set(src.Elem())
out = append(out, fresh.Interface().(Plugin))
default:
out = append(out, e.plugin)
}
}
return out, nil
}
// Activate resolves ids in manifest order, topologically sorts Requires(),
// then runs every Register before any Boot. Each call works on fresh plugin
// instances (see Register and RegisterFactory), so two applications
// activated in one process, also concurrently, never share a plugin struct.
func Activate(app *backpack.App, ids []string) ([]Plugin, error) {
if app == nil {
return nil, fmt.Errorf("party: app is nil")
}
instances, err := snapshot()
if err != nil {
return nil, err
}
return activate(instances, app, ids)
}
func activate(registered []Plugin, app *backpack.App, ids []string) ([]Plugin, error) {
byID := make(map[string]Plugin, len(registered))
for _, p := range registered {
if p == nil {
continue
}
id := p.ID()
if id == "" {
return nil, fmt.Errorf("party: registered plugin has empty id")
}
if _, exists := byID[id]; exists {
return nil, fmt.Errorf("party: duplicate plugin id %q", id)
}
byID[id] = p
}
seen := make(map[string]struct{}, len(ids))
selected := make([]Plugin, 0, len(ids))
index := make(map[string]int, len(ids))
for _, id := range ids {
if id == "" {
return nil, fmt.Errorf("party: empty plugin id in manifest")
}
if _, dup := seen[id]; dup {
return nil, fmt.Errorf("party: duplicate plugin id %q", id)
}
seen[id] = struct{}{}
p, ok := byID[id]
if !ok {
return nil, fmt.Errorf("party: plugin %q is not registered", id)
}
index[id] = len(selected)
selected = append(selected, p)
}
for _, p := range selected {
for _, req := range p.Requires() {
if _, ok := seen[req]; !ok {
return nil, fmt.Errorf("party: plugin %q requires %q, which is not registered", p.ID(), req)
}
}
}
ordered, err := topoSort(selected, index)
if err != nil {
return nil, err
}
orderedIDs := make([]string, len(ordered))
for i, p := range ordered {
orderedIDs[i] = p.ID()
}
app.SetPlugins(orderedIDs)
if err := app.Publish(Activated(ordered)); err != nil {
return nil, fmt.Errorf("party: %w", err)
}
for _, p := range ordered {
if hc, ok := p.(pact.HasConfig); ok && app.Config != nil {
if err := app.Config.MergePlugin(p.ID(), hc.ConfigFS()); err != nil {
return nil, fmt.Errorf("party: config %s: %w", p.ID(), err)
}
}
}
for _, p := range ordered {
if err := p.Register(app); err != nil {
return nil, fmt.Errorf("party: register %s: %w", p.ID(), err)
}
}
if err := phrasebook.Activate(app, ordered); err != nil {
return nil, fmt.Errorf("party: lang: %w", err)
}
if err := postcard.Activate(app, ordered); err != nil {
return nil, fmt.Errorf("party: mail: %w", err)
}
// Menu item types (pact.HasMenuItemTypes) are collected after every
// Register and before the first Boot, so a plugin's Boot can read the
// registry.
if err := signpost.Activate(app, ordered); err != nil {
return nil, fmt.Errorf("party: menu item types: %w", err)
}
for _, p := range ordered {
if err := postcard.BootPlugin(app, p); err != nil {
return nil, fmt.Errorf("party: boot %s: %w", p.ID(), err)
}
if err := p.Boot(app); err != nil {
return nil, fmt.Errorf("party: boot %s: %w", p.ID(), err)
}
}
return ordered, nil
}
func topoSort(plugins []Plugin, index map[string]int) ([]Plugin, error) {
byID := make(map[string]Plugin, len(plugins))
indeg := make(map[string]int, len(plugins))
dependents := make(map[string][]string, len(plugins))
for _, p := range plugins {
byID[p.ID()] = p
indeg[p.ID()] = 0
}
for _, p := range plugins {
seenReq := make(map[string]struct{})
for _, req := range p.Requires() {
if _, ok := seenReq[req]; ok {
continue
}
seenReq[req] = struct{}{}
if _, ok := byID[req]; !ok {
continue
}
indeg[p.ID()]++
dependents[req] = append(dependents[req], p.ID())
}
}
ready := make([]string, 0, len(plugins))
for _, p := range plugins {
if indeg[p.ID()] == 0 {
ready = append(ready, p.ID())
}
}
out := make([]Plugin, 0, len(plugins))
for len(ready) > 0 {
id := ready[0]
ready = ready[1:]
out = append(out, byID[id])
next := append([]string(nil), dependents[id]...)
sortByIndex(next, index)
for _, dep := range next {
indeg[dep]--
if indeg[dep] == 0 {
ready = insertByIndex(ready, dep, index)
}
}
}
if len(out) != len(plugins) {
leftover := make([]string, 0)
done := make(map[string]struct{}, len(out))
for _, p := range out {
done[p.ID()] = struct{}{}
}
for _, p := range plugins {
if _, ok := done[p.ID()]; !ok {
leftover = append(leftover, p.ID())
}
}
return nil, fmt.Errorf("party: dependency cycle involving %s", strings.Join(leftover, ", "))
}
return out, nil
}
func sortByIndex(ids []string, index map[string]int) {
for i := 1; i < len(ids); i++ {
j := i
for j > 0 && index[ids[j]] < index[ids[j-1]] {
ids[j], ids[j-1] = ids[j-1], ids[j]
j--
}
}
}
func insertByIndex(ready []string, id string, index map[string]int) []string {
at := len(ready)
for i, existing := range ready {
if index[id] < index[existing] {
at = i
break
}
}
ready = append(ready, "")
copy(ready[at+1:], ready[at:])
ready[at] = id
return ready
}