Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Inter-Event GClasses

RPC-like communication between yunos over the network. A local gobj subscribes to a remote service as if it were local.

Source: kernel/c/root-linux/src/c_ievent_cli.c, c_ievent_srv.c

The kw a gate is given is the caller’s still. To send a request (gobj_command(), gobj_stats()) or an event (gobj_send_event() of an event the gate does not take, mt_inject_event()), both gates write the ievent stack and the message type into the kw, and serialize its binary fields (the gbuffer goes into the frame as __gbuffer___). A kw that somebody else holds too (its refcount above 1: a published kw, or a caller’s kw_incref()) is twinned first (kw_twin(), which takes its own reference of the gbuffer), and its __md_iev__ copied, so the caller’s kw is returned as it went, gbuffer included:

json_t *kw = kw_duplicate(gobj, request);    // or a kw of your own, with a gbuffer
json_t *webix = gobj_command(agent_gate, "list-yunos", kw_incref(kw), gobj);
JSON_DECREF(webix)
// kw is as it was: its gbuffer still there, released with it
KW_DECREF(kw)

Up to 7.25.4, only an event was twinned. Up to 7.30.17, gobj_command() and gobj_stats() wrote in the caller’s kw and took its gbuffer away, so the reference that kw_incref() had taken was never released.


C_IEVENT_CLI

Inter-event client — connects to a remote yuno and simulates its service as a local gobj. Handles identity-card exchange, authentication, and subscription management.

PropertyValue
StatesST_STOPPED, ST_DISCONNECTED, ST_WAIT_CONNECTED, ST_WAIT_IDENTITY_CARD, ST_SESSION, ST_SUBSCRIBED
Input eventsEV_SEND_MESSAGE, EV_ON_MESSAGE, EV_ON_OPEN, EV_ON_CLOSE, EV_TIMEOUT, EV_DROP, EV_STOPPED
Output eventsEV_ON_MESSAGE, EV_ON_OPEN, EV_ON_CLOSE

Key attributes

AttributeTypeDescription
wanted_yuno_rolestringRole of the remote yuno to connect to.
wanted_yuno_namestringName of the remote yuno.
wanted_yuno_servicestringService name on the remote yuno.
urlstringConnection URL.
jwtstringJSON Web Token for authentication.
timeout_idackintegerIdentity-card ack timeout in seconds.
verify_operatorbooleanVerify the operator of each request of the server from an operator assertion signed for this node (default false). See below.
service_principalstringWith verify_operator, the __username__ of a request that carries no operator assertion. Empty: such a request is refused.

The operator of a request of the server

A server that forwards a command of somebody else says who asks in __username__, and the client’s authz reads it. An example is a controlcenter that forwards an operator’s command to an agent. With verify_operator the client does not believe the server’s word (7.30.9+):

The operator’s login token never leaves the server. An assertion taken from one node is good on no other node, and it lives for one minute. The keys of a login are not asked: a login token sent as an assertion is refused.

The client takes __operator_assertion__ out of every request, verified or not. It also takes out __operator_jwt__, the field of 7.30.6–7.30.8, which was never sent. No command and no audit sees either of them. The identity card says knows_operator_assertion: true, and a server gives assertions only to a client that says so. Otherwise, an older client hands the unknown key to its command.

Example: the agent’s link to its controlcenter, in the agent’s main.c (7.30.9+). Verification is on by default there:

'kw': {
    'remote_yuno_role': 'controlcenter',
    'remote_yuno_service': 'controlcenter',
    'verify_operator': true,
    'service_principal': 'controlcenter'
}

To switch it off from the agent’s json file:

"global": {
    "controlcenter.verify_operator": false
}

Stopping with remote subscriptions open

gobj_stop() closes the transport, but the FSM stays in ST_SESSION until the close arrives, so EV_ON_CLOSE is still published. A subscription added or withdrawn in that window is not sent to the peer. The peer’s C_IEVENT_SRV drops every subscription of the channel when the channel closes, and an added subscription is sent at the next open. Up to 7.25.4 the __unsubscribing__ frame went down to the stopping transport, and C_WEBSOCKET or C_TCP logged “Event NOT DEFINED in state”. Example:

gobj_stop_tree(priv->gobj_remote);                          // the transport starts to close
gobj_unsubscribe_event(priv->gobj_remote, EV_X, 0, gobj);   // not sent, and not an error

C_IEVENT_SRV

Inter-event server — entry gate for authenticated service access. Manages incoming connections, routes inter-event messages to local services, and handles WebSocket upgrade.

PropertyValue
StatesST_STOPPED, ST_DISCONNECTED, ST_WAIT_IDENTITY_CARD, ST_SESSION
Input eventsEV_ON_MESSAGE, EV_ON_OPEN, EV_ON_CLOSE, EV_TIMEOUT, EV_DROP, EV_STOPPED
Output eventsEV_ON_MESSAGE, EV_ON_OPEN, EV_ON_CLOSE

Key attributes

