Connection system source files
Comprehensive source file listing for the connection system
Comprehensive reference of all source files related to node connections in Korall Engineering™.
Implementation Status Legend
- Implemented - Feature is complete and functional
- Partial - Core functionality exists, some features incomplete
- Planned - Documented but not yet implemented
- Testing - For development/testing purposes only
Library Overview
| Library | Purpose | Location |
|---|---|---|
| libcomms | Core communication infrastructure | src/libs/libcomms/ |
| libpair | Discovery, pairing, trust management | src/libs/libpair/ |
| libsec | Security, keys, encryption | src/libs/libsec/ |
| libnode | Node base classes | src/libs/libnode/ |
| libservice | Service wrappers | src/libs/libservice/ |
| libwidgets | Connection UI widgets | src/libs/libwidgets/ |
| libdebug | Debug widgets | src/libs/libdebug/ |
The tables below give the file name only. The line above or below each table gives the folder of the files, relative to the folder of the library.
1. Core Communication (libcomms)
Comms Engine
The files are in comms/.
| File | Purpose | Status |
|---|---|---|
Comms.hpp |
Top-level communication manager | Implemented |
Comms.cpp |
Manages channels, courier registration | Implemented |
CommsChannel.hpp |
Per-carrier communication channel | Implemented |
CommsChannel.cpp |
Packet sending/receiving, session control | Implemented |
CommsSession.hpp |
Active peer communication session | Implemented |
CommsSession.cpp |
Handshake, nonce, encryption state | Implemented |
CommsSessionDirectory.hpp |
Session lookup directory | Implemented |
CommsSessionDirectory.cpp |
Session ID to session mapping | Implemented |
CommsSignature.hpp |
Minimal peer identification (8-byte) | Implemented |
CommsSignature.cpp |
Shorthand + address for quick ID | Implemented |
CommsSessionIDType.hpp |
Session ID type definition | Implemented |
Handshake & Protocol
The files are in comms/.
| File | Purpose | Status |
|---|---|---|
HandshakeState.hpp |
3-way handshake state machine | Implemented |
HandshakeState.cpp |
Initiator/adherent role tracking | Implemented |
Multimagic.hpp |
Protocol magic values (SYN, ACK, etc.) | Implemented |
Multimagic.cpp |
Maps magic to handshake steps | Implemented |
ProtocolMagic.hpp |
Protocol magic constants | Implemented |
IDDuel.hpp |
ID comparison for conflict resolution | Implemented |
IDDuel.cpp |
Determines winner when both initiate | Implemented |
Magic Values (Multimagic.hpp):
MULTIMAGIC_IDLE- No operationMULTIMAGIC_SYN- Session initiationMULTIMAGIC_SYNACK- Session acknowledgmentMULTIMAGIC_ACK- Connection confirmedMULTIMAGIC_LAN_ANNOUNCE- LAN broadcast discoveryMULTIMAGIC_LAN_ANNOUNCE_ACK- LAN discovery response
Packet Management
The files are in comms/.
| File | Purpose | Status |
|---|---|---|
PacketReadState.hpp |
Incoming packet state | Implemented |
PacketReadState.cpp |
Packet parsing state machine | Implemented |
PacketSendState.hpp |
Outgoing packet state | Implemented |
PacketSendState.cpp |
Packet serialization | Implemented |
Network Quality & Reliability
The files are in comms/.
| File | Purpose | Status |
|---|---|---|
FlowControl.hpp |
Flow control state machine | Implemented |
FlowControl.cpp |
Good/Bad modes, dynamic rate | Implemented |
ReliabilitySystem.hpp |
Packet tracking and statistics | Implemented |
ReliabilitySystem.cpp |
RTT, bandwidth, sequence numbers | Implemented |
NetworkOptimizer.hpp |
Network optimization hints | Implemented |
NetworkOptimizer.cpp |
Bandwidth adaptation | Implemented |
IConnectionStatus.hpp |
Connection status interface | Implemented |
IConnectionStatus.cpp |
Status reporting contract | Implemented |
2. Carriers (libcomms)
Carrier Base
The files are in comms/carriers/.
| File | Purpose | Status |
|---|---|---|
CommsCarrier.hpp |
Abstract carrier base class | Implemented |
CommsCarrier.cpp |
Connection state, send scheduling | Implemented |
Carrier Implementations
The files are in comms/carriers/.
| File | Purpose | Status |
|---|---|---|
CommsCarrierUDP.hpp |
UDP/IP transport | Implemented |
CommsCarrierUDP.cpp |
QUdpSocket management | Implemented |
CommsCarrierLocal.hpp |
In-process loopback | Testing |
CommsCarrierLocal.cpp |
For unit testing | Testing |
CommsCarrierBluetooth.hpp |
Bluetooth transport | Planned |
CommsCarrierBluetooth.cpp |
BLE communication | Planned |
Carrier Addresses
| File | Purpose | Status |
|---|---|---|
CarrierAddress.hpp |
Abstract address base | Implemented |
CarrierAddress.cpp |
Serialization interface | Implemented |
CarrierAddressType.hpp |
Address type enumeration | Implemented |
CarrierAddressType.cpp |
UDP, Bluetooth, Local types | Implemented |
CarrierAddressUDP.hpp |
IPv4/IPv6 + port addressing | Implemented |
CarrierAddressUDP.cpp |
UDP address implementation | Implemented |
CarrierAddressBluetooth.hpp |
Bluetooth device addressing | Planned |
CarrierAddressBluetooth.cpp |
BLE address implementation | Planned |
CarrierAddressLocal.hpp |
In-process addressing | Testing |
CarrierAddressLocal.cpp |
Local address implementation | Testing |
CarrierAddressFactory.hpp |
Address factory | Implemented |
CarrierAddressFactory.cpp |
Creates from serialized data | Implemented |
CarrierAddressUDPWidget.hpp |
UDP address UI | Implemented |
CarrierAddressUDPWidget.cpp |
Address input/display | Implemented |
The folders of the files:
comms/address/: CarrierAddress, CarrierAddressType, CarrierAddressUDP, CarrierAddressBluetooth, CarrierAddressLocal, CarrierAddressFactorycomms/address/ui/: CarrierAddressUDPWidget
3. Couriers (libcomms)
Courier Base
The files are in comms/couriers/.
| File | Purpose | Status |
|---|---|---|
Courier.hpp |
Abstract courier base | Implemented |
Courier.cpp |
Registration, scheduling | Implemented |
CourierMandate.hpp |
Transmission requirements | Implemented |
CourierMandate.cpp |
Priority, frequency, reliability | Implemented |
CourierSet.hpp |
Courier collection | Implemented |
CourierSet.cpp |
Scheduling across couriers | Implemented |
Specific Couriers
The files are in comms/couriers/.
| File | Purpose | Status |
|---|---|---|
DiscoveryCourier.hpp |
Discovery protocol | Implemented |
DiscoveryCourier.cpp |
Node discovery messages | Implemented |
SensorsCourier.hpp |
Sensor data transfer | Implemented |
SensorsCourier.cpp |
Sensor readings AgentāRemote | Implemented |
AgentStateCourier.hpp |
Main state synchronization | Implemented |
AgentStateCourier.cpp |
Agent state, idle packets | Implemented |
Blob Courier (Large Data Transfer)
The files are in comms/couriers/blob/.
| File | Purpose | Status |
|---|---|---|
BlobCourier.hpp |
Large binary data transfer | Implemented |
BlobCourier.cpp |
Chunking, reassembly, retry | Implemented |
Blob.hpp |
Blob data container | Implemented |
Blob.cpp |
Binary data with metadata | Implemented |
BlobChunk.hpp |
Individual blob chunk | Implemented |
BlobChunk.cpp |
Chunk tracking | Implemented |
BlobFuture.hpp |
Async transfer result | Implemented |
BlobFuture.cpp |
Progress, completion events | Implemented |
Role-Specific Courier Sets
The files are in comms/couriers/sets/.
| File | Purpose | Status |
|---|---|---|
AgentCourierSet.hpp |
Agent-side couriers | Implemented |
AgentCourierSet.cpp |
State, sensors, blob | Implemented |
AgentClientCourierSet.hpp |
Agent as client | Implemented |
AgentClientCourierSet.cpp |
When connecting to Hub | Implemented |
RemoteCourierSet.hpp |
Remote-side couriers | Implemented |
RemoteCourierSet.cpp |
Commands, control | Implemented |
RemoteClientCourierSet.hpp |
Remote as client | Implemented |
RemoteClientCourierSet.cpp |
When connecting to Agent | Implemented |
HubCourierSet.hpp |
Hub-side couriers | Implemented |
HubCourierSet.cpp |
Coordination messages | Implemented |
HubClientCourierSet.hpp |
Hub as client | Implemented |
HubClientCourierSet.cpp |
When connecting to nodes | Implemented |
4. Messages & Sync (libcomms)
Message Types
The files are in comms/messages/.
| File | Purpose | Status |
|---|---|---|
MessageType.hpp |
Message type enumeration | Implemented |
MessageType.cpp |
Type registry | Implemented |
SensorsMessage.hpp |
Sensor data message | Implemented |
SensorsMessage.cpp |
Serialization | Implemented |
AgentMode.hpp |
Agent operation mode | Implemented |
AgentMode.cpp |
Mode enumeration | Implemented |
Synchronization
The files are in comms/sync/.
| File | Purpose | Status |
|---|---|---|
ISyncParameter.hpp |
Sync parameter interface | Implemented |
ISyncParameter.cpp |
Parameter contract | Implemented |
SyncParameter.hpp |
Templated sync parameter | Implemented |
SyncContext.hpp |
Sync state context | Implemented |
SyncContext.cpp |
Parameter collection | Implemented |
5. Discovery (libpair)
Discovery Client
The files are in discovery/.
| File | Purpose | Status |
|---|---|---|
DiscoveryClient.hpp |
Main discovery orchestrator | Implemented |
DiscoveryClient.cpp |
HTTP + LAN discovery | Implemented |
DiscoveryMandate.hpp |
Desired discovery state | Implemented |
DiscoveryMandate.cpp |
Channel enable/disable | Implemented |
DiscoveryStatus.hpp |
Actual discovery state | Implemented |
DiscoveryStatus.cpp |
Per-channel status | Implemented |
LAN Discovery
The files are in discovery/.
| File | Purpose | Status |
|---|---|---|
LANDiscovery.hpp |
UDP broadcast discovery | Implemented |
LANDiscovery.cpp |
LAN_ANNOUNCE packets | Implemented |
Discovery Server
The files are in discovery/.
| File | Purpose | Status |
|---|---|---|
DiscoveryServer.hpp |
Server-side discovery | Implemented |
DiscoveryServer.cpp |
Discovery request handling | Implemented |
DiscoveryServerSession.hpp |
Server session | Implemented |
DiscoveryServerSession.cpp |
Per-client session | Implemented |
DiscoveryServerEntry.hpp |
Server registry entry | Implemented |
DiscoveryServerEntry.cpp |
Node registration data | Implemented |
Discovery UI
The files are in discovery/ping/.
| File | Purpose | Status |
|---|---|---|
PingWidget.hpp |
Ping status widget | Implemented |
PingWidget.cpp |
Visual ping display | Implemented |
6. Pairing & Trust (libpair)
Pairing Activities
| File | Purpose | Status |
|---|---|---|
PairingMenuActivity.hpp |
Pairing method selection | Implemented |
PairingMenuActivity.cpp |
Menu UI | Implemented |
PairingActivity.hpp |
Main pairing activity | Implemented |
PairingActivity.cpp |
Pairing flow coordinator | Implemented |
NetworkPairingActivity.hpp |
Network-based pairing | Implemented |
NetworkPairingActivity.cpp |
LAN/Zoo pairing UI | Implemented |
CameraPairingActivity.hpp |
QR code pairing | Implemented |
CameraPairingActivity.cpp |
Camera scanning UI | Implemented |
CameraPairingWidget.hpp |
Camera preview widget | Implemented |
CameraPairingWidget.cpp |
QR scanning logic | Implemented |
The folders of the files:
pairing/: PairingMenuActivity, PairingActivitypairing/network/: NetworkPairingActivitypairing/camera/: CameraPairingActivity, CameraPairingWidget
Trust Management
The files are in pairing/trust/.
| File | Purpose | Status |
|---|---|---|
PairingTrustActivity.hpp |
Trust assignment UI | Implemented |
PairingTrustActivity.cpp |
Trust level selection | Implemented |
TrustLevel.hpp |
Trust level enumeration | Implemented |
TrustLevel.cpp |
IGNORED, TRUST, BLOCK | Implemented |
TrustSymbolWidget.hpp |
Trust icon display | Implemented |
TrustSymbolWidget.cpp |
Visual trust indicator | Implemented |
Pairing Lists
The files are in pairing/list/.
| File | Purpose | Status |
|---|---|---|
PairingListWidget.hpp |
Peer list UI | Implemented |
PairingListWidget.cpp |
List display | Implemented |
PairingListModel.hpp |
List data model | Implemented |
PairingListModel.cpp |
Associate data source | Implemented |
PairingEditButtonDelegate.hpp |
List item delegate | Implemented |
PairingEditButtonDelegate.cpp |
Edit button rendering | Implemented |
7. Associate & Address Book (libpair)
Associate
The files are in address/.
| File | Purpose | Status |
|---|---|---|
Associate.hpp |
Known peer representation | Implemented |
Associate.cpp |
ID, name, type, role, trust | Implemented |
AddressList.hpp |
Peer address tracking | Implemented |
AddressList.cpp |
Address scoring, selection | Implemented |
AddressEntry.hpp |
Single address with stats | Implemented |
AddressEntry.cpp |
Success/failure counts | Implemented |
TrustList.hpp |
Trust level storage | Implemented |
TrustList.cpp |
Per-peer trust settings | Implemented |
LocalAddressList.hpp |
Local addresses | Implemented |
LocalAddressList.cpp |
This node's addresses | Implemented |
Address Book
The files are in discovery/.
| File | Purpose | Status |
|---|---|---|
AddressBook.hpp |
Persistent peer storage | Implemented |
AddressBook.cpp |
Async load/save, queries | Implemented |
8. Delivery (libpair)
Agent Delivery
The files are in delivery/.
| File | Purpose | Status |
|---|---|---|
AgentDeliveryActivity.hpp |
Agent setup flow | Implemented |
AgentDeliveryActivity.cpp |
Agent initialization UI | Implemented |
AgentBaptismActivity.hpp |
Agent identity creation | Implemented |
AgentBaptismActivity.cpp |
Key generation UI | Implemented |
AgentSipAndSeeActivity.hpp |
Agent intro display | Implemented |
AgentSipAndSeeActivity.cpp |
Shows identity info | Implemented |
Control/Remote Delivery
The files are in delivery/.
| File | Purpose | Status |
|---|---|---|
ControlDeliveryActivity.hpp |
Remote setup flow | Implemented |
ControlDeliveryActivity.cpp |
Remote initialization UI | Implemented |
ControlBaptismActivity.hpp |
Remote identity creation | Implemented |
ControlBaptismActivity.cpp |
Key generation UI | Implemented |
ControlSipAndSeeActivity.hpp |
Remote intro display | Implemented |
ControlSipAndSeeActivity.cpp |
Shows identity info | Implemented |
Delivery Management
The files are in delivery/.
| File | Purpose | Status |
|---|---|---|
BirthControl.hpp |
Node identity validation | Implemented |
BirthControl.cpp |
Ensures key/identity setup | Implemented |
IdentityMenuActivity.hpp |
Identity options menu | Implemented |
IdentityMenuActivity.cpp |
Identity management UI | Implemented |
ConnectionWidget.hpp |
Connection status widget | Implemented |
ConnectionWidget.cpp |
Status display | Implemented |
ConnectionManager.hpp |
Connection orchestrator | Implemented |
ConnectionManager.cpp |
Connection lifecycle | Implemented |
9. Connection Activities (libpair)
The files are in connection/.
| File | Purpose | Status |
|---|---|---|
ConnectionActivity.hpp |
Main connection UI | Implemented |
ConnectionActivity.cpp |
Metrics display | Implemented |
ConnectionStatusWidget.hpp |
Status indicator | Implemented |
ConnectionStatusWidget.cpp |
Visual status | Implemented |
SignalStrengthWidget.hpp |
Signal strength bars | Implemented |
SignalStrengthWidget.cpp |
Quality visualization | Implemented |
10. Security (libsec)
Key Management
The files are in security/.
| File | Purpose | Status |
|---|---|---|
Key.hpp |
Public key wrapper | Implemented |
Key.cpp |
Key operations | Implemented |
KeyPrivate.hpp |
Private key wrapper | Implemented |
KeyPrivate.cpp |
Signing operations | Implemented |
KeyFactory.hpp |
Key generation | Implemented |
KeyFactory.cpp |
RSA key pair creation | Implemented |
KeyStore.hpp |
Persistent key storage | Implemented |
KeyStore.cpp |
Thread-safe key store | Implemented |
KeySecurityPolicy.hpp |
Key security rules | Implemented |
KeySecurityPolicy.cpp |
Policy enforcement | Implemented |
Identity
The files are in security/.
| File | Purpose | Status |
|---|---|---|
PortableNodeID.hpp |
Portable identity of a node | Implemented |
PortableNodeID.cpp |
Node ID serialization | Implemented |
PortableSentientID.hpp |
Portable identity of a sentient | Implemented |
PortableSentientID.cpp |
Sentient ID serialization | Implemented |
ISigningKey.hpp |
Signing interface | Implemented |
SecurityConstants.hpp |
Security constants | Implemented |
SecurityConstants.cpp |
Algorithm parameters | Implemented |
SecurityConstantsPrivate.hpp |
Internal constants | Implemented |
11. Node Framework (libnode)
| File | Purpose | Status |
|---|---|---|
Node.hpp |
Base node class | Implemented |
Node.cpp |
Comms, AddressBook, KeyStore | Implemented |
NodeType.hpp |
Node type enum | Implemented |
NodeType.cpp |
Agent, Remote, Hub, Zoo | Implemented |
NodeRole.hpp |
Node role enum | Implemented |
NodeRole.cpp |
Agent, Control | Implemented |
LocalIdentityStore.hpp |
Local identity storage | Implemented |
LocalIdentityStore.cpp |
Persistent identity | Implemented |
IContextProvider.hpp |
Context provider interface | Implemented |
IContextProvider.cpp |
Service access | Implemented |
NodeFactory.hpp |
Node creation factory | Implemented |
NodeFactory.cpp |
Creates typed nodes | Implemented |
NodeWindow.hpp |
Base node window | Implemented |
NodeWindow.cpp |
Common window behavior | Implemented |
The folders of the files:
node/: Node, NodeType, LocalIdentityStore, IContextProvider, NodeFactory, NodeWindowapp/of libapp: NodeRole
12. Services
| File | Purpose | Status |
|---|---|---|
CommsService.hpp |
Comms lifecycle service | Implemented |
DiscoveryClientService.hpp |
Discovery service | Implemented |
DiscoveryClientService.cpp |
Discovery lifecycle | Implemented |
AddressBookService.hpp |
AddressBook service | Implemented |
AddressBookService.cpp |
Persistence | Implemented |
KeyStoreService.hpp |
KeyStore service | Implemented |
LocalAddressListService.hpp |
Local addresses | Implemented |
The folders of the files:
nodekit/services/of libnodekit: CommsService, KeyStoreService, LocalAddressListServicenode/services/of libnode: DiscoveryClientService, AddressBookService
13. Connection UI Widgets (libwidgets)
| File | Purpose | Status |
|---|---|---|
PeerListItemWidget.hpp |
Peer list row | Partial |
PeerListItemWidget.cpp |
Peer display | Partial |
PeerDetailActivity.hpp |
Peer details view | Partial |
PeerDetailActivity.cpp |
Full peer info | Partial |
ConnectionStatusIndicator.hpp |
Status indicator | Planned |
TrustIconWidget.hpp |
Trust icons | Planned |
TrustSelectorWidget.hpp |
Trust selection | Planned |
ChannelBarWidget.hpp |
Channel quality bars | Planned |
ActivityOrbWidget.hpp |
Activity status orb | Planned |
CapabilityDescriptionWidget.hpp |
Trust capabilities | Planned |
VerificationContextWidget.hpp |
Verification UI | Planned |
The folders of the files:
components/: PeerListItemWidget, ConnectionStatusIndicator, TrustIconWidget, TrustSelectorWidget, ChannelBarWidget, ActivityOrbWidget, CapabilityDescriptionWidget, VerificationContextWidgetactivities/: PeerDetailActivity
Note: Several connection UI widgets are specified in
internal/specs/comms/ui/but not yet implemented.
14. Debug Widgets (libdebug)
| File | Purpose | Status |
|---|---|---|
CarrierDebugWidget.hpp |
Carrier debugging | Implemented |
CarrierDebugWidget.cpp |
Carrier status display | Implemented |
CouriersDebugWidget.hpp |
Courier debugging | Implemented |
CouriersDebugWidget.cpp |
Courier status display | Implemented |
DiscoveryClientDebugWidget.hpp |
Discovery debugging | Implemented |
DiscoveryClientDebugWidget.cpp |
Discovery status | Implemented |
PairingDebugWidget.hpp |
Pairing debugging | Implemented |
PairingDebugWidget.cpp |
Pairing status | Implemented |
The folders of the files:
debug/carrier/: CarrierDebugWidgetdebug/courier/: CouriersDebugWidgetdebug/discovery/: DiscoveryClientDebugWidgetdebug/pairing/: PairingDebugWidget
15. Node-Specific Frameworks
Agent (libagent)
The files are in agent/.
| File | Purpose | Status |
|---|---|---|
Agent.hpp |
Agent node class | Implemented |
Agent.cpp |
Agent implementation | Implemented |
AgentConfig.hpp |
Agent configuration | Implemented |
AgentConfigStore.hpp |
Config persistence | Implemented |
AgentMain.hpp |
Agent main entry | Implemented |
AgentWindow.hpp |
Agent window | Implemented |
AgentMainMenu.hpp |
Agent menu | Implemented |
Remote (libremote)
The files are in remote/.
| File | Purpose | Status |
|---|---|---|
Remote.hpp |
Remote node class | Implemented |
Remote.cpp |
Remote implementation | Implemented |
RemoteMain.hpp |
Remote main entry | Implemented |
RemoteWindow.hpp |
Remote window | Implemented |
RemoteController.hpp |
Control logic | Implemented |
AgentSelectActivity.hpp |
Agent selection UI | Implemented |
AgentListModel.hpp |
Agent list model | Implemented |
ControlUnboxingWizard.hpp |
Setup wizard | Implemented |
Hub (libhub)
The files are in hub/.
| File | Purpose | Status |
|---|---|---|
Hub.hpp |
Hub node class | Implemented |
Hub.cpp |
Hub implementation | Implemented |
HubMain.hpp |
Hub main entry | Implemented |
HubWindow.hpp |
Hub window | Implemented |
HubMainMenu.hpp |
Hub menu | Implemented |
NodesManagementWidget.hpp |
Node management | Implemented |
UtilitiesWidget.hpp |
Hub utilities | Implemented |
Client Framework (libclient, libagentclient)
| File | Purpose | Status |
|---|---|---|
ClientConnectionStatus.hpp |
Client status | Implemented |
ClientConnectionStatus.cpp |
Status tracking | Implemented |
AgentClient.hpp |
Agent client | Implemented |
AgentClient.cpp |
Agent connection | Implemented |
AgentClientWidget.hpp |
Agent client UI | Implemented |
AgentConnectionWidget.hpp |
Connection display | Implemented |
The folders of the files:
client/: ClientConnectionStatusclient/agent/: AgentClient, AgentClientWidget, AgentConnectionWidget
Aspirational Features
The following features are documented or planned but not yet implemented:
| Feature | Location | Status |
|---|---|---|
| Bluetooth carrier | libcomms/carriers | Planned |
| NFC discovery | libpair/discovery | Planned |
| Audio (ultrasonic) discovery | libpair/discovery | Planned |
| Connection UI widgets (spec) | internal/specs/connection-ui | Planned |
| NAT hole punching | internal/specs/network-discovery | Planned (Phase 2) |
| Multi-factor authentication | Pairing flow | Planned |
| Key rotation | CommsSession | Planned |
File Count Summary
| Library | Files | Lines (approx) |
|---|---|---|
| libcomms | ~80 | ~15,000 |
| libpair | ~60 | ~12,000 |
| libsec | ~15 | ~3,000 |
| libnode | ~15 | ~4,000 |
| libservice | ~15 | ~2,000 |
| libwidgets (conn) | ~10 | ~2,000 |
| libdebug (conn) | ~8 | ~1,500 |
| Total | ~200 | ~40,000 |