pact

Capability interfaces that compiled plugins implement to contribute routes, config, migrations, middleware, commands, admin screens, translations, mail templates and jobs.

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). 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.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.
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.
pact.OptionalMessage, a service an optional plugin can publish so others integrate with it without importing its package.
pact.HasModels, pact.HasJobs 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)  {}

API reference

Identifier	Description
`pact.Router`	Laravel-style route group builder (`pact.Router.Group`, `pact.Router.GroupRaw`, one method per HTTP verb, `pact.Router.Where`, `pact.Router.WhereIn`); implemented by surf.
`pact.HasRoutes`	Declares HTTP routes on a `pact.Router`.
`pact.Middleware`	A named `func(http.Handler) http.Handler` wrapper.
`pact.HasMiddleware`	Registers named middleware.
`pact.HasMiddlewareFactories`	Registers parameterized middleware resolved from `name:param` at wrap time.
`pact.HasHouseMiddleware`	Registers middleware tagged as envelope and error handling, which raw groups refuse.
`pact.HasConfig`	Ships default YAML config, merged under the plugin ID.
`pact.HasMigrations`	Ships an ordered gormigrate set, run with a per-plugin history table.
`pact.HasCommands`	Contributes bonfire console commands to the application binary.
`pact.HasModels`	Exposes GORM models.
`pact.Job`	Background unit of work that receives `pact.JobArgs`.
`pact.HasJobs`	Registers background jobs.
`pact.HasLang`	Ships translation YAML under `lang/<locale>/<group>.yaml`.
`pact.HasLangOverrides`	Replaces or adds translations of any loaded namespace, including the framework's own.
`pact.HasMailTemplates`	Ships mail templates and layout aliases.
`pact.Permission`	One backend permission entry (code, tab, label, roles).
`pact.NavigationItem`	One backend navigation entry, with an optional side menu.
`pact.SettingsItem`	One settings screen entry.
`pact.AdminController`	Admin controller identity: ID, model name and YAML config directory.
`pact.AdminAssets`	Embedded tree of the plugin's admin YAML.
`pact.AdminRecordSource`	Supplies a new model record for the generic admin handlers.
`pact.FilterScope`	Model scopes a list filter may call, limited to an exact allow list.
`pact.Option`	One dropdown choice (value and label).

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.

Testing

go test ./modules/pact/...

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

5.7 KiB Raw Blame History