Adding a Language to Octonode (Archived)

The active release supports TypeScript only. This historical guide is retained for a future runtime-expansion project and is not a supported release surface.

Octonode's promise is that a node can be written in any language. That works because a node is just a program that honors the IPC protocol: read one JSON request from stdin, write one JSON response to stdout. There is no required framework — a "thin runner" of ~50–150 lines is enough.

This guide shows what a thin runner must do.

The four things a runner must do

1. Read the entire request envelope from stdin and parse it as JSON.
2. Dispatch on type:
   • "describe" → emit a manifest envelope describing the node (id, language, inputs/outputs JSON Schema, optional icon).
   • "invoke" → run the handler with inputs + context, emit a result.
3. Isolate stdout: write only the response envelope to stdout. Send all logging to stderr.
4. Never crash on a handled failure: convert exceptions into a status:"error" result envelope with an appropriate code and retryable flag.

Optional but recommended: validate inputs against the declared JSON Schema before running, and outputs after. A ~80-line subset validator (type, required, properties, items, enum) is enough. A minimal runner may skip validation.

Reference implementations

Verifying your runner

Drive it with the engine exactly as any built-in node:

# invoke
octonode run-node "<your command>" --input '{"name":"Ada"}'
# => {"greeting":"Hello, Ada"}

# discovery
octonode run-node "<your command>" --describe
# => the manifest JSON

If both work, your language is a first-class Octonode citizen. Set the manifest's "language" field to your language's name so octonode scan (Phase 3) can record it in .octonode.