plugins

Procyon plugin runtime

Procyon plugins are ordinary Go packages linked into the application binary. There is no directory scanning, .so loading or second runtime for private plugins. The application combines project-owned registrations from plugins_local.go with installed registrations from generated plugins_gen.go.

Lifecycle

The registry performs these phases in order:

1. validate registration names and factories;
2. instantiate enabled plugins with their namespaced JSON configuration;
3. validate instance names and Requires dependencies;
4. reject missing dependencies and cycles, then sort topologically;
5. run migrations when requested by the application;
6. register and seal synchronous capabilities;
7. register typed event handlers;
8. collect policies and register routes;
9. start background workers;
10. stop plugins in reverse dependency order.

plugins.<name>.enabled=false prevents a registered plugin from being instantiated. A required disabled plugin is consequently reported as missing.

Optional interfaces

Existing plugins only need to implement Plugin. New plugins can additionally implement:

• DependencyDeclarer for Requires() []string;
• CapabilityRegistrar for synchronous ports;
• EventRegistrar for event subscriptions before events.Bus.Seal;
• MigrationProvider for Core-managed versioned migrations;
• Starter for workers that receive the application cancellation context.

Factories receive Dependencies with the database, logger, event bus, business metrics, UTC clock and shared capability registry. Configuration stays as the separate json.RawMessage factory argument and must be decoded by the owning plugin.

Routes

RegisterRoutes receives the existing public, authenticated and Kratos/RBAC admin groups. It can also receive Routes.Operations, a group on the separate admin server that Core has already protected with RequireAdminKey. Operations is nil when admin-key authentication is not configured, so a plugin must guard its registration:

func (p *Plugin) RegisterRoutes(routes plugins.Routes) {
	if routes.Operations != nil {
		routes.Operations.POST("/maintenance/run", p.runMaintenance)
	}
}

Plugins must not add another admin-key middleware to this group. Route collision detection covers the public, admin and upload servers, including operations routes registered by different plugins.

Capabilities

Capabilities are immediate, synchronous calls. Register a stable interface:

type PlayerLookup interface {
	ExistsAndActive(context.Context, uint) (bool, error)
}

err := plugins.Provide[PlayerLookup](registry, "players", "players.lookup.v1", lookup)

Consumers resolve the interface only after the capability registration phase:

lookup, err := plugins.Resolve[PlayerLookup](registry, "players.lookup.v1")

Duplicate names, missing capabilities, wrong Go types and writes after sealing return explicit errors. Use typed events instead when communicating a fact that has already occurred.

Migrations

A MigrationProvider returns ordered migrations with stable versions:

func (*Plugin) Migrations() []plugins.Migration {
	return []plugins.Migration{{
		Version: "001-create-leagues",
		Up: func(ctx context.Context, tx *gorm.DB) error {
			return tx.WithContext(ctx).AutoMigrate(&League{})
		},
	}}
}

Applied versions are recorded under the composite primary key (plugin_name, migration_version) in plugin_schema_migrations. Each migration is attempted in a GORM transaction. Database-specific DDL rules still apply; notably, MySQL can implicitly commit some schema operations.