AttributeTypeDescription
__username__stringAuthenticated username (read-only).
__session_id__stringSession identifier (read-only).
jwt_payloadjsonDecoded JWT payload.
client_yuno_rolestringRole of the connected client yuno.
client_yuno_namestringName of the connected client yuno.
this_servicestringLocal service name this gate serves.
authenticatedboolWhether the connection is authenticated.
max_subscriptionsintegerSubscriptions a peer can hold on the channel (default 5000, 0 no limit). See What a peer may hold.
max_subscription_sizeintegerBytes, as compact json, of the __filter__, of the __global__ and of the routing back (__md_iev__) of a peer’s subscription, each one (default 16384, 0 no limit).
max_pre_session_frameintegerBytes of a frame received before the session (default 65536, 0 no limit). See below.
peer_certdictThe certificate the client presented to the TLS of its transport (C_TCP’s peer_cert: subject, cn, spki_sha256, verified, ...), {} if none (7.30.10+). It goes in the EV_ON_OPEN the gate publishes too, for a service that binds an identity to it: the controlcenter pins each node to its agent’s key.

Lifecycle of a channel

The tree of a channel (C_CHANNEL → C_IEVENT_SRV → C_WEBSOCKET or C_PROT_TCP4H → C_TCP) belongs to its gate, not to one connection. gobj_start_tree() of the gate starts it. When the peer leaves, only its C_TCP stops: the protocol gobj stays running and serves the next connection that the channel accepts.

When the gate stops, all of the tree stops: each layer stops the one below it, and C_IEVENT_SRV stops its protocol gobj since 7.25.5. Up to 7.25.4 a gate stopped with a plain gobj_stop() (the way the yuno stops an autostart service) left each C_WEBSOCKET or C_PROT_TCP4H running, and the yuno exited with “Destroying a RUNNING gobj”. Only an owner that called gobj_stop_tree() on the gate stopped it all.

A channel that is disabled and enabled again (the C_IOGATE commands disable-channel and enable-channel) is restored whole: C_CHANNEL restarts its tree, and C_IEVENT_SRV starts its protocol gobj in its start, the mirror of its stop. The transport C_TCP is manual start: C_TCP_S starts it for each connection it accepts.

ycommand -c 'command-yuno id=<id> service=__input_side__ command=disable-channel channel_name=^input-1$'
ycommand -c 'command-yuno id=<id> service=__input_side__ command=enable-channel channel_name=^input-1$'

