Source Files Reference

Comprehensive source file listing for the connection system

Connection System Source Files

Comprehensive reference of all source files related to node connections in OctoMY™.

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/

1. Core Communication (libcomms)

Comms Engine

File Purpose Status
comms/Comms.hpp Top-level communication manager Implemented
comms/Comms.cpp Manages channels, courier registration Implemented
comms/CommsChannel.hpp Per-carrier communication channel Implemented
comms/CommsChannel.cpp Packet sending/receiving, session control Implemented
comms/CommsSession.hpp Active peer communication session Implemented
comms/CommsSession.cpp Handshake, nonce, encryption state Implemented
comms/CommsSessionDirectory.hpp Session lookup directory Implemented
comms/CommsSessionDirectory.cpp Session ID to session mapping Implemented
comms/CommsSignature.hpp Minimal peer identification (8-byte) Implemented
comms/CommsSignature.cpp Shorthand + address for quick ID Implemented
comms/CommsSessionIDType.hpp Session ID type definition Implemented

Handshake & Protocol

File Purpose Status
comms/HandshakeState.hpp 3-way handshake state machine Implemented
comms/HandshakeState.cpp Initiator/adherent role tracking Implemented
comms/Multimagic.hpp Protocol magic values (SYN, ACK, etc.) Implemented
comms/Multimagic.cpp Maps magic to handshake steps Implemented
comms/ProtocolMagic.hpp Protocol magic constants Implemented
comms/IDDuel.hpp ID comparison for conflict resolution Implemented
comms/IDDuel.cpp Determines winner when both initiate Implemented

Magic Values (Multimagic.hpp):

  • MULTIMAGIC_IDLE - No operation
  • MULTIMAGIC_SYN - Session initiation
  • MULTIMAGIC_SYNACK - Session acknowledgment
  • MULTIMAGIC_ACK - Connection confirmed
  • MULTIMAGIC_LAN_ANNOUNCE - LAN broadcast discovery
  • MULTIMAGIC_LAN_ANNOUNCE_ACK - LAN discovery response

Packet Management

File Purpose Status
comms/PacketReadState.hpp Incoming packet state Implemented
comms/PacketReadState.cpp Packet parsing state machine Implemented
comms/PacketSendState.hpp Outgoing packet state Implemented
comms/PacketSendState.cpp Packet serialization Implemented

Network Quality & Reliability

File Purpose Status
comms/FlowControl.hpp Flow control state machine Implemented
comms/FlowControl.cpp Good/Bad modes, dynamic rate Implemented
comms/ReliabilitySystem.hpp Packet tracking and statistics Implemented
comms/ReliabilitySystem.cpp RTT, bandwidth, sequence numbers Implemented
comms/NetworkOptimizer.hpp Network optimization hints Implemented
comms/NetworkOptimizer.cpp Bandwidth adaptation Implemented
comms/IConnectionStatus.hpp Connection status interface Implemented
comms/IConnectionStatus.cpp Status reporting contract Implemented

2. Carriers (libcomms)

Carrier Base

File Purpose Status
comms/carriers/CommsCarrier.hpp Abstract carrier base class Implemented
comms/carriers/CommsCarrier.cpp Connection state, send scheduling Implemented

Carrier Implementations

File Purpose Status
comms/carriers/CommsCarrierUDP.hpp UDP/IP transport Implemented
comms/carriers/CommsCarrierUDP.cpp QUdpSocket management Implemented
comms/carriers/CommsCarrierLocal.hpp In-process loopback Testing
comms/carriers/CommsCarrierLocal.cpp For unit testing Testing
comms/carriers/CommsCarrierBluetooth.hpp Bluetooth transport Planned
comms/carriers/CommsCarrierBluetooth.cpp BLE communication Planned

Carrier Addresses

