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
This commit is contained in:
Jakub Zych
2026-11-18 15:37:06 +01:00
parent 4d3b1e9f62
commit ea1befdd6c
5 changed files with 347 additions and 16 deletions

View File

@@ -37,7 +37,7 @@ This is the WinterCMS `register` and `boot` split: when any Boot runs, every plu
## The container ## The container
`backpack.App` is the application container that Register and Boot receive. It holds the configuration in `backpack.App.Config`, the event bus in `backpack.App.Events` and a typed service registry. Nothing in it is process-global, so two applications in one test do not share state. `backpack.App` is the application container that Register and Boot receive. It holds the configuration in `backpack.App.Config`, the event bus in `backpack.App.Events` and a typed service registry. Nothing in it is process-global, so two applications in one test do not share state. `party.Activate` also gives each application its own plugin instances, so plugin state is not shared either.
Services are keyed by their Go type. A plugin publishes a value with `backpack.App.Publish` and another plugin reads it with `backpack.App.Lookup` and the same type argument. Publish under an interface type when consumers should not depend on your implementation: Services are keyed by their Go type. A plugin publishes a value with `backpack.App.Publish` and another plugin reads it with `backpack.App.Lookup` and the same type argument. Publish under an interface type when consumers should not depend on your implementation:

View File

@@ -25,6 +25,8 @@ A plugin is a Go type that implements `party.Plugin`. Its package registers it f
| `party.Plugin.Register` | Runs before any plugin boots. Publish services on the container here. | | `party.Plugin.Register` | Runs before any plugin boots. Publish services on the container here. |
| `party.Plugin.Boot` | Runs after every plugin registered. Listen to events and use other plugins' services here. | | `party.Plugin.Boot` | Runs after every plugin registered. Listen to events and use other plugins' services here. |
Every application gets its own instance of the plugin. `party.Activate` hands each application a fresh shallow copy of the struct passed to `party.Register`, so a plugin keeps per-application state (the app it stored in Register, clients built from its config) on its struct, never in package variables. Fields set in the registered literal carry over to every copy; a map or pointer set there is shared by all applications. A plugin whose `init` builds such maps or pointers registers a constructor with `party.RegisterFactory` instead, which `party.Activate` calls once per application. A plugin that is not a pointer to a struct is used as is.
Here is a complete plugin that also declares a backend permission: Here is a complete plugin that also declares a backend permission:
```go src=modules/party/example_plugin_test.go ```go src=modules/party/example_plugin_test.go

View File

