dfx::Server::UnixRouter Class Reference

JSON command router for the Unix domain socket control protocol. More...

#include <dfx-server/UnixRouter.hpp>

Public Types
using	Handler = std::move_only_function<bool (UnixSessionPtr, nlohmann::json, std::string)>
	Handler type for a routed command.

Public Member Functions
	UnixRouter ()
	Construct the router and register the request envelope schema.
	~UnixRouter ()
	Destructor.
void	registerCommand (std::string command, Handler handler, bool allowOverride=false)
	Register a command handler.
bool	deregisterCommand (std::string_view command)
	Deregister a command handler.
bool	isRegistered (std::string_view command) const
	Check whether a command is registered.
bool	route (UnixSessionPtr session, nlohmann::json json)
	Validate and route a JSON request to the appropriate command handler.

Detailed Description

JSON command router for the Unix domain socket control protocol.

UnixRouter is the dispatch point for the Unix control plane (used by UnixServer and UnixSession).

It receives a decoded JSON request envelope, validates it against an internal schema, extracts the command name, and forwards execution to a registered handler.

The router also implements protocol-level guard rails:

• request envelope validation (required fields, types),
• protocol version gating (currently only version 1 is accepted),
• unknown command handling with a helpful "possible commands" list.

Request envelope format

The router expects a JSON object with the following shape:

• version (integer, required): protocol version. Must be 1.
• command (string, required): command name used to select the handler.
• params (object, optional): command parameters. Defaults to {} if missing.
• id (string, optional): request identifier echoed back in responses.

Example:

{
  "version": 1,
  "command": "list_instances",
  "params": { "verbose": true },
  "id": "42"
}

Handler contract

Handlers are registered per command name and have the signature: bool handler(UnixSessionPtr session, nlohmann::json params, std::string id).

• params is moved into the handler (so it can be consumed efficiently).
• id is the request id string (may be empty).
• The handler is responsible for producing a reply through the session (session->reply(...) / session->replyError(...)).

The boolean return value is propagated back to the caller of route() and is used by the session/server to decide whether the connection should remain alive after handling the request.

Note

If the envelope is invalid, version is unsupported, or the command is unknown, the router itself sends an error reply via the provided session and returns true (i.e. the request was handled, and the session will continue).

Member Typedef Documentation

Handler

using dfx::Server::UnixRouter::Handler = std::move_only_function<bool (UnixSessionPtr, nlohmann::json, std::string)>

Handler type for a routed command.

Parameters

session	The session that sent this request.
params	The parameters of the command.
id	The optional id that needs to be passed down to reply() / replyError()

Returns

A boolean forwarded by route() to the caller (typically used as a "keep session alive" decision).

Constructor & Destructor Documentation

UnixRouter()

dfx::Server::UnixRouter::UnixRouter

(

)

Construct the router and register the request envelope schema.

The constructor registers the JSON schema used to validate incoming request envelopes.

~UnixRouter()

dfx::Server::UnixRouter::~UnixRouter

(

)

Destructor.

Member Function Documentation

deregisterCommand()

bool dfx::Server::UnixRouter::deregisterCommand

(

std::string_view

command

)

Deregister a command handler.

Removes both the handler and the command from the internal "possible commands" list.

Parameters

command

Command name to remove.

Returns

True if the command existed and was removed, false otherwise.

isRegistered()

bool dfx::Server::UnixRouter::isRegistered

(

std::string_view

command

)

const

Check whether a command is registered.

Parameters

command

Command name.

Returns

True if a handler is registered for this command.

registerCommand()

void dfx::Server::UnixRouter::registerCommand	(	std::string	command,
		Handler	handler,
		bool	allowOverride = false )

Register a command handler.

By default, registering an already-registered command is considered a bug and triggers an assertion. Set allowOverride to true to explicitly replace a handler (useful for tests or for composing routers in layers).

The command name is also recorded in an internal list used to produce the "Possible commands are: [...]" diagnostics for unknown commands.

Parameters

command	Command name as used in the request envelope ("command").
handler	Handler to invoke when the command is routed.
allowOverride	If true, replaces an existing handler for the same command.

route()

bool dfx::Server::UnixRouter::route	(	UnixSessionPtr	session,
		nlohmann::json	json )

Validate and route a JSON request to the appropriate command handler.

Routing steps:

1. Extract id if present (string), otherwise use an empty id.
2. Validate the envelope against the registered schema.
   • On failure: send replyError(errors, id) and return true.
3. Check version == 1.
   • Otherwise: send replyError("Unknown version ...", id) and return true.
4. Look up the handler using command.
   • If missing: send an error listing known commands and return true.
5. Extract params (defaults to {}) and invoke the handler.

Parameters

session	Session that originated the request (used to send replies).
json	Parsed JSON request envelope.

Returns

The handler's boolean return value, or true if the router handled the request by replying with a protocol error (invalid envelope/version/unknown command).

---

The documentation for this class was generated from the following file:

• lib/dfx-server/UnixRouter.hpp