ADR-server-001
AutoServerApp — write once, deploy anywhere
Context
Running a nodeset as a server requires writing three artifacts: a BaseNodeSet subclass, a separate ServerApp subclass (re-declaring all port schemas as PortSchema), and a ServerNodeSet config class. Port definitions are duplicated between PortDef (tool side) and PortSchema (server side). Adding a server-mode deployment to an existing local nodeset is disproportionately expensive — 2 extra files and ~100 lines for what is a deployment concern, not a logic change.
Decision
(1) AutoServerApp: A ServerApp subclass that introspects any BaseNodeSet's tools' input_ports/output_ports and auto-generates ServerFunction entries. Handles both BaseTool (via execute_as_node) and raw BaseCanvasNode tools (via execute). (2) auto_host CLI: python -m app.server.auto_host --file path/to/nodeset.py --class NodeSetClass --port 9200 — launches any nodeset as a plugin server. (3) Registry mode parameter: load_nodeset(name, mode="server") spawns an auto_host subprocess, fetches the manifest, generates proxy nodes — identical to YAML-based servers. (4) server_python attribute: Optional ClassVar on BaseNodeSet to specify a different Python interpreter for server mode. (5) API mode parameter: POST /api/components/nodesets/{name}/load?mode=server.
Alternatives
(a) Code generation from BaseNodeSet to ServerApp source files. (b) RPC framework (gRPC, msgpack) instead of REST. (c) Automatic environment detection to choose mode.
Rationale
Introspection at runtime is simpler than codegen and avoids generated files. REST stays consistent with the existing ServerApp manifest protocol — no new transport needed. The existing ServerNodeSet + manual ServerApp pattern is preserved for non-Python servers (C++, Rust) or custom protocols. Users write ONE BaseNodeSet class; deployment topology becomes a config decision, not a code decision.
Affected docs
nodesets.md, plugin-servers.md, tutorials/habitat-nodeset.md, architecture.md, glossary.md, roadmap.md, capabilities/isolated-runtime-environments.md, blueprint.md