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

@@ -8,7 +8,7 @@ Compiled plugin registry that orders plugins by their dependencies and runs thei
## 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
@@ -23,7 +23,8 @@ Use cases:
## Features
- `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.
- 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`.
@@ -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):
```go
@@ -79,8 +84,9 @@ if err != nil {
| Identifier | Description |
|------------|-------------|
| `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.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.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.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.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. |
@@ -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).
- Third-party: none.
- Standard library: `fmt`, `strings`, `sync`.
- Standard library: `fmt`, `reflect`, `strings`, `sync`.
## Testing