Ana içeriğe geç

External plugins (any language)

An external plugin is a small HTTP server. Tenarium calls it to deliver events, run hooks and provisioners, authenticate and authorize requests, proxy HTTP routes, and act as a user directory or mailer. Everything the plugin registers behaves exactly like a built-in registration: subscriptions get cursors, retries and dead letters, and hooks can reject operations.

SDKs:

  • Go: pkg/extplugin. extplugin.Serve(p) runs any sdk.Plugin out of process.
  • TypeScript / JavaScript: sdks/typescript (Node 22.6+, no dependencies).
  • Python: sdks/python (3.9+, standard library only).

The three SDKs ship the same example plugins (guard, and directory for a user directory and mailer), and one conformance test checks all of them.

Configuring it in Tenarium​

Managed mode. Tenarium starts the process, assigns it an address and a secret, captures its output into Tenarium's log, restarts it with backoff if it crashes (calling init again with the same configuration), and stops it on shutdown:

- plugin: external
name: guard
config:
command: ["node", "plugins/guard.ts"] # or ["python3", "guard.py"], ["./my-plugin"]
dir: /opt/tenarium
env: {TENARIUM_API_URL: "http://localhost:8080", TENARIUM_API_KEY: "${GUARD_API_KEY}"}
inherit_env: [HTTPS_PROXY] # extra variables to pass through (see below)
config: {forbidden_prefix: "test-"} # passed to the plugin's init
startup_timeout: 30s
request_timeout: 30s

Remote mode. The plugin runs elsewhere (another container, a serverless function):

- plugin: external
name: billing
config:
url: http://billing-plugin:9000
secret: ${BILLING_PLUGIN_SECRET}
config: {...}

A managed process gets a minimal environment (PATH, HOME, locale and temp directories, and what Windows needs to start programs) plus env and anything listed in inherit_env. It does not see Tenarium's other environment variables, such as database credentials or other plugins' secrets.

Registrations are fixed when Tenarium starts. If a restarted plugin reports different registrations, Tenarium logs a warning; restart Tenarium to apply them.

TypeScript​

import { definePlugin, reject, serve } from "@tenarium/plugin-sdk";

const plugin = definePlugin<{ forbidden_prefix?: string }>({
manifest: { id: "guard", name: "Guard", version: "1.0.0" },
init(r) {
const prefix = r.config.forbidden_prefix ?? "test-";
r.hook("tenant.before_create", (req) => {
if (req.tenant.slug.startsWith(prefix)) reject(`slugs starting with "${prefix}" are not allowed`);
req.tenant.labels = { ...req.tenant.labels, guarded: "true" }; // mutations are kept
});
r.subscribe("audit", ["tenant.*"], async (event) => { /* at-least-once */ });
r.provisioner({ name: "crm", provision: async (t) => {}, deprovision: async (t) => {} });
r.authorizer("no-delete", (p, action) => (action === "tenants:delete" && !p.roles?.includes("admin") ? "deny" : "allow"));
r.route("GET /stats", (req) => ({ body: { caller: req.principal?.subject } }));
},
});

await serve(plugin);

Python​

from tenarium_plugin import Plugin, reject, serve

plugin = Plugin(id="guard", name="Guard", version="1.0.0")

@plugin.init
def init(r):
@r.hook("tenant.before_create")
def guard(req):
if req["tenant"]["slug"].startswith("test-"):
reject("test tenants are not allowed")

@r.subscribe("audit", ["tenant.*"])
def audit(event):
print(event["type"], event.get("tenantid"))

serve(plugin)

User directories and mailers​

An external plugin can provide the user directory and the mailer, like the built-in Keycloak, LDAP and SMTP plugins. Select its instance as usual:

plugins:
- plugin: external
name: corp-directory
config:
command: ["node", "directory.ts"]
users:
directory: corp-directory
mailer: corp-directory

All directory operations must be idempotent: Tenarium retries after timeouts, so a second create_user for the same email returns the existing ID and deleting a missing user succeeds. verify_password (password login) and send_invitation (the directory sends its own invitation email) are optional; Tenarium only uses them when the plugin implements them.

Raise or throw the SDK's error types so Tenarium can tell the cases apart: not found (unknown user), unsupported (for example set_password when passwords are managed by SSO; for send_invitation Tenarium then falls back to its own email), invalid credentials (verify_password rejected the password) and forbidden. Any other error is a plain failure.

import { definePlugin, InvalidCredentialsError, NotFoundError, serve } from "@tenarium/plugin-sdk";

const plugin = definePlugin({
manifest: { id: "corp-directory", name: "Corporate directory", version: "1.0.0" },
init(r) {
r.userDirectory({
createUser: async (user) => (await corp.upsert(user.email, user.name)).id, // returns the external ID
updateUser: async (user) => { if (!(await corp.update(user.external_id, user))) throw new NotFoundError(); },
deleteUser: async (user) => { await corp.remove(user.external_id); },
setPassword: async (user, password) => { await corp.setPassword(user.external_id, password); },
verifyPassword: async (user, password) => { if (!(await corp.check(user.email, password))) throw new InvalidCredentialsError(); },
});
r.mailer({ send: async (msg) => { await mail.send(msg.to, msg.subject, msg.text, msg.html); } });
},
});
await serve(plugin);
from tenarium_plugin import InvalidCredentials, NotFound, Plugin, Unsupported, serve

