Functions for creating, serializing, and managing inter-event messages exchanged between yunos.
Source: kernel/c/root-linux/src/msg_ievent.h
iev_create()¶
Creates an inter-event object for use within a yuno. Adds the
__iev_event__ field to kw.
json_t *iev_create(
hgobj gobj,
gobj_event_t event,
json_t *kw // like owned, same kw returned
);Parameters
| Key | Type | Description |
|---|---|---|
gobj | hgobj | GObject instance. |
event | gobj_event_t | Event to encapsulate. |
kw | json_t * | Keyword arguments (like owned — same pointer is returned). |
Returns
The modified kw with __iev_event__ added, or NULL on error.
iev_create2()¶
Creates an inter-event object and copies the __temp__ metadata from a
request kw.
json_t *iev_create2(
hgobj gobj,
gobj_event_t event,
json_t *kw, // like owned, same kw returned
json_t *kw_request // owned, only __temp__ is extracted
);Parameters
| Key | Type | Description |
|---|---|---|
gobj | hgobj | GObject instance. |
event | gobj_event_t | Event to encapsulate. |
kw | json_t * | Keyword arguments (like owned). |
kw_request | json_t * | Request kw from which __temp__ is extracted (owned). |
Returns
The modified kw, or NULL on error.
iev_create_to_gbuffer()¶
Serializes an inter-event message into a gbuffer_t for sending to the
outside world.
gbuffer_t *iev_create_to_gbuffer(
hgobj gobj,
gobj_event_t event,
json_t *kw // owned
);Parameters
| Key | Type | Description |
|---|---|---|
gobj | hgobj | GObject instance. |
event | gobj_event_t | Event name. |
kw | json_t * | Keyword arguments (owned). |
Returns
gbuffer_t pointer with the serialized JSON, or NULL on error.
The frame carries no __temp__ (7.30.27+): it is local to the yuno (the
channel a message came in by, a pointer of this process), and a kw that is
published or forwarded as it came carries it. It is deleted with no log, and from
a twin of the kw (kw_twin()) when somebody else holds it too, so they keep
theirs. Up to 7.30.26 it was sent: a kw received through a C_IOGATE and
published to a subscriber over a link told the peer a pointer of this process.
json_t *kw = json_pack("{s:i, s:{s:I}}", "a", 1, "__temp__", "channel_gobj", (json_int_t)(uintptr_t)channel);
gbuffer_t *gbuf = iev_create_to_gbuffer(gobj, EV_X, kw); // {"event": "EV_X", "kw": {"a": 1}}With the drop of iev_create_from_gbuffer(),
__temp__ crosses the frontier of a yuno in neither direction.
iev_create_from_gbuffer()¶
Deserializes an inter-event message received from the outside world.
json_t *iev_create_from_gbuffer(
hgobj gobj,
gobj_event_t *event, // output: the public event the frame names, NULL if none
gbuffer_t *gbuf, // owned, data consumed
int verbose // 1 = log, 2 = log + dump
);Parameters
| Key | Type | Description |
|---|---|---|
gobj | hgobj | GObject instance. |
event | gobj_event_t * | Output — the public event the frame names (the registered name, compared by pointer), NULL when no gclass has it as public. |
gbuf | gbuffer_t * | Buffer with the serialized message (owned and consumed). |
verbose | int | 0: a frame that is not json or not an inter-event is the caller’s to say. 1 or 2: said here, a WARNING (a frame that is not json with a masked DEBUG dump of its first bytes). An event that is not public is said whatever verbose is. |
Returns
Deserialized kw JSON object (yours), or NULL for a frame that is not json
or not an inter-event (no "event" string, no "kw" dict). *event is the
public event the frame names, NULL when no gclass has it as public.
What a frame gets wrong is the peer’s, said ONCE, a WARNING (MSGSET_PROTOCOL,
peername, no stack), saying what it got wrong:
With
verbose, a frame that is not json is “frame is not json” (gbuf2json_from_peer(): the parser’s error and its position -- not the bytes jansson quotes near it, which showed the value of a secret (7.27.0+) --, the bytes, and a DEBUG dump of the first 256 masked asmask_secrets_in_text()masks them).With
verbose, a frame of json that is not an inter-event (no"event"string, no"kw"dict) is “Frame is not an inter-event (an “event” string and a “kw” dict), refused”, with the frame inframe, masked (json_mask_secrets()) and capped to 256 bytes, andframe_size.With
0, the caller says both.An event that is not public is said HERE whatever
verboseis, since only here is the name the frame gave known: “Frame of an event that is not public, refused”, with the name ineventmasked and THEN capped to 64 bytes (mask_secrets_inline_capped(): a password or a JWT sent as the name of the event was written in clear up to 7.26.9, and capped first, a token that the cap cut showed its first bytes), the kw inkwmasked and capped to 256 bytes, andframe_size.
The kw handed back carries no __temp__ (7.30.27+): it is local
metadata -- C_IOGATE writes there the channel a message came in by, and
channel_gobj is a pointer of this process that the receiver dereferences --
so a peer’s one is deleted from the top level of the kw, after
kw_deserialize(), with no log. A yuno of the SDK can send its own back
(C_TRANGER’s answer to EV_TRANGER_ADD_RECORD serializes it, and nothing on
the way out removes it from a kw that is published or forwarded), so it is no
fault of the peer. Up to 7.30.26 it was handed on: a frame of a web client of
the control center, or of a session of the agent, with
{"event": "EV_MT_COMMAND_ANSWER", "kw": {"__temp__": [1094795585]}}left the list where C_IOGATE was not able to write its own channel, and the reader
took 1094795585 for the channel: a SIGSEGV.
__send_type__ is the yuno’s own key too, and it is NOT deleted here: a
C_IOGATE reads it from the kw of a SEND (EV_SEND_MESSAGE, EV_SEND_IEV,
where 1 sends to every open channel), and that kw is always built by code of the
yuno -- a gclass builds its {"gbuffer": ...}, an answer is built from the
__md_iev__ of its request, and an answer that goes back to a session is
sent to its C_CHANNEL, not to the gate. No path of the SDK makes a peer’s
json the kw of a send. Keep it so: a gclass that forwards a peer’s json puts
it under a key of its own (or serializes it into the gbuffer), never as the
kw of a send to a gate.
frame_size is the bytes of the frame RECEIVED. Up to 7.26.9 the WARNING of an
event that is not public said a kw_size that was the size of the masked,
capped copy (a kw of 900 KB said 101). C_IEVENT_SRV and C_IEVENT_CLI pass
1 (7.27.0+) and close the channel: they passed 0 and said “Bad json” for
both refusals, a frame of json among them, with a dump of the frame’s bytes
raw, where a JWT under a plain key, cut by the window, showed its header. Up to
7.26.9 the lookup of the event was silent and both callers traced the whole kw
raw (“iev_event NULL”: a jwt and a password before the session among it),
and a frame with no "event" logged two ERRORs here and the caller’s WARNING.
Example
gobj_event_t iev_event;
json_t *iev_kw = iev_create_from_gbuffer(gobj, &iev_event, gbuf, 1);
if(!iev_kw) {
// not json, or not an inter-event: said by iev_create_from_gbuffer()
} else if(!iev_event) {
// an event that is not public: logged by iev_create_from_gbuffer()
KW_DECREF(iev_kw)
}WARNING {"msgset": "Protocol", "msg": "Frame of an event that is not public, refused",
"event": "EV_NO_SUCH_EVENT password=********", "peername": "127.0.0.1:45216",
"kw": "{\"jwt\":\"********\",\"password\":\"********\",...", "frame_size": 66034}
WARNING {"msgset": "Protocol",
"msg": "Frame is not an inter-event (an \"event\" string and a \"kw\" dict), refused",
"peername": "127.0.0.1:45218", "frame": "{\"note\":\"xxxx ********\"}", "frame_size": 321}msg_iev_push_stack()¶
Pushes a record onto an inter-event metadata stack (LIFO).
The stack is stored in __md_iev__[stack].
int msg_iev_push_stack(
hgobj gobj,
json_t *kw, // not owned
const char *stack,
json_t *jn_data // owned
);Parameters
| Key | Type | Description |
|---|---|---|
gobj | hgobj | GObject instance. |
kw | json_t * | Message kw (not owned). |
stack | const char * | Stack name (for example "ievent_gate_stack"). |
jn_data | json_t * | Data to push (owned). |
Returns
0 on success, -1 on failure.
msg_iev_get_stack()¶
Returns the top record of an inter-event stack without popping it.
json_t *msg_iev_get_stack(
hgobj gobj,
json_t *kw, // not owned
const char *stack,
BOOL verbose
);Parameters
| Key | Type | Description |
|---|---|---|
gobj | hgobj | GObject instance. |
kw | json_t * | Message kw (not owned). |
stack | const char * | Stack name. |
verbose | BOOL | TRUE to log when the kw has no __md_iev__ or no such stack. |
Returns
Top record (not owned — do not free), or NULL if not found.
Notes
The routing travels in the frame, so a kw without it is what the peer sent: with verbose, one WARNING (MSGSET_PROTOCOL, “md_iev NOT FOUND” or “md_iev stack NOT FOUND”) naming the stack and the peer, with the kw masked and capped to 256 bytes (7.27.0+). Up to 7.26.9 it was an ERROR with a stack trace and the whole kw traced in clear -- the frame of a server, a command’s password among it, reached it in C_IEVENT_CLI. Without verbose nothing is logged: the caller decides.
Example
json_t *jn_ievent_id = msg_iev_get_stack(gobj, kw, IEVENT_STACK_ID, FALSE);
if(jn_ievent_id) {
// __RESPONSE__: the request this kw answers
} else {
// __REQUEST__: the routing is pushed here
}msg_iev_pop_stack()¶
Pops and returns the top record from an inter-event stack.
json_t *msg_iev_pop_stack(
hgobj gobj,
json_t *kw,
const char *stack
);Parameters
| Key | Type | Description |
|---|---|---|
gobj | hgobj | GObject instance. |
kw | json_t * | Message kw. |
stack | const char * | Stack name. |
Returns
Popped record (owned: the caller must free it), or NULL if not found. A kw without __md_iev__ or without the stack is logged as msg_iev_get_stack() with verbose logs it: a WARNING, the kw masked and capped (7.27.0+, and before that it was an ERROR with the kw traced in clear).
Example
The agent forwarding the answer of a yuno to whoever asked:
json_t *jn_ievent_id = msg_iev_pop_stack(gobj, kw, IEVENT_STACK_ID);
const char *dst_service = kw_get_str(gobj, jn_ievent_id, "dst_service", "", 0);
// ... route kw to dst_service ...
JSON_DECREF(jn_ievent_id)msg_iev_stack_command_line()¶
Returns the line of a command in the form that the command_stack of __md_iev__ keeps.
Each answer carries back the stack of its request, so a long line must not go there whole.
json_t *msg_iev_stack_command_line(
const char *command
);Parameters
| Key | Type | Description |
|---|---|---|
command | const char * | The command line, as the caller sends it. NULL gives an empty string. |
Returns
A new json string. The caller owns it. The function never returns NULL.
The function returns a line of 1 KB or less as it is.
It returns a longer line as a trace shows it, masked by names only (
command_mask_secret_line()with no command table). Each parameter value over 1 KB becomes<N bytes>. The command name stays first. The line has 64 KB at most, and a parameter that does not fit is<...>.It returns
<...>for a line that is not valid UTF-8.
C_IEVENT_CLI and C_IEVENT_SRV push this value into the stack (7.31.27+). Up to 7.31.26 they pushed the whole line. The content64 of an upgrade-agent or an install-binary (tens of MB) then came back in each answer. A control center dropped the client (client_max_tx_bytes) before the answer of the agent arrived.
Example
How C_IEVENT_CLI pushes the line of a command:
msg_iev_push_stack(
gobj,
kw, // not owned
COMMAND_STACK_ID,
json_pack("{s:o, s:o}", // owned
"command", msg_iev_stack_command_line(command),
"kw", __md_command__
)
);With a 46 MB content64, the stack keeps this line:
command-agent agent_id=deploycenter cmd2agent=<48646516 bytes>msg_iev_set_back_metadata()¶
Copies inter-event metadata from a request into a response.
Optionally reverses src/dst in the ievent_gate_stack.
json_t *msg_iev_set_back_metadata(
hgobj gobj,
json_t *kw_request, // owned (only __md_iev__ extracted)
json_t *kw_response, // like owned, returned (created if NULL)
BOOL reverse_dst
);Parameters
| Key | Type | Description |
|---|---|---|
gobj | hgobj | GObject instance. |
kw_request | json_t * | Request kw (owned). |
kw_response | json_t * | Response kw (like owned, returned, and created if NULL). |
reverse_dst | BOOL | TRUE to swap src/dst in the ievent gate stack. |
Returns
The kw_response with metadata set.
msg_iev_build_response()¶
Builds a complete command/stats response with result code, comment,
schema, and data fields. Sets metadata with reversed src/dst.
json_t *msg_iev_build_response(
hgobj gobj,
json_int_t result,
json_t *jn_comment, // owned
json_t *jn_schema, // owned
json_t *jn_data, // owned
json_t *kw_request // owned
);Parameters
| Key | Type | Description |
|---|---|---|
gobj | hgobj | GObject instance. |
result | json_int_t | Result code (0 = success, negative = error). |
jn_comment | json_t * | Comment string (owned). |
jn_schema | json_t * | Response schema (owned). |
jn_data | json_t * | Response data (owned). |
kw_request | json_t * | Original request kw (owned). |
Returns
Complete response kw ready to send.
msg_iev_build_response_without_reverse_dst()¶
Same as msg_iev_build_response() but does
not reverse src/dst in the metadata.
json_t *msg_iev_build_response_without_reverse_dst(
hgobj gobj,
json_int_t result,
json_t *jn_comment, // owned
json_t *jn_schema, // owned
json_t *jn_data, // owned
json_t *kw_request // owned
);Parameters
Same as msg_iev_build_response().
Returns
Complete response kw with metadata set but src/dst not reversed.
msg_iev_clean_metadata()¶
Removes all inter-event metadata from kw: __md_iev__, __temp__,
__md_tranger__, and __md_yuno__.
json_t *msg_iev_clean_metadata(
json_t *kw // not owned
);Parameters
| Key | Type | Description |
|---|---|---|
kw | json_t * | Message kw (not owned). |
Returns
Same kw with metadata fields removed.
msg_iev_set_msg_type()¶
Sets the message type in __md_iev__.__msg_type__.
int msg_iev_set_msg_type(
hgobj gobj,
json_t *kw,
const char *msg_type
);Parameters
| Key | Type | Description |
|---|---|---|
gobj | hgobj | GObject instance. |
kw | json_t * | Message kw. |
msg_type | const char * | Message type string (for example "__command__", "__stats__", "__message__"). Pass an empty string to delete. |
Returns
0 on success.
msg_iev_get_msg_type()¶
Reads the message type from __md_iev__.__msg_type__.
const char *msg_iev_get_msg_type(
hgobj gobj,
json_t *kw
);Parameters
| Key | Type | Description |
|---|---|---|
gobj | hgobj | GObject instance. |
kw | json_t * | Message kw. |
Returns
Message type string, or an empty string if not set.
trace_inter_event()¶
Traces an inter-event with compact metadata (only result and
__md_iev__). Used by the ievents trace level. The secrets are masked as in
trace_inter_event2() — the command line of an
inter-event is also in __md_iev__, in the command_stack (COMMAND_STACK_ID)
where every emitter puts it, and a SDF_SECRET parameter in it (a positional
one, a content64) is masked by the command table of its destination service.
In any event but the request (EV_MT_COMMAND) -- its answer, or another event
that echoes the request’s metadata, as the agent’s EV_TTY_CLOSE -- the line
is its first word only, with <...> for the rest: the routing of an answer
names no service that knows the line, and the line was shown, masked, with the
request.
void trace_inter_event(
hgobj gobj,
const char *prefix,
const char *event,
json_t *kw
);Parameters
| Key | Type | Description |
|---|---|---|
gobj | hgobj | GObject instance. |
prefix | const char * | Trace message prefix. |
event | const char * | Event name. |
kw | json_t * | Message kw. |
Returns
This function does not return a value.
Example
/*
* A service "vault" of this yuno, whose command takes its secret
* positionally (a leading SDF_REQUIRED parameter):
*
* PRIVATE sdata_desc_t pm_set_password[] = {
* SDATAPM (DTP_STRING, "password", SDF_REQUIRED|SDF_SECRET, 0, "The new password"),
* SDATA_END()
* };
*/
json_t *kw = json_pack("{s:s, s:{s:[{s:s}], s:[{s:s, s:{}}]}}",
"__command__", "set-password hunter2",
"__md_iev__",
"ievent_gate_stack", "dst_service", "vault",
"command_stack", "command", "set-password hunter2", "kw"
);
trace_inter_event(gobj, "ievents", "EV_MT_COMMAND", kw);
// the trace shows "command": "set-password ********"
trace_inter_event(gobj, "ievents", "EV_MT_COMMAND_ANSWER", kw);
// the trace shows "command": "set-password <...>"
json_decref(kw);Up to 7.25.21 this trace masked by key names only, and such a positional
secret went in clear. Up to 7.30.26 it looked for the line under
__md_iev__.__command__, a name no emitter uses: the command_stack was shown
masked by names only, so create-config id=x content64=<s> sent to the agent
was traced with <s> in clear, in the request and in its answer.
trace_inter_event2()¶
Traces an inter-event with the full kw content.
void trace_inter_event2(
hgobj gobj,
const char *prefix,
const char *event,
json_t *kw
);Parameters
| Key | Type | Description |
|---|---|---|
gobj | hgobj | GObject instance. |
prefix | const char * | Trace message prefix. |
event | const char * | Event name. |
kw | json_t * | Full message kw. |
Returns
This function does not return a value.