ADR-038: the wire frame for the A/B<->C util side channel (RTE_EXAMPLE_RELAY_KIND_UTIL) and the C-side pub/sub broker. More...

#include <stdbool.h>
#include <stdint.h>
#include <string.h>

Include dependency graph for rbc_util_frame.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	rbc_util_frame_t
	Decoded view of a util frame (payload is a pointer into the caller's buffer, NUL-terminated into `payload_z` by the codec). More...

Macros
#define	RBC_UTIL_FRAME_SIZE 256U
#define	RBC_UTIL_HEADER_SIZE 6U
#define	RBC_UTIL_PAYLOAD_MAX (RBC_UTIL_FRAME_SIZE - RBC_UTIL_HEADER_SIZE)
#define	RBC_UTIL_TOPIC_STATUS 1U
	Topic ids (byte 2..3).
#define	RBC_UTIL_TOPIC_JRU_LOG 2U
	A/B -> Gateway log-event forwarding (see rbc_util_jru_payload.h). Gateway's status service forwards each publish straight to Platform_Protocol_JRU's rte_osadapter_log_t, bypassing the pub/sub broker's latest-only storage - every event matters here, not just the newest one per source.
#define	RBC_UTIL_TOPIC_KM114_FILE 3U
	Gateway -> A/B: raw Subset-114 off-line KMC file bytes, chunked (see rbc_util_km114_relay.h). Gateway is a pure byte relay - it never decodes these; A/B each independently decode/verify/decrypt with their own predefined key (Platform_Protocol_KM114/CLAUDE.md's "Consumption design" note).
#define	RBC_UTIL_TOPIC_TAKEOVER_CONFIRM 4U
	Gateway -> A/B: the dispatcher has confirmed that the OTHER site is not ONLINE, so a STANDBY whose counterpart stopped responding may promote itself (the only path to ONLINE besides normal negotiation and the counterpart's FAULTED/reboot notice). Payload is ignored. See AB/GP/com/ab_gp_standby_policy.h and docs/STANDBY_AND_SITE_LINK_ARCHITECTURE.md.

Enumerations
enum	rbc_util_msg_type_t { RBC_UTIL_MSG_KEEPALIVE = 0 , RBC_UTIL_MSG_HELLO = 1 , RBC_UTIL_MSG_SUBSCRIBE = 2 , RBC_UTIL_MSG_UNSUBSCRIBE = 3 , RBC_UTIL_MSG_PUBLISH = 4 , RBC_UTIL_MSG_BYE = 5 }
	Control-plane opcode - byte 0 of the frame. More...
enum	rbc_util_source_t { RBC_UTIL_SRC_UNKNOWN = 0 , RBC_UTIL_SRC_A = 1 , RBC_UTIL_SRC_B = 2 , RBC_UTIL_SRC_GW_TRAIN = 3 , RBC_UTIL_SRC_GW_IL = 4 , RBC_UTIL_SRC_GW_CTC = 5 , RBC_UTIL_SRC_GW_STATUS = 6 , RBC_UTIL_SRC_SIM_TRAIN = 7 , RBC_UTIL_SRC_SIM_IL = 8 , RBC_UTIL_SRC_SIM_CTC = 9 }
	Stable small source ids. West/East are disambiguated by the link the frame arrived on / the log's own site field, so these are per-role not per-(role,site). More...

Functions
static void	rbc_util_frame_encode (uint8_t out[RBC_UTIL_FRAME_SIZE], rbc_util_msg_type_t msg_type, uint8_t source_id, uint16_t topic_id, uint8_t seq, const char *payload)
	Encodes a util frame into a fixed RBC_UTIL_FRAME_SIZE buffer.
static bool	rbc_util_frame_decode (const uint8_t in[RBC_UTIL_FRAME_SIZE], rbc_util_frame_t *out)
	Decodes a util frame. Returns false only on a NULL arg or a payload_len past the buffer (a corrupt frame); an unknown msg_type/topic_id still decodes (caller decides what to do).

Detailed Description

ADR-038: the wire frame for the A/B<->C util side channel (RTE_EXAMPLE_RELAY_KIND_UTIL) and the C-side pub/sub broker.

Deliberately general: a small typed envelope carrying a publish/subscribe control-plane message plus an opaque ASCII key=value payload. Two users today: status indication (topic_id == RBC_UTIL_TOPIC_STATUS) and JRU/diagnostic log-event forwarding (topic_id == RBC_UTIL_TOPIC_JRU_LOG, see rbc_util_jru_payload.h) - each rides the same frame and link.

Pure types + a static-inline codec, no I/O. Consumed by C99 (A/B side, ab_gp_channel.c / post_execute.c) and C++ (the role-C broker / status service - role C is non-vital, ADR-001 4). The one copy in AB/common and the one in C/common must stay byte-identical (same discipline as rbc_wire_types.h's two copies).

Layout (little-endian), RBC_UTIL_FRAME_SIZE (256) bytes total: [0] util_msg_type rbc_util_msg_type_t [1] source_id rbc_util_source_t - stable small id per unit [2..3] topic_id uint16 - RBC_UTIL_TOPIC_* [4] seq uint8, wraps - publisher's own counter [5] payload_len uint8, 0..RBC_UTIL_PAYLOAD_MAX [6..] payload payload_len ASCII bytes, unused tail zero

Definition in file rbc_util_frame.h.

Macro Definition Documentation

◆ RBC_UTIL_FRAME_SIZE

#define RBC_UTIL_FRAME_SIZE 256U

Definition at line 39 of file rbc_util_frame.h.

◆ RBC_UTIL_HEADER_SIZE

#define RBC_UTIL_HEADER_SIZE 6U

Definition at line 40 of file rbc_util_frame.h.

◆ RBC_UTIL_PAYLOAD_MAX

#define RBC_UTIL_PAYLOAD_MAX (RBC_UTIL_FRAME_SIZE - RBC_UTIL_HEADER_SIZE)

Definition at line 41 of file rbc_util_frame.h.

◆ RBC_UTIL_TOPIC_STATUS

#define RBC_UTIL_TOPIC_STATUS 1U

Topic ids (byte 2..3).

Definition at line 55 of file rbc_util_frame.h.

◆ RBC_UTIL_TOPIC_JRU_LOG

#define RBC_UTIL_TOPIC_JRU_LOG 2U

A/B -> Gateway log-event forwarding (see rbc_util_jru_payload.h). Gateway's status service forwards each publish straight to Platform_Protocol_JRU's rte_osadapter_log_t, bypassing the pub/sub broker's latest-only storage - every event matters here, not just the newest one per source.

Definition at line 60 of file rbc_util_frame.h.

◆ RBC_UTIL_TOPIC_KM114_FILE

#define RBC_UTIL_TOPIC_KM114_FILE 3U

Gateway -> A/B: raw Subset-114 off-line KMC file bytes, chunked (see rbc_util_km114_relay.h). Gateway is a pure byte relay - it never decodes these; A/B each independently decode/verify/decrypt with their own predefined key (Platform_Protocol_KM114/CLAUDE.md's "Consumption design" note).

Definition at line 65 of file rbc_util_frame.h.

◆ RBC_UTIL_TOPIC_TAKEOVER_CONFIRM

#define RBC_UTIL_TOPIC_TAKEOVER_CONFIRM 4U

Gateway -> A/B: the dispatcher has confirmed that the OTHER site is not ONLINE, so a STANDBY whose counterpart stopped responding may promote itself (the only path to ONLINE besides normal negotiation and the counterpart's FAULTED/reboot notice). Payload is ignored. See AB/GP/com/ab_gp_standby_policy.h and docs/STANDBY_AND_SITE_LINK_ARCHITECTURE.md.

Definition at line 70 of file rbc_util_frame.h.

Enumeration Type Documentation

◆ rbc_util_msg_type_t

enum rbc_util_msg_type_t

Control-plane opcode - byte 0 of the frame.

Enumerator
RBC_UTIL_MSG_KEEPALIVE	Nothing to say - keeps the link fresh (relay staleness).
RBC_UTIL_MSG_HELLO	Client announces/refreshes itself (source_id).
RBC_UTIL_MSG_SUBSCRIBE	Client subscribes to topic_id.
RBC_UTIL_MSG_UNSUBSCRIBE	Client unsubscribes from topic_id.
RBC_UTIL_MSG_PUBLISH	payload published on topic_id - broker fans out.
RBC_UTIL_MSG_BYE	Client leaving (best-effort; the sweep covers a silent drop).

Definition at line 44 of file rbc_util_frame.h.

◆ rbc_util_source_t

enum rbc_util_source_t

Stable small source ids. West/East are disambiguated by the link the frame arrived on / the log's own site field, so these are per-role not per-(role,site).

Enumerator
RBC_UTIL_SRC_UNKNOWN
RBC_UTIL_SRC_A
RBC_UTIL_SRC_B
RBC_UTIL_SRC_GW_TRAIN
RBC_UTIL_SRC_GW_IL
RBC_UTIL_SRC_GW_CTC
RBC_UTIL_SRC_GW_STATUS
RBC_UTIL_SRC_SIM_TRAIN
RBC_UTIL_SRC_SIM_IL
RBC_UTIL_SRC_SIM_CTC

Definition at line 75 of file rbc_util_frame.h.

Function Documentation

◆ rbc_util_frame_encode()

void rbc_util_frame_encode	(	uint8_t	out[RBC_UTIL_FRAME_SIZE],
		rbc_util_msg_type_t	msg_type,
		uint8_t	source_id,
		uint16_t	topic_id,
		uint8_t	seq,
		const char *	payload )

inlinestatic

Encodes a util frame into a fixed RBC_UTIL_FRAME_SIZE buffer.

Parameters

out	Destination, RBC_UTIL_FRAME_SIZE bytes. Must not be NULL.
msg_type	Opcode.
source_id	Sender id.
topic_id	Topic (0 for HELLO/BYE/KEEPALIVE - ignored).
seq	Sender's sequence byte.
payload	ASCII payload or NULL. Truncated to RBC_UTIL_PAYLOAD_MAX.

Definition at line 110 of file rbc_util_frame.h.

◆ rbc_util_frame_decode()

bool rbc_util_frame_decode	(	const uint8_t	in[RBC_UTIL_FRAME_SIZE],
		rbc_util_frame_t *	out )