Relayed GossipSub topics

This page shows how to make the server carry GossipSub topics that belong to other applications, with pubsub.relay_topics.

Why a server needs this

GossipSub forwards a topic only through peers that announce it. If a service publishes on a topic and an app subscribes to it, and each is connected only to your server, they exchange nothing on that topic unless your server announces it too. A bootstrap server that most peers connect to is the usual place this bites.

For example, a bootstrap server shared by OverMedia and the overnode app should relay OverMedia’s /overmedia/service-announce topic. Otherwise the app does not hear OverMedia’s announcements, and has to find the service another way, such as a DHT lookup.

Configure it

/etc/ricochet/config.yaml

pubsub:
  relay_topics:
    - /overmedia/service-announce

The default is an empty list, which relays nothing. There is no command-line flag.

For each listed topic, the server joins the topic and relays it: it takes part in the topic’s mesh and forwards its messages, but does not subscribe, so messages are never delivered to the server itself.

Rules:

• An empty topic name, or a topic listed twice, is a startup error.
• A topic the server already uses itself (for example /sf-network/services/announce) is skipped with a warning. It is forwarded anyway, because the server already takes part in it.
• A topic that cannot be joined is skipped with a warning; the others are still relayed.

Check it works

At startup, after its own services have started, the server logs:

• relaying topic with the topic name, once per relayed topic.
• not relaying topic with the topic and error, for each one skipped.
• some topics are not relayed with the combined error, if any were skipped.
• relaying pubsub topics with the list actually being relayed.

grep -E 'relaying|not relaying' /var/log/ricochet/stdout.log

The real test is end to end: a subscriber connected only to this server receives messages from a publisher also connected only to this server.

Troubleshooting

• invalid config: relay_topics lists "..." twice or relay_topics must not contain an empty topic: fix the list.
• A listed topic shows as not relaying topic: read the error on that line. If the server already uses the topic, nothing needs to change.
• Messages still do not arrive: both ends must be connected to this server (or to peers that also carry the topic), and the publisher’s messages must pass GossipSub’s signature checks.