pluginkit

package module

v0.5.0 Latest Latest Go to latest Published: Aug 15, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/gopherium/pluginkit

Links

Open Source Insights

README ¶

pluginkit

Compile-time plugin infrastructure for Go applications: a lifecycle host, plugin wiring generation, and route guarding. Framework-free and storage-agnostic. The application owns its plugin contract and its SDK surface, and pluginkit owns the mechanism underneath.

Design

pluginkit is a set of primitives, not a framework. It grows by adding small independent building blocks, each usable on its own.

Plugin is the lifecycle contract, with the optional Migrator, Seeder, RouteProvider, and PublicPathProvider capabilities.
Host migrates, starts, and stops a fixed set of plugins with rollback and panic isolation, and seeds them on request outside the start path.
Protect guards a plugin's mounted routes with caller-supplied middleware while letting its declared public paths through untouched.
wire generates the Go and TypeScript plugin wiring files from plugins/*/plugin.json manifests.

Applications re-export the lifecycle types from their own SDK package as type aliases, so plugins depend only on the application's contract.

Usage

host := pluginkit.NewHost(registeredPlugins...)
if err := host.Start(ctx); err != nil {
    // every migrator ran first and a failed start rolled back cleanly
}
defer host.Stop(ctx)

for id, handler := range host.Routes() {
    mux.Handle("/api/plugins/"+id+"/", http.StripPrefix("/api/plugins/"+id,
        pluginkit.Protect(handler, host.PublicPaths()[id], requireSession)))
}

License

Apache License 2.0 (LICENSE). Every file carries an SPDX-License-Identifier: Apache-2.0 header.

Documentation ¶

Overview ¶

Package pluginkit provides compile-time plugin infrastructure: a lifecycle contract, a plugin host, and route guarding for plugin namespaces.

Index ¶

func Protect(handler http.Handler, publicPaths []string, ...) http.Handler
type Host
- func NewHost(plugins ...Plugin) *Host
type Migrator
type Plugin
type PublicPathProvider
type RouteProvider
type Seeder

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func Protect ¶

func Protect(handler http.Handler, publicPaths []string, wrap func(http.Handler) http.Handler) http.Handler

Protect wraps a plugin handler in the caller-supplied middleware and serves the plugin's declared public paths untouched (exact match, per PublicPathProvider).

Types ¶

type Host ¶

type Host struct {
	// contains filtered or unexported fields
}

Host starts and stops a fixed set of plugins.

func NewHost ¶

func NewHost(plugins ...Plugin) *Host

NewHost returns a Host managing plugins. It panics when two plugins share an ID.

func (*Host) PublicPaths ¶

func (h *Host) PublicPaths() map[string][]string

PublicPaths returns the session-exempt paths of every PublicPathProvider plugin, keyed by plugin ID.

func (*Host) Routes ¶

func (h *Host) Routes() map[string]http.Handler

Routes returns the HTTP handler of every RouteProvider plugin, keyed by plugin ID.

func (*Host) Seed ¶ added in v0.3.0

func (h *Host) Seed(ctx context.Context) error

Seed asks every Seeder plugin to fill its schema in registration order, stopping at the first failure.

func (*Host) Start ¶

func (h *Host) Start(ctx context.Context) error

Start migrates every Migrator plugin, then starts every plugin in registration order, stopping the already-started ones in reverse order when a start fails.

func (*Host) Stop ¶

func (h *Host) Stop(ctx context.Context) error

Stop stops every plugin in reverse registration order, continuing past failures and returning them joined.

type Migrator ¶

type Migrator interface {
	Migrate(ctx context.Context) error
}

Migrator is implemented by plugins that own database schema, which the host migrates before starting any plugin.

type Plugin ¶

type Plugin interface {
	ID() string
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
}

Plugin is an independently addable unit of functionality with a managed lifecycle.

type PublicPathProvider ¶

type PublicPathProvider interface {
	PublicPaths() []string
}

PublicPathProvider is implemented by plugins declaring namespace-relative paths that must stay reachable without a session. Paths match exactly, for every HTTP method, and all else stays protected.

type RouteProvider ¶

type RouteProvider interface {
	Routes() http.Handler
}

RouteProvider is implemented by plugins that expose HTTP endpoints under their own namespace.

type Seeder ¶ added in v0.3.0

type Seeder interface {
	Seed(ctx context.Context) error
}

Seeder is implemented by plugins that can fill their own schema with development data, which the host asks for outside the start path.

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
graphwire module
wire Package wire generates an application's plugin wiring files from the plugin.json manifest of every directory under each configured plugin root.	Package wire generates an application's plugin wiring files from the plugin.json manifest of every directory under each configured plugin root.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL