rte_site_role.h

Go to the documentation of this file.

#ifndef RTE_SITE_ROLE_H
#define RTE_SITE_ROLE_H
 
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
 
#include "rte/oal/netlink/rte_netlink.h"
#include "rte/redundancy/dual/rte_dual_channel.h"
#include "rte/redundancy/dual/rte_dual_negotiator.h"
#include "rte/redundancy/site_role/rte_site_role_policy.h"
#include "rte/utils/status/rte_status.h"
#include "rte/utils/types/rte_types.h"
 
#ifdef __cplusplus
extern "C" {
#endif

#define RTE_SITE_ROLE_FRAME_OVERHEAD 7U
#define RTE_SITE_ROLE_FRAME_STATE_OFFSET 6U
#define RTE_SITE_ROLE_VALID_MARKER 0xA5U
#define RTE_SITE_ROLE_SINGLE_MODE_DUAL 0U
#define RTE_SITE_ROLE_SINGLE_MODE_SINGLE 1U

typedef struct
{
    bool faulted;           
    bool single_mode;       
    bool own_ready;         
    bool sibling_online;    
    bool sibling_ready;     
    bool sibling_reachable; 
} rte_site_role_local_t;

typedef enum
{
    RTE_SITE_ROLE_CHANGE_PROMOTED = 0, 
    RTE_SITE_ROLE_CHANGE_DEMOTED,      
    RTE_SITE_ROLE_CHANGE_RENEGOTIATED  
} rte_site_role_change_kind_t;

typedef struct
{
    rte_site_role_change_kind_t kind;
    rte_site_role_reason_t      reason;
    bool                        online;         
    bool                        apply_state;    
    bool                        snapshot_valid; 
    uint32_t                    snapshot_cycle; 
} rte_site_role_change_t;

typedef rte_status_t (*rte_site_role_encode_state_fn)(void *user, uint8_t *out, size_t size, bool live);
typedef bool (*rte_site_role_receive_state_fn)(void *user, const uint8_t *in, size_t size, bool valid);
typedef void (*rte_site_role_change_fn)(void *user, const rte_site_role_change_t *change);
typedef void (*rte_site_role_trace_fn)(void *user, const char *line);
typedef void (*rte_site_role_delay_fn)(void *user, uint32_t ms);
 
/*
 * Takeover confirmation token (ADR-040 step 4, REQ-SITEROLE-015), RTE_SITE_ROLE_TOKEN_LEN bytes:
 *   message (RTE_SITE_ROLE_TOKEN_MSG_LEN): version(1) | site id(1) | channel id(1) | 0(1) |
 *                                          challenge(4, little endian) | issuer sequence(4, little endian) | 0(4)
 *   mac (RTE_SITE_ROLE_TOKEN_MAC_LEN):     the issuer's MAC over the message, with the site's takeover key
 * The challenge makes a token single-use and bounds its age without a wall clock: the issuer reads the current
 * challenge from the channel's status, and a token for an older challenge is rejected.
 */
#define RTE_SITE_ROLE_TOKEN_MSG_LEN 16U
#define RTE_SITE_ROLE_TOKEN_MAC_LEN 8U
#define RTE_SITE_ROLE_TOKEN_LEN (RTE_SITE_ROLE_TOKEN_MSG_LEN + RTE_SITE_ROLE_TOKEN_MAC_LEN)
#define RTE_SITE_ROLE_TOKEN_VERSION 1U
#define RTE_SITE_ROLE_CHALLENGE_LIFETIME_DEFAULT_CYCLES 240U

typedef bool (*rte_site_role_verify_mac_fn)(void *user, const uint8_t *msg, size_t msg_len,
                                            const uint8_t mac[RTE_SITE_ROLE_TOKEN_MAC_LEN]);

typedef enum
{
    RTE_SITE_ROLE_TOKEN_ACCEPTED = 0,     
    RTE_SITE_ROLE_TOKEN_IGNORED_ONLINE,   
    RTE_SITE_ROLE_TOKEN_NOT_CONFIGURED,   
    RTE_SITE_ROLE_TOKEN_NO_CHALLENGE,     
    RTE_SITE_ROLE_TOKEN_BAD_FORMAT,       
    RTE_SITE_ROLE_TOKEN_BAD_MAC,          
    RTE_SITE_ROLE_TOKEN_STALE_CHALLENGE   
} rte_site_role_token_result_t;

#define RTE_SITE_ROLE_SIBLING_MISMATCH_LIMIT 3U
#define RTE_SITE_ROLE_SIBLING_REACH_DEFAULT_CYCLES 3U

typedef struct
{
    bool known;       
    bool online;      
    bool single_mode; 
    bool ready;       
} rte_site_role_sibling_t;

typedef bool (*rte_site_role_sibling_source_fn)(void *user, rte_site_role_sibling_t *out);

typedef enum
{
    RTE_SITE_ROLE_SIBLING_UNKNOWN = 0, 
    RTE_SITE_ROLE_SIBLING_AGREE,       
    RTE_SITE_ROLE_SIBLING_PENDING,     
    RTE_SITE_ROLE_SIBLING_FAULT        
} rte_site_role_sibling_verdict_t;

typedef struct
{
    uint32_t           own_id;               
    uint32_t           peer_id;              
    bool               is_west;              
    bool               listen;               
    const char        *peer_host;            
    uint16_t           port;                 
    size_t             link_message_size;    
    rte_duration_ms_t  ack_timeout_ms;       
    rte_duration_ms_t  peer_lost_timeout_ms; 
    rte_duration_ms_t  reconnect_attempt_ms; 
    rte_duration_ms_t  startup_timeout_ms;   
    rte_duration_ms_t  link_poll_ms;         
    uint32_t           connect_retry_ms;     
    rte_duration_ms_t  connect_timeout_ms;   
    uint8_t            send_miss_threshold;  
    bool               standby_sync;         
    rte_timestamp_ms_t startup_timestamp_ms; 
    size_t             frame_size;           
    uint8_t           *tx_buf;               
    uint8_t           *rx_buf;               
    const char        *role_tag;             
    const char        *peer_tag;             
    const char        *site_name;            
    const char        *sibling_tag;          
    rte_site_role_encode_state_fn  encode_state;
    rte_site_role_receive_state_fn receive_state;
    rte_site_role_change_fn        on_change;
    rte_site_role_trace_fn         trace;    
    rte_site_role_delay_fn         delay;    
    void                          *user;
    /* Takeover confirmation (REQ-SITEROLE-015). verify_mac NULL = the interim unauthenticated path. */
    rte_site_role_verify_mac_fn    verify_mac;
    uint8_t                        channel_id;                
    uint32_t                       challenge_lifetime_cycles; 
    /* Sibling site state (REQ-SITEROLE-016). sibling_source NULL = the application supplies the sibling facts in
     * rte_site_role_local_t and calls rte_site_role_check_sibling() itself (step 3). Also polled once by
     * rte_site_role_start() before the inter-site negotiation (REQ-SITEROLE-017). */
    rte_site_role_sibling_source_fn sibling_source;
    uint32_t                        sibling_reach_cycles; 
} rte_site_role_config_t;

typedef struct
{
    bool                   online;
    bool                   link_up;
    bool                   peer_answering;   
    bool                   peer_online_now;
    bool                   peer_unresponsive;
    bool                   standby_warm;
    bool                   standby_healthy;
    rte_site_role_reason_t last_reason;
} rte_site_role_status_t;

typedef struct
{
    rte_site_role_config_t cfg;
    rte_netlink_storage_t  link_storage;
    rte_netlink_handle_t   link;
    rte_dual_channel_t     dual_channel;
    rte_dual_negotiator_t  negotiator;
    rte_timestamp_ms_t     startup_timestamp_ms;
    uint8_t                send_miss;
    bool                   online;
    bool                   local_faulted;
    bool                   local_single_mode;
    bool                   peer_faulted;
    uint8_t                peer_single_mode;
    bool                   peer_online_now;
    uint32_t               peer_last_rx_cycle;
    bool                   peer_snapshot_valid;
    uint32_t               peer_snapshot_cycle;
    bool                   peer_unresponsive;
    bool                   lost_peer_while_online;
    bool                   takeover_confirmed;
    uint32_t               takeover_confirm_cycle;
    uint32_t               both_standby_cycles;
    rte_site_role_reason_t last_reason;
    bool                   last_reason_set;
    bool                   standby_healthy;
    uint32_t               standby_last_try_cycle;
    uint32_t               standby_rx_cycle;
    bool                   standby_warm;
    uint32_t               cycle;
    uint8_t                sibling_mismatch;
    bool                   challenge_valid;
    uint32_t               challenge;
    uint32_t               challenge_cycle;
    bool                   challenge_fail_reported;
    rte_site_role_sibling_t         sibling;          
    uint32_t                        sibling_rx_cycle; 
    rte_site_role_sibling_verdict_t sibling_verdict;  
} rte_site_role_t;

rte_status_t rte_site_role_init(rte_site_role_t *rs, const rte_site_role_config_t *cfg);

rte_status_t rte_site_role_start(rte_site_role_t *rs);

void rte_site_role_execute(rte_site_role_t *rs, uint32_t cycle, const rte_site_role_local_t *local);

void rte_site_role_service_link(rte_site_role_t *rs, uint32_t cycle);

void rte_site_role_sync_standby(rte_site_role_t *rs, uint32_t cycle, const rte_site_role_local_t *local);

void rte_site_role_on_takeover_confirm(rte_site_role_t *rs, uint32_t cycle);

rte_site_role_token_result_t rte_site_role_on_takeover_token(rte_site_role_t *rs, uint32_t cycle, const uint8_t *token,
                                                             size_t token_len);

bool rte_site_role_takeover_challenge(const rte_site_role_t *rs, uint32_t *out);

void rte_site_role_note_lost_contact(rte_site_role_t *rs);

void rte_site_role_flush_faulted(rte_site_role_t *rs, bool single_mode);

rte_site_role_sibling_verdict_t rte_site_role_check_sibling(rte_site_role_t *rs, uint32_t cycle, bool own_single_mode,
                                                            const rte_site_role_sibling_t *sibling);

rte_site_role_sibling_verdict_t rte_site_role_sibling_verdict(const rte_site_role_t *rs);

void rte_site_role_shutdown(rte_site_role_t *rs);

bool rte_site_role_is_online(const rte_site_role_t *rs);

void rte_site_role_get_status(const rte_site_role_t *rs, rte_site_role_status_t *out);

void rte_site_role_get_negotiator_states(const rte_site_role_t *rs, rte_dual_state_t *own, rte_dual_state_t *peer);
 
#ifdef __cplusplus
}
#endif
 
#endif /* RTE_SITE_ROLE_H */