@@ -8,7 +8,7 @@ Compiled plugin registry that orders plugins by their dependencies and runs thei
## Overview ## Overview
`party` is the WinterCMS PluginBase and PluginManager counterpart for plugins compiled into the binary. Each plugin package calls `party.Register` from its `init` function, and the application's generated `main` calls `party.Activate` with the plugin IDs listed in its manifest. Activation validates the selection, sorts it so every plugin comes after the plugins it requires, merges plugin config, runs every Register before any Boot, and wires translations, mail templates and menu item types in between. Capabilities beyond the lifecycle are declared through the interfaces in [pact](../pact/README.md). `party` is the WinterCMS PluginBase and PluginManager counterpart for plugins compiled into the binary. Each plugin package calls `party.Register` from its `init` function, and the application's generated `main` calls `party.Activate` with the plugin IDs listed in its manifest. Every application gets its own instance of each plugin. Activation validates the selection, sorts it so every plugin comes after the plugins it requires, merges plugin config, runs every Register before any Boot, and wires translations, mail templates and menu item types in between. Capabilities beyond the lifecycle are declared through the interfaces in [pact](../pact/README.md).
## Role in the framework ## Role in the framework
@@ -23,7 +23,8 @@ Use cases:
## Features ## Features
- `party.Plugin`, the descriptor every plugin implements: `party.Plugin.ID`, `party.Plugin.Requires`, `party.Plugin.Register` and `party.Plugin.Boot`. - `party.Plugin`, the descriptor every plugin implements: `party.Plugin.ID`, `party.Plugin.Requires`, `party.Plugin.Register` and `party.Plugin.Boot`.
- A process-wide, concurrency-safe registry filled by `party.Register` (nil plugins are ignored). - A process-wide, concurrency-safe registry filled by `party.Register` (nil plugins are ignored) and `party.RegisterFactory`.
- Per-application instances: each `party.Activate` works on a fresh shallow copy of every pointer-to-struct plugin (or a factory's result), so two applications in one process, also activated concurrently, never share a plugin struct.
- `party.Activate` selects plugins by manifest ID and fails on an empty ID, a duplicate ID, an unregistered plugin, a missing requirement or a dependency cycle. - `party.Activate` selects plugins by manifest ID and fails on an empty ID, a duplicate ID, an unregistered plugin, a missing requirement or a dependency cycle.
- Stable topological ordering: plugins without a dependency relation keep their manifest order. - Stable topological ordering: plugins without a dependency relation keep their manifest order.
- Build-time metadata: `party.Describe` publishes `party.Installed`, the plugin metadata (`party.Info`: ID, module, package, name, description, version and source) and the framework version that `summer build` baked into the application's `plugins.gen.go`. The generated `main` calls it before `party.Activate`. - Build-time metadata: `party.Describe` publishes `party.Installed`, the plugin metadata (`party.Info`: ID, module, package, name, description, version and source) and the framework version that `summer build` baked into the application's `plugins.gen.go`. The generated `main` calls it before `party.Activate`.
@@ -53,6 +54,10 @@ func init() {
} }
``` ```
### Per-application instances
Each application gets its own plugin instances: `party.Activate` gives every application a fresh shallow copy of the struct passed to `party.Register`, and the registered value itself is never handed out. A plugin keeps per-application state on its struct, never in package variables. Fields set in the registered literal carry over to every copy, so a map or pointer set there is shared by all applications; a plugin whose `init` builds maps or pointers registers a constructor with `party.RegisterFactory` instead, which runs once per `party.Activate`. A plugin that is not a pointer to a struct is used as is.
The application publishes its build-time metadata and activates the plugins it lists, in dependency order (`summer build` generates both lists): The application publishes its build-time metadata and activates the plugins it lists, in dependency order (`summer build` generates both lists):
```go ```go
@@ -79,8 +84,9 @@ if err != nil {
| Identifier | Description | | Identifier | Description |
|------------|-------------| |------------|-------------|
| `party.Plugin` | Interface every compiled plugin implements: ID, required plugin IDs, Register and Boot. | | `party.Plugin` | Interface every compiled plugin implements: ID, required plugin IDs, Register and Boot. |
| `party.Register` | Adds a plugin to the process-wide registry; called from the plugin's `init`. | | `party.Register` | Adds a plugin to the process-wide registry; called from the plugin's `init`. A pointer to a struct is kept as a pristine copy, and each `party.Activate` gets a fresh copy of it; other plugins are used as is. |
| `party.Activate` | Selects registered plugins by ID, orders them by `party.Plugin.Requires` and runs the config, Register, translation, mail, menu item type and Boot steps; returns the ordered plugins. | | `party.RegisterFactory` | Adds a plugin built by a constructor that `party.Activate` calls once per application; for plugins whose `init` builds maps or pointers. A nil constructor is ignored; a nil result or a plugin with another ID fails `party.Activate`. |
| `party.Activate` | Gives the application fresh plugin instances, selects them by ID, orders them by `party.Plugin.Requires` and runs the config, Register, translation, mail, menu item type and Boot steps; returns the ordered plugins. |
| `party.Info` | One plugin's build-time metadata: `ID`, `Module`, `Package`, `Name`, `Description` (from its `plugin.yaml`), `Version` and `Source`. | | `party.Info` | One plugin's build-time metadata: `ID`, `Module`, `Package`, `Name`, `Description` (from its `plugin.yaml`), `Version` and `Source`. |
| `party.SourceModule` | Source of a plugin built from the Go module cache; its version is the module version. | | `party.SourceModule` | Source of a plugin built from the Go module cache; its version is the module version. |
| `party.SourceSubmodule` | Source of a plugin directory that is its own git repository; its version is `git describe --tags` output. | | `party.SourceSubmodule` | Source of a plugin directory that is its own git repository; its version is `git describe --tags` output. |
@@ -93,7 +99,7 @@ if err != nil {
- SummerCMS modules: [backpack](../backpack/README.md), [pact](../pact/README.md), [phrasebook](../phrasebook/README.md), [postcard](../postcard/README.md), [signpost](../signpost/README.md). - SummerCMS modules: [backpack](../backpack/README.md), [pact](../pact/README.md), [phrasebook](../phrasebook/README.md), [postcard](../postcard/README.md), [signpost](../signpost/README.md).
- Third-party: none. - Third-party: none.
- Standard library: `fmt`, `strings`, `sync`. - Standard library: `fmt`, `reflect`, `strings`, `sync`.
## Testing ## Testing

View File

@@ -0,0 +1,250 @@
package party
import (
"os"
"path/filepath"
"strings"
"sync"
"testing"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/compass"
)
// withRegistry swaps the package registry for an empty one for the length
// of the test and restores it afterwards.
func withRegistry(t *testing.T) {
t.Helper()
mu.Lock()
saved := plugins
plugins = nil
mu.Unlock()
t.Cleanup(func() {
mu.Lock()
plugins = saved
mu.Unlock()
})
}
// scopedPlugin keeps per-application state on its struct, as plugins are
// told to.
type scopedPlugin struct {
id string
label string
app *backpack.App
register int
boot int
}
func (p *scopedPlugin) ID() string { return p.id }
func (p *scopedPlugin) Requires() []string { return nil }
func (p *scopedPlugin) Register(app *backpack.App) error {
p.app = app
p.register++
return nil
}
func (p *scopedPlugin) Boot(app *backpack.App) error {
p.boot++
return nil
}
// Name is a capability-style method that reads the plugin's own app.
func (p *scopedPlugin) Name() string {
if p.app == nil || p.app.Config == nil {
return ""
}
return p.app.Config.String("app.name")
}
type valuePlugin struct{ id string }
func (p valuePlugin) ID() string { return p.id }
func (valuePlugin) Requires() []string { return nil }
func (valuePlugin) Register(*backpack.App) error { return nil }
func (valuePlugin) Boot(*backpack.App) error { return nil }
type countPlugin int
func (*countPlugin) ID() string { return "acme.count" }
func (*countPlugin) Requires() []string { return nil }
func (*countPlugin) Register(*backpack.App) error { return nil }
func (*countPlugin) Boot(*backpack.App) error { return nil }
func namedApp(t *testing.T, name string) *backpack.App {
t.Helper()
dir := t.TempDir()
if err := os.WriteFile(filepath.Join(dir, "app.yaml"), []byte("name: "+name+"\n"), 0o644); err != nil {
t.Fatal(err)
}
cfg, err := compass.Load(dir)
if err != nil {
t.Fatalf("Load: %v", err)
}
return backpack.New(cfg)
}
func activatedScoped(t *testing.T, app *backpack.App, id string) *scopedPlugin {
t.Helper()
list, ok := app.Lookup[Activated]()
if !ok {
t.Fatal("Activated not published")
}
for _, p := range list {
if p.ID() == id {
sp, ok := p.(*scopedPlugin)
if !ok {
t.Fatalf("plugin %s is %T, want *scopedPlugin", id, p)
}
return sp
}
}
t.Fatalf("plugin %s not activated", id)
return nil
}
func TestActivatePerAppInstances(t *testing.T) {
withRegistry(t)
orig := &scopedPlugin{id: "acme.scoped", label: "fixed"}
Register(orig)
Register(valuePlugin{id: "acme.value"})
count := new(countPlugin)
Register(count)
ids := []string{"acme.scoped", "acme.value", "acme.count"}
one := namedApp(t, "one")
two := namedApp(t, "two")
if _, err := Activate(one, ids); err != nil {
t.Fatalf("Activate one: %v", err)
}
if _, err := Activate(two, ids); err != nil {
t.Fatalf("Activate two: %v", err)
}
p1 := activatedScoped(t, one, "acme.scoped")
p2 := activatedScoped(t, two, "acme.scoped")
if p1 == p2 {
t.Fatal("both applications got the same *scopedPlugin")
}
if p1 == orig || p2 == orig {
t.Fatal("the value passed to Register was handed to an application")
}
if p1.app != one || p2.app != two {
t.Fatal("a plugin stored another application's app")
}
if got := p1.Name(); got != "one" {
t.Fatalf("app one plugin reads app.name %q, want one", got)
}
if got := p2.Name(); got != "two" {
t.Fatalf("app two plugin reads app.name %q, want two", got)
}
for _, p := range []*scopedPlugin{p1, p2} {
if p.label != "fixed" {
t.Fatalf("label = %q, want the registered literal's fixed", p.label)
}
if p.register != 1 || p.boot != 1 {
t.Fatalf("register=%d boot=%d, want 1 and 1 per instance", p.register, p.boot)
}
}
if orig.app != nil || orig.register != 0 || orig.boot != 0 {
t.Fatalf("original was touched: app=%v register=%d boot=%d", orig.app, orig.register, orig.boot)
}
for _, app := range []*backpack.App{one, two} {
list, _ := app.Lookup[Activated]()
var sawValue, sawCount bool
for _, p := range list {
switch v := p.(type) {
case valuePlugin:
sawValue = v == (valuePlugin{id: "acme.value"})
case *countPlugin:
sawCount = v == count
}
}
if !sawValue {
t.Fatal("value plugin not used as is")
}
if !sawCount {
t.Fatal("pointer to a non-struct type not used as is")
}
}
t.Run("parallel", func(t *testing.T) {
apps := []*backpack.App{namedApp(t, "left"), namedApp(t, "right")}
var wg sync.WaitGroup
errs := make([]error, len(apps))
for i, app := range apps {
wg.Add(1)
go func() {
defer wg.Done()
_, errs[i] = Activate(app, ids)
}()
}
wg.Wait()
for i, err := range errs {
if err != nil {
t.Fatalf("Activate %d: %v", i, err)
}
}
l := activatedScoped(t, apps[0], "acme.scoped")
r := activatedScoped(t, apps[1], "acme.scoped")
if l == r || l.Name() != "left" || r.Name() != "right" {
t.Fatalf("parallel activation shared instances: %q %q", l.Name(), r.Name())
}
})
}
func TestRegisterFactory(t *testing.T) {
t.Run("called per Activate", func(t *testing.T) {
withRegistry(t)
calls := 0
RegisterFactory("acme.made", func() Plugin {
calls++
return &scopedPlugin{id: "acme.made"}
})
one := namedApp(t, "one")
two := namedApp(t, "two")
if _, err := Activate(one, []string{"acme.made"}); err != nil {
t.Fatalf("Activate one: %v", err)
}
if _, err := Activate(two, []string{"acme.made"}); err != nil {
t.Fatalf("Activate two: %v", err)
}
if calls != 2 {
t.Fatalf("factory ran %d times, want 2", calls)
}
if activatedScoped(t, one, "acme.made") == activatedScoped(t, two, "acme.made") {
t.Fatal("factory instances are shared")
}
})
t.Run("nil fn", func(t *testing.T) {
withRegistry(t)
RegisterFactory("acme.none", nil)
mu.Lock()
n := len(plugins)
mu.Unlock()
if n != 0 {
t.Fatalf("registry length = %d after RegisterFactory(nil), want 0", n)
}
})
t.Run("nil result", func(t *testing.T) {
withRegistry(t)
RegisterFactory("acme.nil", func() Plugin { return nil })
_, err := Activate(namedApp(t, "one"), nil)
if err == nil || !strings.Contains(err.Error(), `factory for "acme.nil" returned nil`) {
t.Fatalf("err = %v, want factory nil error", err)
}
})
t.Run("id mismatch", func(t *testing.T) {
withRegistry(t)
RegisterFactory("acme.wrong", func() Plugin { return &scopedPlugin{id: "acme.other"} })
_, err := Activate(namedApp(t, "one"), nil)
if err == nil || !strings.Contains(err.Error(), "acme.wrong") || !strings.Contains(err.Error(), "acme.other") {
t.Fatalf("err = %v, want an error naming acme.wrong and acme.other", err)
}
})
}

View File

@@ -2,6 +2,7 @@ package party
import ( import (
"fmt" "fmt"
"reflect"
"strings" "strings"
"sync" "sync"
@@ -21,40 +22,112 @@ type Plugin interface {
} }
// Activated is the ordered plugin list published by Activate. Commands look // Activated is the ordered plugin list published by Activate. Commands look
// it up at Run time with app.Lookup[Activated](). // it up at Run time with app.Lookup[Activated](). The plugins in it are the
// application's own instances (see Activate).
type Activated []Plugin 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 ( var (
mu sync.Mutex mu sync.Mutex
plugins []Plugin plugins []registration
) )
// Register appends a plugin to the process-wide registry. Plugins call this // Register adds a plugin to the process-wide registry. Plugins call this
// from init() after a blank import; Activate selects and orders them. // 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) { func Register(p Plugin) {
if p == nil { if p == nil {
return 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() mu.Lock()
defer mu.Unlock() defer mu.Unlock()
plugins = append(plugins, p) plugins = append(plugins, entry)
} }
func snapshot() []Plugin { // 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() mu.Lock()
defer mu.Unlock() defer mu.Unlock()
out := make([]Plugin, len(plugins)) plugins = append(plugins, registration{id: id, factory: fn})
copy(out, plugins) }
return out
// 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(), // Activate resolves ids in manifest order, topologically sorts Requires(),
// then runs every Register before any Boot. // 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) { func Activate(app *backpack.App, ids []string) ([]Plugin, error) {
if app == nil { if app == nil {
return nil, fmt.Errorf("party: app is nil") return nil, fmt.Errorf("party: app is nil")
} }
return activate(snapshot(), app, ids) 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) { func activate(registered []Plugin, app *backpack.App, ids []string) ([]Plugin, error) {