sapi_checkpoint.c

Go to the documentation of this file.

#include "safeapi/redundancy/checkpoint/sapi_checkpoint.h"
 
#include <stdbool.h>
#include <stdio.h>
 
#include "safeapi/utils/buffer/sapi_buffer.h"
#include "safeapi/redundancy/checksum/sapi_checksum.h"
#include "safeapi/utils/safestate/sapi_safestate.h"
#include "safeapi/oal/timer/sapi_timer.h"

#define SAPI_CHECKPOINT_SENDER_ID ((uint32_t)0xC4EC0001U)

#define SAPI_CHECKPOINT_RETRY_ROUND_MS ((sapi_duration_ms_t)250U)

#define SAPI_CHECKPOINT_MIN_ROUNDS_PER_BUDGET ((sapi_duration_ms_t)3U)

#define SAPI_CHECKPOINT_MAX_ROUNDS ((uint32_t)64U)

static sapi_status_t build_arrival_message(uint32_t checkpoint_id, sapi_vital_message_t *out_msg)
{
    uint8_t payload_bytes[4];
    sapi_buffer_t payload_buf;
    sapi_status_t status = sapi_buffer_init(&payload_buf, payload_bytes, sizeof(payload_bytes));
 
    if (status == SAPI_STATUS_OK)
    {
        status = sapi_buffer_write_u32_le(&payload_buf, checkpoint_id);
    }
 
    if (status == SAPI_STATUS_OK)
    {
        status = sapi_checksum_vital_message_create(out_msg,
                                                      SAPI_CHECKPOINT_SENDER_ID,
                                                      checkpoint_id,
                                                      payload_bytes,
                                                      sizeof(payload_bytes));
    }
 
    return status;
}

static bool reply_confirms_checkpoint(const sapi_vital_message_t *reply, uint32_t checkpoint_id)
{
    uint8_t payload_out[4];
    uint8_t payload_size_out = 0U;
    bool confirmed = false;
    sapi_status_t verify_status = sapi_checksum_vital_message_verify(
        reply, checkpoint_id, payload_out, sizeof(payload_out), &payload_size_out);
 
    if ((verify_status == SAPI_STATUS_OK) && (payload_size_out == sizeof(payload_out)))
    {
        sapi_buffer_t payload_buf;
 
        if (sapi_buffer_init(&payload_buf, payload_out, sizeof(payload_out)) == SAPI_STATUS_OK)
        {
            uint32_t decoded_id = 0U;
 
            /* Reads happen against buf->length, not just capacity; the
             * buffer was just fully written by verify() above, so its
             * length must be advanced to cover it before reading back. */
            (void)sapi_buffer_set_length(&payload_buf, sizeof(payload_out));
 
            if ((sapi_buffer_read_u32_le(&payload_buf, 0U, &decoded_id) == SAPI_STATUS_OK)
                && (decoded_id == checkpoint_id))
            {
                confirmed = true;
            }
        }
    }
 
    return confirmed;
}

static sapi_duration_ms_t remaining_budget_ms(sapi_timestamp_ms_t start_ms,
                                               sapi_timestamp_ms_t now_ms,
                                               sapi_duration_ms_t max_delay_ms)
{
    sapi_duration_ms_t remaining;
    sapi_timestamp_ms_t elapsed_ms = now_ms - start_ms;
 
    if (elapsed_ms >= (sapi_timestamp_ms_t)max_delay_ms)
    {
        remaining = 0U;
    }
    else
    {
        remaining = max_delay_ms - (sapi_duration_ms_t)elapsed_ms;
    }
 
    return remaining;
}
 