File Purpose Status
comms/address/CarrierAddress.hpp Abstract address base Implemented
comms/address/CarrierAddress.cpp Serialization interface Implemented
comms/address/CarrierAddressType.hpp Address type enumeration Implemented
comms/address/CarrierAddressType.cpp UDP, Bluetooth, Local types Implemented
comms/address/CarrierAddressUDP.hpp IPv4/IPv6 + port addressing Implemented
comms/address/CarrierAddressUDP.cpp UDP address implementation Implemented
comms/address/CarrierAddressBluetooth.hpp Bluetooth device addressing Planned
comms/address/CarrierAddressBluetooth.cpp BLE address implementation Planned
comms/address/CarrierAddressLocal.hpp In-process addressing Testing
comms/address/CarrierAddressLocal.cpp Local address implementation Testing
comms/address/CarrierAddressFactory.hpp Address factory Implemented
comms/address/CarrierAddressFactory.cpp Creates from serialized data Implemented
comms/address/ui/CarrierAddressUDPWidget.hpp UDP address UI Implemented
comms/address/ui/CarrierAddressUDPWidget.cpp Address input/display Implemented

3. Couriers (libcomms)

Courier Base

File Purpose Status
comms/couriers/Courier.hpp Abstract courier base Implemented
comms/couriers/Courier.cpp Registration, scheduling Implemented
comms/couriers/CourierMandate.hpp Transmission requirements Implemented
comms/couriers/CourierMandate.cpp Priority, frequency, reliability Implemented
comms/couriers/CourierSet.hpp Courier collection Implemented
comms/couriers/CourierSet.cpp Scheduling across couriers Implemented

Specific Couriers

File Purpose Status
comms/couriers/DiscoveryCourier.hpp Discovery protocol Implemented
comms/couriers/DiscoveryCourier.cpp Node discovery messages Implemented
comms/couriers/SensorsCourier.hpp Sensor data transfer Implemented
comms/couriers/SensorsCourier.cpp Sensor readings Agent→Remote Implemented
comms/couriers/AgentStateCourier.hpp Main state synchronization Implemented
comms/couriers/AgentStateCourier.cpp Agent state, idle packets Implemented

Blob Courier (Large Data Transfer)

File Purpose Status
comms/couriers/blob/BlobCourier.hpp Large binary data transfer Implemented
comms/couriers/blob/BlobCourier.cpp Chunking, reassembly, retry Implemented
comms/couriers/blob/Blob.hpp Blob data container Implemented
comms/couriers/blob/Blob.cpp Binary data with metadata Implemented
comms/couriers/blob/BlobChunk.hpp Individual blob chunk Implemented
comms/couriers/blob/BlobChunk.cpp Chunk tracking Implemented
comms/couriers/blob/BlobFuture.hpp Async transfer result Implemented
comms/couriers/blob/BlobFuture.cpp Progress, completion events Implemented

Role-Specific Courier Sets

File Purpose Status
comms/couriers/sets/AgentCourierSet.hpp Agent-side couriers Implemented
comms/couriers/sets/AgentCourierSet.cpp State, sensors, blob Implemented
comms/couriers/sets/AgentClientCourierSet.hpp Agent as client Implemented
comms/couriers/sets/AgentClientCourierSet.cpp When connecting to Hub Implemented
comms/couriers/sets/RemoteCourierSet.hpp Remote-side couriers Implemented
comms/couriers/sets/RemoteCourierSet.cpp Commands, control Implemented
comms/couriers/sets/RemoteClientCourierSet.hpp Remote as client Implemented
comms/couriers/sets/RemoteClientCourierSet.cpp When connecting to Agent Implemented
comms/couriers/sets/HubCourierSet.hpp Hub-side couriers Implemented
comms/couriers/sets/HubCourierSet.cpp Coordination messages Implemented
comms/couriers/sets/HubClientCourierSet.hpp Hub as client Implemented
comms/couriers/sets/HubClientCourierSet.cpp When connecting to nodes Implemented

4. Messages & Sync (libcomms)

Message Types

File Purpose Status
comms/messages/MessageType.hpp Message type enumeration Implemented
comms/messages/MessageType.cpp Type registry Implemented
comms/messages/SensorsMessage.hpp Sensor data message Implemented
comms/messages/SensorsMessage.cpp Serialization Implemented
comms/messages/AgentMode.hpp Agent operation mode Implemented
comms/messages/AgentMode.cpp Mode enumeration Implemented

Synchronization