channel_name is a regular expression. It selects the channels whose name it matches: ^input-1$ on a gate with input-1 and input-2 selects only input-1. One that matches no channel selects nothing, and the command answers with the header of the view only. (Up to 7.25.4 each of the six commands looped for ever on the first channel that did not match, and blocked the yuno.) A text that is not a valid regular expression is refused with -1, for example channel_name=input-[ answers “<role^name>: channel_name is not a valid regular expression: ‘input-[’” (up to 7.25.4: “regcomp() failed”).

Start and stop the gate as a pair. Either declare it "autostart": true in the config and let the yuno start and stop it, or do both in the owner:

PRIVATE int mt_play(hgobj gobj)
{
    PRIVATE_DATA *priv = gobj_priv_data(gobj);

    priv->gobj_input_side = gobj_find_service("__input_side__", TRUE);
    gobj_subscribe_event(priv->gobj_input_side, 0, 0, gobj);
    gobj_start_tree(priv->gobj_input_side);
    return 0;
}

PRIVATE int mt_pause(hgobj gobj)
{
    PRIVATE_DATA *priv = gobj_priv_data(gobj);

    gobj_stop_tree(priv->gobj_input_side);
    return 0;
}

Subscription authz

A peer subscribes to an event of a local service with a __subscribing__ message. C_IEVENT_SRV accepts it only for a public output event of a service the channel can reach. Since 7.25.5, when the yuno sets enable_subscription_authz (off by default) and the event is flagged EVF_AUTHZ_SUBSCRIBE, the channel’s user also needs the publisher’s permission aliased __subscribe_event__ — read for the EV_TREEDB_NODE_* feed of a treedb and for the EV_TRANGER_RECORD_ADDED feed of a C_TRANGER — or the global __subscribe_event__. A refused subscription is a WARNING (“No permission to subscribe event”, MSGSET_AUTH, with the service, the event, the permission and the username, and up to 7.30.15 an ERROR, though the peer causes it) and is not made. The channel stays open. The refusal is logged once per service and event on a channel: a peer that repeats it does not write a log line per frame. When the peer withdraws a refused subscription later, that is logged at info level (“its subscription was refused”). A withdrawal that matches no subscription of the channel, and was not refused, is a warning (“UNSUBSCRIBING event matches no subscription of this channel”), with the frame cut to 256 bytes. Both are the peer’s to repeat, so each is written at most once per 10 s per channel, with the count of the ones not written (suppressed). Up to 7.25.4 each frame wrote its line, and the no-match warning the whole frame, as big as the peer made it.

Example: a yuno that enforces the treedb feed permission, in its config:

{
    "yuno": {
        "enable_subscription_authz": true
    }
}

Details, and how a gclass declares a guarded event: YUNO_AUTH.md §4.6.

What a peer may put in a subscription

The kw of a __subscribing__ message can carry __config__, __global__ and __filter__, as a local gobj_subscribe_event() does. C_IEVENT_SRV builds the subscription from those three, and keeps of them only what a peer can set (since 7.25.5):

KeyWhat is kept
__filter__All of it. It decides only the peer’s own deliveries.
__config__The keys in the list below.
__global__The keys of the peer’s own: not one that starts with _ (the framework’s: __md_iev__, __md_yuno__, __service__, ...), and not gbuffer, the binary field of every kw. They return to the peer in every event of this subscription, and to nobody else.
__local__Nothing. The one __local__ of a remote subscription is the reference to the channel, set by C_IEVENT_SRV.
any other keyNothing.

What is dropped is logged as a warning, “SUBSCRIBING keys a peer may not set, ignored”, at most once per 10 s per channel. A __filter__ or a __global__ bigger than max_subscription_size refuses the subscription (“SUBSCRIBING refused, bigger than max_subscription_size”, same pace).

To route every event of the subscription back to the peer, the gate adds its own back-metadata to the stored __global__: __md_yuno__, and a __md_iev__ built from the TOP record of the frame’s routing stack (the hop of this peer, with the gate’s stamps), reversed. Nothing else of the frame’s __md_iev__ is kept: no key of the peer’s own and no deeper hop. That routing is measured against max_subscription_size too, after it is built: a bigger one (a record with long strings) refuses the subscription, “SUBSCRIBING refused, its routing is bigger than max_subscription_size”, at most once per 10 s. Up to 7.25.4 the frame’s whole __md_iev__ was copied, keys of the peer’s own included, and nothing of a subscription was measured: a peer was able to store as much as a frame holds in each subscription, with no cap on their number, and got it back with every event.

Up to 7.25.4 only __config__ was filtered, and the publish shared ONE kw with every subscriber, so a peer’s subscription changed the event of every subscriber after it: its __global__ forged keys of the event (a topic_name, a node), its __local__ removed them, the filters of the later subscribers were evaluated on the forged kw, and the back-metadata of the gate (__md_iev__, with the peer’s user name and channel) reached a local subscriber. A gbuffer in the peer’s __global__ was taken for a pointer when the event was serialized back to it, and crashed the yuno. Now gobj_publish_event() gives a subscription with a __local__ or a __global__ a twin of the kw of its own (gobj_publish_event()), and C_IEVENT_SRV changes a kw that somebody else holds only on a copy.

Of __config__, the list of keys a peer can set has one key:

KeyMeaning
__first_shot__Read by the publisher in its mt_subscription_added(): false asks it not to send its current state when the subscription is made.

Any other key is removed before the subscription is made, and logged as a warning (“SUBSCRIBING config keys a peer may not set, ignored”). Three of those keys change how the framework delivers the event, and a peer must never have them:

Up to 7.25.4 the peer’s __config__ went through whole. Also since 7.25.5, the close of a channel removes every subscription it made with force, hard or not.

Example: a SPA subscribes without the first shot, and that key arrives:

gobj_subscribe_event(gobj_remote, "EV_REALTIME_TRACK", {
    __config__: {__first_shot__: false},
    __filter__: {id: device_id}
}, gobj);

A key that a publisher reads from a peer is added to the list in c_ievent_srv.c (peer_subscription_config_keys), and documented here.

A peer withdraws a subscription with an __unsubscribing__ message that repeats what it subscribed. The kw is filtered the same way, and compared with what the peer SENT: the __global__ that C_IEVENT_SRV stores carries its own back-metadata too, which the peer never repeats. Up to 7.25.4, it was compared whole, and the peer was not able to withdraw a subscription with a __global__ until the channel closed.

Example: a C client tags the events of its subscription, and withdraws it:

json_t *kw = json_pack("{s:{s:s}, s:{s:s}}",
    "__filter__", "topic_name", "devices",
    "__global__", "tag", "devices_view"     // comes back in each event
);
gobj_subscribe_event(gobj_remote, EV_REALTIME_TRACK, json_incref(kw), gobj);
gobj_unsubscribe_event(gobj_remote, EV_REALTIME_TRACK, kw, gobj);   // the same kw

What a peer may hold

Every subscription costs a scan of the publisher’s subscriptions when it is made, and one more on every publish of its event. A peer was able to make them without end: 20000 subscriptions of one peer blocked the event loop for 80 s, and every later publish took 13 ms. So a channel holds at most max_subscriptions of its peer. Beyond it a subscription is refused, logged once (“SUBSCRIBING refused, the peer holds max_subscriptions”), and not again until the peer is under the cap.

A subscription that repeats one the peer holds takes no room:

Both are logged as a warning, at most once per 10 s per channel (“SUBSCRIBING repeated, the one held is kept”, “SUBSCRIBING overrides one held, it is replaced”). A client does not send either: C_IEVENT_CLI withdraws the subscription it replaces first. Up to 7.25.4 every repeated frame went to gobj_subscribe_event(), which deleted the subscription, made it again, and logged a warning with a stack trace and the whole kw.

A gate whose peers subscribe per device (two subscriptions per device, in a monitoring SPA) raises the cap in the kw of the C_IEVENT_SRV of its channel tree:

{
    "name": "input-(^^__range__^^)",
    "gclass": "C_IEVENT_SRV",
    "kw": {
        "max_subscriptions": 20000
    }
}

What the gate stamps

The gate writes who sent a message into the kw it hands on, and overwrites whatever the peer put there under the same key. In a command, a stats request and an event, __username__ is the channel’s authenticated user (set by C_AUTHZ), whatever the peer sent. In the routing stack of an event (__md_iev__), __username__, input_channel and input_service are the gate’s. The command parser’s authz check reads that __username__.

Example: a peer sends list-yunos with a __username__ of its own in the kw of the command:

{"__username__": "admin"}

The service gets "__username__": "bob" when the channel’s user is bob. Up to 7.25.4 kw_set_dict_value() kept a key that already existed, so the peer’s admin reached the service.

A frame the gate cannot route

Every frame of a session carries its routing: __md_iev__ with the ievent stack, whose top record says where the frame is from (src_yuno, src_role, src_service, strings) and, if it says, where it goes (dst_yuno, dst_role, dst_service, strings). C_IEVENT_CLI (C and JS) pushes it on every request, and an answer copies the one of its request. A well-formed routing (__msg_type__ is optional, a string when present):

"__md_iev__": {
    "ievent_gate_stack": [
        {
            "src_yuno": "", "src_role": "ycommand", "src_service": "ycommand",
            "dst_yuno": "", "dst_role": "yuneta_agent", "dst_service": "agent"
        }
    ],
    "__msg_type__": "__command__"
}

The same frame with "src_role": 7, with an empty ievent_gate_stack, or with no __md_iev__ at all, has no routing, and its channel is closed. The gate reads what the peer sent with plain json calls, never with a kw_get_*() reader that logs a wrong type with a stack. What it refuses, and how:

The frameWhat the gate doesLog (per channel)
No routing, or a malformed oneCloses the channel, as for a frame that is not json. It cannot be answered, nor routed back.“Frame without its routing (__md_iev__ ievent stack), channel closed”, WARNING, MSGSET_PROTOCOL, the kw capped to 256 bytes, at most once per 10 s.
For another yuno (dst_role, dst_yuno)Closes the channel.“It’s not my role, channel closed” / “It’s not my name, channel closed”, WARNING, the routing capped.
For a service the channel is not allowed to reachA command or a stats request gets a negative answer and the channel stays. A subscription, a withdrawal or an event closes it.“event ignored, dst_service not authorized for this channel”, WARNING, MSGSET_AUTH, the kw capped, at most once per 10 s.
For a service that does not existThe same.“event ignored, service not found”, WARNING, same pace.
A subscription or a withdrawal of an event that is not publicRefused. The channel stays.“SUBSCRIBING event ignored, not PUBLIC...”, WARNING, same pace.
A command or a stats request that names no command (neither __command__ in the kw nor in its stack), or whose service is not a stringAnswered with an error. The channel stays.“Request without the command or stats it asks, refused”, WARNING, the kw capped, same pace.
A command or a stats request whose service does not exist, or is one the channel is not allowed to reachAnswered with an error. The channel stays.“Service not found” / “Not authorized to request commands of a different service” / “Not authorized to request stats of a different service”, WARNING, MSGSET_AUTH, same pace (one kind with the “dst_service not authorized” above).
An event no gclass has as public (any state)Closes the channel.“Frame of an event that is not public, refused”, WARNING, MSGSET_PROTOCOL, the name masked and THEN capped to 64 bytes (mask_secrets_inline_capped(): capped first, a token the cap cut showed its first bytes), the kw masked and capped to 256 bytes -- said by iev_create_from_gbuffer(), once per connection. Up to 7.26.9 it was silent there, and the gate traced the whole kw raw (“iev_event NULL”), credentials before the session among it. C_IEVENT_CLI the same.
An event the transport publishes on its own (EV_ON_OPEN, EV_ON_CLOSE, EV_ON_MESSAGE, EV_ON_IEV_MESSAGE, EV_ON_ID, EV_ON_ID_NAK), in session. Other gclasses declare these names public (C_PROT_HTTP_SR, C_POSTGRES, the decoders of a gate), so the frame readsDrops the frame. The channel stays. The gate’s subscriber (a C_IOGATE, which publishes the event again as its own) hears nothing. Up to 7.30.26 it was published as if the transport had said it, with the kw the peer wrote: in the agent each EV_ON_OPEN {} was 16 ERRORs with a stack, and in the control center an agent was able to take a forged EV_ON_OPEN (its identity card and certificate) to the check of its node key, and an EV_ON_CLOSE wiped the state of its channel (7.30.27). EV_ON_COMMAND is not refused: no transport emits it, and the agent takes it as an answer.“event of the transport itself sent by a peer, refused”, WARNING, MSGSET_PROTOCOL, the event, peername and username, at most once per 10 s (suppressed says how many were not written).
An event a treedb publishes (EV_TREEDB_NODE_CREATED, EV_TREEDB_NODE_UPDATED, EV_TREEDB_NODE_DELETED, EV_TREEDB_NODE_LINKED, EV_TREEDB_NODE_UNLINKED), in session. They are public in C_NODE, so the frame readsDrops the frame. The channel stays. The gate’s subscriber is often the yuno’s main gclass, which is subscribed to its own treedb too and cannot tell a peer’s event from its store’s. Up to 7.30.26 a session of the lowest privilege was able to disable (DELETED), enable (UPDATED) or create (CREATED) users of the yuno’s C_AUTHZ this way. A remote SUBSCRIPTION to these events is not affected: the published events arrive at the client (C_IEVENT_CLI), not here.“event of a treedb sent by a peer, refused”, WARNING, MSGSET_AUTH, the event, peername and username, at most once per 10 s.
EV_REMOTE_LOG: a log line of the peer’s app (gobj-js set_remote_log_functions()), in sessionLogged.“Remote Error”, ERROR, MSGSET_APP, the remote msg capped to 1 KB and masked (mask_secrets_inline()), its whole size and the username. The kw is not dumped. Up to 7.26.9 the text was written whole, and the kw traced raw.

Each of these is the peer’s to repeat, frame after frame, so none writes a line per frame, none carries a stack trace, and none dumps the whole kw. Up to 7.25.4 a frame without routing logged an error with a stack and the whole kw (the lookup was verbose, “TODO check”) and was processed all the same. A command to a service the channel is not allowed to reach logged an error, the whole kw, the authorized services and the routing, for each frame. A subscription to an event that is not public returned an error without closing the channel, which left it connected and deaf.

The service of a command is checked as the one of a stats request: a channel reaches the service of its identity card, the services its user has roles in (services_roles, see C_AUTHZ), and any service when its user is a superuser (a role of service: "*"). A session of a user who can reach only controlcenter:

kw      {"__command__": "help", "service": "__yuno__"}
answer  -1: "Not authorized to request commands of service: '__yuno__'"

Up to 7.30.14 the service of a command was not checked (only its routing was): that session reached every service of the yuno through it -- __yuno__ with its write-attr, shutdown, add-denied-ip.

tests/c/c_ievent_srv_peer_subs, tests/c/c_ievent_srv_transport_events.

What the client refuses from its server

C_IEVENT_CLI reads the frames of its server the same way: its faults are the peer’s, one WARNING each (MSGSET_PROTOCOL, no stack, the names it wrote masked and capped).

The frameWhat the client doesLog
Any event but EV_IDENTITY_CARD_ACK before the sessionCloses the channel.“event UNKNOWN in not-session state”
For another yuno (dst_role, dst_yuno)Closes the channel.“It’s not my role” / “It’s not my name”
A subscription or a withdrawal (__subscribing__, __unsubscribing__)Closes the channel: a client is not subscribed to.“subscription event ignored, I’m client” / “unsubscription event ignored, I’m client”
In session, an event of the client itself that is not public (EV_ON_OPEN, EV_ON_CLOSE, EV_DROP...: another gclass, C_PROT_HTTP_SR, declares them public, so the frame reads), or the ACK againDrops the frame. The channel stays. Up to 7.26.9, EV_ON_OPEN and EV_ON_CLOSE reached the app as the client’s own open and close, with the kw the server chose, and the ACK was sent back to the server.“event of the transport itself, or out of its place, refused”
In session, an event of another gclass whose dst_service is no serviceDrops it. The channel stays (a view gone with its frames still on the wire). Up to 7.26.9 it was published to the client’s subscribers, with an ERROR and a stack, the name in clear.“service of the event not found, event dropped”
In session, an event whose dst_service is a service that does not have it as publicDrops it. The channel stays. Up to 7.26.9, it was published to the client’s subscribers, with no log.“event not public in its service, event dropped”
In session, an event with an empty dst_servicePublishes it to the client’s subscribers: it names no destination, so it belongs to whoever subscribed. Up to 7.26.9 also an ERROR with a stack, “service EMPTY”.None
In session, an event whose dst_service is the client’s own name (the src_service of its identity card: what the server sends on its own, with no __service__)Publishes it to the client’s subscribers, as an empty one (7.27.0). The name is compared without case, as gobj_find_service() compares it: a client created as a plain child (no as_service, and every client of the tree is a service) does with "CLI" for cli what a service does.None
In session, EV_MT_STATS / EV_MT_COMMAND whose service is no serviceAnswers with an error (“Service not found: ‘...’”). The channel stays.“Service not found”, MSGSET_PARAMETER, the name masked and capped (7.27.0, but up to 7.26.9 in clear)

tests/c/c_ievent_cli_peer_faults.

Who may play and pause the yuno

EV_PLAY_YUNO and EV_PAUSE_YUNO are public events of every C_IEVENT_CLI: they call gobj_play() / gobj_pause() of the YUNO and answer with EV_PLAY_YUNO_ACK / EV_PAUSE_YUNO_ACK. Their one legitimate sender is the yuno’s agent, over the link the agent gives every yuno it launches. Since 7.30.27 only a client whose CONFIGURED remote role is yuneta_agent takes them:

/* The link the agent writes into every yuno's config: plays and pauses it */
{
    "name": "agent_client",
    "gclass": "C_IEVENT_CLI",
    "kw": {
        "remote_yuno_role": "yuneta_agent",
        "remote_yuno_service": "agent"
    }
}

The role compared is wanted_yuno_role, copied from the config’s remote_yuno_role when the client is created. It is never the role the server SAYS: the identity-card ack overwrites remote_yuno_role with what the server writes, so a server that claims to be an agent changes nothing. Any other client configured to reach a yuneta_agent passes too (a tool that links to the agent of a node): its server is an agent all the same.

Any other client (a gate’s link to a central, the agent’s own link to its control center) refuses both events:

What it doesLog
The yuno is not played or paused. The ack is answered with "result": -1 and a comment (“<role>^<name>: only the link to the yuno’s agent plays or pauses the yuno”). The channel stays.ONE WARNING per session, MSGSET_AUTH, no stack, the server’s role and name masked: “play/pause of the yuno refused: only the link to its agent plays or pauses it”

Up to 7.30.26 every client played and paused the yuno: the server of any link (a central, a control center) was able to pause the yuno. In the agent the pause by its control-center link stopped that same link inside its own action.

tests/c/c_ievent_cli_play_pause.

The C client and the gobj-js client refuse differently

The gobj-js C_IEVENT_CLI (the browser’s) reads its server with the same severity, one WARNING without a stack and the server’s names masked, but it does not always do the same with the frame. The differences, checked in c_ievent_cli.c and gobj-js src/c_ievent_cli.js (7.26.27):

The frameC C_IEVENT_CLIgobj-js C_IEVENT_CLI
Not json, or not an inter-eventWARNING, and closes the channelWARNING, and drops the frame. The channel stays
An event no gclass has as publicWARNING, and closes the channelWARNING, and drops the frame. The channel stays
__subscribing__ / __unsubscribing__WARNING, and closes the channelWARNING, and drops the frame. The channel stays
dst_service names no serviceWARNING, and drops it (7.27.0, but up to 7.26.9 it published it)WARNING, and drops it
dst_service is a service that does not have the event as publicWARNING, and drops it (7.27.0, but up to 7.26.9 it published it, no log)WARNING, and drops it
What the server sends on its own, with no __service__ (addressed to the src_service of the identity card)Its card names the transport itself: published to its subscribersIts card names the transport’s PARENT: delivered to that service if it has the event as public, else dropped with a WARNING
EV_MT_STATS / EV_MT_COMMANDServed: the stats or the command of the service named, and the answerNot served: a browser does not run what its server asks
How a fault closes the channel (an event before the session, another dst_role / dst_yuno)EV_DROP to the transport: the TCP connection is cut, with no WebSocket close frameThe WebSocket is closed with code 4002, which EV_ON_CLOSE carries

Since 7.27.0 the two clients do the same with a dst_service they cannot deliver to: they drop the event. The C one published it until then. No node logged it in a week of logs, and no C client of the tree receives anything that way (each one is the src_service of what it asks, and declares the answers public). What a server sends on its own is the other case: an app that sends an event to the C_IEVENT_SRV of a channel, with no __service__ in the kw, addresses it to the service the client’s identity card gave -- the C client’s transport, which publishes it to its subscribers, as an empty dst_service. Name a service to reach it instead:

gobj_send_event(gobj_channel_srv, EV_ALARM,        // to the subscribers of the client's transport
    json_pack("{s:s}", "device", "dev1"), gobj);
gobj_send_event(gobj_channel_srv, EV_ALARM,        // to the client's service `monitor`, which has EV_ALARM public
    json_pack("{s:s, s:s}", "device", "dev1", "__service__", "monitor"), gobj);

To an anonymous client (no yuno_name) the gate writes no dst_yuno (7.27.0): its ^peer-sock name is the gate’s label, and up to 7.26.9 the client refused it (“It’s not my name”) and the channel was closed. Both keep the session when an event of the transport itself arrives (“event of the transport itself, or out of its place”), so a hostile server can make either write one WARNING per frame.

An identity card the gate refuses

Before its session, a peer can send two things: its identity card (EV_IDENTITY_CARD) or EV_GOODBYE. The card carries the same routing as any frame, and it must name this yuno and one of its services:

{
    "jwt": "<token, or empty with the BFF cookie>",
    "__md_iev__": {
        "ievent_gate_stack": [
            {
                "src_yuno": "", "src_role": "ycommand", "src_service": "ycommand",
                "dst_yuno": "", "dst_role": "yuneta_agent", "dst_service": "agent"
            }
        ],
        "__msg_type__": "__identity__"
    }
}

What is refused, each time, is the peer’s: the channel is closed, and the gate writes ONE warning (MSGSET_PROTOCOL, peername, the kw capped to 256 bytes in kw and its size in kw_size, no stack), with no credential in it. kw_size is the size of the kw RECEIVED, as compact json (7.27.0+: it was the size of the masked, capped copy, and a kw of 900 KB said 101). A frame that is not json, or not an inter-event, is said as what it is by iev_create_from_gbuffer() (“frame is not json”, “Frame is not an inter-event ...”), masked. The gate said “Bad json” for both up to 7.26.9, with a dump of the bytes raw. Before a session there is no command table to ask which parameter is SDF_SECRET, so the NAME decides (is_secret_name(), the one list of the SDK: passw, token, secret, jwt, api_key, private_key, pin... any case): at any depth of the kw the value of such a key is shown as ******** (whatever its json type), and in a string (a command line) the value of such a name=value too. Also, under any key, a value with the shape of a credential -- a JWT, the credential after Bearer or Basic -- the kernel’s json_mask_secrets(), the same rule as the ievents traces. A command sent before the card:

kw   {"jwt": "eyJ...", "password": "s3cr3t", "kw": {"passw": "x"}, "__command__": "help token=abc",
      "note": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ4In0.c2ln", "h": "Authorization: Bearer abc"}
log  {"jwt":"********","password":"********","kw":{"passw":"********"},"__command__":"help token=********",
      "note":"********","h":"Authorization: ********", ...}

A command to a channel that is NOT in session (mt_command of C_IEVENT_SRV or C_IEVENT_CLI: the agent’s command-yuno to a yuno that has just gone) is refused with “Not in session”, an ERROR that names the command by its first word, capped to 64 bytes and masked: the line is forwarded whole, so up to 7.26.9 it logged a set-password password=... (and, with the line password=hunter2 user=x, the first word itself: it is password=******** now). A stats asked out of session (mt_stats) is said the same way, its name capped to 64 bytes and masked: it was logged whole (7.27.0+).

C_IEVENT_CLI ANSWERS such a command at once: -1, “<yuno>: service ‘<name>’ not in session”, and logs it as one WARNING with no stack (MSGSET_OPERATIONAL). A link that is down is a state, not a broken contract, and a peer with a session in the yuno can ask for it. Up to 7.30.26 it returned NULL -- which for a command means “the answer will come” -- after an ERROR with a stack, and the caller waited for ever: the agent’s command-agent service=controlcenter with the link to the control center down answered nothing.

ycommand -c 'command-agent service=controlcenter command=list-yunos'
yuneta_agent^node1: service 'controlcenter' not in session

A stats asked out of session (mt_stats of C_IEVENT_CLI) is answered the same way, -1 and one WARNING: up to 7.30.26 the agent’s stats-agent service=controlcenter with the link down never answered, after an ERROR with a stack. An event sent to a C_IEVENT_CLI out of session (mt_inject_event) still returns -1, and logs one WARNING instead of an ERROR with a stack. C_IEVENT_SRV answers a command or a stats out of session the same way (-1, one WARNING).

ycommand -c 'stats-agent service=controlcenter'
yuneta_agent^node1: service 'controlcenter' not in session

In the browser (@yuneta/gobj-js 7.31.0+), C_IEVENT_CLI answers a command or a stats asked out of session the same way: gobj_command() / gobj_stats() return a command response with result: -1 and the comment “<role>^<name>: service ‘<transport>’ not in session”, nothing is sent, and one WARNING names the command, never its parameters. Up to gobj-js 7.30.0 they returned null -- “the answer will come” -- after an ERROR, and a view waiting for that answer waited for ever. A non-null return is the failure, so the guard every view writes is enough:

const ret = gobj_command(remote, "list-devices", {}, gobj);
if(ret) {
    // {result: -1, comment: "myapp^gui: service '__remote_service__' not in session", ...}
    set_status(gobj, "backend not connected", ret.comment || "");
    return -1;
}
// null: sent, the answer comes as EV_MT_COMMAND_ANSWER

A request already sent when the socket drops is still never answered: that one is the view’s to handle, on the transport’s EV_ON_CLOSE.

A peer that is closing. A WebSocket Close of the peer (or a protocol error of its frames) puts C_WEBSOCKET in ST_DISCONNECTED at once, and so does the close of C_PROT_TCP4H. The channel leaves ST_SESSION only at its EV_ON_CLOSE, when the connection ends, on a later turn of the loop (a client waits for the server to end it, or for its timeout_close). In that window the channel is still in session, but its transport takes nothing. C_IEVENT_SRV and C_IEVENT_CLI ask their transport first (its state is ST_DISCONNECTED). When the bottom of a C_IEVENT_CLI is a C_IOGATE, as in the agent’s link to the control center, the iogate stays in ST_IDLE and the transport is the bottom of its opened C_CHANNEL: the client asks that one, and the link is closing when the transport of every opened channel is.

{
    "name": "controlcenter", "gclass": "C_IEVENT_CLI",
    "children": [
        {"name": "controlcenter_cli", "gclass": "C_IOGATE", "children": [
            {"name": "controlcenter_cli", "gclass": "C_CHANNEL", "children": [
                {"name": "controlcenter_cli", "gclass": "C_PROT_TCP4H", "children": [
                    {"name": "controlcenter_cli", "gclass": "C_TCP"}
                ]}
            ]}
        ]}
    ]
}

In that window a command or a stats is answered -1 “<yuno>: service ‘<name>’ not in session” with one WARNING “Not in session”, as out of session. Anything else that goes to the peer (an answer, an event of a subscription, an injected event) is dropped, and the channel logs one WARNING “Transport closing, nothing sent” per session, naming the first event. Up to 7.30.26 each of them was “Event NOT DEFINED in state” in the transport, an ERROR with a stack, and the caller of a command or a stats waited for ever. The agent’s stats-yuno or command-yuno to a yuno that closes just then is the usual case. So a caller of gobj_command() or gobj_stats() on a channel takes a non-NULL return as the answer, and as nothing sent:

json_t *webix = gobj_command(channel_gobj, "help", kw, src);    // kw owned
if(webix) {
    /*
     *  Answered at once: the channel is out of session, or its peer is
     *  closing. Nothing went to the peer, and no answer will come.
     */
    int result = (int)kw_get_int(gobj, webix, "result", -1, 0);     // -1
    JSON_DECREF(webix)
    return result;
}
return 0;   // sent: the answer comes as EV_MT_COMMAND_ANSWER

The ievents and ievents2 traces of C_IEVENT_CLI and C_IEVENT_SRV (trace_inter_event(), trace_inter_event2()) mask the same way, in both directions. A command line (in __command__, and in the command_stack of __md_iev__, where every emitter puts it too) is also masked by the command table of its destination service when that service is in this yuno -- its SDF_SECRET parameters, positional ones too, a content64 -- as the commands trace does (command_mask_secret_line()). In its answer, and in any other event that echoes the request, the line is its first word only (create-config <...>). Up to 7.25.20 ievents2 printed a command’s password in clear, and up to 7.30.26 both traces showed the line of the command_stack masked by names only: create-config id=x content64=<s> sent to the agent was traced with <s> in clear, in the request and in its answer.

kw   {"__command__": "set-user-pwd username=bob password=hunter2", "password": "hunter2"}
log  {"event": "EV_MT_COMMAND", "kw": {"__command__": "set-user-pwd username=bob password=********", "password": "********"}}
The cardLog
No routing, or a malformed one“Identity card without its routing (__md_iev__ ievent stack), refused”
dst_role is not this yuno’s role“Identity card refused, dst_role NOT MATCH”, with dst_role
dst_yuno given and not this yuno’s name“Identity card refused, dst_yuno NOT MATCH”, with dst_yuno
Empty src_role“Identity card refused, without yuno role”
Empty src_service“Identity card refused, without yuno service”
dst_service is no service of this yuno“Identity card refused, dst_service NOT FOUND in this yuno”, with dst_service
jwt present and not a string“Identity card refused, its jwt is not a string”
Any event but the card or EV_GOODBYE“Event before the identity card, channel closed”, with event
A frame bigger than max_pre_session_frame“Frame before the identity card too big, channel closed”, with size and max. The frame is not parsed, and its bytes are not dumped (unparsed they cannot be masked, and a card carries a jwt)
An event no gclass has as public“Frame of an event that is not public, refused”, with event capped to 64 bytes, said by iev_create_from_gbuffer(). Up to 7.26.9, the kw was traced raw, the jwt with it

A frame before the session is not even parsed when it is bigger than max_pre_session_frame. An identity card is a few KB (its jwt the largest part). Parsed, a frame of [{},...] takes about 100 times its size (16 MB: 1.7 GB), so up to 7.25.21 the max block of a yuno (200 MB) let a peer nobody had authenticated ask for some 20 GB. A gate whose peers send bigger cards raises it:

{
    "name": "input",
    "gclass": "C_IEVENT_SRV",
    "kw": {
        "max_pre_session_frame": 1048576
    }
}

A card refused by the authentication is answered with a negative EV_IDENTITY_CARD_ACK, logged by the authenticator, and the channel is dropped at timeout_idgot (default 5000 ms).

A card can carry a gbuffer. Every frame of a peer goes through kw_deserialize(), so a serialized field the peer writes becomes a real gbuffer of the kw, released with the frame:

{"jwt": "...", "__gbuffer___": {"label": "", "data": "cGVlciBieXRlcw=="}}

Up to 7.30.14 a card refused by the authentication released that gbuffer twice (a double free a peer caused before any login, fixed in 7.30.15). The card the gate keeps (its identity_card attribute) and the one it publishes in EV_ON_OPEN are a copy without the gbuffer field. Up to 7.30.15 both kept it: an integer that pointed to freed memory, which the controlcenter’s list of agents showed to an operator.

A frame has no "gbuffer" of the peer, at any depth. The frame is parsed with gbuf2json_from_peer(), which drops every "gbuffer" key with one warning. Only the top-level "gbuffer" that kw_deserialize() makes of a "__gbuffer___" reaches the services. A command of a peer with {"topic_name": "items", "record": {"id": "a", "gbuffer": 4096}} crashed the yuno up to 7.30.16: C_NODE makes a kw of the record, and the integer was taken for a pointer.

A session has one identity. A card sent IN a session is refused without being authenticated: a negative EV_IDENTITY_CARD_ACK (“Identity card refused: the session has its identity already”), ONE warning per 10 s (“Identity card in a session, refused: the session keeps its identity”, with the username of the session), and the session goes on, with its user, its services and its channel. The services above the gate checked the first card, in the EV_ON_OPEN it published -- the agent registers the yuno, the controlcenter binds the node to its key -- and C_CHANNEL does not pass a second EV_ON_OPEN up. A client sends one card per connection. A second one is a client that sent its card again before the first ACK arrived, which is why the channel stays. Up to 7.30.14 the second card was authenticated again: a good one replaced the user, the services, the superuser flag and the identity_card that the services read later, without their checks. A refused one armed timeout_idgot, and the timeout went to the peer as a frame.

What the gate sends to its peer on its own (mt_inject_event, the events its FSM does not take in the session) is from outside its tree: what a service publishes to a remote subscription, the answer of a service to a request of the peer, what an app or the agent sends to the peer (EV_SEND_IEV by its channel, or to the gate itself). An event of the gate’s own tree -- its timer, its transport -- is not a message: an ERROR (“Event of the gate’s own tree not taken in this state, not sent to the peer”) and nothing sent. Up to 7.30.14 every such event went to the peer as a frame. Up to 7.25.20 each refusal above was an error with the whole kw (its jwt with it), followed by a second error, “event UNKNOWN in not-session state”, with the whole kw again, credentials and all. A jwt that was not a string went on to the authentication.

tests/c/c_ievent_srv_identity_card.