Service discovery

This page explains how Ricochet servers learn about each other: what each server publishes, how often, and when the others stop listing it.

Two topics

Every server joins two GossipSub topics at startup:

Topic	Message	Sent every
/sf-network/services/announce	Full announcement	intervals.service_announcement_min (60 minutes by default)
/sf-network/services/heartbeat	Health verdict	intervals.health_check_min (5 minutes by default)

Both are sent once at startup as well. The development preset shortens the intervals to 1 minute and 30 seconds.

/etc/ricochet/config.yaml

intervals:
  service_announcement_min: 60
  health_check_min: 5

The announcement carries the server’s peer ID, its capabilities (store-and-forward, mailbox, document-sync), its storage budget, its retention policy, its region, its listen port, whether its last self-check passed, its uptime score and a timestamp.

The region is a label you set; it defaults to default:

/etc/ricochet/config.yaml

server:
  region: eu-west

The heartbeat carries only the peer ID, the health verdict, the uptime score and a timestamp.

Each message is accepted only from the server it names. GossipSub signs every message (the node runs strict signing), and a message whose signer is not the server named in it is rejected.

The self-check and the uptime score

Every health_check_min the server runs the same readiness checks as /readyz (today, a PostgreSQL ping) and publishes the verdict as a heartbeat. It runs one check before its first announcement, so even that carries a measured score.

The uptime score is the share of the last 288 checks that passed: 24 hours at the default 5-minute interval. Change the interval and the window changes with it.

A failed check is logged as self-check failed with the error.

When a server drops out

Other servers keep an entry for each server they have heard announce, refresh it from each heartbeat, and list it as available only while both of these hold:

• Its last reported check passed. A server that reports a failed check leaves the list at that heartbeat.
• It has been heard from within the last two hours. A server that goes silent drops out two hours after its last message.

A heartbeat from a server that has not announced yet is ignored until it announces. Available servers are ordered by uptime score, highest first.

Because heartbeats refresh the entry, a healthy server never goes stale between hourly announcements.

What it takes to be discovered

• GossipSub only carries a message between peers that are connected and share the topic. Servers find each other when they are connected, directly or through peers that also join these topics. Bootstrap peers are the usual way to connect your servers. See DHT & bootstrap peers.
• The registry has no on/off switch: every server joins both topics.

Check it works

At startup the server logs registry started with both topic names, the health-check interval and whether the first check passed. It also logs joined topic for each topic it joins.

At DEBUG level (--development), it logs published server announcement, published heartbeat with the verdict and score, and discovered server when another server’s announcement arrives. A message that fails validation is logged at WARN as rejected message with the topic and sender.

Troubleshooting

• A server never appears to the others: check that they are connected, for example through shared bootstrap peers. GossipSub does not route across servers that have no path between them.
• A server keeps dropping out: its self-check is failing. Look for self-check failed in its log and check /readyz. See Health & readiness.
• failed to publish announcement or failed to publish heartbeat: GossipSub refused the publish; the log line carries the error. The server tries again on the next interval.