Protocols¶

A protocol is a live topic where nodes actively talk back to each other, not just receive data. Unlike a plain data-sync topic — where one side exports records and the other imports them — a protocol topic defines a round-trip conversation: a node can respond to a received event and influence the sender’s behaviour.

Protocols are built on the same ip.topic infrastructure as any other topic. The distinction is semantic: a protocol carries coordination signals, not business records.

Heartbeat & Presence¶

The only built-in core protocol. Every Odoo Sync instance automatically subscribes to and publishes on the heartbeat topic.

What it does

Each gateway broadcasts a lightweight presence payload at a regular interval (default: every 5 minutes). The payload contains the sender’s PeerID and a timestamp. When a remote node receives a heartbeat from a peer it has pending events for, it immediately flushes those events rather than waiting for the next scheduled delivery cycle.

Why it matters

Without heartbeat, a node that goes offline and comes back would have to wait for the postman cron before receiving queued events. With heartbeat, the recovery is nearly instant: the moment the returning node broadcasts its presence, the gateway dispatches the accumulated outbox.

Presence state

ip.node.last_seen is stamped on every incoming heartbeat and on successful sync completion. ip.node.is_online is True when last_seen is less than 3 minutes ago.

A built-in Reaper cron fires every 5 minutes. Any node whose ip.node.last_seen has gone stale is marked offline, ip.node.is_online is cleared, and retry attempts are paused. When the node comes back and its next heartbeat arrives, last_seen is updated and delivery resumes automatically.

Sync ▸ Network ▸ Nodes shows a live is_online badge for each node, updated in real time via bus.bus on every heartbeat.

Outbound events routed with routing_mode = direct that are queued for an offline peer are held in routing_state = pending. The moment the peer’s next heartbeat is received, the gateway resumes delivery automatically — no manual intervention required.

Future Protocols¶

The following protocols are planned for future core releases.

Acknowledgement

A receiver sends an explicit ack event back to the sender after an inbound event has been successfully mapped to an Odoo record. This allows the sender to distinguish between “delivered to the network” and “confirmed written to the remote database” — a much stronger delivery guarantee than the current routing_state: sent.