Sources/SophaxChatCore/Network/MessageTransport.swift

1// MessageTransport.swift
2// SophaxChatCore
3//
4// Pluggable transport layer protocol.
5//
6// SophaxChat's cryptographic layer is completely independent of the physical
7// transport. All message routing goes through WireMessage objects, which are
8// already serialized, signed, and (for targeted messages) encrypted.
9//
10// A transport adapter needs to:
11//   1. Discover peers in its medium (BLE, WiFi, LoRa, audio covert channel, …)
12//   2. Send/broadcast WireMessage objects to one or all peers
13//   3. Notify the delegate of incoming messages and peer state changes
14//
15// Current implementation: MeshManager (MultipeerConnectivity — BLE + WiFi Direct)
16// Future adapters:
17//   - LoRaTransport  — long-range low-bandwidth radio (e.g. TTGO T-Beam)
18//   - AudioTransport — acoustic covert channel via microphone/speaker
19//   - SerialTransport — USB/serial cable for air-gapped transfer
20
21import Foundation
22
23// MARK: - Delegate
24
25/// Callbacks fired by a MessageTransport when peers or messages arrive.
26/// All callbacks MUST be dispatched to the main thread by the transport.
27public protocol MessageTransportDelegate: AnyObject {
28
29    /// A new peer became visible in the transport medium (before identity exchange).
30    func transport(_ transport: any MessageTransport,
31                   didDiscoverPeer peerID: String, withName displayName: String)
32
33    /// A peer is no longer reachable via this transport.
34    func transport(_ transport: any MessageTransport, didLosePeer peerID: String)
35
36    /// A direct transport-layer connection was established (Hello exchange can begin).
37    func transport(_ transport: any MessageTransport, didConnectToPeer peerID: String)
38
39    /// A direct transport-layer connection was torn down.
40    func transport(_ transport: any MessageTransport, didDisconnectFromPeer peerID: String)
41
42    /// A wire message was received from a peer.
43    func transport(_ transport: any MessageTransport,
44                   didReceiveMessage message: WireMessage, fromPeer peerID: String)
45
46    /// A previous `send` call failed to deliver to a peer.
47    func transport(_ transport: any MessageTransport,
48                   sendDidFailForPeer peerID: String, error: Error)
49}
50
51// MARK: - MessageTransport protocol
52
53/// Abstraction over a physical/logical message delivery medium.
54///
55/// Implementations must be thread-safe for `send` and `broadcast` (they may be
56/// called from any thread). All delegate callbacks must be delivered on the main thread.
57public protocol MessageTransport: AnyObject {
58
59    /// The delegate to notify on peer events and inbound messages.
60    var delegate: (any MessageTransportDelegate)? { get set }
61
62    // MARK: Lifecycle
63
64    /// Start advertising and discovering peers.
65    func start()
66
67    /// Stop all peer discovery and advertising. Active connections may be dropped.
68    func stop()
69
70    // MARK: Addressing
71
72    /// Returns `true` if `peerID` is currently directly reachable (no relay needed).
73    func isConnected(peerID: String) -> Bool
74
75    /// Number of directly-connected peers (used to decide direct vs. relay routing).
76    var directPeerCount: Int { get }
77
78    // MARK: Sending
79
80    /// Send a message to a specific peer.
81    /// Throws if the peer is not currently connected or if serialization fails.
82    func send(_ message: WireMessage, toPeerID peerID: String) throws
83
84    /// Broadcast a message to all currently connected peers.
85    /// - Parameter excluding: optionally skip one peer (relay loop prevention).
86    func broadcast(_ message: WireMessage, excluding excludedPeerID: String?) throws
87}
88
89// MARK: - Default broadcast convenience
90
91public extension MessageTransport {
92    /// Broadcast to all peers without exclusion.
93    func broadcast(_ message: WireMessage) throws {
94        try broadcast(message, excluding: nil)
95    }
96}
97
98// MARK: - Future adapter stubs (not yet implemented)
99
100// LoRaTransport will conform to MessageTransport.
101// Minimum viable LoRa implementation requires:
102//   - Serial/Bluetooth connection to a LoRa radio module (e.g. TTGO T-Beam via BLE)
103//   - Packet fragmentation for WireMessage payloads > LoRa MTU (~240 bytes)
104//   - Link-layer acknowledgement (LoRaWAN ACK or custom)
105//   - Long-range mode: typically 1–10 km in open terrain at SF12/BW125
106
107// AudioTransport will conform to MessageTransport.
108// A near-ultrasonic (18–22 kHz) acoustic channel using OFDM or chirp spread spectrum.
109// Achievable in short range (<5 m) with device speakers/mic at ~100 bps.
110// Useful for extreme scenarios (air-gapped rooms, no wireless hardware).