Extending62 min read
Writing a plugin
The plugin contract, what Host and ConfigHost expose, every hook and what it may change, and a complete plugin with its tests.
A plugin is a Go type with four methods. Everything else — reacting to a render, rewriting output, adding a template function — is opt-in: you implement the interface for the hook you want, and the framework finds it by type assertion.
This page is the reference for that surface. Using plugins is the other side of it: how an application registers and configures what you write. To have collage plugin add install your plugin, meet the repository contract.
A plugin's life runs from the value an application constructs to its Shutdown. Each stage below has a section of its own, and Lifecycle lists them in order.
The contract
type Plugin interface {
Name() string
Version() string
Init(ctx context.Context, host collage.Host) error
Shutdown(ctx context.Context) error
}
Nameidentifies the plugin. It must be non-empty and unique within the application, and it is the key of the plugin's configuration section — so make it read like a module path:acme/stamp.Versionis your plugin's own version, for diagnostics.Initruns once when the application starts, after the application has registered its own pages and before the first request.Shutdownreleases whateverInitacquired. It is called once, and only for a plugin whoseInitsucceeded; keep it idempotent anyway — see Lifecycle.
Because hooks are discovered by type assertion, a misspelled hook method is not a compile error — it is a hook that never runs. Assert every interface you mean to implement:
var (
_ collage.Plugin = (*Plugin)(nil)
_ collage.AfterRenderHook = (*Plugin)(nil)
)
Stable within v1
pkg/collage follows semantic versioning, and for a plugin that means this:
Plugingains no methods. Nor doMetrics,Tracer,Spanand the cache interfaces —Cache,TaggedCache,StaleCacheandSharedCache— a plugin may implement or bridge to. A new method would break every implementation, so none arrives within v1.- Embed the no-op types. A
Metricsimplementation embedscollage.NoopMetrics, aTracerembedscollage.NoopTracerand its spanscollage.NoopSpan, and each defines only the methods that measure something. An implementation that lists every method itself works too, and has nothing to gain from it. - New capabilities are optional interfaces, found by type assertion like a hook: a signal the framework reports later arrives as an interface a plugin may implement, and one that does not simply never hears of it.
HostandConfigHostare sealed and may grow. Only collage's own hosts implement them, so a new method breaks no plugin; what a plugin may call on one stays callable. This is also why a test double cannot stand in for aHost: test through a real application, as Testing a plugin shows.- A store a plugin provides is checked with
collagetest.CacheSuiteorcollagetest.SharedCacheSuite, which test the whole documented contract; a store that marks an entry stale where the contract says it is removed, or that resets its epoch onClear, fails.
Two phases: Configure and Init
Some work has to happen before templates are parsed. html/template can only call a function that was in its function map when the template was parsed, and parsing happens inside collage.New. So there is an optional earlier phase:
type Configurer interface {
Configure(ctx context.Context, host collage.ConfigHost) error
}
Configure runs inside New, once per plugin, in registration order, before the templates are parsed. A returned error aborts New. Nothing has been acquired yet, so there is no rollback.
Init runs later, when the application starts — the first call to Handler, ListenAndServe, Start, RenderPath, RenderDocumentPath or DispatchCommands, which includes a static build, since the builder renders through RenderPath. By then the application has registered its pages, so a plugin can read them and add documents and mounts of its own.
A plugin that needs both implements both. A plugin that implements Configurer must be supplied in Config.Plugins: RegisterPlugin is called after New has already parsed the templates, so it refuses such a plugin with ErrConfigurerRegisteredLate instead of skipping its Configure silently.
What each phase can reach
ConfigHost (Configure) | Host (Init) | |
|---|---|---|
DevMode, Logger, collage.PluginConfig(host, …) | yes | yes |
AddTemplateFunc, AddRenderFunc, WrapMount | yes | — |
collage.FindPlugin[T](host) | yes | — |
Pages, Page | — | yes |
URL, Locales, PageURLs, OriginFor, MultiOrigin | — | yes |
BuildID, ServeStatus | — | yes |
RegisterDocument, Mount, OpenMounted, Handle, Use | — | yes |
RenderFragment | — | yes |
RegisterCommand | — | yes |
ConfigHost is narrower on purpose. During Configure the application has registered nothing, so pages would be an empty list, and a site's origins are not known until every plugin, an OriginResolver among them, is.
ConfigHost and Host are narrow on purpose, and leave off what no plugin used:
Host.InvalidateTagsis gone. Invalidating is the application's —App.InvalidateTags,ActionResult.InvalidateTags— and a plugin hears of it withOnCacheInvalidate.ConfigHost.BaseURL,OriginForandMultiOriginare gone.Hostkeeps all three: read them inInit.- The
Hostgiven toInitlists no plugins, socollage.FindPluginfromInitreports false. Call it fromConfigureand keep what it finds. ErrorEvent.PageandBeforeActionEvent.Pageare gone: a hook was handed the framework's live page, which nothing read.
ConfigHost
| Method | What it does |
|---|---|
DevMode() bool | Whether the application runs in development mode. |
Logger() *slog.Logger | The application's logger. |
ConfigReader (embedded) | What collage.PluginConfig(host, defaults) reads this plugin's configuration section through — see Configuration. |
AddTemplateFunc(name, fn) error | Adds a template function. Returns ErrDuplicateTemplateFunc when the name was already added — by another plugin, or by this one earlier — or is a built-in's or the template language's. |
WrapMount(wrap func(fs.FS) fs.FS) | Registers a transformation applied to every mounted filesystem, in the order wrappers were registered. |
AddRenderFunc(name, factory) error | Adds a template function made anew for each render from its *RenderContext — see Template functions. |
A ConfigHost closes when the plugin's Configure returns. A plugin that kept it gets collage.ErrConfigureClosed from a later AddTemplateFunc or AddRenderFunc, a later WrapMount wraps nothing and is logged, and collage.FindPlugin through it finds nothing: templates are parsed once construction finishes, and requests render with what was registered by then.
Host
| Method | What it does |
|---|---|
DevMode() bool | Whether the application runs in development mode. |
Logger() *slog.Logger | The application's logger. |
ConfigReader (embedded) | What collage.PluginConfig(host, defaults) reads this plugin's configuration section through. |
Pages() []*collage.Page | Every registered page, each a defensive copy. |
Page(name) (*collage.Page, bool) | One page by name, a defensive copy. |
RegisterDocument(doc) error | Registers a document the plugin contributes. |
Mount(prefix, fsys, opts...) error | Serves a filesystem under a URL prefix. |
OpenMounted(urlPath) (fs.File, error) | Opens one of the site's own files by the URL it is served at — /static/icon.png — through the mount whose prefix it is under: from disk in development, embedded in a built binary. A missing file is fs.ErrNotExist. |
Handle(prefix, handler) error | Serves an http.Handler under a URL prefix ending in /, or at one exact path without it (/metrics), as App.Handle does — an event stream, a WebSocket. Unlike a plain App.Handle mount, it runs inside the middleware, and its request body is bounded at Server.MaxBodyBytes before the middleware, as a page's is. |
RenderFragment(r, req) (*collage.FragmentRender, error) | Renders a fragment a page opened with WithFragmentPath, in parts — see Pushing fragments. |
RegisterCommand(cmd) error | Contributes a command — see Commands. |
Use(middleware) error | Wraps every request, where the plugin was registered: for one in Config.Plugins, outside the application's own middleware. Not a request for a handler the application mounted with plain App.Handle. |
URL(name, locale, params) (string, error) | The path of a page or document, as App.URL builds it. |
BaseURL() string | Config.BaseURL, without a trailing slash; empty when none is set. |
OriginFor(ctx, host) string | The public origin of a host: an OriginResolver's, else Config.BaseURL — see Which origin a host has. |
MultiOrigin() bool | Whether an OriginResolver is registered, so origins vary by host. |
Locales() (default, supported) | The default locale and every supported one, the default included. |
PageURLs(ctx, name) ([]collage.PageURL, error) | Every URL a page answers, in every locale, a pattern expanded through its WithStaticParams — a sitemap's contents. |
BuildID() string | The build serving — Config.Cache.Version, or a fingerprint of the executable — for versioning what a browser keeps across deploys: a service worker's caches, an asset's query string. |
ServeStatus(w, r, status) | Answers the request with the status and the site's own page for it — the not-found page for 404 and 410, the error page otherwise — for a plugin answering a request itself that should look like the site. |
RegisterPage and FragmentURL are the application's (App.RegisterPage, App.FragmentURL), not the Host's.
What Init receives is not the *App. It is a narrow value that forwards these methods and nothing else, so a plugin cannot assert its way to ListenAndServe, Shutdown, the router, the cache or the template set.
Host and ConfigHost are sealed: both include collage.ConfigReader, whose one method is unexported, so only collage's own hosts satisfy it; test a plugin through a real application instead — see Testing a plugin.
Host limits what a plugin can reach, not what it can change.Pages and Page return copies of the page struct, of every slice and map it holds — Paths, CacheParams, FragmentPaths and its per-locale maps, DependencyTags, LayoutChain — and of its Redirect and Action values, so editing those does not touch the application's own page, its cache key or its fragment URLs. The fragments inside a copy are still shared, and the events below carry the live page, not a copy — copying a page and its fragment tree on every request would cost the hot path.
Writing through an event's Page changes the page every concurrent request is reading: that is a data race, and go test -race will say so. Treat pages as read-only. Plugins are trusted code, not a sandbox.
Documents and mounts a plugin registers are held to the same rules as the application's own: a name or a path that is already taken is a startup error, not a race decided by registration order.
Pushing fragments
RenderFragment is for a plugin that sends fragments over a connection it owns — an event stream or a WebSocket — instead of waiting for the browser to ask for them. It renders exactly what a request to the fragment's path renders, and returns the parts instead of a response. One difference: values read through collage.Cached are fresh. A request may be served a stale value while it is refreshed, but a pushed fragment is not asked for again, so RenderFragment waits for the upstream, and returns an error when it fails:
| Field | |
|---|---|
HTML | The markup, with the reader's forgery token in any form it holds |
Head | What the fragment hoisted into an area it placed no marker for, as HoistItems with their area and key |
DependencyTags | The tags the render depended on — match them against CacheInvalidateEvent.Tags to know what to push |
Shared | The render is the same for every reader on the same host at this moment: the page is cached for everyone, or every handler in the subtree is declared Static() or Shared() and there is no slot resolver — and there is no form token, and nothing a PersonaliseHook made personal. Such a render is made from a request with the reader's cookies, headers and context values stripped, as the page cache's is |
ETag | The ETag a request to the fragment's path would get for the same body, so a client can tell a pushed copy from one it already shows, or recognise the two as the same |
Cookie | The forgery cookie the forms in HTML need, when the request carried none |
A FragmentRequest names the fragment either by Page, Fragment, Locale and Params, or by Path — the URL a page linked with {{fragmentURL}}, query included — which is resolved as a request to it would be. A client subscribing to the elements it shows only knows their URLs, so Path is usually what a stream has.
out, err := host.RenderFragment(r, collage.FragmentRequest{Path: "/live/cpu"})
Only fragments the page opened are rendered: a stream reaches exactly what HTTP reaches. Each call is served as a request to the fragment's URL would be: a GET to it carrying r's host, client address, headers and cookies — not its path values, body or method — passes the application's and every plugin's middleware for the fragment's path, in the order a request does, then the fragment's own guard and the page's, which read the fragment URL's parameters with r.PathValue, never the caller's own.
- A refusal is
collage.ErrGuardRefusedinstead of a render: a guard that refuses, or a middleware that answers instead of calling next — a basicauth 401, a ratelimit 429, a login redirect, a timeout's 503. Send that connection nothing. What the middleware wrote, and the headers and cookies it set, are dropped; the context values it sets reach the guard and the render. A panicking middleware is an error wrappingErrPanic. - The caller's context values do not carry over. What the stream's own middleware put there was about the stream's path. The render ends when
rdoes, and a trace spanrcarries is not its parent. - Every
PersonaliseHookruns on the markup and on each hoisted item, so a CSP nonce or a honeypot marker is filled in as on a page; a render a hook made personal is notShared. - Every call is a request to the middleware: a rate limit counts each push.
- Called from a plugin's
Init, while the application is starting, it returns an error rather than render without the middleware.
By Page and Fragment, the URL is built from the page's pattern in the requested locale, as FragmentURL builds it: a parameter no request could carry — an undeclared name, a value with / outside a catch-all, ., .., empty — a locale the fragment has no path in, and a path a request would be redirected to its clean spelling from are ErrUnknownFragmentPath.
To ask each reader's middleware and guards about a change, call it once per reader, with that reader's request, and send each connection the render made for it. A render that is not Shared may hold one reader's data. A Shared one costs one render per change however many readers it reaches: once a reader's middleware and guards have passed, a Shared render already made for the same host, URL, locale and cached query is handed over as a copy, and readers arriving during the render wait for it. That reader's forgery token and PersonaliseHook pass go into the copy, so a copy that took a token, or that a hook made personal, is reported not Shared. It is made again once a tag it depended on — its URL's PathTag and its host's among them — is invalidated or purged, after the page's cache lifetime, and, for a page rendered per request, with the cache off or with a store shared between instances, a second after it was made. At most 4096 renders or 32 MiB (Cache.MaxBytes, if lower) are kept, none in development, and none for a reader whose request skips the cache: a middleware's SkipCache makes the render that reader's own, as over HTTP. A fragment whose handler returns the same for everyone at one moment — a measurement — is marked Shared() so that its render counts, without making its page static. App.RenderFragment is the same method, for an application's own code.
Streams and shutdown
A plugin's Shutdown runs after the server has stopped, and the server stops by waiting for every open request to end — which an event stream or a WebSocket never does by itself. A plugin serving one implements StreamCloser:
var _ collage.StreamCloser = (*Plugin)(nil)
func (p *Plugin) CloseStreams() { p.hub.close() }
CloseStreams runs when shutdown begins, before the server waits, and must end the streams without waiting for them. A handler served through Handle can push its write deadline forward with http.NewResponseController(w).SetWriteDeadline, and take the connection over with Hijack, as it could on a bare net/http server.
A plugin that must know the server is about to stop taking traffic — readiness turning false, new work refused — implements DrainHook:
var _ collage.DrainHook = (*Plugin)(nil)
func (p *Plugin) OnDrain() { p.draining.Store(true) }
OnDrain is called once, when the drain starts: before Server.DrainDelay is waited out and before CloseStreams, and even when DrainDelay is 0. It must not block — the server goes on serving while the drain lasts, and a slow hook delays every step after it. A panic in it is contained and logged at Warn with the plugin's name. Like Shutdown and CloseStreams, it reaches only plugins whose Init succeeded.
A Shutdown before Start, or after a Start that failed, tells none of them, so a plugin reused for a second start — as collagetest.TrySite followed by NewSite does with the same plugin value — does not begin already draining.
A plugin that does work only while the application is serving — a scheduler, a queue worker — implements ServeHook:
var _ collage.ServeHook = (*Plugin)(nil)
func (p *Plugin) OnServe(ctx context.Context) { go p.run(ctx) }
OnServe is called once, in registration order, by ListenAndServe: after the port is bound — when collage: listening is logged — and before it serves. It is not called by Start() or Handler(), so not in a static build, not in a plugin command, not by an application that runs its own http.Server over app.Handler(), and not when Shutdown ran before ListenAndServe. collage dev serves through ListenAndServe, so it is called in development too, again on every restart.
ctx derives from context.Background() and is cancelled when the drain starts, at the same moment OnDrain runs, whether the stop came from a signal or from App.Shutdown(ctx).
It means "start no new work"; finishing the work already running belongs in the plugin's Shutdown, which runs after the server stops and is bounded by the shutdown ctx. The ctx may already be done when OnServe is called — a drain that started a moment earlier — so check it before starting work.
OnServe must not block: start goroutines and return. A panic in it is contained and logged at Warn with the plugin's name, and the server still serves.
The hooks
| Interface | Method | Event | Fires | May change |
|---|---|---|---|---|
RequestHook | OnRequest | the *http.Request | First on every request, before collage's request span, middleware and routing | the request's context |
BeforeRenderHook | OnBeforeRender | BeforeRenderEvent | Before a fresh page render | nothing on the event; may hoist through ev.Context |
BeforeActionHook | OnBeforeAction | BeforeActionEvent | Before an action's handler, after its guards, body limit and forgery check | ev.Result, which answers in the handler's place |
AfterRenderHook | OnAfterRender | AfterRenderEvent | After a page render succeeded, with ev.Values (read with a key's In) | ev.HTML; reports with ev.Warn, ev.Error |
PersonaliseHook | OnPersonalise | PersonaliseEvent | For every HTML response on its way to one reader, after the cache | ev.Body, ev.Header, ev.Personal |
DocumentRenderedHook | OnDocumentRendered | DocumentRenderedEvent | After a document handler produced its body | ev.Body |
CacheInvalidateHook | OnCacheInvalidate | CacheInvalidateEvent | After entries were invalidated by tag | nothing |
OriginResolver | Origin | the host, as a string | When collage.BaseURL or Host.OriginFor names a host's origin | the origin returned |
ErrorHook | OnError | ErrorEvent | On a failure while serving a request | nothing |
BuildFinishedHook | OnBuildFinished | BuildFinishedEvent | Once, when a static build has written every file and captured its headers | reports with ev.Warn, ev.Error |
On a request, the hooks run in this order:
Every hook method has the shape func(ctx context.Context, ev *Event) error, except OnRequest. A request a plugin wants to see is OnRequest's, and a render about to run is OnBeforeRender's.
RequestHook
type RequestHook interface {
OnRequest(r *http.Request) (context.Context, func(status int))
}
Runs before anything else on a request: before collage starts its request span, before middleware, before routing. It returns the context the request is served under — derived from r.Context() — and a function collage calls with the status when the response is written: once, unless serving the request panics. The function may be nil, and it must not write to the response.
It is what a tracing plugin needs. A trace carried in from the caller has to be the parent of collage's own collage.http span, and middleware added with Host.Use runs too late for that, inside the span collage has already started:
func (p *Plugin) OnRequest(r *http.Request) (context.Context, func(status int)) {
ctx := p.propagator.Extract(r.Context(), propagation.HeaderCarrier(r.Header))
ctx, span := p.tracer.Start(ctx, r.Method, trace.WithSpanKind(trace.SpanKindServer))
return ctx, func(status int) {
if route := collage.RouteInfo(ctx); route.Kind != "" {
span.SetName(r.Method + " " + route.Kind + ":" + route.Name)
}
span.SetAttributes(attribute.Int("http.response.status_code", status))
span.End()
}
}
collage.RouteInfo(ctx) reports what the request resolved to, as a collage.Route: its Kind — collage.RouteKindPage, RouteKindDocument, RouteKindAction, RouteKindMount or RouteKindHandler (the strings "page", "document", "action", "mount", "handler", and the set may grow), or RouteKindRejected ("rejected", below) — and its Name, the registered name or prefix: the page's, the document's or the action's name, the mount's or the handler's prefix. It is the zero Route while the request is unresolved, and for a request that resolved to nothing, such as a 404 for a path no route has.
It reads the context collage serves the request under, which the finish function's context shares and Metrics.HTTPResponse receives, so a span or a metric can be labelled with the route rather than the raw path — a bounded set rather than one per URL.
Route carries two more fields: Pattern, the path pattern the route was registered with (/blog/{slug}, without a locale prefix, or a mount's or handler's prefix), and Locale. It is what to label with when the name is not enough — a trace's http.route for a document as well as a page.
Hooks run in registration order, and each is handed the request under the context the one before it made; the finish functions run in the reverse order. One that panics is skipped, and the request is served under the context before it.
The hooks also see a request collage answers before routing: a path with an encoded slash (/a%2f..%2fb), answered with a 404, and a dirty path (/a/../b), redirected with 301 (308 for a method other than GET and HEAD). These are a scanner's probes more often than not.
For such a request the finish function is called with the status written (once, unless serving the request panics), and r.URL is the raw path. collage.ClientIP(r) works inside OnRequest, so a plugin that bans or counts clients can see them.
Once the response is written, collage.RouteInfo reports such a request with KindRouteKindRejected ("rejected") and NameRouteNameNormalise ("normalise"), as it does the router's 404 for a path no route can ever match (an encoded slash /a%2fb, a NUL, malformed percent-encoding). A label built from RouteInfo stays bounded; one built from the path, a scanner's, does not. Metrics.HTTPResponse and collage's own request span see these requests too, with an empty path and no http.path.
Collage's own collage.http span records http.method bucketed: the standard methods as themselves, anything else a client sends as OTHER.
The hooks also see a static build's header capture: when a BuildFinishedHook plugin is registered, the build asks the handler for each file it wrote, and collage.IsCapture(r.Context()) is true for those requests. A plugin that counts or bans clients skips them. See BuildFinishedHook.
Use collage.ClientIP(r) rather than r.RemoteAddr for the client's address. It is a netip.Addr: RemoteAddr's host, or, behind the proxies the application lists in Server.TrustedProxies (see Deployment), the client the proxy reports. It is unmapped and has no zone, and is the zero netip.Addr when there is no address to give: in a shared page render, whose request has no RemoteAddr, and behind a trusted proxy whose X-Forwarded-For names no usable client (unknown). Never count that one.
collage.IsHTTPS(r) is whether the request arrived over TLS: on its own connection, or at a proxy that says so in X-Forwarded-Proto. With Server.TrustedProxies listed, the header is believed only from one of them, so a client cannot claim a TLS connection it does not have; with none listed it is believed from anyone. It is the decision the forgery guard makes for its own cookie's Secure flag. A plugin setting Secure on a cookie, or sending Strict-Transport-Security, uses it rather than reading the header itself.
BeforeRenderHook
type BeforeRenderEvent struct {
Context *collage.RenderContext // the render about to run
Page *collage.Page
Locale string
Path string
Static bool // rendered for a static build, not for a request
}
Fires immediately before a fresh render and not on a cache hit. It fires after the page's guards, and not at all for a request one of them blocked. It fires for pages, for error pages, for a page an action answers with through RenderPage, and for every page a static build renders.
It is the only hook that gets the render context, and the reason is hoisting. A plugin that contributes to the page declares before the tree renders, so that a fragment can still override it:
func (p *Plugin) OnBeforeRender(_ context.Context, ev *collage.BeforeRenderEvent) error {
ev.Context.HoistMeta("generator", p.opts.Generator)
return nil
}
A declaration made here sits at depth zero, so any fragment that declares the same key replaces it: the plugin provides the default, the page provides the specific thing. It lands only where the layout calls {{hoist "head"}}. An error fails the request with a 500, under "before_render".
Static says the page is being rendered for a static build — through App.RenderPath — rather than for a request. It is on AfterRenderEvent too. A render for the build's header capture is a request, so Static is false for it; collage.IsCapture(ctx) tells it apart.
BeforeActionHook
type BeforeActionEvent struct {
Action *collage.Action
Locale string
Request *http.Request
Result *collage.ActionResult // set it to answer in the handler's place
}
func (ev *BeforeActionEvent) Form() (url.Values, error)
Fires once per action request, immediately before the handler: after the page's guards, after the action's body limit is in place, and after the forgery check. It is where a plugin checks a submission, a spam filter or a quota, because the body there is bounded by the action's own limit, and a plugin that read it earlier, in middleware, would need a limit of its own.
ev.Form() parses the form, URL-encoded or multipart, and returns its fields. What it parsed stays parsed, so the handler reads the same form without the body being read twice. Use it rather than ParseMultipartForm alone, which for a URL-encoded body discards the error of reading it, a body past the limit among them.
For an action built with WithStreamingBody(), ev.Form() reads nothing and returns collage.ErrStreamingBody, so a plugin cannot consume the stream the handler reads. A plugin that inspects forms must treat that error as "this action has no form to check" and let the request through; one that returns it fails every upload. A plugin that calls ev.Request.ParseForm() itself still reads the body, and takes the stream from the handler.
func (p *Plugin) OnBeforeAction(_ context.Context, ev *collage.BeforeActionEvent) error {
form, err := ev.Form()
if errors.Is(err, collage.ErrStreamingBody) {
return nil // a streaming action: no form to check
}
if err != nil {
return err // past the action's limit: 413
}
if form.Get("website") != "" {
ev.Result = &collage.ActionResult{Status: http.StatusBadRequest}
}
return nil
}
Setting ev.Result answers the request with it, exactly as if the handler had returned it, and stops dispatch: no later plugin and no handler runs. That holds for all of it: its InvalidateTags are invalidated before the response and its Location is warmed, as a handler's are. One setting more than one of Location, Fragment, Page and Body is refused with a 500, and Location and Status go out as given. An error fails the request under "before_action", with 413 when it wraps *http.MaxBytesError and 500 otherwise — or 400 (408 for a read deadline) when the body was cut off while the plugin read it, logged at debug and handed to no error hook.
AfterRenderHook
type AfterRenderEvent struct {
Page *collage.Page
Locale string
Degraded bool // some fragment failed, fallback or not, or stale cached data was used
Static bool // rendered for a static build, not for a request
HTML []byte // replace it to post-process the page
// Fragments: each fragment's time and failure, as collage.FragmentReport
// DependencyTags: the tags the render depended on
// Values: the render's shared values, read with a collage.Key's In
// Findings: what ev.Warn and ev.Error reported so far
}
Fires after a page render succeeded, for pages, error pages, a page an action answers with through RenderPage, and static builds. Replace ev.HTML to post-process; what you leave there is what is served, and what is cached. Later plugins see what earlier ones produced.
ev.Values (a *collage.RenderValues) are the values the page's fragments exchanged through keys, so they are what the page was built from, for a plugin that wants the article rather than markup to parse back. A hook has no RenderContext, so it reads them with the key's In:
var ArticleKey = collage.NewKey[Article]("jsonld:article")
func (p *Plugin) OnAfterRender(_ context.Context, ev *collage.AfterRenderEvent) error {
article, ok := ArticleKey.In(ev.Values)
if !ok {
return nil // this page stored no article
}
ev.Hoist("head", "jsonld", p.script(article))
return nil
}
The values are opaque: a plugin reads only what it holds a key for, and there is no listing them. A plugin that wants the application to hand it something exports the key, and the application stores under it; a plugin that carries state from its own render functions to its hook keeps the key unexported. The framework puts nothing there. They are the render's own, not a copy: keeping them past the hook is holding request state.
Begin a key's name with the plugin's own name — "jsonld:article", "validate:errors". A key is only its name and its type, so two plugins that each declare NewKey[string]("errors") hold one value between them, and whichever sets it last wins.
ev.Fragments and ev.DependencyTags report how the render went, for a development tool to show beside the page. Each collage.FragmentReport has the fragment's Name; its Duration, the fragments in its slots included; Failed, even when a fallback stood in; UsedFallback; and Err, what it failed with. DependencyTags are the tags the render depended on. Both are the event's own copies.
Two consequences of where it sits:
- It does not run again on a cache hit. Its output is what was cached. A hook that must run per request cannot be combined with a cached page.
- An empty result is a failure. If
ev.HTMLis empty after dispatch, the request fails with a 500 rather than serving a blank page.
A page an action answers with through RenderPage runs it too, so a validation page is minified like any other. An error fails the request with a 500, under "after_render".
Adding to the head after the render
A plugin that learns what a page needs only from its finished markup — the code blocks it highlighted need a stylesheet — adds it with ev.Hoist(area, key, html) in OnAfterRender:
if highlighted {
ev.Hoist("head", "highlight:css", `<link rel="stylesheet" href="/_highlight/style.css">`)
}
It lands where the layout put {{hoist "head"}}, after what the render declared there. A key the render already declared in that area is left alone — the page is more specific than a plugin afterwards — and so is a key hoisted twice. ev.Hoist reports whether it added the HTML.
It finds the layout's place only in the HTML the render produced. If an earlier plugin replaced ev.HTML — or you did, in the same hook — "head" lands before </head> instead, and any other area reports false. Hoist first, then rewrite.
Checking the output: findings
A plugin that checks what a page renders — a heading level skipped, an image without alt, a form field without a label — reports what it finds rather than failing the render:
func (p *Plugin) OnAfterRender(_ context.Context, ev *collage.AfterRenderEvent) error {
if !bytes.Contains(ev.HTML, []byte("<h1")) {
ev.Error("one-h1", "the page has no <h1>")
}
return nil
}
ev.Warn(rule, message) reports a collage.FindingWarning, worth fixing and stopping nothing; ev.Error a collage.FindingError. A finding (collage.Finding) has its Level, the Rule that found it, a Message, the Plugin and the page's Path — the last two filled in by the framework. Where it goes depends on where the page was rendered:
- In development it is shown over the page, in the panel a failed fragment uses, and the page is served as it is.
- In a static build it is listed in the report under the page it is about (
BuildReport.Findings). An error-level finding fails the build withcollage.ErrBuildFindings; the pages are written either way. See Static export. - In production nothing is done with it. A check re-run on every render would spend a server's time on what the build already knew, so a checking plugin turns itself off there:
ev.Staticsays a render is a static build's, andhost.DevMode()says the server is a development one.
if !ev.Static && !p.dev { // p.dev from host.DevMode() in Init
return nil
}
What no single render can tell — two pages with one title, a link to a page the build did not write — belongs in OnBuildFinished. elagoht/htmlcheck is a checking plugin built on both.
Rewriting each response: PersonaliseHook
OnAfterRender runs once, before the cache, so it cannot give each reader something of their own. A plugin that must, such as a Content-Security-Policy nonce or a per-visitor token, implements PersonaliseHook, called for every HTML response on its way to one reader:
func (p *Plugin) OnPersonalise(_ context.Context, ev *collage.PersonaliseEvent) error {
if !bytes.Contains(ev.Body, []byte(p.marker)) {
return nil
}
nonce, err := newNonce()
if err != nil {
return err
}
ev.Body = bytes.ReplaceAll(ev.Body, []byte(p.marker), []byte(nonce))
ev.Header.Set("Content-Security-Policy", "script-src 'nonce-"+nonce+"'")
ev.Personal = true
return nil
}
The event carries:
ev.Request: the reader's own request, not a shared render's stripped one.ev.Header: the response header; set here what must match the body.ev.Body: what will be written, the reader's forgery token already in it. A hook replaces it (assigns a new slice); it must never write into it: the slice may be the cache's, shared with concurrent readers.ev.Personal: set it when the body became particular to this reader.
It runs after the forgery token goes into the shared body, inside every middleware, so before compression, and before the dev reload script. On a page it runs before the dev overlay; on an error page, or a page an action answers with, the overlay is already in the body. Plugins run in registration order and each sees the previous body. It covers a page (from the cache or fresh), a fragment path or fragment read, an action's HTML answer, an error page and what RenderFragment returns — the markup and each hoisted item — never a document. Once a hook sets Personal, a later one cannot clear it.
Personal treats the response as a forgery token does: its ETag is recomputed from the body sent, a page answers private, no-store, and neither a page from the cache nor a fragment read is answered 304, not even to If-None-Match: *.
A fragment read answers private, no-cache with the recomputed ETag and an action's HTML private, no-store, overriding even a Cache-Control the handler set. A compressing middleware that keeps compressed bodies per ETag, such as elagoht/compress, gains nothing from a personal response: its ETag is new every time. elagoht/compress compresses it for each reader and keeps nothing.
A body changed without Personal still gets an ETag naming the bytes sent. A hook that returns an error or panics is logged and the page, fragment or action answers 500; on an error page the built-in page for that status is sent instead. A site without such a plugin sends the same responses as before.
DocumentRenderedHook
type DocumentRenderedEvent struct {
Document *collage.Document
ContentType string
Locale string
Path string
Body []byte // replace it to transform the document
}
AfterRenderHook's counterpart for documents — sitemaps, feeds, JSON. Without it, a plugin that post-processes output would cover pages and silently skip everything else. It fires before the ETag is computed and before the body is cached, so what you produce is what is stored and what the ETag describes. Check ContentType to decide whether a body is yours to touch. An empty body after dispatch, or an error, fails the request with a 500.
A document does not dispatch OnBeforeRender or OnAfterRender: it has no page and renders no templates.
CacheInvalidateHook
type CacheInvalidateEvent struct {
Tags []string
Entries []InvalidatedEntry // the cached entries invalidated, each with its host, sorted
}
type InvalidatedEntry struct {
Host string
Path string
}
Fires after InvalidateTags or PurgeTags reached the entries for some tags — whether the application or an action called it. It is dispatched from that call, not from a request. Every plugin implementing it is called, even after one before it failed or panicked, so one failing plugin cannot keep a CDN purge or a live update from running, and each failure is logged and joined into what InvalidateTags returns. A plugin does not invalidate: the Host has no InvalidateTags.
Entries names the cached pages and documents the invalidation reached — what a CDN has to purge, and a search engine be told has changed. On the built-in stores an InvalidateTags entry was marked stale, not removed: it is no longer served as fresh, and is served again only, marked STALE, when its re-render fails or is degraded. A page that was not cached is never in it: nothing of it was reached. Nor is a page an earlier invalidation already marked stale, until it is rendered and stored again — except with a store a fleet shares, a collage.SharedCache: its own tag index names every page any instance wrote, and keeps a page invalidated and not yet re-rendered, so a second invalidation names it again.
Every cached entry also depends on the tag collage.PathTag(path), so an application that knows a path rather than a tag invalidates what is cached there with app.InvalidateTags(ctx, collage.PathTag("/blog")). See Caching.
Each entry is a host and a URL path, sorted by host and then path. A path cached under two hosts is two entries, and the host keeps its port if the request had one. A plugin that purges a CDN or pings a search engine reads it to build each URL against the right origin. The host is recorded as a collage:host:<host> dependency tag beside collage:path:; host tags are exempt from the tracker's per-tag cap, and MaxEntries still bounds memory.
Which origin a host has: OriginResolver
A plugin that serves several sites from one process, a host per customer, says which public origin absolute URLs for a host are built against by implementing OriginResolver:
func (p *Plugin) Origin(ctx context.Context, host string) (string, bool) {
origin, ok := p.origins[host]
return origin, ok
}
The host arrives lower-cased with its port stripped, and an IPv6 literal without its brackets (::1). The first plugin in registration order that returns ok wins. An origin must be a bare scheme://host[:port] with scheme http or https, which collage.ParseOrigin checks and normalizes, and must name a host (https://:8080 does not); an invalid one counts as not known, and dev mode logs it once per plugin and origin.
A host no plugin knows gets Config.BaseURL, and a resolver that panics is logged and skipped. Application code reads the result with collage.BaseURL(rc), which is safe in a cached render because the host is in the cache key, and a static build, which has no request, gets Config.BaseURL. A site without a resolver sees no change.
A plugin that builds absolute URLs itself asks the Host it was given in Init. ConfigHost has no BaseURL, OriginFor or MultiOrigin: during Configure not every resolver is known.
origin := host.OriginFor(ctx, "acme.test") // a resolver's, else Config.BaseURL
varies := host.MultiOrigin() // is a resolver registered?
A plugin that takes origins in its own configuration validates them with collage.ParseOrigin rather than a copy of the rule; what it refuses is collage.ErrInvalidOrigin. Code that holds only a context reads a header declared with collage.Vary through collage.Varied(ctx, header).
ErrorHook
type ErrorEvent struct {
Err error
Path string
Stage string
Status int // the HTTP status the failure is answered with; 0 for none
Request *http.Request // the reader's request, read-only; nil outside a request
}
Fires on a failure while serving a request: a page, a document, an action, a mount or a handler registered with App.Handle. Stage names where it happened.
The event carries no Page; read Path to tell what failed.
The stages the framework uses each have a constant, to compare against instead of the literal:
| Stage | Constant |
|---|---|
"route" | collage.StageRoute |
"not_found" | collage.StageNotFound |
"guard" (a page's guard failed or answered with a decision it cannot write) | collage.StageGuard |
"before_render" | collage.StageBeforeRender |
"before_action" | collage.StageBeforeAction |
"render" | collage.StageRender |
"after_render" | collage.StageAfterRender |
"cache_write" | collage.StageCacheWrite |
"error_page" | collage.StageErrorPage |
"asset" | collage.StageAsset |
"plugin" | collage.StagePlugin |
"handler" | collage.StageHandler |
"panic" | collage.StagePanic |
The set is not a closed enum and may grow, so name the stages you handle rather than assuming you have seen them all.
"error_page" is the one worth alerting on: it means the page that reports failures itself failed, and the client still received a plausible built-in page, so nobody would otherwise find out.
Classify Err with errors.Is — collage.ErrNoRoute for a URL that matched nothing, collage.ErrNotFound for content that does not exist, collage.ErrMethodNotAllowed for a 405, collage.ErrCSRFMissing and its siblings for a refused submission, collage.ErrAssetFailed for a mount answering 4xx or 5xx, collage.ErrPanic for a recovered panic, and the rest listed in Errors.
A panic recovered while serving a request (stage "panic") is a *collage.PanicError. It still matches errors.Is(err, collage.ErrPanic); errors.As reaches the panic value and the stack it was raised on, and errors.Is reaches the value itself when the code panicked with an error. The stack is no longer in the error's message, only in a separate stack attribute of the framework's collage: request failed log line, so code that matched the stack in the message reads PanicError.Stack instead.
Status is the HTTP status the failure is answered with: 404 for a missing asset, 500 for a failed render or a panic, and 0 when no response is written for it, as for a cache write that failed after the page was served, or a failed render a stale page was served in place of. That one keeps the stage it failed in, "render" say, and reaches OnError once per failed render, however many readers were waiting on it and were served the stale page; see Caching. An "error_page" event always says 500.
Request is the reader's live request, for reading only: its URL, method and headers, with a body that may already have been read. It is nil when the failure did not come from a request. Read what you need during OnError; do not keep it or hand it to another goroutine. Together they let a plugin tell a 5xx from a 4xx and name the URL without a middleware of its own.
A page's failed cache write ("cache_write") happens inside the render shared by every reader waiting on the same cache key, so its Request is that shared render's stripped request, not a particular reader's: no cookies, only the headers middleware declared with collage.Vary, no RemoteAddr. A document's cache write carries the request of the reader whose miss started the shared render.
An error returned from OnError is logged and swallowed, and the remaining plugins still receive the event: an error handler that fails must not start another round of error handling.
BuildFinishedHook
type BuildFinishedEvent struct {
OutDir string // the directory the build wrote into
Files []collage.BuiltFile // every file it wrote, in no particular order
Redirects []collage.BuiltRedirect // every redirect the site declares
// Findings: what ev.Warn and ev.Error reported so far
}
type BuiltFile struct {
Kind string // collage.BuiltPage, BuiltDocument or BuiltAsset: "page", "document", "asset"
Name string // the page's or document's name; empty for an asset
Locale string
Path string // the URL path the file answers
File string // its absolute path on disk
Captured bool // the build asked the application for this path
Status int // what it answered with; 0 when not captured or failed
Headers http.Header // the headers a static host can carry
}
type BuiltRedirect struct {
From string // "/old/{slug}", as registered
To string // "/new/{slug}", an absolute URL, or empty for a 410
Status int // 301, 302, 307, 308 or 410
Source string // "page:<name>", "document:<name>" or a plugin's name
}
Fires once, when a static build has written every page, document and asset, for checks across pages. Read a file with os.ReadFile when its content is needed. ev.Warn(path, rule, message) and ev.Error report a finding against the page at path, or against the build as a whole with an empty one.
An error returned from the hook fails the build too, beside the files already written. It never fires on a server, and a build whose context ended is not handed to it.
Headers. Before the hook runs, the build asks the application's handler for each file's path twice and puts the answer on the file: Status and Headers, without the headers about one response (Date, ETag, Set-Cookie, …) and without any that differ between the two answers, such as a CSP nonce. Captured is true for every file the build asked for, also one whose capture failed (Status 0), and false for the 404.html pages, which the build makes itself. The root copy of the home page, under PrefixDefault, carries the home page's capture.
The capture runs only when a BuildFinishedHook plugin is registered. What it finds is reported as warnings; see Static export.
Redirects.ev.Redirects holds every redirect the site declares: every page's in registration order (Source"page:<name>"), every document's ("document:<name>"), then every plugin's. Status is the redirect's status, 302 for one that set none. A page registered only with RegisterNotFoundPage or RegisterErrorPage is never matched, so its redirects are left out.
Together they are what a deploy adapter needs: elagoht/deploy writes them as a host's _headers, _redirects or vercel.json.
The capture is a request. Middleware and the request hooks see it, and the page renders again, with OnBeforeRender, OnAfterRender and OnDocumentRendered. A plugin that counts or limits traffic, or writes files or keeps a tally from a render hook, checks collage.IsCapture(ctx) and skips it. A capture request never writes the response cache.
RedirectSource
type RedirectSource interface {
Redirects() []collage.BuiltRedirect
}
A plugin that serves redirects of its own — from a file, a database — implements RedirectSource, so a static export carries its rules to the host. The build asks it once, after every file is written, and adds its rules to ev.Redirects with Source set to the plugin's name. Each is checked as a registered redirect is: From starts with one / and parses as a route pattern, and every placeholder in To is captured by it. Unlike a page's redirect, To may be an absolute http or https URL, and a 410 (a path that is gone) has no To; 301, 302, 307 and 308 need one.
Any other Status fails the build with collage.ErrInvalidRedirectStatus, and a malformed rule, or one with a control character, with collage.ErrInvalidRedirect, naming the rule and the plugin. A From or To holding a space, which a host's redirect file reads as a field separator, is malformed, and each bad rule is reported, every plugin's. A plugin rule from the same path as another redirect, or over a written file, fails the build like any other (What fails). elagoht/redirects is one.
Dispatch rules
- Hooks run in registration order.
- Every call is panic-guarded. A panicking hook fails like one that returned an error; it does not take the process down.
- For
OnBeforeRender,OnAfterRenderandOnDocumentRendered, the first error stops dispatch and fails the request. - For
OnPersonalise, the first error stops dispatch; a page, fragment or action answers 500 and an error page falls back to the built-in page for its status. - For
OnBeforeAction, the first error stops dispatch and fails the request, and so does the first plugin to setev.Result, which answers it. - For
OnCacheInvalidate, every plugin is called, even after one failed or panicked; the errors are logged and returned joined fromInvalidateTags. - For
OriginResolver, the first plugin that returnsokwith a valid origin wins; a resolver that panics is logged and skipped. - For
OnError, errors are logged and dispatch continues. OnRequestreturns no error. A panicking one is logged and skipped, and the request goes on under the context before it.- For
OnBuildFinished, the first error stops dispatch and fails the build. - A finding is not an error: it never stops dispatch, and every later plugin still runs.
Template functions
A plugin adds a template function from Configure:
func (p *Plugin) Configure(_ context.Context, host collage.ConfigHost) error {
return host.AddTemplateFunc("readingTime", func(words int) string {
return fmt.Sprintf("%d min read", max(1, words/200))
})
}
Every template can then call {{readingTime .Words}}. The function is any value html/template accepts in a function map.
- A name added twice — by two plugins, or twice by the same one — is
ErrDuplicateTemplateFunc, returned from the secondAddTemplateFunc.Newfails if yourConfigurereturns it, as it does when you pass the error on. The application cannot resolve it withTemplate.Funcs: the conflict is between plugins, and one of them has to give way. - The application wins otherwise. An entry in
Config.Template.Funcsunder a name a plugin added replaces the plugin's function: the application can see both and decide, andNewlogs each such name once. That holds forAddRenderFunctoo. - A built-in's name is not a plugin's to take.
AddTemplateFuncrefuses the name of any built-in function,jsonortruncateas much aspageURL, withErrDuplicateTemplateFunc: the plugin's function would replace the built-in under every template written against it. Pick a name of your own;Config.Template.Funcsis where an application replaces a built-in. - Nor is a name of the template language.
AddTemplateFuncandAddRenderFuncrefuse Go's builtins (eq,len,index,print…) and escapers (html,js,urlquery, html/template's own) withErrDuplicateTemplateFunc: a plugin'shtmlwould be all the escaping a value piped through it got. - It must be called from
Configure. There is no way to add one later, because a function added after parsing is one no template can call; a call through a keptConfigHostafterConfigurereturned isErrConfigureClosed.
AddTemplateFunc's function is one value for the life of the application. AddRenderFunc takes a factory instead, called for each render with its *RenderContext, so the function it returns can read what that render holds — a nonce a BeforeRender hook set, the render's locale:
var nonceKey = collage.NewKey[string]("csp:nonce")
host.AddRenderFunc("nonce", func(rc *collage.RenderContext) any {
nonce, _ := nonceKey.Get(rc)
return func() string { return nonce }
})
It follows AddTemplateFunc's rules: it is called from Configure, and a name another plugin added, or a built-in's, is ErrDuplicateTemplateFunc: a render function cannot replace one of the framework's own, those listed on Template functions.
Wrapping mounts
WrapMount registers a function applied to every mounted filesystem:
func (p *Plugin) Configure(_ context.Context, host collage.ConfigHost) error {
host.WrapMount(func(fsys fs.FS) fs.FS {
return minifyingFS{inner: fsys} // your own fs.FS
})
return nil
}
It wraps the filesystem rather than the response because mounts serve through http.ServeContent, which supports Range, If-Range and partial responses. Changing bytes per response shifts every offset, and a range request would return the wrong slice of a file whose advertised length no longer matches. A wrapper whose files are the transformed ones keeps that arithmetic true. Wrappers run in the order they were registered, and a nil wrapper is ignored. It is called from Configure; a later call wraps nothing and is logged.
Contributing documents and mounts
From Init, a plugin can add routes of its own through Host.RegisterDocument and Host.Mount, built with the same builders an application uses. A plugin registers no pages: pages are the application's. Host.Handle serves a plain http.Handler under a prefix, for what is not a page — an event stream, a WebSocket. A prefix ending in / claims every path beneath it; one without, /metrics, is a single exact path. It always runs inside the middleware, the application's and every plugin's: it is part of the site, and may read the session or rely on a basicauth in front of it. Its request body is bounded at Server.MaxBodyBytes before the middleware, as a page's is, so no middleware reads an unbounded body there; App.Handle is unchanged.
Host.Use wraps every request, as App.Use does, where the plugin was registered. A plugin in Config.Plugins is outside the application's own middleware, so what it puts in the request's context, a session, is there for the application's middleware to read, and its headers and cookies wrap what that middleware produced. One registered with App.RegisterPlugin sits among the application's middleware where the call was made. It does not run for a handler the application mounted with plain App.Handle, which brings its own middleware: a plugin that bans, limits, guards or logs cannot answer for such a mount. See No middleware, unless you ask.
A plugin that links to pages asks where they live rather than guessing: Host.URL builds a path as App.URL does, Host.Locales returns the default locale and every supported one, and Host.PageURLs(ctx, name) lists every URL a page answers — one collage.PageURL (Locale, Path, Params) per locale, and per parameter set a pattern's WithStaticParams lists. A pattern without it has none a plugin could know. It is what a sitemap is made of. App.Locales and App.PageURLs are the same, for an application's own code.
A plugin that reads one of the site's own files — a source image, a stylesheet — asks for it by the URL the site serves it at, with Host.OpenMounted, rather than by a path on disk:
f, err := host.OpenMounted("/static/icon.png")
if errors.Is(err, fs.ErrNotExist) {
// no icon yet: fall back, and say where to put one
}
It goes through the application's mount, so it reads static/icon.png from disk in development and the embedded copy in a built binary, and nothing has to be copied beside the binary. Only what a request could reach opens: a dotfile, or a path outside every mount, is fs.ErrNotExist. elagoht/favicon reads its source this way.
A plugin that produces files — resized images, generated icons — should serve them from a mount rather than a route. A static build copies every mount into its output after every page has rendered, so a filesystem that records what the pages asked for hands the builder exactly the right set, and the exported site needs nothing running behind it. A document at a dynamic path cannot be enumerated that way.
A plugin that answers a request itself — a page that is gone, a request it refuses — can answer with the site's own page rather than a line of text: host.ServeStatus(w, r, http.StatusGone) serves the not-found page for 404 and 410, and the error page for any other status.
A plugin versioning what a browser keeps across deploys — a service worker's caches, an asset's query string — reads host.BuildID(): Config.Cache.Version when it is set, or a fingerprint of the executable. App.BuildID and App.ServeStatus are the same, for an application's own code.
Commands
A plugin contributes a command from Init:
type Command struct {
Name string // as typed on the command line
Usage string // for your program's own help; the framework never prints it
Short string // one line
Run func(ctx context.Context, args []string) error
}
RegisterCommand refuses a name it could never run:
- an empty name;
- one that is not a single shell word — letters and digits of any script,
-_.:, a letter or digit first; no space, no shell syntax — isErrInvalidCommandName; - a
collage-name, whichDispatchCommandsanswers itself (collage-check,collage-inspect), and a name another command already holds areErrDuplicateCommand; - so is, for a plugin's command, one of the
collagebinary's own names (new,dev,build,export,serve,version,help…):go run . buildandcollage builddoing different things is a trap. An application's own command may still take one.
It stays open while every plugin's Init runs, and is closed with ErrAppStarted once the application has started.
Usage and Short are data. Neither the framework nor the collage binary prints them; a program that wants a help listing builds it from app.Commands().
The collage CLI does not run plugin commands: it never loads your application. The application's own main dispatches them with collage.DispatchCommands, and a scaffolded main.go does so for any word left after the flags, so a user of your plugin runs go run . <command>:
flag.Parse()
// ... build app and register everything ...
if args := flag.Args(); len(args) > 0 {
code, err := collage.DispatchCommands(context.Background(), app, args)
if err != nil {
fmt.Fprintln(os.Stderr, err)
}
os.Exit(code)
}
log.Fatal(app.ListenAndServe())
DispatchCommands starts the application first, because Init is what registers the commands. The exit codes are:
0for success;1for a startup failure, a command that ran and failed, or a command with noRun;2for a nil app, no arguments, or an unclaimed name (ErrUnknownCommand).
Say in your plugin's README that its commands run through the application. See The collage CLI.
Configuration
A plugin reads its own section of Config.PluginConfig into a typed struct with collage.PluginConfig(host, defaults), which takes Host or ConfigHost alike and returns the type of the defaults. It decodes the application's section over a copy of them:
type Options struct {
Generator string `json:"generator"`
Disabled bool `json:"disabled"`
Timeout collage.Duration `json:"timeout"` // "5s", "1m30s"
}
func (p *Plugin) Configure(_ context.Context, host collage.ConfigHost) error {
opts, err := collage.PluginConfig(host, p.opts) // what New was given, overlaid by the application's section
p.opts = opts
return err
}
- An absent, empty or
nullsection returns the defaults unchanged, so "not configured" and "configured to the zero value" stay different statements. - A present but malformed section is an error naming the plugin and, when one member's value is what fails, its key —
collage: acme/stamp: "timeout": …— returned with the defaults. The operator wrote something, and running on defaults silently would hide it. The section is decoded into a copy, so a failure leaves the defaults as they were. - A key your options do not have is an error, at any depth, and so is one named after a field tagged
json:"-":collage: acme/stamp: unknown key "generater" in plugins-config.json; remove it, or rename it to a key the plugin documents. It stops the application atConfigureorInit. Keys match fields case-insensitively, asencoding/jsonmatches them. Decode the fullOptionstype in onePluginConfigcall: the check is made against the type it decodes into, and a type with its ownUnmarshalJSONchecks its own keys, or none. A renamed or removed key therefore fails loudly by itself. - A scalar in the JSON replaces your default. A top-level list replaces the default list whole: its elements are new, so a field an element leaves out is that field's zero value, not the default element's. A top-level map adds its entries to a copy of yours. Neither writes into your slices or maps. Below the top level, a JSON object is decoded over the default's, setting only the fields it names, and a nested map is still filled in place: write the defaults as a literal rather than sharing one value between calls.
- A duration is a
collage.Duration, not atime.Duration. It reads a stringtime.ParseDurationunderstands —"10s","1h30m"— and writes one back. A bare number is refused with an error naming its key, wheretime.Durationwould have read3600as 3.6µs without a word, and so is a negative duration;nullleaves the default. Convert it where you use it:time.Duration(p.opts.Timeout). - The application sees a key that names no registered plugin as a startup error (
ErrUnknownPluginConfig). YourNameis therefore the whole of your configuration's address; changing it is a breaking change.
Document every key, its type and its default in your README. Take the same options in Go through one constructor, func New(opts Options) *Plugin, and decode the section over them: an application then configures you in Go, in JSON, or both, and collage plugin add writes New(Options{}), so the zero Options must be a working plugin (or fail in Init with a message that says what is missing).
Call the type Options, not Config, which reads as collage.Config at the call site. Booleans default to their zero value: an opt-out is a noX key rather than a key that defaults to true.
A secret never goes in plugins-config.json: a <x>Env key names the environment variable that holds it, and a json:"-" field takes the value from Go.
Editor support: collage.json
A plugin can describe itself to editors in a collage.json at its module's root. The file ships in the module like any other, and an editor extension finds it through the project's module graph — go list -m -json all — so a plugin the project depends on is described whether it is published or not. The extension offers what the file lists: the template functions with their signatures and documentation, the attributes, the snippets, and the schema of the plugin's section of plugins-config.json.
{
"$schema": "https://raw.githubusercontent.com/Elagoht/collage-snippets-highlighter/main/schemas/collage-plugin-manifest.schema.json",
"name": "you/greeting",
"description": "Greets the reader by name.",
"templateFunctions": [
{
"name": "greet",
"signature": "greet name",
"insert": "greet ${1:.Name}",
"doc": "\"Hello, name\" in the render's locale."
}
],
"attributes": [],
"snippets": {
"greeting": { "language": "html", "prefix": "cgreet", "body": ["<p>{{greet .Name}}</p>"], "description": "A greeting" }
},
"config": {
"type": "object",
"properties": { "formal": { "type": "boolean", "description": "Use the formal greeting." } }
}
}
| Field | What it is for |
|---|---|
$schema | The manifest's JSON Schema, so an editor checks the file as you write it |
name | The plugin's Name(), the key its configuration is found under in plugins-config.json |
description | What the plugin does, in a sentence |
repository | Where the plugin's documentation lives |
templateFunctions | The functions the plugin adds with AddTemplateFunc or AddRenderFunc: each one's name, its signature as a template calls it, what completion inserts (insert, the name by default) and its doc in Markdown |
attributes | HTML attributes the plugin reads, offered in tags: each one's name, the value completion inserts (null for a boolean attribute) and its doc |
snippets | Snippets by name, each with its language (html or go), prefix, body and description |
config | The JSON Schema of the plugin's section of plugins-config.json |
Every field but name is optional. insert, value and snippet bodies use VS Code's snippet syntax. The editor learns which of those functions the application actually has, and every page, fragment, slot and mounted file by name, from collage inspect.
A complete plugin
acme/stamp names the generator in every page's head, offers the same name to templates, adds a command that lists the pages, and reports a failing error page. It uses both phases, one render hook, one error hook and a command.
// Package stamp names the generator in every page's head, offers the same name
// to templates, and adds a command that lists the application's pages.
package stamp
import (
"context"
"fmt"
"log/slog"
"github.com/Elagoht/collage/pkg/collage"
)
// Name is the plugin's name, and the key of its section in plugins-config.json.
const Name = "acme/stamp"
// Options is the plugin's configuration. The zero value is the defaults.
type Options struct {
// Generator is what the generator meta tag says; "collage" when empty.
Generator string `json:"generator"`
}
// Plugin is the stamp plugin. Construct it with New.
type Plugin struct {
opts Options
logger *slog.Logger
}
// New returns the plugin. The application's plugins-config.json section is
// decoded over opts.
func New(opts Options) *Plugin { return &Plugin{opts: opts} }
var (
_ collage.Plugin = (*Plugin)(nil)
_ collage.Configurer = (*Plugin)(nil)
_ collage.BeforeRenderHook = (*Plugin)(nil)
_ collage.ErrorHook = (*Plugin)(nil)
)
func (p *Plugin) Name() string { return Name }
func (p *Plugin) Version() string { return "0.1.0" }
// Configure runs inside collage.New, before templates are parsed: the one
// moment a template function can still be added.
func (p *Plugin) Configure(_ context.Context, host collage.ConfigHost) error {
opts, err := collage.PluginConfig(host, p.opts) // the options New was given
if err != nil {
return err // a section that is malformed or names an unknown key
}
if opts.Generator == "" {
opts.Generator = "collage"
}
p.opts = opts
return host.AddTemplateFunc("generator", func() string { return p.opts.Generator })
}
// Init runs when the application starts, after it has registered its pages.
func (p *Plugin) Init(_ context.Context, host collage.Host) error {
p.logger = host.Logger()
return host.RegisterCommand(collage.Command{
Name: "pages",
Usage: "pages",
Short: "List every registered page",
Run: func(_ context.Context, _ []string) error {
for _, page := range host.Pages() {
fmt.Println(page.Name)
}
return nil
},
})
}
func (p *Plugin) Shutdown(context.Context) error { return nil }
// OnBeforeRender declares the meta tag before the page renders, at depth zero,
// so a fragment that declares its own generator replaces this one.
func (p *Plugin) OnBeforeRender(_ context.Context, ev *collage.BeforeRenderEvent) error {
ev.Context.HoistMeta("generator", p.opts.Generator)
return nil
}
// OnError reports the one failure nobody would otherwise notice: the error page
// itself failing.
func (p *Plugin) OnError(_ context.Context, ev *collage.ErrorEvent) error {
if ev.Stage == collage.StageErrorPage {
p.logger.Error("stamp: the error page failed", "path", ev.Path, "error", ev.Err)
}
return nil
}
An application uses it like any other plugin:
app, err := collage.New(&collage.Config{
Template: collage.TemplateConfig{Root: "templates"},
Plugins: []collage.Plugin{stamp.New(stamp.Options{})},
PluginConfig: pluginConfig, // {"acme/stamp": {"generator": "The Wire"}}
})
Lifecycle
Registration.
Config.PluginsinsideNew, orRegisterPluginbefore the application starts. After that,RegisterPluginreturnsErrAppStarted— also after any start that failed.Configure, inside
New, for plugins that implement it — in registration order, stopping at the first error.Init, when the application starts, in registration order. If one fails, startup is aborted and every plugin already initialised is shut down in reverse order. The failing plugin is not, since it never finished initialising.
OnServe, for a
ServeHook, onceListenAndServehas bound its port and before it serves, in registration order. OnlyListenAndServecalls it; its ctx is cancelled when the drain starts — see Streams and shutdown.Shutdown, from
App.Shutdown— whichListenAndServecalls onSIGINTorSIGTERM— in reverse registration order.- It calls
Shutdownonce, and only for a plugin whoseInitsucceeded: a plugin whoseInitnever ran or failed is not called, and one already shut down is not called again. - A start that fails after every
Initsucceeded — a mount that swallows a page, an error page never registered — shuts the plugins down there and then, as a failingInitrolls back the ones before it. - A
ShutdownbeforeStartinitialises no plugin at all:Startthen fails, andListenAndServereturns nil. AStartafterShutdownfails whether or not plugins are registered. - Every plugin gets its turn even if one fails, and the errors are joined.
- A plugin implementing
StreamCloserhas itsCloseStreamscalled earlier, when shutdown begins, and a plugin implementingDrainHookhas itsOnDraincalled before that, when the drain starts — both only for plugins whoseInitsucceeded; aShutdownbeforeStarttells none — see Streams and shutdown.
With
ListenAndServe, plugins are shut down after the drain'sServer.DrainDelayand after the server has finished its requests, or onceServer.ShutdownTimeouthas passed if it has not — past the deadline a request may still be running.With a server you own, the
Appknows of none: startServeHookplugins yourself, stop your server first, then callApp.Shutdown, or a plugin can be torn out from under an in-flight request (see Deployment).A static build or a plugin command serves nothing, so nothing calls
App.Shutdownfor it either: a scaffoldedmain.gocalls it once the build or the command is done.- It calls
Testing a plugin
Test a plugin the way an application would use it: in a real application, driven through its handler. collagetest.NewSite builds one with the least configuration a test needs — a layout with {{hoist "head"}} and {{slot "content"}}, a home page at /, a debug-level logger whose records it keeps — puts your plugin in it, and starts it, so Configure and Init run at once and their errors fail the test.
The application shuts down when the test ends. No server listens and no port is chosen.
package stamp_test
import (
"errors"
"log/slog"
"net/http"
"strings"
"testing"
"github.com/Elagoht/collage/pkg/collage"
"github.com/Elagoht/collage/pkg/collagetest"
"example.com/stamp"
)
// newSite builds a one-page application with the plugin in it.
func newSite(t *testing.T, options ...collagetest.SiteOption) *collagetest.Site {
t.Helper()
return collagetest.NewSite(t, append([]collagetest.SiteOption{
collagetest.WithPlugins(stamp.New(stamp.Options{})),
collagetest.WithTemplates(map[string]string{"home.html": `<p>{{generator}}</p>`}),
}, options...)...)
}
func TestStamp_UsesItsDefaults(t *testing.T) {
site := newSite(t)
body := site.Get("/").WantStatus(http.StatusOK).Body
if !strings.Contains(body, `<meta name="generator" content="collage">`) {
t.Errorf("no default meta tag in %s", body)
}
if site.Logs.Has(slog.LevelError) {
t.Errorf("the plugin logged an error:\n%s", site.Logs)
}
}
func TestStamp_ReadsItsConfiguration(t *testing.T) {
site := newSite(t, collagetest.WithPluginConfig(stamp.Name, `{"generator": "my site"}`))
body := site.Get("/").WantStatus(http.StatusOK).Body
if !strings.Contains(body, `<meta name="generator" content="my site">`) {
t.Errorf("no configured meta tag in %s", body)
}
if !strings.Contains(body, "<p>my site</p>") {
t.Errorf("template function not applied in %s", body)
}
}
func TestStamp_RefusesAnUnknownKey(t *testing.T) {
_, err := collagetest.TrySite(t,
collagetest.WithPlugins(stamp.New(stamp.Options{})),
collagetest.WithPluginConfig(stamp.Name, `{"generater": "typo"}`),
)
if err == nil || !strings.Contains(err.Error(), `unknown key "generater"`) {
t.Errorf("err = %v, want the unknown key named", err)
}
}
func TestStamp_RegistersItsCommand(t *testing.T) {
commands := newSite(t).App.Commands()
if len(commands) != 1 || commands[0].Name != "pages" {
t.Errorf("commands = %v, want one named pages", commands)
}
}
func TestStamp_RefusesLateRegistration(t *testing.T) {
app, err := collage.New(&collage.Config{Template: collage.TemplateConfig{Root: t.TempDir()}})
if err != nil {
t.Fatalf("New: %v", err)
}
if err := app.RegisterPlugin(stamp.New(stamp.Options{})); !errors.Is(err, collage.ErrConfigurerRegisteredLate) {
t.Errorf("RegisterPlugin: err = %v, want ErrConfigurerRegisteredLate", err)
}
}
A Site is the started App, a collagetest.Client on its handler — so Get, Submit, Follow and every other client method work on it — and Logs, every record the application wrote at debug level and above.
Logs.Has(level, parts...) reports whether a record at that level or above contains every part, and it is safe to call while the application serves requests from other goroutines. A test adds what its plugin needs:
| Option | Effect |
|---|---|
WithPlugins(plugins...) | Adds plugins, in order |
WithPluginConfig(name, json) | Sets one plugin's section, as plugins-config.json would. Invalid JSON fails the test |
WithTemplates(files) | Adds or replaces templates by name under the root: "layout.html", "home.html", or one a registered page renders |
WithRegister(items...) | Registers pages, documents and actions after the home page |
WithoutHome() | Leaves the home page out, so / is the test's |
WithConfig(func(*collage.Config)) | Edits the configuration before the application is built: locales, a cache, BaseURL, development mode, anything |
WithSetup(func(*collage.App) error) | Registers on the application itself before it starts — Handle, Mount, Use, RegisterNotFoundPage, RegisterErrorPage. Runs after the default registrations; several run in order; an error fails the site |
collagetest.TrySite is NewSite for a test that expects building or starting to fail — a plugin refusing a bad configuration — and returns the error instead of failing the test. When building the site fails — a WithRegister item, a WithSetup or Start — it shuts the application down first, so a plugin value can be used again for the next site.
A collagetest.Site can be copied (s := *site); go vet's copylocks check no longer objects.
A test that shuts the application down itself — to check what your Shutdown returns — calls site.Shutdown(ctx), not site.App.Shutdown(ctx). App.Shutdown runs once and returns its first error on every later call, so the cleanup would report the error the test expected; site.Shutdown closes the site and the cleanup does nothing more.
A few things worth testing that are easy to forget:
- The unconfigured case. Most applications will never write a section for you.
- Documents, if you implement
OnDocumentRendered: register a document and request it, since a plugin tested only against pages never sees one. If you implementOnError, request a document that fails too. - Run with
-race. A hook that writes through an event's livePageis a data race the detector reports and nothing else will. - A static export, if you produce files:
collage.Build(ctx, app, ...)into at.TempDir()shows whether the exported site has what the served one had. See Testing and Static export.
Example: a catalogue's referrer policy, from scratch
A product catalogue links out to its suppliers, a payment provider and review sites. Its URLs say what a shopper was looking at — /products/{slug}?colour=red&campaign=autumn — and the team wants every page to tell the browser, in a Referrer-Policy header, how much of that it may pass on. The policy must be the same on the server and in the exported copy of the site, and the footer names the address to report a vulnerability to.
acme/policy is a plugin written for that, small but complete:
- Options, set in Go or in
plugins-config.json: the policy and the contact. - Middleware added in
InitwithHost.Use, which sets the header on every response. - A template function,
{{securityContact}}, added inConfigure. - A build finding from
OnBuildFinished: a page the static build captured without the configured header.
A site that wants the whole set of security headers uses elagoht/secure, which sends Referrer-Policy among them. This one stays small so that each part of a plugin shows.
The plugin
// Package policy sends a Referrer-Policy header on every response, offers the
// site's security contact to templates, and checks a static build for pages
// that went out without the header.
package policy
import (
"context"
"fmt"
"net/http"
"slices"
"github.com/Elagoht/collage/pkg/collage"
)
// Name is the plugin's name, and the key of its section in plugins-config.json.
const Name = "acme/policy"
// DefaultReferrerPolicy is what is sent when Options.ReferrerPolicy is empty.
const DefaultReferrerPolicy = "strict-origin-when-cross-origin"
// policies are the values a Referrer-Policy header may hold.
var policies = []string{
"no-referrer", "no-referrer-when-downgrade", "origin", "origin-when-cross-origin",
"same-origin", "strict-origin", "strict-origin-when-cross-origin", "unsafe-url",
}
// Options is the plugin's configuration. The zero value is a working plugin.
type Options struct {
// ReferrerPolicy is the header's value; DefaultReferrerPolicy when empty.
ReferrerPolicy string `json:"referrerPolicy"`
// Contact is where to report a vulnerability, offered as {{securityContact}}.
Contact string `json:"contact"`
}
// Plugin is the policy plugin. Construct it with New.
type Plugin struct {
opts Options
}
// New returns the plugin. The application's plugins-config.json section is
// decoded over opts.
func New(opts Options) *Plugin { return &Plugin{opts: opts} }
var (
_ collage.Plugin = (*Plugin)(nil)
_ collage.Configurer = (*Plugin)(nil)
_ collage.BuildFinishedHook = (*Plugin)(nil)
)
func (p *Plugin) Name() string { return Name }
func (p *Plugin) Version() string { return "0.1.0" }
// Configure reads the options and adds the template function: it runs inside
// collage.New, before the templates are parsed.
func (p *Plugin) Configure(_ context.Context, host collage.ConfigHost) error {
opts, err := collage.PluginConfig(host, p.opts)
if err != nil {
return err
}
if opts.ReferrerPolicy == "" {
opts.ReferrerPolicy = DefaultReferrerPolicy
}
if !slices.Contains(policies, opts.ReferrerPolicy) {
return fmt.Errorf("%s: %q is not a referrer policy", Name, opts.ReferrerPolicy)
}
p.opts = opts
return host.AddTemplateFunc("securityContact", func() string { return p.opts.Contact })
}
// Init adds the middleware. A plugin in Config.Plugins wraps the application's
// own middleware, so a header the application sets wins over this one.
func (p *Plugin) Init(_ context.Context, host collage.Host) error {
return host.Use(func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Referrer-Policy", p.opts.ReferrerPolicy)
next.ServeHTTP(w, r)
})
})
}
func (p *Plugin) Shutdown(context.Context) error { return nil }
// OnBuildFinished checks what a static host will be told to send: the build
// asked the application for every file it wrote, and kept the headers.
func (p *Plugin) OnBuildFinished(_ context.Context, ev *collage.BuildFinishedEvent) error {
if p.opts.Contact == "" {
ev.Warn("", "no-contact", "no security contact is configured; set contact in plugins-config.json")
}
for _, f := range ev.Files {
if f.Kind != collage.BuiltPage || f.Status < 200 || f.Status > 299 {
continue // not a page, or not captured with a 2xx
}
if got := f.Headers.Get("Referrer-Policy"); got != p.opts.ReferrerPolicy {
ev.Error(f.Path, "referrer-policy", fmt.Sprintf("Referrer-Policy is %q, want %q", got, p.opts.ReferrerPolicy))
}
}
return nil
}
Where each part sits follows from the sections above:
- The options are checked in
Configure. A policy the header cannot hold failscollage.New, as an unknown key does, rather than going out on every response. - The middleware sets the header before calling
next. A plugin inConfig.Pluginswraps the application's own middleware, so a header the application's middleware or a handler sets afterwards replaces this one: the application has the last word. - The check reads
f.Headers, which a build fills in only because aBuildFinishedHookplugin is registered, so it costs a server nothing. A file the build did not capture, or that was not answered with a 2xx, is skipped. - A missing contact is a warning, a wrong header an error. The warning is listed in the report; the error fails the build with
collage.ErrBuildFindings, and the pages are written either way.
Registered in the application
The catalogue's plugins-config.json:
{
"acme/policy": {
"referrerPolicy": "same-origin",
"contact": "security@catalogue.example"
}
}
pluginConfig, err := collage.LoadPluginConfig("plugins-config.json")
if err != nil {
log.Fatal(err)
}
app, err := collage.New(&collage.Config{
Template: collage.TemplateConfig{Root: "templates"},
Plugins: []collage.Plugin{policy.New(policy.Options{})},
PluginConfig: pluginConfig,
})
if err != nil {
log.Fatal(err)
}
The footer template then shows the contact:
<footer>Found a vulnerability? Write to {{securityContact}}.</footer>
Its tests
package policy_test
import (
"context"
"errors"
"net/http"
"strings"
"testing"
"github.com/Elagoht/collage/pkg/collage"
"github.com/Elagoht/collage/pkg/collagetest"
"example.com/policy"
)
// newSite builds a one-page application with the plugin in it.
func newSite(t *testing.T, options ...collagetest.SiteOption) *collagetest.Site {
t.Helper()
return collagetest.NewSite(t, append([]collagetest.SiteOption{
collagetest.WithPlugins(policy.New(policy.Options{})),
collagetest.WithTemplates(map[string]string{"home.html": `<footer>{{securityContact}}</footer>`}),
}, options...)...)
}
func TestPolicy_SendsTheDefault(t *testing.T) {
res := newSite(t).Get("/").WantStatus(http.StatusOK)
if got := res.Header.Get("Referrer-Policy"); got != policy.DefaultReferrerPolicy {
t.Errorf("Referrer-Policy = %q, want %q", got, policy.DefaultReferrerPolicy)
}
}
func TestPolicy_ReadsItsConfiguration(t *testing.T) {
site := newSite(t, collagetest.WithPluginConfig(policy.Name,
`{"referrerPolicy": "no-referrer", "contact": "security@example.com"}`))
res := site.Get("/").WantStatus(http.StatusOK)
if got := res.Header.Get("Referrer-Policy"); got != "no-referrer" {
t.Errorf("Referrer-Policy = %q, want no-referrer", got)
}
if !strings.Contains(res.Body, "<footer>security@example.com</footer>") {
t.Errorf("no contact in %s", res.Body)
}
}
func TestPolicy_RefusesAnUnknownPolicy(t *testing.T) {
_, err := collagetest.TrySite(t,
collagetest.WithPlugins(policy.New(policy.Options{})),
collagetest.WithPluginConfig(policy.Name, `{"referrerPolicy": "never"}`),
)
if err == nil || !strings.Contains(err.Error(), "not a referrer policy") {
t.Errorf("err = %v, want the policy refused", err)
}
}
func TestPolicy_BuildFindsAnOverriddenHeader(t *testing.T) {
site := newSite(t,
collagetest.WithPluginConfig(policy.Name, `{"contact": "security@example.com"}`),
// The application's own middleware runs inside the plugin's, so its
// header replaces the plugin's.
collagetest.WithSetup(func(app *collage.App) error {
return app.Use(func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Referrer-Policy", "unsafe-url")
next.ServeHTTP(w, r)
})
})
}),
)
report, err := collage.Build(context.Background(), site.App, collage.BuildOptions{OutDir: t.TempDir()})
if !errors.Is(err, collage.ErrBuildFindings) {
t.Fatalf("Build: err = %v, want ErrBuildFindings", err)
}
var found bool
for _, f := range report.Findings {
if f.Rule == "referrer-policy" && f.Path == "/" && f.Level == collage.FindingError {
found = true
}
}
if !found {
t.Errorf("findings = %+v, want referrer-policy on /", report.Findings)
}
}
func TestPolicy_BuildWarnsWithoutAContact(t *testing.T) {
report, err := collage.Build(context.Background(), newSite(t).App, collage.BuildOptions{OutDir: t.TempDir()})
if err != nil {
t.Fatalf("Build: %v", err) // a warning fails nothing
}
if len(report.Findings) != 1 || report.Findings[0].Rule != "no-contact" || report.Findings[0].Level != collage.FindingWarning {
t.Errorf("findings = %+v, want one no-contact warning", report.Findings)
}
}
Each test covers one promise of the plugin:
| Test | What it shows |
|---|---|
SendsTheDefault | The zero Options is a working plugin |
ReadsItsConfiguration | The section reaches both the header and the template function |
RefusesAnUnknownPolicy | A bad value fails collage.New, and TrySite returns the error |
BuildFindsAnOverriddenHeader | The application's own middleware, registered with WithSetup, runs inside the plugin's and wins; the build reports the page and fails with ErrBuildFindings |
BuildWarnsWithoutAContact | A warning about the whole build has an empty Path and fails nothing |