File Purpose Status
comms/sync/ISyncParameter.hpp Sync parameter interface Implemented
comms/sync/ISyncParameter.cpp Parameter contract Implemented
comms/sync/SyncParameter.hpp Templated sync parameter Implemented
comms/sync/SyncContext.hpp Sync state context Implemented
comms/sync/SyncContext.cpp Parameter collection Implemented

5. Discovery (libpair)

Discovery Client

File Purpose Status
discovery/DiscoveryClient.hpp Main discovery orchestrator Implemented
discovery/DiscoveryClient.cpp HTTP + LAN discovery Implemented
discovery/DiscoveryMandate.hpp Desired discovery state Implemented
discovery/DiscoveryMandate.cpp Channel enable/disable Implemented
discovery/DiscoveryStatus.hpp Actual discovery state Implemented
discovery/DiscoveryStatus.cpp Per-channel status Implemented

LAN Discovery

File Purpose Status
discovery/LANDiscovery.hpp UDP broadcast discovery Implemented
discovery/LANDiscovery.cpp LAN_ANNOUNCE packets Implemented

Discovery Server

File Purpose Status
discovery/DiscoveryServer.hpp Server-side discovery Implemented
discovery/DiscoveryServer.cpp Discovery request handling Implemented
discovery/DiscoveryServerSession.hpp Server session Implemented
discovery/DiscoveryServerSession.cpp Per-client session Implemented
discovery/DiscoveryServerEntry.hpp Server registry entry Implemented
discovery/DiscoveryServerEntry.cpp Node registration data Implemented

Discovery UI

File Purpose Status
discovery/ping/PingWidget.hpp Ping status widget Implemented
discovery/ping/PingWidget.cpp Visual ping display Implemented

6. Pairing & Trust (libpair)

Pairing Activities

File Purpose Status
pairing/PairingMenuActivity.hpp Pairing method selection Implemented
pairing/PairingMenuActivity.cpp Menu UI Implemented
pairing/PairingActivity.hpp Main pairing activity Implemented
pairing/PairingActivity.cpp Pairing flow coordinator Implemented
pairing/network/NetworkPairingActivity.hpp Network-based pairing Implemented
pairing/network/NetworkPairingActivity.cpp LAN/Zoo pairing UI Implemented
pairing/camera/CameraPairingActivity.hpp QR code pairing Implemented
pairing/camera/CameraPairingActivity.cpp Camera scanning UI Implemented
pairing/camera/CameraPairingWidget.hpp Camera preview widget Implemented
pairing/camera/CameraPairingWidget.cpp QR scanning logic Implemented

Trust Management

File Purpose Status
pairing/trust/PairingTrustActivity.hpp Trust assignment UI Implemented
pairing/trust/PairingTrustActivity.cpp Trust level selection Implemented
pairing/trust/TrustLevel.hpp Trust level enumeration Implemented
pairing/trust/TrustLevel.cpp IGNORE, TRUST, BLOCK Implemented
pairing/trust/TrustSymbolWidget.hpp Trust icon display Implemented
pairing/trust/TrustSymbolWidget.cpp Visual trust indicator Implemented

Pairing Lists

File Purpose Status
pairing/list/PairingListWidget.hpp Peer list UI Implemented
pairing/list/PairingListWidget.cpp List display Implemented
pairing/list/PairingListModel.hpp List data model Implemented
pairing/list/PairingListModel.cpp Associate data source Implemented
pairing/list/PairingEditButtonDelegate.hpp List item delegate Implemented
pairing/list/PairingEditButtonDelegate.cpp Edit button rendering Implemented

7. Associate & Address Book (libpair)

Associate

File Purpose Status
address/Associate.hpp Known peer representation Implemented
address/Associate.cpp ID, name, type, role, trust Implemented
address/AddressList.hpp Peer address tracking Implemented
address/AddressList.cpp Address scoring, selection Implemented
address/AddressEntry.hpp Single address with stats Implemented
address/AddressEntry.cpp Success/failure counts Implemented
address/TrustList.hpp Trust level storage Implemented
address/TrustList.cpp Per-peer trust settings Implemented
address/LocalAddressList.hpp Local addresses Implemented
address/LocalAddressList.cpp This node's addresses Implemented

Address Book