class CorpDirectory:
def create_user(self, user): return corp.upsert(user["email"], user.get("name")) # external ID
def update_user(self, user): ... # raise NotFound() for an unknown external_id
def delete_user(self, user): ...
def set_password(self, user, password): raise Unsupported("managed by SSO")
def verify_password(self, user, password): ... # optional; raise InvalidCredentials()
# send_invitation(self, user) is optional too

plugin = Plugin(id="corp-directory", name="Corporate directory", version="1.0.0")

@plugin.init
def init(r):
r.user_directory(CorpDirectory())
r.mailer(lambda message: smtp_send(message)) # or an object with send(message)

serve(plugin)

In Go, extplugin.Serve serves whatever r.UserDirectory and r.Mailer registered; return sdk.ErrNotFound, sdk.ErrUnsupported, sdk.ErrForbidden or extplugin.ErrInvalidCredentials (wrapped or not). See examples/directory.ts and examples/directory.py.

Passwords travel in the request body to the plugin, so in remote mode use HTTPS or a private network. While a managed plugin restarts, directory and mailer calls fail (and a password login fails) until it is back.

Protocol (version 1)​

Every request from Tenarium carries Authorization: Bearer <secret>; plugins must reject other requests. In managed mode the plugin listens on $TENARIUM_PLUGIN_ADDR and reads the secret from $TENARIUM_PLUGIN_SECRET. Bodies are JSON.

Proving identity (managed mode). Tenarium also passes $TENARIUM_PLUGIN_PROOF_KEY, which is never sent over the network. /init carries a random nonce, and the plugin must answer with "proof": hex(HMAC-SHA256(proof_key, nonce)). Without a valid proof Tenarium makes no calls to the plugin, so another local process that grabs the port while the plugin restarts cannot impersonate it. Secret and proof key are regenerated on every restart. The SDKs handle all of this.

A non-2xx response with {"error": "...", "code": "..."} is an error. code is optional; Tenarium maps it to the matching Go error and otherwise treats the error as a plain failure. It never interprets the HTTP status alone (a 404 without a code is an unknown endpoint, not a missing user), but the SDKs use the status shown:

codeGo errorStatus
not_foundsdk.ErrNotFound404
unsupportedsdk.ErrUnsupported501
forbiddensdk.ErrForbidden403
invalid_credentialsextplugin.ErrInvalidCredentials403
RequestBodyResponse
GET /health2xx when healthy
POST /init{"protocol": 1, "instance": "guard", "config": {...}}InitResponse (below)
POST /events/{subscription}CloudEvent2xx; anything else is retried
POST /hooks/{point}{"point", "tenant", "previous", "member"}{"reject": "reason"} or {"tenant": ..., "member": ...}
POST /provisioners/{name}/provisionTenant2xx
POST /provisioners/{name}/deprovisionTenant2xx
POST /authorize/{name}{"principal", "action", "resource"}{"decision": "allow" | "deny" | "abstain"}
POST /authenticate/{name}{"method", "path", "headers"}{"principal": ...}, {"no_credentials": true} or {"error": "..."}
POST /directory/create_user{"user": User}{"external_id": "..."} (non-empty)
POST /directory/update_user{"user": User}2xx
POST /directory/delete_user{"user": User}2xx
POST /directory/set_password{"user": User, "password": "..."}2xx
POST /directory/verify_password{"user": User, "password": "..."}2xx if the password is right (only if declared)
POST /directory/send_invitation{"user": User}2xx (only if declared)
POST /mailer/send{"to": [...], "subject", "text", "html", "tag"}2xx
ANY /routes/...proxied requestyour response

InitResponse:

{
"protocol": 1,
"manifest": {"id": "guard", "name": "Guard", "version": "1.0.0"},
"subscriptions": [{"name": "audit", "types": ["tenant.*"], "max_attempts": 10, "timeout_ms": 30000, "start_at_end": false}],
"hooks": [{"point": "tenant.before_create", "priority": 0}],
"provisioners": ["crm"],
"routes": ["GET /stats"],
"authenticators": [],
"authorizers": ["no-delete"],
"user_directory": {"name": "corp", "verify_password": true, "send_invitation": false},
"mailer": {"name": "corp-mail"}
}

user_directory and mailer are present only if the plugin offers them; their name defaults to the instance name. User is the user as in the REST API, with external_id set to the ID returned by create_user (Tenarium's own ID is id). Tenarium validates what it gets back: names and external IDs must be non-empty UTF-8 without control characters or surrounding spaces (at most 128 and 512 bytes), and response bodies are limited to 8 MiB.

Events carry the W3C trace context of the request that caused them, when tracing is on, in the optional CloudEvents attributes traceparent and tracestate.

Routes are proxied from /v1/plugins/{instance}/... to /routes/... after Tenarium has authenticated the caller. The client's Authorization header is replaced with the plugin secret, and the caller is passed as base64url-encoded JSON in X-Tenarium-Principal.

A plugin that needs to read Tenarium data calls the REST API. The Go SDK provides sdk.Host over REST when TENARIUM_API_URL (and TENARIUM_API_KEY) are set.