sapi_status_t sapi_channel_checkpoint(sapi_voter_t *voter, const sapi_checkpoint_config_t *config)
{
    sapi_status_t status = SAPI_STATUS_OK;
    sapi_vital_message_t arrival_msg;
    uint32_t channel_count;
 
    channel_count = sapi_voter_get_channel_count(voter);
 
    if ((voter == NULL) || (config == NULL))
    {
        status = SAPI_STATUS_INVALID_PARAM;
    }
    else if ((config->expected_node_count == 0U) || (config->expected_node_count > channel_count))
    {
        status = SAPI_STATUS_INVALID_PARAM;
    }
    else
    {
        status = build_arrival_message(config->checkpoint_id, &arrival_msg);
    }
 
    if (status == SAPI_STATUS_OK)
    {
        sapi_timestamp_ms_t start_ms = 0U;
        sapi_timestamp_ms_t now_ms = 0U;
        uint32_t confirmed_count = 0U;
        uint32_t i;
        sapi_status_t last_send_status = SAPI_STATUS_OK;
        sapi_status_t last_recv_status = SAPI_STATUS_OK;
        bool channel_confirmed[SAPI_VOTER_MAX_CHANNELS];
        uint32_t round_count = 0U;
        sapi_duration_ms_t round_cap_ms = SAPI_CHECKPOINT_RETRY_ROUND_MS;
        sapi_duration_ms_t budget_based_round_cap_ms =
            (sapi_duration_ms_t)(config->max_delay_ms / SAPI_CHECKPOINT_MIN_ROUNDS_PER_BUDGET);
 
        if ((budget_based_round_cap_ms > 0U) && (budget_based_round_cap_ms < round_cap_ms))
        {
            round_cap_ms = budget_based_round_cap_ms;
        }
 
        for (i = 0U; i < SAPI_VOTER_MAX_CHANNELS; i++)
        {
            channel_confirmed[i] = false;
        }
 
        (void)sapi_timer_now(&start_ms);
        now_ms = start_ms;
 
        /* Retries the whole send+receive round, per not-yet-confirmed
         * channel, until either every expected channel has confirmed, the
         * overall max_delay_ms budget is exhausted, or SAPI_CHECKPOINT_MAX_ROUNDS
         * rounds have run - see SAPI_CHECKPOINT_RETRY_ROUND_MS's own doc for
         * why a single round cannot succeed on a cold two-way start. Still
         * bounded by max_delay_ms in total (REQ-CHECKPOINT-001): each
         * round's own receive is capped to whatever's left of that budget,
         * never more. The round-count cap is a separate, deliberate
         * backstop against a transport whose receive call returns near-
         * instantly instead of genuinely blocking for its requested
         * timeout (confirmed live: this project's own mock-backed unit
         * tests do exactly that, which turned this loop into a real
         * busy-spin consuming the full max_delay_ms in real wall-clock
         * time at 100% CPU before this cap was added) - real production
         * backends block for close to the requested duration, so this
         * cap is not expected to bind there, only to guarantee it can't
         * regardless of transport behavior. */
        while ((confirmed_count < config->expected_node_count)
               && (round_count < SAPI_CHECKPOINT_MAX_ROUNDS)
               && (remaining_budget_ms(start_ms, now_ms, config->max_delay_ms) > 0U))
        {
            for (i = 0U; i < channel_count; i++)
            {
                sapi_channel_t *channel;
                sapi_status_t send_status;
 
                if ((i < SAPI_VOTER_MAX_CHANNELS) && channel_confirmed[i])
                {
                    continue;
                }
 
                channel = sapi_voter_get_channel(voter, i);
                send_status = sapi_channel_send(channel, &arrival_msg, sizeof(arrival_msg));
 
                last_send_status = send_status;
                if (send_status == SAPI_STATUS_OK)
                {
                    sapi_vital_message_t reply;
                    sapi_duration_ms_t sub_budget_ms;
                    sapi_status_t recv_status;
 
                    (void)sapi_timer_now(&now_ms);
                    sub_budget_ms = remaining_budget_ms(start_ms, now_ms, config->max_delay_ms);
                    if (sub_budget_ms > round_cap_ms)
                    {
                        sub_budget_ms = round_cap_ms;
                    }
 
                    recv_status = sapi_channel_receive(channel, &reply, sizeof(reply), sub_budget_ms);
 
                    last_recv_status = recv_status;
                    if ((recv_status == SAPI_STATUS_OK) && reply_confirms_checkpoint(&reply, config->checkpoint_id))
                    {
                        if (i < SAPI_VOTER_MAX_CHANNELS)
                        {
                            channel_confirmed[i] = true;
                        }
                        confirmed_count++;
                    }
                }
            }
            (void)sapi_timer_now(&now_ms);
            round_count++;
 
            /* Kick config->watchdog (if any) once per round, not only on
             * final success below - a caller-supplied liveness watchdog
             * exists to catch a genuinely stuck cyclic executive, and a
             * round that just performed real send/receive I/O is genuine
             * forward progress, not a fake kick. Found live: a caller
             * whose own liveness watchdog has a short (sub-second) timeout
             * and is kicked only once per full cycle, AFTER this function
             * returns, would otherwise have that watchdog fire out from
             * under a call that is still legitimately retrying within its
             * own much longer config->max_delay_ms budget (e.g. the
             * relaxed startup window this retry loop exists for) - not a
             * hung caller, just a caller who has not been given a chance
             * to kick its own watchdog yet. */
            if (config->watchdog != NULL)
            {
                (void)sapi_watchdog_kick(config->watchdog);
            }
        }
 
        if (confirmed_count >= config->expected_node_count)
        {
            if (config->watchdog != NULL)
            {
                (void)sapi_watchdog_kick(config->watchdog);
            }
            status = SAPI_STATUS_OK;
        }
        else
        {
            /* Diagnostic-only, fixed-size buffer (no dynamic allocation,
             * CLAUDE.md): before this REQ-COMMON-SAFESTATE-002 permanent
             * halt, capture the LAST channel's own send/receive outcome so
             * a registered SAFE-level handler (see sapi_safestate.h) can
             * actually log WHY this rendezvous failed - confirmed_count
             * alone does not distinguish "peer never sent" (send_status
             * failure) from "peer sent but didn't reply in time"
             * (recv_status == SAPI_STATUS_TIMEOUT) from "replied with the
             * wrong checkpoint_id" (recv_status == SAPI_STATUS_OK but not
             * confirmed) - this was previously impossible to tell apart
             * from outside this function, since no handler was ever
             * registered for this level anywhere in this codebase and the
             * halt itself is otherwise completely silent. */
            char diag_message[96];
 
            (void)snprintf(diag_message, sizeof(diag_message),
                            "checkpoint confirmed=%u expected=%u channels=%u last_send=%d last_recv=%d",
                            (unsigned int)confirmed_count, (unsigned int)config->expected_node_count,
                            (unsigned int)channel_count, (int)last_send_status, (int)last_recv_status);
            /* Matches the pattern sapi_voter_receive() already uses on a
             * voting disagreement: safe-state is triggered directly by
             * the sync/vote logic itself, not left to the caller to
             * notice and react to (REQ-CHECKPOINT-003). */
            sapi_safestate_enter(SAPI_SAFESTATE_LEVEL_SAFE, SAPI_SAFESTATE_REASON_CHECKPOINT_TIMEOUT, __FILE__,
                                  (int32_t)__LINE__, diag_message);
            status = SAPI_STATUS_TIMEOUT;
        }
    }
 
    return status;
}