File Purpose Status
discovery/AddressBook.hpp Persistent peer storage Implemented
discovery/AddressBook.cpp Async load/save, queries Implemented

8. Delivery (libpair)

Agent Delivery

File Purpose Status
delivery/AgentDeliveryActivity.hpp Agent setup flow Implemented
delivery/AgentDeliveryActivity.cpp Agent initialization UI Implemented
delivery/AgentBaptismActivity.hpp Agent identity creation Implemented
delivery/AgentBaptismActivity.cpp Key generation UI Implemented
delivery/AgentSipAndSeeActivity.hpp Agent intro display Implemented
delivery/AgentSipAndSeeActivity.cpp Shows identity info Implemented

Control/Remote Delivery

File Purpose Status
delivery/ControlDeliveryActivity.hpp Remote setup flow Implemented
delivery/ControlDeliveryActivity.cpp Remote initialization UI Implemented
delivery/ControlBaptismActivity.hpp Remote identity creation Implemented
delivery/ControlBaptismActivity.cpp Key generation UI Implemented
delivery/ControlSipAndSeeActivity.hpp Remote intro display Implemented
delivery/ControlSipAndSeeActivity.cpp Shows identity info Implemented

Delivery Management

File Purpose Status
delivery/BirthControl.hpp Node identity validation Implemented
delivery/BirthControl.cpp Ensures key/identity setup Implemented
delivery/IdentityMenuActivity.hpp Identity options menu Implemented
delivery/IdentityMenuActivity.cpp Identity management UI Implemented
delivery/ConnectionWidget.hpp Connection status widget Implemented
delivery/ConnectionWidget.cpp Status display Implemented
delivery/ConnectionManager.hpp Connection orchestrator Implemented
delivery/ConnectionManager.cpp Connection lifecycle Implemented

9. Connection Activities (libpair)

File Purpose Status
connection/ConnectionActivity.hpp Main connection UI Implemented
connection/ConnectionActivity.cpp Metrics display Implemented
connection/ConnectionStatusWidget.hpp Status indicator Implemented
connection/ConnectionStatusWidget.cpp Visual status Implemented
connection/SignalStrengthWidget.hpp Signal strength bars Implemented
connection/SignalStrengthWidget.cpp Quality visualization Implemented

10. Security (libsec)

Key Management

File Purpose Status
security/Key.hpp Public key wrapper Implemented
security/Key.cpp Key operations Implemented
security/KeyPrivate.hpp Private key wrapper Implemented
security/KeyPrivate.cpp Signing operations Implemented
security/KeyFactory.hpp Key generation Implemented
security/KeyFactory.cpp RSA key pair creation Implemented
security/KeyStore.hpp Persistent key storage Implemented
security/KeyStore.cpp Thread-safe key store Implemented
security/KeySecurityPolicy.hpp Key security rules Implemented
security/KeySecurityPolicy.cpp Policy enforcement Implemented

Identity

File Purpose Status
security/PortableID.hpp Portable identity Implemented
security/PortableID.cpp ID serialization Implemented
security/ISigningKey.hpp Signing interface Implemented
security/SecurityConstants.hpp Security constants Implemented
security/SecurityConstants.cpp Algorithm parameters Implemented
security/SecurityConstantsPrivate.hpp Internal constants Implemented

11. Node Framework (libnode)

File Purpose Status
node/Node.hpp Base node class Implemented
node/Node.cpp Comms, AddressBook, KeyStore Implemented
node/NodeType.hpp Node type enum Implemented
node/NodeType.cpp Agent, Remote, Hub, Zoo Implemented
node/NodeRole.hpp Node role enum Implemented
node/NodeRole.cpp Server, Client, Both Implemented
node/LocalIdentityStore.hpp Local identity storage Implemented
node/LocalIdentityStore.cpp Persistent identity Implemented
node/IContextProvider.hpp Context provider interface Implemented
node/IContextProvider.cpp Service access Implemented
node/NodeFactory.hpp Node creation factory Implemented
node/NodeFactory.cpp Creates typed nodes Implemented
node/NodeWindow.hpp Base node window Implemented
node/NodeWindow.cpp Common window behavior Implemented

12. Services (libservice)

