testplugin

Overview ¶

Command testplugin is a plugin that exercises every part of the contract and does nothing useful.

That is the point. A host needs something honest to test against: something that answers when it should, reports what it spent, is handed a credential and proves it received one without printing it, and — on request — crashes, hangs past its deadline, or writes rubbish to standard error. A real plugin cannot be asked to do those things on demand, and a fake one built inside the host's own tests proves only that the host agrees with itself.

It is also the shortest complete example of writing a plugin, so it is worth reading before the first real one.

What it answers ¶

Three kinds, spelled with whatever name the host installed it under:

<name>.echo    answers with what it was asked, who asked, and how deep
<name>.ask     asks whatever the payload names — {"kind": ..., "payload": ...} — and relays the answer
<name>.chain   asks itself the same question, until the host refuses; answers with how deep it got

The last two are how a host proves its broker: one plugin reaching another through it, and a loop being stopped rather than run.

Making it misbehave ¶

Behaviour comes from behaviour.json beside the binary, read fresh on every call so a test can change its mind mid-flight. A missing file is a plugin that behaves.

{
  "crash_at": "answer",   // "start", "settings", "notify" or "answer"
  "exit_code": 3,         // what it exits with when it crashes
  "hang": "10s",          // how long to ignore the deadline for
  "leak_secret": true,    // print the credential to standard error
  "leak_database": true,  // print its own connection string to standard error
  "stderr": "...",        // print this to standard error at startup
  "spend": 1200           // tokens to report having spent on each call
}