dfx::Core::ControlMessage Class Reference

Control-plane message (command + params). More...

#include <dfx-core/messages/ControlMessage.hpp>

Inheritance diagram for dfx::Core::ControlMessage:

Collaboration diagram for dfx::Core::ControlMessage:

Public Member Functions
int	version () const noexcept
	Protocol version of this control message (default: 1).
std::string const &	command () const noexcept
	Command name carried by this message.
nlohmann::json const &	params () const noexcept
	JSON parameters carried by this message (may be null).
nlohmann::json	toJson () const
	Serialize this control message to JSON.
Kind	kind () const override
	This message belongs to the control-plane connectivity domain.
MessagePtr	clone () const override
	Clone this message (deep copy).
Public Member Functions inherited from dfx::Core::Message
	DISABLE_COPY_AND_MOVE (Message)
	Messages are non-copyable and non-movable.
virtual	~Message ()
	Virtual destructor.
template<typename Clock = std::chrono::steady_clock> requires std::chrono::is_clock_v<Clock>
std::chrono::time_point< Clock, std::chrono::microseconds >	timestampToTimePoint () const noexcept
	Convert timestamp() into a time_point of the given clock type.
void	addToPathTaken (std::string path)
	Append one hop to the message path trace.
template<DerivedFromMessage T>
bool	is () const noexcept
	Check whether this message is of a given derived type.
template<DerivedFromMessage T>
T &	as () noexcept
	Cast this message to a derived type (unchecked).
template<DerivedFromMessage T>
T const &	as () const noexcept
	Cast this message to a derived type (unchecked).
Utils::UUID const &	uuid () const noexcept
	Unique identifier of this message instance.
Utils::UUID const &	parentUuid () const noexcept
	UUID of the parent message if created from one, otherwise default UUID value.
std::vector< std::string > const &	pathTaken () const noexcept
	Sequence of "node.port" hops this message has traversed.
std::chrono::microseconds	timestamp () const noexcept
	Construction timestamp in microseconds since timestampClock epoch. This is not "wall clock time" unless timestampClock is CLOCK_REALTIME.
bool	hasMimeType () const noexcept
	Whether the message carries an explicit MIME type.
MimeType	mimeType () const noexcept
	Get the message MIME type. If no explicit MIME type is set, returns dfx::Core::MimeType::OctetStream.
void	setMimeType (MimeType mimeType)
	Set the message MIME type.
void	resetMimeType ()
	Clear the explicit MIME type (message then defaults to octet-stream).

Protected Member Functions
void	cloneFromBase (Message const &base) override
	Copy base and derived state from base into this instance.
	ControlMessage (MessagePtr const &parent=nullptr)
	Construct an empty control message, optionally inheriting from a parent.
	ControlMessage (std::string command, nlohmann::json params={}, int version=1, MessagePtr const &parent=nullptr)
	Construct a control message with command, params and version.
Protected Member Functions inherited from dfx::Core::Message
	Message (MessagePtr const &parent=nullptr)
	Construct a message, optionally inheriting state from a parent message.
	Message (MimeType mimeType, MessagePtr const &parent=nullptr)
	Construct a message with an explicit MIME type, optionally inheriting from a parent.

Friends
class	Message

Additional Inherited Members
Static Public Member Functions inherited from dfx::Core::Message
template<DerivedFromMessage T, typename ... Args>
static std::unique_ptr< T >	create (Args &&... args)
	Convenience allocator for derived message types.
Static Public Attributes inherited from dfx::Core::Message
static clockid_t	timestampClock
	Clock used by the constructor to capture timestamps.

Detailed Description

Control-plane message (command + params).

Kind and MIME type

• kind() is always dfx::Core::Kind::Control.
• Both constructors force the base dfx::Core::Message MIME type to dfx::Core::MimeType::DfxControl.

This makes control messages unambiguous on the wire and allows ports/runtime to treat them separately from data-plane payloads.

Versioning

The version() field exists to support protocol evolution between producers and consumers. The default version is 1.

JSON representation

toJson() produces an object of the form:

{
  "version": 1,
  "command": "some_command",
  "params":  { ... }
}

If the stored params value is JSON null, toJson() normalizes it to an empty JSON object ({}) in the output.

Cloning

clone() creates a new ControlMessage and copies:

• all base fields via Message::cloneFromBase(...)
• _version, _command, and _params

Note

In dfx, fan-out delivery relies on cloning so each channel gets an independent message instance.

Constructor & Destructor Documentation

ControlMessage() [1/2]

dfx::Core::ControlMessage::ControlMessage ( MessagePtr const & parent = nullptr )

protected

Construct an empty control message, optionally inheriting from a parent.

The base constructor always sets the MIME type to MimeType::DfxControl.

Parameters

parent

Optional parent message whose UUID is inherited.

ControlMessage() [2/2]

dfx::Core::ControlMessage::ControlMessage ( std::string command, nlohmann::json params = {}, int version = 1, MessagePtr const & parent = nullptr )

protected

Construct a control message with command, params and version.

The base constructor always sets the MIME type to MimeType::DfxControl.

Parameters

command	Command name.
params	JSON parameters (moved into the message).
version	Protocol version (default: 1).
parent	Optional parent message whose UUID is inherited.

Member Function Documentation

clone()

MessagePtr dfx::Core::ControlMessage::clone ( ) const

overridevirtual

Clone this message (deep copy).

The clone copies the base state and duplicates the version, command and params JSON.

Returns

Newly allocated message of the same dynamic type.

Implements dfx::Core::Message.

cloneFromBase()

void dfx::Core::ControlMessage::cloneFromBase ( Message const & base )

overrideprotectedvirtual

Copy base and derived state from base into this instance.

Copies the base fields via Message::cloneFromBase(base) then copies:

• version
• command
• params

Reimplemented from dfx::Core::Message.

command()

std::string const & dfx::Core::ControlMessage::command ( ) const

inlinenoexcept

Command name carried by this message.

kind()

Kind dfx::Core::ControlMessage::kind ( ) const

inlineoverridevirtual

This message belongs to the control-plane connectivity domain.

Implements dfx::Core::Message.

params()

nlohmann::json const & dfx::Core::ControlMessage::params ( ) const

inlinenoexcept

JSON parameters carried by this message (may be null).

toJson()

nlohmann::json dfx::Core::ControlMessage::toJson

(

)

const

Serialize this control message to JSON.

If params() is null, this returns an empty object for "params".

Output format:

• "version": integer
• "command": string
• "params" : object (never null in the returned JSON)

Returns

JSON object representing this message.

version()

int dfx::Core::ControlMessage::version ( ) const

inlinenoexcept

Protocol version of this control message (default: 1).

---

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

• lib/dfx-core/messages/ControlMessage.hpp