pact

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

Overview#

pact is the contract layer between plugins and the framework. It holds interfaces and plain data types, with no behaviour of its own. A plugin opts into a capability by implementing one of the Has* interfaces, and the framework package that owns the capability discovers it with a type assertion (party for config, surf for routes and middleware, lagoon for migrations, cabana for admin controllers, conga for jobs and schedules). It replaces the register*() methods of a WinterCMS PluginBase (registerPermissions, registerNavigation, registerSettings and so on) with small, separately implementable interfaces.

Features#

• Plugin capability interfaces: pact.HasRoutes, pact.HasConfig, pact.HasMigrations, pact.HasCommands, pact.HasModels, pact.HasJobs, pact.HasSchedule, pact.HasLang, pact.HasLangOverrides and pact.HasMailTemplates.
• HTTP contracts: the pact.Router group builder (implemented by surf), the pact.Middleware type, and named, parameterized (name:param) and house-envelope middleware through pact.HasMiddleware, pact.HasMiddlewareFactories and pact.HasHouseMiddleware.
• Backend registration data: pact.Permission, pact.NavigationItem and pact.SettingsItem, exposed through pact.HasPermissions, pact.HasNavigation and pact.HasSettings.
• Admin controller contracts: pact.AdminController, pact.HasAdminControllers, pact.AdminAssets (embedded Winter-shaped admin YAML), pact.AdminPermissioned and pact.AdminRecordSource.
• Admin extension contracts, so a plugin extends the compiled admin SPA without a Node build: pact.AdminClientAssets (per-controller JS and CSS from the plugin's embedded assets/ tree, Winter's addJs/addCss), pact.HasAdminActions with pact.AdminAction, pact.AdminActionInput and pact.AdminActionResult (named toolbar and widget actions whose routes, CSRF check, permissions and record scoping the framework owns), and pact.AdminPartialData (the curated view model a partial template renders).
• Optional admin hooks a controller or model can implement: list and form query scoping (pact.ListExtendQuery, pact.FormExtendQuery), create, update and delete hooks (pact.FormBeforeCreate, pact.FormAfterUpdate, pact.FormBeforeDelete and their siblings), relation hooks (pact.RelationExtendManageQuery, pact.RelationExtendOptionsQuery, pact.RelationBeforeLink), filter scopes (pact.FilterScope, pact.FilterOptions) and dropdown options (pact.DropdownOptionsProvider).
• A background job contract (pact.Job, pact.JobArgs) that does not depend on any queue library.
• A schedule contract: pact.HasSchedule returns pact.ScheduledCommand entries (a registered command name, its arguments and a pact.Cadence built with pact.Daily, pact.DailyAt or pact.Every), the Go form of WinterCMS registerSchedule. It does not depend on any queue library either.
• pact.OptionalMessage, a service an optional plugin can publish so others integrate with it without importing its package.
• pact.HasModels and pact.OptionalMessage are declared for plugins to implement, but no framework package consumes them yet.

Usage#

A plugin declares its capabilities by implementing the interfaces and asserting them at compile time:

package blog

import (
	"net/http"

	"git.golem15.com/golem15/summercms/modules/pact"
)

var (
	_ pact.HasRoutes      = (*Plugin)(nil)
	_ pact.HasPermissions = (*Plugin)(nil)
)

type Plugin struct{}

func (p *Plugin) Routes(r pact.Router) error {
	r.Group("/api/blog", []string{"auth"}, func(r pact.Router) {
		r.Get("/posts", listPosts)
		r.Get("/posts/{id}", showPost)
		r.Where("id", "[0-9]+")
	})
	return nil
}

func (p *Plugin) Permissions() []pact.Permission {
	return []pact.Permission{
		{Code: "acme.blog.access_posts", Tab: "Blog", Label: "Manage posts"},
	}
}

func listPosts(w http.ResponseWriter, r *http.Request) {}
func showPost(w http.ResponseWriter, r *http.Request)  {}

A plugin schedules one of its registered commands by implementing pact.HasSchedule:

var _ pact.HasSchedule = (*Plugin)(nil)

func (p *Plugin) Schedule() []pact.ScheduledCommand {
	return []pact.ScheduledCommand{
		{Command: "blog:prune-drafts", Cadence: pact.Daily()},
		{Command: "blog:ping", Args: []string{"--quiet"}, Cadence: pact.Every(15 * time.Minute)},
	}
}

API reference#

Dependencies#

• SummerCMS modules: bonfire (the command type in pact.HasCommands).
• Third-party: github.com/go-gormigrate/gormigrate/v2, gorm.io/gorm.
• Standard library: context, io/fs, net/http, time.

Testing#

go test ./modules/pact/...

The tests are compile-time interface checks and need no external services.