File Purpose Status
node/services/CommsService.hpp Comms lifecycle service Implemented
node/services/CarrierService.hpp Carrier management Implemented
node/services/CarrierService.cpp Carrier lifecycle Implemented
node/services/DiscoveryClientService.hpp Discovery service Implemented
node/services/DiscoveryClientService.cpp Discovery lifecycle Implemented
node/services/AddressBookService.hpp AddressBook service Implemented
node/services/AddressBookService.cpp Persistence Implemented
node/services/KeyStoreService.hpp KeyStore service Implemented
node/services/LocalAddressListService.hpp Local addresses Implemented
service/services/LocalIdentityStoreService.hpp Identity service Implemented

13. Connection UI Widgets (libwidgets)

File Purpose Status
components/PeerListItemWidget.hpp Peer list row Partial
components/PeerListItemWidget.cpp Peer display Partial
activities/PeerDetailActivity.hpp Peer details view Partial
activities/PeerDetailActivity.cpp Full peer info Partial
components/ConnectionStatusIndicator.hpp Status indicator Planned
components/TrustIconWidget.hpp Trust icons Planned
components/TrustSelectorWidget.hpp Trust selection Planned
components/ChannelBarWidget.hpp Channel quality bars Planned
components/ActivityOrbWidget.hpp Activity status orb Planned
components/CapabilityDescriptionWidget.hpp Trust capabilities Planned
components/VerificationContextWidget.hpp Verification UI Planned

Note: Several connection UI widgets are specified in internal/specs/comms/ui/ but not yet implemented.


14. Debug Widgets (libdebug)

File Purpose Status
debug/carrier/CarrierDebugWidget.hpp Carrier debugging Implemented
debug/carrier/CarrierDebugWidget.cpp Carrier status display Implemented
debug/courier/CouriersDebugWidget.hpp Courier debugging Implemented
debug/courier/CouriersDebugWidget.cpp Courier status display Implemented
debug/discovery/DiscoveryClientDebugWidget.hpp Discovery debugging Implemented
debug/discovery/DiscoveryClientDebugWidget.cpp Discovery status Implemented
debug/pairing/PairingDebugWidget.hpp Pairing debugging Implemented
debug/pairing/PairingDebugWidget.cpp Pairing status Implemented

15. Node-Specific Frameworks

Agent (libagent)

File Purpose Status
agent/Agent.hpp Agent node class Implemented
agent/Agent.cpp Agent implementation Implemented
agent/AgentConfig.hpp Agent configuration Implemented
agent/AgentConfigStore.hpp Config persistence Implemented
agent/AgentMain.hpp Agent main entry Implemented
agent/AgentWindow.hpp Agent window Implemented
agent/AgentMainMenu.hpp Agent menu Implemented

Remote (libremote)

File Purpose Status
remote/Remote.hpp Remote node class Implemented
remote/Remote.cpp Remote implementation Implemented
remote/RemoteMain.hpp Remote main entry Implemented
remote/RemoteWindow.hpp Remote window Implemented
remote/RemoteController.hpp Control logic Implemented
remote/AgentSelectActivity.hpp Agent selection UI Implemented
remote/AgentListModel.hpp Agent list model Implemented
remote/ControlUnboxingWizard.hpp Setup wizard Implemented

Hub (libhub)

File Purpose Status
hub/Hub.hpp Hub node class Implemented
hub/Hub.cpp Hub implementation Implemented
hub/HubMain.hpp Hub main entry Implemented
hub/HubWindow.hpp Hub window Implemented
hub/HubMainMenu.hpp Hub menu Implemented
hub/NodesManagementWidget.hpp Node management Implemented
hub/UtilitiesWidget.hpp Hub utilities Implemented

Client Framework (libclient, libagentclient)

File Purpose Status
client/ClientConnectionStatus.hpp Client status Implemented
client/ClientConnectionStatus.cpp Status tracking Implemented
client/agent/AgentClient.hpp Agent client Implemented
client/agent/AgentClient.cpp Agent connection Implemented
client/agent/AgentClientWidget.hpp Agent client UI Implemented
client/agent/AgentConnectionWidget.hpp Connection display Implemented

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

In this section
Topics
reference source-files comms development
See also