Writing Go plugins
Skeleton
package quota
import (
"context"
"encoding/json"
"github.com/AimTune/tenarium/pkg/sdk"
)
func init() {
sdk.Register("seat-guard", func() sdk.Plugin { return &Plugin{} })
}
type Config struct {
MaxTrialTenantsPerDomain int `json:"max_trial_tenants_per_domain"`
}
type Plugin struct {
cfg Config
host sdk.Host
}
func (p *Plugin) Manifest() sdk.Manifest {
return sdk.Manifest{
ID: "seat-guard",
Name: "Seat guard",
Version: "1.0.0",
// Optional: validated before Init, with errors pointing at the bad field.
ConfigSchema: json.RawMessage(`{"type":"object","properties":{"max_trial_tenants_per_domain":{"type":"integer","minimum":1}},"additionalProperties":false}`),
}
}
func (p *Plugin) Init(ctx context.Context, r sdk.Registrar) error {
if err := r.Config(&p.cfg); err != nil { // strict: unknown keys are errors
return err
}
p.host = r.Host()
r.Hook(sdk.HookBeforeMemberAdd, p.checkSeats)
r.Subscribe("welcome", sdk.EventFilter{Types: []string{sdk.EventMemberAdded}}, p.sendWelcome,
sdk.WithMaxAttempts(20))
return nil
}
Optional interfaces:
sdk.Stopper:Stop(ctx)on shutdown (close connections, flush buffers).sdk.HealthChecker:Health(ctx), reported by/readyz.
Rules of the road
- Event handlers must be idempotent. Delivery is at least once, so deduplicate on
e.IDif a side effect must not happen twice. Return an error to retry; afterMaxAttemptsthe event is dead-lettered. - Provisioners must be idempotent and tolerate unknown tenants.
Provisionmay run again after a crash or a retry.Deprovisionmay run for a tenant that was never provisioned (for example when the plugin's scope changed). - Hooks must be fast. They run on the request path. Return
sdk.Reject("...")for a business rule violation (the client gets 422 with your message); any other error is a 500. - Registrations happen only in
Init. Calling the registrar later panics. - Check access in routes. Routes are reachable by any caller allowed
plugins:route, including tenant-scoped ones. Before returning tenant data, callr.Host().Authorize(ctx, sdk.ActionTenantsRead, sdk.Resource{Type: "tenant", ID: t.ID, TenantID: t.ID}). - Use the caller.
sdk.PrincipalFrom(ctx)returns the API caller in hooks, routes and authorizers. Event handlers and provisioners run asynchronously and have no caller; use the event'sActorfield instead.
Reading data
t, err := r.Host().GetTenant(ctx, "acme") // ID or slug
ent, err := r.Host().Entitlements(ctx, t.ID) // plan + overrides
if limit, ok := ent.Limit("projects"); ok && used >= limit { ... }
page, err := r.Host().ListTenants(ctx, afterID, 500)
Decode event payloads with the matching type: sdk.TenantEventData, sdk.MemberEventData,
sdk.PlanEventData, sdk.UsageEventData, sdk.UsagePeriodData or sdk.UserEventData. The
JSON Schema of every event type's data is in the event schema registry.
Tenant events carry Tenant.Region, PlanRevision and AddOns; tenant.region_changed has
the old region in Previous.Region.
Changing state
The host can also change tenants. These calls run hooks and emit events like API calls, with
the plugin instance as the actor (plugin:<instance>):
t, err := r.Host().SuspendTenant(ctx, tenantID, "billing: invoice overdue")
t, err = r.Host().ResumeTenant(ctx, tenantID)
t, err = r.Host().SetTenantPlan(ctx, tenantID, "pro")
value, err := r.Host().RecordUsage(ctx, tenantID, "api_calls", 1) // enforces limits
Billing plugins (stripe, chargebee, paddle) use these to drive the tenant lifecycle from
webhooks.
Reloading configuration
A plugin can accept a changed config without a restart (SIGHUP or POST /v1/admin/reload,
see reloading the configuration) by implementing
the optional sdk.Reconfigurer:
type Reconfigurer interface {
Reconfigure(ctx context.Context, decode func(v any) error) error
}
decode decodes the new configuration exactly like Registrar.Config, after the manifest's
ConfigSchema accepted it. Returning an error keeps the old configuration and reports the
instance under failed. Subscriptions, hooks, routes and filters registered in Init cannot
change this way; settings read at run time (endpoints, credentials, templates, timeouts) can.
Without the interface, any config change of the instance is reported as restart_required.
The pattern used by the built-in smtp and webhook plugins: build a fresh, fully configured
copy, validate it, then swap it in atomically, so deliveries in flight finish with the old
settings and none ever sees a half-applied one:
type Plugin struct {
cfg Config
next atomic.Pointer[Plugin] // configuration applied by Reconfigure
}
func (p *Plugin) current() *Plugin {
if n := p.next.Load(); n != nil {
return n
}
return p
}
func (p *Plugin) Reconfigure(_ context.Context, decode func(v any) error) error {
n := &Plugin{}
if err := decode(&n.cfg); err != nil {
return err
}
if !slices.Equal(n.cfg.Events, p.cfg.Events) { // fixed by the subscription made in Init
return errors.New("events take effect after a restart")
}
if err := n.validate(); err != nil {
return err
}
p.next.Store(n)
return nil
}
Handlers then read their settings through p.current().
Testing
pkg/sdk/sdktest gives you a recording registrar and an in-memory host:
func TestRejectsTrials(t *testing.T) {
ctx := context.Background()
reg := sdktest.NewRegistrar(map[string]any{"max_trial_tenants_per_domain": 1})
if err := (&Plugin{}).Init(ctx, reg); err != nil {
t.Fatal(err)
}
tenant := reg.HostImpl.AddTenant(sdk.Tenant{Slug: "acme", Name: "Acme"})
err := reg.RunHooks(ctx, &sdk.HookRequest{Point: sdk.HookBeforeMemberAdd, Tenant: &tenant, Member: &sdk.Member{...}})
...
err = reg.Deliver(ctx, "welcome", sdktest.MemberEvent(sdk.EventMemberAdded, member))
}
Shipping it
As part of a custom binary (recommended for Go plugins):
go install github.com/AimTune/tenarium/cmd/tenarium-build@latest
tenarium-build -o tenarium --with github.com/acme/seat-guard=../seat-guard # local checkout
This generates a main that blank-imports plugins/all plus your modules (use -no-builtins
to leave out the built-in plugins) and builds it. You can also write that main.go yourself:
package main
import (
"github.com/AimTune/tenarium/pkg/server"
_ "github.com/AimTune/tenarium/plugins/all"
_ "github.com/acme/seat-guard"
)
func main() { server.Main() }
As an external process, without rebuilding Tenarium:
func main() { log.Fatal(extplugin.Serve("a.Plugin{})) }
See External plugins.