Project plugins (experimental)

A project plugin is an ordinary program, usually Go, that the engine starts, supervises and calls when a declared endpoint reaches a plugin step. It is for the logic an endpoint’s YAML cannot express: a rule with branches, a calculation, a partner’s API that needs an SDK. The endpoint keeps everything else: its access rule, input validation, CSRF, rate limits, audit, caching and response shape. The plugin receives the endpoint’s validated input and returns data; it never sees the request.

A plugin is not an extension. It runs out of process, so it needs no matching Go toolchain, and a crash costs the endpoints that use it rather than the site. It cannot add template functions or routes.

A minimal pluginCopy Anchor Link

A market calendar whose rules have branches in them: every Thursday except over Christmas, plus the last Saturday of every month but December.

// plugin/main.go
package main

import (
	"fmt"
	"time"

	plugin "github.com/wrux/meridian-plugin"
)

func main() {
	plugin.Serve(plugin.Handlers{
		Endpoints: map[string]plugin.EndpointFunc{"market-days": marketDays},
	})
}

type Day struct {
	Date string `json:"date"`
	Kind string `json:"kind"`
}

func marketDays(ctx plugin.Context, r plugin.Request) (plugin.Response, error) {
	from := time.Now().UTC().Truncate(24 * time.Hour)
	if s := r.Input.String("from"); s != "" {
		d, err := time.Parse(time.DateOnly, s)
		if err != nil {
			return plugin.Response{}, fmt.Errorf("from is a date such as 2026-10-08, got %q", s)
		}
		from = d
	}
	count := 4
	if f, ok := r.Input.Float("count"); ok {
		count = min(max(int(f), 1), 12)
	}
	var out []Day
	for d := from; len(out) < count; d = d.AddDate(0, 0, 1) {
		christmas := (d.Month() == time.December && d.Day() >= 24) || (d.Month() == time.January && d.Day() == 1)
		switch {
		case d.Weekday() == time.Thursday && !christmas:
			out = append(out, Day{d.Format(time.DateOnly), "market"})
		case d.Weekday() == time.Saturday && d.Month() != time.December && d.AddDate(0, 0, 7).Month() != d.Month():
			out = append(out, Day{d.Format(time.DateOnly), "farmers-market"})
		}
	}
	ctx.Log.Info("market days", "from", from.Format(time.DateOnly), "count", len(out))
	return plugin.Data(out), nil
}

Declare it for the site, with the handlers an endpoint may call:

# config/sites/<site>/plugins.yaml
plugins:
  markets:
    command: bin/markets          # the binary, relative to the project
    build: plugin                 # the Go program engine-dmo plugin build compiles to it
    endpoints: [market-days]      # the handlers a plugin step may call
    timeout: 2s
    concurrency: 4
    memory: 256MB
    circuit_breaker: { failures: 5, window: 1m, cooldown: 30s }

Call it from an endpoint:

# config/sites/<site>/endpoints.yaml
endpoints:
  - key: market-days
    path: /api/market-days.json
    methods: [get]
    access: public
    input:
      from:  { type: date, from: query }
      count: { type: number, from: query, min: 1, max: 12 }
    steps:
      - plugin: { name: markets, handler: market-days, with: { from: $from, count: $count }, as: days }
    respond:
      json: { from: days, fields: [date, kind] }
    cache: 1h

Build it, then check:

engine-dmo plugin build --project .
engine-dmo check --fix --project .    # writes the endpoint's id, then checks everything

GET /api/market-days.json?count=3 answers the projection of what the handler returned, with only date and kind exposed.

plugins.yamlCopy Anchor Link

One file per site, config/sites/<site>/plugins.yaml, with a map of plugins by key. A key is lowercase letters, digits and hyphens, at most 63 characters.

The plugin stepCopy Anchor Link

- plugin: { name: markets, handler: market-days, with: { from: $from, count: $count }, as: days }

The step takes only these four keys. engine-dmo check refuses a plugin that is not declared, a handler the plugin is not granted, and anything else, each with a suggestion where one is close. respond: json: projects the result as for a query or source step, exposing only the fields it lists.

Any failure of the call (the binary missing, the process down, the breaker open, every slot busy, a timeout, or the handler’s own error) fails the endpoint with HTTP 502 and the message “This information is not available just now. Try again in a moment.”, as a failing upstream source does. The handler’s error and any panic stack go to the engine’s log, never to the visitor.

Writing a plugin in GoCopy Anchor Link

Require github.com/wrux/meridian-plugin in the plugin’s own go.mod. It uses the standard library only, and the plugin may use any Go version, since the contract is messages, not shared code.

// go.mod
module example.com/markets-plugin

go 1.26.0

require github.com/wrux/meridian-plugin v0.0.0-00010101000000-000000000000

replace github.com/wrux/meridian-plugin => ../meridian-plugin

While the module is not published to a Go module proxy, point a replace directive at your copy of its source. A release does not carry that source (it is in the Meridian source repository, libs/plugin), so a Go plugin needs it from Cherwell Studio. A plugin in another language needs only the protocol, which this page describes.

A panic in a handler is recovered and returned with its stack; the engine logs it and the plugin keeps running. Handlers are plain functions, so you test them with go test and nothing else running.

Building, pinning and deployingCopy Anchor Link

engine-dmo plugin build [key...] [--site key] --project .

For each plugin with a build: directory, this runs go build -trimpath -o <command> . in that directory (Go must be on PATH) and prints the binary’s sha256. When plugins.yaml pins a different digest, it says so and prints the one to set. engine-dmo check warns when a declared binary is not built (the binary bin/markets is not built, so its steps would fail with 502).

The binary runs on the machine the engine runs on, so build it for that operating system and architecture: in a container image, build it in the image build and copy it to the path command names. Pin sha256 in production so a changed binary is refused rather than run.

How the engine runs a pluginCopy Anchor Link

• Started on first use, per site and plugin, and replaced when its declaration (command, arguments, pin, environment or memory) changes.
• Environment: PATH, HOME, TMPDIR, USER, LANG, LC_ALL, SSL_CERT_FILE and SSL_CERT_DIR from the engine’s environment if set, the env: you declared, and MERIDIAN_PLUGIN_SOCKET, MERIDIAN_PLUGIN_PROTOCOL, MERIDIAN_PLUGIN_NAME and MERIDIAN_PLUGIN_LIFELINE. Nothing else of the engine’s environment, its secrets included, is passed.
• Working directory: the project directory.
• Start: it must answer the handshake within 10 seconds, naming protocol 0 and serving every handler endpoints: grants.
• Health: checked every 10 seconds; a process that fails twice is killed and restarted.
• Restarts: a process that exits is restarted with a backoff from 100ms doubling to 30s; one that ran for a minute resets it.
• Lifeline: with MERIDIAN_PLUGIN_LIFELINE=stdin the engine holds the plugin’s standard input open; when it closes, the engine has gone and the plugin exits (plugin.Serve does this for you).
• Logs: the plugin writes JSON records to standard error, which the engine reads into its own log.

The protocol, version 0Copy Anchor Link

For a plugin in another language. JSON over HTTP/1.1 on the Unix socket at the path in MERIDIAN_PLUGIN_SOCKET:

SecurityCopy Anchor Link

A plugin is not a sandbox. It runs as a normal process with the engine user’s privileges and can read what that user can read. The engine contains it (a timeout per call, bounded concurrency, restarts, a circuit breaker, a memory limit where the platform allows, no inherited secrets) but does not isolate it. Treat plugin code as trusted, like your templates: review it, build it yourself, and pin it.

engine-cms behaves the same.