bridge_sync.cpp File Reference

Implements the controller-side bridge handshake state machine. More...

#include "communication/bridge_sync.hpp"
#include "communication/constants/config.hpp"
#include "communication/serializer.hpp"
#include "util/saturating_time.hpp"

Include dependency graph for bridge_sync.cpp:

Functions
void	BridgeSync::begin ()
	Mark the bridge as out of sync and send the initial BOOT.
void	BridgeSync::restartFromBridgeBoot ()
	Re-open the handshake after the bridge explicitly requested a runtime resync.
void	BridgeSync::tick (uint16_t elapsed_ms)
	Advance the bridge synchronization state machine.
void	BridgeSync::onRequestDetailsServed ()
	Record that REQUEST_DETAILS has just been served.
void	BridgeSync::onRequestStateServed ()
	Record that REQUEST_STATE has just been served.
auto	BridgeSync::allowsStateRequests () -> bool
	Return whether REQUEST_STATE may be served safely right now.
auto	BridgeSync::allowsMutatingCommands () -> bool
	Return whether inbound bridge commands may mutate controller state.

Detailed Description

Implements the controller-side bridge handshake state machine.

Author

Jacopo Labardi (labodj)

Copyright 2026 Jacopo Labardi

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Function Documentation

allowsMutatingCommands()

auto BridgeSync::allowsMutatingCommands

(

)

-> bool

Return whether inbound bridge commands may mutate controller state.

Mutating commands stay blocked until the bridge completed the REQUEST_DETAILS -> REQUEST_STATE handshake after the latest boot.

Returns

true if mutating commands are currently trusted.

false if the handshake is still incomplete.

Here is the call graph for this function:

Here is the caller graph for this function:

allowsStateRequests()

auto BridgeSync::allowsStateRequests

(

)

-> bool

Return whether REQUEST_STATE may be served safely right now.

State snapshots are blocked while the bridge still has to request details first, otherwise it could interpret a fresh state using a stale topology model.

Returns

true if state requests are currently safe to serve.

false if the bridge still needs details first.

Here is the call graph for this function:

Here is the caller graph for this function:

begin()

void BridgeSync::begin

(

)

Mark the bridge as out of sync and send the initial BOOT.

This is called whenever the controller starts up. From that moment on the bridge must ask for REQUEST_DETAILS and REQUEST_STATE before controller-side mutating commands are trusted.

Here is the call graph for this function:

Here is the caller graph for this function:

onRequestDetailsServed()

void BridgeSync::onRequestDetailsServed

(

)

Record that REQUEST_DETAILS has just been served.

When the bridge is waiting for details this transitions the handshake into the phase where a subsequent REQUEST_STATE is expected. When already synchronized this remains a harmless read-only refresh.

Here is the call graph for this function:

Here is the caller graph for this function:

onRequestStateServed()

void BridgeSync::onRequestStateServed

(

)

Record that REQUEST_STATE has just been served.

This closes the startup handshake only when the bridge was already in the AwaitBridgeState phase of the current synchronization session.

Here is the call graph for this function:

Here is the caller graph for this function:

restartFromBridgeBoot()

void BridgeSync::restartFromBridgeBoot

(

)

Re-open the handshake after the bridge explicitly requested a runtime resync.

Unlike begin(), this helper must not emit another BOOT back to the bridge. It only resets the controller-side trust gate so the caller can immediately serve fresh details and state in response to the bridge BOOT.

Here is the call graph for this function:

Here is the caller graph for this function:

tick()

void BridgeSync::tick

(

uint16_t

elapsed_ms

)

Advance the bridge synchronization state machine.

This hot-path helper emits periodic PING_ payloads once the bridge is synchronized, retries BOOT while waiting for REQUEST_DETAILS, and times out back to the boot phase if the bridge stalls after requesting details but before requesting state.

Parameters

elapsed_ms

Milliseconds elapsed since the previous bridge housekeeping pass.

Here is the call graph for this function:

Here is the caller graph for this function: