Skip to main content

​
How Discovery Works

  1. Subscriber Connects: When a network subscriber is created, it sends a DiscoveryMessage on the _discovery channel
  2. Publisher Responds: TopicManager’s discovery thread receives the message and matches it to registered publishers
  3. Network Enable: Publisher’s network transport is automatically enabled
  4. Keep-Alive: Subscriber sends keep-alive messages every 20 seconds
  5. Cleanup: If keep-alive expires (60s timeout), network is automatically disabled

​
Discovery Message

The discovery protocol uses a simple message format that is serialized to bytes and sent over the _discovery channel: 
#[repr(C)]
pub struct DiscoveryMessage {
    pub topic_hash: u64,              // Fast topic matching
    pub keep_alive_timeout_secs: u32, // Default 60s
    pub subscriber_id: u64,           // Unique identifier
}

​
Message Components

  • topic_hash: A 64-bit hash computed from the topic name. This enables fast topic matching without string comparisons. The hash is computed using a deterministic algorithm from the topic name, allowing TopicManager to quickly identify which publisher should respond to a discovery message.
  • keep_alive_timeout_secs: The timeout duration in seconds after which a subscriber is considered disconnected if no keep-alive message is received. The default is 60 seconds. This value is set automatically by the subscriber when it creates the discovery message.
  • subscriber_id: A unique 64-bit identifier for the subscriber. This ID is generated when the subscriber is created and is used to track individual subscriber connections. Multiple subscribers to the same topic will have different IDs.

​
Serialization

Discovery messages are serialized to bytes using the SerializableMessage trait. The #[repr(C)] attribute ensures a consistent memory layout across different platforms, making the serialization straightforward and efficient.

​
Message Flow

  1. Subscriber sends discovery: When a network subscriber is created, it automatically serializes a DiscoveryMessage and sends it to the _discovery channel via Zenoh.
  2. TopicManager receives: TopicManager’s discovery thread continuously listens on the _discovery channel for incoming messages.
  3. Topic matching: TopicManager computes the hash for each registered publisher’s topic and compares it with the topic_hash in the discovery message.
  4. Network enable: When a match is found, TopicManager enables network transport for the corresponding publisher by setting an atomic flag.
  5. Keep-alive tracking: The subscriber’s ID and current timestamp are stored in TopicManager’s active subscribers map, which is used for keep-alive management.
Topic hashing enables fast topic matching without string comparisons. The hash is computed from the topic name using a deterministic algorithm, allowing O(1) lookup performance when matching discovery messages to publishers.
Discovery messages are sent on the _discovery channel, which is a reserved topic name. Do not use this channel for your own messages, as it will interfere with the discovery protocol.

​
Keep-Alive Management

​
How Keep-Alive Works

  1. Initial Discovery: Subscriber sends discovery message on creation
  2. Periodic Updates: Subscriber sends keep-alive every 20 seconds
  3. Timeout: If no keep-alive received for 60 seconds, subscriber is considered disconnected
  4. Cleanup: TopicManager’s cleanup thread runs every 10 seconds to remove expired subscribers
  5. Network Disable: When no active subscribers remain, publisher’s network is automatically disabled

​
Keep-Alive Configuration

Keep-alive timeout is configurable per subscriber: 
// DiscoveryMessage includes keep_alive_timeout_secs
// Default is 60 seconds
// This is set automatically by the subscriber
The 60-second timeout with 20-second keep-alive intervals provides a good balance between responsiveness and network efficiency. Subscribers that disconnect are detected within 60 seconds.

​
Next Steps

Transport Modes

Learn about network vs local transport

Overview

Return to TopicManager overview

API Reference

Browse the complete API documentation

Best Practices

Learn recommended usage patterns