hive_discovery/
types.rs

1use serde::{Deserialize, Serialize};
2use std::collections::{BTreeMap, BTreeSet, HashMap};
3use std::net::IpAddr;
4use std::net::SocketAddr;
5
6/// Represents various events that occur during the service discovery process.
7#[derive(Clone, Debug)]
8pub enum DiscoveryEvent {
9    /// A new service has been found, or an existing service's information has been updated.
10    /// Contains the details of the discovered or updated service.
11    ServiceFound(DiscoveryServiceDetails),
12    /// A service has gone offline or become unavailable.
13    /// The `String` parameter is the full instance name of the lost service.
14    ServiceLost(String),
15    /// The service discovery process has successfully started.
16    DiscoveryStarted,
17    /// The service discovery process has stopped.
18    DiscoveryStopped,
19}
20
21/// Represents the current operational status of the service discovery component.
22#[derive(Debug, Clone, Copy, PartialEq)]
23pub enum DiscoveryServiceStatus {
24    /// The service is stopped and not performing any discovery or registration.
25    Stopped,
26    /// The service is actively running, discovering and/or registering services.
27    Running,
28    /// The service is in the process of stopping.
29    Stopping,
30}
31
32/// Detailed information about a discovered remote service.
33///
34/// This structure contains metadata obtained from network discovery,
35/// such as mDNS/DNS-SD. It's designed to be serializable and hashable.
36#[derive(Clone, Debug, Serialize, Deserialize, Hash, PartialEq, Eq)]
37pub struct DiscoveryServiceDetails {
38    /// The type of the service (e.g., `"_http._tcp.local."`), specifying the protocol and domain.
39    pub service_type: String,
40    /// The unique instance name of the service (e.g., `"My Web Server._http._tcp.local."`).
41    /// This distinguishes different instances of the same service type.
42    pub instance_name: String,
43    /// The domain name for the service, typically a local network domain like `".local."`.
44    pub domain_name: String,
45    /// The hostname of the machine providing the service. May be `None` if not available.
46    pub host_name: Option<String>,
47    /// A set of IP addresses associated with the service.
48    /// `BTreeSet` is used to ensure consistent ordering for hashing and comparison.
49    pub addresses: BTreeSet<IpAddr>,
50    /// A set of socket addresses (IP address and port) for the service.
51    /// `BTreeSet` is used for consistent ordering.
52    pub socket_addresses: BTreeSet<SocketAddr>,
53    /// The network port on which the service is listening.
54    pub port: u16,
55    /// A map of additional properties (TXT records in mDNS) associated with the service.
56    /// `BTreeMap` is used for consistent ordering.
57    pub properties: BTreeMap<String, String>,
58    /// Timestamp (seconds since UNIX_EPOCH) of when this service was last seen or updated.
59    /// Used to determine service liveness and for TTL management.
60    pub last_seen: Option<u64>,
61}
62
63/// Configuration for registering a local service and for discovery behavior.
64#[derive(Clone, Debug)]
65pub struct LocalServiceConfig {
66    /// The type of service to be broadcast and discovered.
67    /// Example: `"_myapp-filetransfer._tcp.local."`.
68    pub service_type: String,
69
70    /// The network port on which the local service is listening.
71    pub port: u16,
72
73    /// An optional custom instance name for the service.
74    /// If not provided, a name might be generated or a default used.
75    /// Example: `"My Custom Service Name"`. The full mDNS name will be constructed from this.
76    pub instance_name: String,
77
78    /// A collection of additional properties (metadata) to be broadcast with the service.
79    /// These are often published as TXT records in mDNS.
80    pub properties: Option<HashMap<String, String>>,
81
82    /// Service Time-To-Live (TTL) in seconds.
83    /// This is the maximum time a discovered service is considered online without a refresh
84    /// by the remote peer. Local cleanup of stale services also uses this.
85    pub service_ttl: u64,
86
87    /// mDNS response delay range in milliseconds: `(min_ms, max_ms)`.
88    /// Helps prevent network congestion (response storms) when multiple devices
89    /// respond to mDNS queries simultaneously. A random delay within this range is chosen.
90    pub mdns_response_delay_ms: (u64, u64),
91
92    /// Discovery refresh interval in seconds.
93    /// The interval at which the discovery component might re-query or re-announce
94    /// to keep service lists fresh. (Note: mDNS has its own refresh mechanisms).
95    pub refresh_interval: u64,
96}
hive_discovery/types.rs

hive_discovery/
types.rs
