processmodule-demo

Overview ¶

Package main is the processmodule-demo: a minimal but real third-party module that speaks the moduleproto protocol over stdio.

It is the canonical example of a process-isolated module (see framework/docs/content/process-modules.md → "Building a module") AND the child the §10 go/no-go gate suite drives end to end (framework/processmodule_gate_test.go). It depends only on the gofastr module's moduleproto package + the standard library.

On start it opens a moduleproto.Codec over stdin/stdout, constructs a moduleproto.Peer in the child role, registers handlers for every host → module method it serves, calls [Peer.Start], and blocks on [Peer.Done] (clean EOF on stdin). Its surface:

• module.handshake → echoes the host's expected identity (instance_id + desired_generation) and surface digest; a mismatch would be terminal.
• module.ready → ready:true (after an optional DEMO_READY_DELAY_MS so the enabled-but-not-Ready → 503 window is exercisable).
• module.health → ok:true, zero in-flight.
• module.http → three routes:
• "hello" (GET /hello) → a ui.node.v1 body: a small valid tree.
• "tree" (GET /tree) → the SAME tree as a json body, so the host can run the closed ui.node.v1 validator over the exact bytes the child would have rendered (the proxy's render path is deferred; this route makes the validator reachable from a test).
• "items" (GET /items) → makes a REVERSE host.entity.query for the entity named by DEMO_QUERY_ENTITY and returns the result as json, proving the reverse broker path end to end.
• module.drain → zero in-flight.
• module.tool.list / module.tool.call → one tool ("ping") whose call body also does a reverse host.entity.query (proves the tool → broker path).

Misbehave knobs (env), each driving one adversarial gate test:

• DEMO_CRASH_ON=<routeID> → os.Exit(1) mid module.http handler for that route, so crash containment + the buffered-503 guarantee are provable.
• DEMO_FORGE_DATAFUI=1 → /hello and /tree return a tree that tries to smuggle a data-fui-rpc prop; the closed validator must whole-tree reject it (the host never renders a forged runtime attribute).
• DEMO_EXTRA_TOOL=1 → module.tool.list returns a tool the descriptor did not approve, so the handshake byte-equality quarantine fires (terminal Failed, no restart loop).
• DEMO_READY_DELAY_MS=<n> → module.ready blocks ~n ms before reporting ready, widening the enabled-but-not-Ready 503 window on demand.
• DEMO_QUERY_ENTITY=<name> → entity the /items route + the ping tool reverse-query (default "articles").