Files
summercms/modules/party
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
..

party

Compiled plugin registry that orders plugins by their dependencies and runs their Register and Boot lifecycle.

import "git.golem15.com/golem15/summercms/modules/party"

Name: The guest list and the order people arrive in; it registers plugins and boots them in dependency order.

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. 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.

Role in the framework

The plugin lifecycle, on top of backpack, pact, phrasebook, postcard and signpost. lagoon, conga, cabana and surf ask it which plugins are active and in what order. It is the counterpart of WinterCMS's plugin manager, without autoloading: plugins are registered at build time.

Use cases:

  • Declare that a plugin depends on another one, and have it registered and booted after it.
  • Choose which compiled plugins are active through the manifest, with missing requirements and cycles caught at boot.
  • Run Register before Boot, so plugins can wire services before they use each other.

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) 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.
  • Activation sequence: records the ordered IDs on the backpack.App, publishes party.Activated (the ordered plugin list for commands that need plugin scopes at Run time), merges each pact.HasConfig tree into the app config under the plugin ID, runs every Register, publishes the translator (phrasebook), the mailer (postcard) and the menu item type registry (signpost, collected from every pact.HasMenuItemTypes plugin; a duplicate type key fails the activation), then registers each plugin's mail templates and runs its Boot.

Usage

A plugin registers itself when its package is imported:

package blog

import (
	"git.golem15.com/golem15/summercms/modules/backpack"
	"git.golem15.com/golem15/summercms/modules/party"
)

type Plugin struct{}

func (p *Plugin) ID() string                       { return "acme.blog" }
func (p *Plugin) Requires() []string               { return []string{"acme.user"} }
func (p *Plugin) Register(app *backpack.App) error { return nil }
func (p *Plugin) Boot(app *backpack.App) error     { return nil }

func init() {
	party.Register(&Plugin{})
}

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):

cfg, err := compass.Load("config")
if err != nil {
	return err
}
app := backpack.New(cfg)
info := []party.Info{
	{ID: "acme.user", Source: party.SourceLocal},
	{ID: "acme.blog", Version: "v0.2.5", Source: party.SourceModule},
}
if err := party.Describe(app, info, "v0.6.0"); err != nil {
	return err
}
plugins, err := party.Activate(app, []string{"acme.user", "acme.blog"})
if err != nil {
	return err
}

API reference

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. 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.
party.SourceLocal Source of a plugin inside the application repository; it has no version.
party.Installed What the application was built with: Framework and Plugins in manifest order; look it up with app.Lookup[party.Installed]().
party.Describe Publishes party.Installed on the app; a nil app is an error.
party.Activated The ordered []party.Plugin published by party.Activate; commands look it up at Run time with app.Lookup[party.Activated]().

Dependencies

Testing

go test ./modules/party/...

The tests use in-memory plugins and testing/fstest file systems and need no external services.