@@ -17,16 +17,45 @@ class Message;
1717
1818namespace SDMS {
1919
20- enum class MessageType { GOOGLE_PROTOCOL_BUFFER, STRING };
20+ /* *
21+ * @enum MessageType
22+ * @brief Discriminator for the payload type carried by an IMessage.
23+ */
24+ enum class MessageType {
25+ GOOGLE_PROTOCOL_BUFFER, // /< Payload is a google::protobuf::Message.
26+ STRING // /< Payload is a plain std::string.
27+ };
2128
2229/* *
23- * The message is on its way to a server this it is a REQUEST
24- * The message is on its way from a server then it is a RESPONSE
25- **/
30+ * @enum MessageState
31+ * @brief Indicates the directional state of a message relative to a server.
32+ *
33+ * - @c REQUEST — the message is traveling *toward* a server.
34+ * - @c RESPONSE — the message is traveling *from* a server.
35+ */
2636enum class MessageState { REQUEST, RESPONSE };
2737
28- enum class MessageAttribute { ID, KEY, STATE, CORRELATION_ID };
38+ /* *
39+ * @enum MessageAttribute
40+ * @brief Named keys for the core metadata attributes stored on a message.
41+ */
42+ enum class MessageAttribute {
43+ ID, // /< Unique message identifier.
44+ KEY, // /< Routing or lookup key.
45+ STATE, // /< Current MessageState (REQUEST or RESPONSE).
46+ CORRELATION_ID // /< Identifier used to correlate requests with responses.
47+ };
2948
49+ /* *
50+ * @brief Convert a MessageAttribute to its human-readable string form.
51+ *
52+ * @param[in] attribute The attribute to stringify.
53+ * @return A string representation, or @c "unsupported_toString_print" if
54+ * the attribute does not have a defined conversion.
55+ *
56+ * @note Only ID and KEY are currently supported; all other values fall
57+ * through to the unsupported case.
58+ */
3059inline const std::string toString (const MessageAttribute attribute) {
3160 if (attribute == MessageAttribute::ID) {
3261 return std::string (" ID"
@@ -37,67 +66,186 @@ inline const std::string toString(const MessageAttribute attribute) {
3766 }
3867}
3968
69+ // / @brief Well-known string constants used throughout the messaging layer.
4070namespace constants {
4171namespace message {
4272namespace google {
43- // / Supported dynamic arguments
73+ // / @brief Key for the serialized frame size of a protobuf message.
4474const std::string FRAME_SIZE = " frame_size"
45- const std::string PROTO_ID = " proto_id"
46- const std::string MSG_ID = " msg_id"
75+ // / @brief Key for the integral message-type identifier (e.g. envelope field number).
4776const std::string MSG_TYPE = " msg_type"
77+ // / @brief Key for the security/session context attached to a message.
4878const std::string CONTEXT = " context"
4979} // namespace google
5080} // namespace message
5181} // namespace constants
5282
83+ /* *
84+ * @class IMessage
85+ * @brief Abstract interface for all messages exchanged through the SDMS
86+ * messaging infrastructure.
87+ *
88+ * IMessage defines a uniform contract for:
89+ * - **Payload management** — carrying either a protobuf Message or a raw
90+ * string, with ownership semantics enforced by the implementation.
91+ * - **Routing** — an ordered list of route identifiers that determines
92+ * how a message is forwarded through the system.
93+ * - **Metadata** — core attributes (ID, KEY, STATE, CORRELATION_ID) plus
94+ * arbitrary named attributes with small-integer values.
95+ *
96+ * Implementations are expected to own the payload and manage its lifetime.
97+ * Callers retrieve payload data via non-owning raw pointers or copies.
98+ */
5399class IMessage {
54100public:
55-
101+ // / @brief Virtual destructor.
56102 virtual ~IMessage () {};
57- virtual bool exists (MessageAttribute) const = 0;
58- virtual bool exists (const std::string &) const = 0;
59103
60104 /* *
105+ * @brief Check whether a core metadata attribute has been set.
106+ *
107+ * @param[in] attribute The attribute to query.
108+ * @return @c true if the attribute is present on this message.
109+ */
110+ virtual bool exists (MessageAttribute attribute) const = 0;
111+
112+ /* *
113+ * @brief Check whether a named (dynamic) attribute has been set.
114+ *
115+ * @param[in] attribute_name The name of the dynamic attribute to query.
116+ * @return @c true if the named attribute is present on this message.
117+ */
118+ virtual bool exists (const std::string &attribute_name) const = 0;
119+
120+ /* ---------------------------------------------------------------------
61121 * Setters
62- **/
122+ *-------------------------------------------------------------------*/
123+
124+ /* *
125+ * @brief Set the message payload.
126+ *
127+ * The implementation must take ownership of the supplied payload. For
128+ * protobuf payloads the unique_ptr is moved in; for string payloads the
129+ * string is copied or moved. After this call the IMessage instance is
130+ * solely responsible for the lifetime of the payload data.
131+ *
132+ * @param[in] payload A variant holding either a protobuf message
133+ * (via @c std::unique_ptr) or a plain string.
134+ */
135+ virtual void setPayload (
136+ std::variant<std::unique_ptr<::google::protobuf::Message>,
137+ std::string>
138+ payload) = 0;
63139
64140 /* *
65- * Adding a payload should make a copy and store internally. It should
66- * Imply ownership of the payload and it's memory management.
67- **/
68- virtual void
69- setPayload (std::variant<std::unique_ptr<::google::protobuf::Message>,
70- std::string>) = 0 ;
141+ * @brief Append a single route to the end of the routing list.
142+ *
143+ * @param[in] route The route identifier to append.
144+ */
71145 virtual void addRoute (const std::string &route) = 0;
72146
147+ /* *
148+ * @brief Replace the entire routing list.
149+ *
150+ * @param[in] routes The new ordered list of route identifiers.
151+ */
73152 virtual void setRoutes (const std::list<std::string> &routes) = 0;
74153
75- virtual void set (MessageAttribute, const std::string &) = 0;
76- virtual void set (MessageAttribute, MessageState) = 0;
154+ /* *
155+ * @brief Set a core metadata attribute to a string value.
156+ *
157+ * Applicable to attributes such as @c ID, @c KEY, and
158+ * @c CORRELATION_ID.
159+ *
160+ * @param[in] attribute The attribute to set.
161+ * @param[in] value The string value to assign.
162+ */
163+ virtual void set (MessageAttribute attribute, const std::string &value) = 0;
77164
78- virtual void set (std::string attribute_name,
79- std::variant<uint8_t , uint16_t , uint32_t >) = 0;
80165 /* *
166+ * @brief Set a core metadata attribute to a MessageState value.
167+ *
168+ * Intended for the @c STATE attribute.
169+ *
170+ * @param[in] attribute The attribute to set (expected: @c STATE).
171+ * @param[in] state The MessageState value to assign.
172+ */
173+ virtual void set (MessageAttribute attribute, MessageState state) = 0;
174+
175+ /* *
176+ * @brief Set a named dynamic attribute to a small unsigned integer.
177+ *
178+ * Dynamic attributes are identified by string keys (e.g. the constants
179+ * in @c SDMS::constants::message::google).
180+ *
181+ * @param[in] attribute_name The name of the dynamic attribute.
182+ * @param[in] value The value, stored as one of uint8/16/32.
183+ */
184+ virtual void set (std::string attribute_name,
185+ std::variant<uint8_t , uint16_t , uint32_t > value) = 0;
186+
187+ /* ---------------------------------------------------------------------
81188 * Getters
82- **/
189+ *------------------------------------------------------------------- */
83190
84191 /* *
85- * The correlation ID is assigned to a message when it is created and is
86- *extremely important for tracing a message in the logs.
87- **/
192+ * @brief Retrieve a core metadata attribute.
193+ *
194+ * The returned variant holds a @c std::string for most attributes, or a
195+ * @c MessageState when querying @c STATE.
196+ *
197+ * @param[in] attribute The attribute to retrieve.
198+ * @return A variant containing either the string value or the
199+ * MessageState, depending on the attribute.
200+ */
88201 virtual std::variant<std::string, MessageState>
89- get (MessageAttribute) const = 0 ;
202+ get (MessageAttribute attribute) const = 0 ;
203+
204+ /* *
205+ * @brief Get a const reference to the ordered routing list.
206+ *
207+ * @return Const reference to the internal route list.
208+ */
90209 virtual const std::list<std::string> &getRoutes () const = 0;
210+
211+ /* *
212+ * @brief Get a mutable reference to the ordered routing list.
213+ *
214+ * @return Mutable reference to the internal route list.
215+ */
91216 virtual std::list<std::string> &getRoutes () = 0;
217+
218+ /* *
219+ * @brief Return the payload type carried by this message.
220+ *
221+ * @return The MessageType discriminator.
222+ */
92223 virtual MessageType type () const noexcept = 0;
224+
225+ /* *
226+ * @brief Retrieve a named dynamic attribute.
227+ *
228+ * @param[in] attribute_name The name of the dynamic attribute.
229+ * @return The value stored as a @c uint8_t, @c uint16_t, or @c uint32_t
230+ * variant.
231+ */
93232 virtual std::variant<uint8_t , uint16_t , uint32_t >
94233 get (const std::string &attribute_name) const = 0 ;
95234
96- // / Note not returning a unique_ptr but a raw pointer because the message
97- // should stil have ownership of the object.
235+ /* *
236+ * @brief Retrieve a non-owning handle to the message payload.
237+ *
238+ * Ownership remains with the IMessage instance. For protobuf payloads
239+ * a raw pointer is returned (not a @c unique_ptr) to make this
240+ * explicit. For string payloads the string is returned by value (copy).
241+ *
242+ * @return A variant holding either a non-owning
243+ * @c google::protobuf::Message* or a @c std::string.
244+ */
98245 virtual std::variant<google::protobuf::Message *, std::string>
99246 getPayload () = 0 ;
100247};
101248
102249} // namespace SDMS
250+
103251#endif // MESSAGE_HPP
0 commit comments