imtcom Namespace Reference

Server Communication and Connection Management Module. More...

Classes
class	CAsyncConnectionCheckerComp
	Timer-based asynchronous connection status checker using HTTP requests. More...
class	CRequestSender
class	CServerConnectionInterfaceParam
	Basic implementation of IServerConnectionInterface with protocol-port mapping. More...
class	CServerConnectionInterfaceParamComp
	ACF component implementation of IServerConnectionInterface with default port configuration. More...
class	CServerDispatcherComp
	ACF component implementing multi-protocol server dispatch for HTTP and WebSocket. More...
class	CSimpleConnectionCheckerComp
	GraphQL-based connection status checker for application-level connectivity validation. More...
class	IConnectionController
	Simple interface for connection lifecycle control. More...
class	IConnectionStatusProvider
	Interface for monitoring network connection status with observable state changes. More...
class	IFileTransfer
	Interface for file upload and download operations via URLs. More...
class	IServerConnectionInterface
	Interface for describing server connection configuration with multi-protocol support. More...
class	IServerDispatcher
	Interface for managing the lifecycle of multi-protocol servers. More...
class	ISslConfigurationApplier
	Interface for applying SSL-related settings to an SSL configuration. More...

Detailed Description

Server Communication and Connection Management Module.

The imtcom module provides comprehensive infrastructure for server connection configuration, multi-protocol dispatch, SSL/TLS security management, and network connection status monitoring.

Overview

This module serves as the foundation for client-server communication in ImtCore, handling:

• Server connection configuration (host, ports, protocols)
• Multi-protocol server dispatch (HTTP, WebSocket, gRPC, File)
• SSL/TLS configuration and certificate management
• Connection status monitoring and health checking
• Secure and insecure connection modes

Architecture

Design Patterns

Interface-Implementation Pattern:

• Clean separation between interface contracts (I*) and implementations (C*)
• Enables dependency injection and testability
• Supports multiple implementation strategies

Component Pattern (ACF):

• All major classes are ACF components
• Factory-based instantiation with I_BEGIN_COMPONENT macros
• Attribute-based configuration support
• Reference-based dependency injection

Observer Pattern:

• IConnectionStatusProvider extends IChangeable for change notifications
• Clients can observe connection status changes reactively
• Event-driven architecture support

Strategy Pattern:

• Multiple connection checker implementations (async, simple, internet)
• Pluggable SSL configuration strategies
• Protocol-specific server implementations

Core Interfaces

The module is organized around several key interface hierarchies:

Connection Configuration Hierarchy:

IServerConnectionInterface (iser::ISerializable, istd::IChangeable)
├─ Defines host, port, protocol configuration
├─ Supports CF_DEFAULT and CF_SECURE connection flags
└─ Protocols: PT_HTTP, PT_WEBSOCKET, PT_FILE, PT_GRPC
    │
    ├─ CServerConnectionInterfaceParam (concrete data holder)
    └─ CServerConnectionInterfaceParamComp (ACF component with defaults)

Server Dispatch Hierarchy:

IServerDispatcher (istd::IPolymorphic)
├─ Manages server lifecycle: StartServer(), StopServer()
├─ Provides server status queries
└─ Multi-protocol support
    │
    └─ CServerDispatcherComp (HTTP and WebSocket dispatcher)

Connection Monitoring Hierarchy:

IConnectionStatusProvider (istd::IChangeable)
├─ CS_UNKNOWN, CS_DISCONNECTED, CS_CONNECTED states
└─ Observable connection status
    │
    ├─ CAsyncConnectionCheckerComp (timer-based HTTP checks)
    ├─ CSimpleConnectionCheckerComp (GraphQL-based checks)
    └─ CInternetConnectionCheckerComp (internet availability)

SSL/TLS Configuration Hierarchy:

ISslConfigurationManager (istd::IPolymorphic)
├─ Creates QSslConfiguration from parameter sets
├─ Defines SSL protocols, key algorithms, encoding formats
└─ Peer verification modes
    │
    └─ CSslConfigurationManagerComp
 
ISslConfigurationApplier (istd::IPolymorphic)
├─ Applies certificates, private keys, CA chains
├─ Sets protocols and peer verification modes
└─ File-based certificate/key loading
    │
    └─ CSslConfigurationAdapterComp

Key Components

Component	Interface	Purpose
CServerConnectionInterfaceParamComp	IServerConnectionInterface	Connection configuration with default ports (HTTP:9001, WS:9000, gRPC:50101)
CServerDispatcherComp	IServerDispatcher	Multi-protocol server lifecycle management
CSslConfigurationManagerComp	ISslConfigurationManager	SSL configuration factory from parameters
CSslConfigurationAdapterComp	ISslConfigurationApplier	SSL settings application (certificates, keys, protocols)
CAsyncConnectionCheckerComp	IConnectionStatusProvider	Timer-based async connection health checks
CSimpleConnectionCheckerComp	IConnectionStatusProvider	GraphQL-based connection validation
CInternetConnectionCheckerComp	IConnectionStatusProvider	General internet connectivity detection
CRequestSender	N/A	Synchronous HTTP request helper (GET/POST/PUT)

Usage Examples

Configuring a Server Connection

// Create connection configuration component
auto connectionParam = icomp::CreateComponent<CServerConnectionInterfaceParamComp>();
 
// Configure connection parameters
connectionParam->SetHost("example.com");
connectionParam->SetPort(IServerConnectionInterface::PT_HTTP, 8080);
connectionParam->SetPort(IServerConnectionInterface::PT_WEBSOCKET, 8081);
connectionParam->SetConnectionFlags(IServerConnectionInterface::CF_SECURE);
 
// Get URL for a protocol
QUrl httpUrl;
if (connectionParam->GetUrl(IServerConnectionInterface::PT_HTTP, httpUrl)) {
    qDebug() << "HTTP URL:" << httpUrl.toString();
    // Output: "https://example.com:8080"
}

Using the Server Dispatcher

// Create server dispatcher component
auto dispatcher = icomp::CreateComponent<CServerDispatcherComp>();
 
// Start HTTP server
if (dispatcher->StartServer(IServerConnectionInterface::PT_HTTP)) {
    qDebug() << "HTTP server started successfully";
}
 
// Check server status
auto status = dispatcher->GetServerStatus(IServerConnectionInterface::PT_HTTP);
if (status == imtrest::IServer::ServerStatus::SS_RUNNING) {
    qDebug() << "Server is running";
}
 
// Stop server when done
dispatcher->StopServer(IServerConnectionInterface::PT_HTTP);

Monitoring Connection Status

// Create connection checker
auto checker = icomp::CreateComponent<CAsyncConnectionCheckerComp>();
 
// Configure the checker (set server URL, check interval, etc.)
// ... component attribute configuration ...
 
// Observe connection status changes
QObject::connect(checker.get(), &IChangeable::OnChanged, [](const IChangeable::ChangeSet& cs) {
    auto provider = dynamic_cast<IConnectionStatusProvider*>(sender());
    auto status = provider->GetConnectionStatus();
    
    switch (status) {
        case IConnectionStatusProvider::CS_CONNECTED:
            qDebug() << "Connection established";
            break;
        case IConnectionStatusProvider::CS_DISCONNECTED:
            qDebug() << "Connection lost";
            break;
        case IConnectionStatusProvider::CS_UNKNOWN:
            qDebug() << "Connection status unknown";
            break;
    }
});

Configuring SSL/TLS

// Create SSL configuration manager
auto sslManager = icomp::CreateComponent<CSslConfigurationManagerComp>();
 
// Create parameter set with SSL configuration
auto params = icomp::CreateComponent<iprm::CParamsSetComp>();
params->SetValue(ISslConfigurationManager::ParamKeys::s_protocolParamKey, 
                 ISslConfigurationManager::SP_TLS_V1_3_OR_LATER);
params->SetValue(ISslConfigurationManager::ParamKeys::s_verifyModeParamKey,
                 ISslConfigurationManager::PVM_VERIFY);
 
// Create SSL configuration
QSslConfiguration sslConfig;
if (sslManager->CreateSslConfiguration(*params, sslConfig)) {
    // Apply to network request
    QNetworkRequest request;
    request.setSslConfiguration(sslConfig);
}
 
// Alternative: Apply settings directly
auto applier = icomp::CreateComponent<CSslConfigurationAdapterComp>();
applier->LoadLocalCertificateFromFile("/path/to/cert.pem");
applier->LoadPrivateKeyFromFile("/path/to/key.pem", QSsl::Rsa);
applier->LoadCaCertificatesFromFile("/path/to/ca.pem");
applier->SetSslProtocol(QSsl::TlsV1_3OrLater);
applier->SetPeerVerifyMode(QSslSocket::VerifyPeer);

Cross-Module Integration

The imtcom module integrates with several other ImtCore modules:

imtrest Module:

• CServerDispatcherComp manages IServer instances (CTcpServerComp, CWebSocketServerComp)
• Server components reference IServerConnectionInterface for configuration
• Protocol-specific servers read ports via GetPort(ProtocolType)

imtclientgql Module:

• CSimpleConnectionCheckerComp uses GraphQL client for health checks
• Connection status affects client connection lifecycle
• IServerConnectionInterface provides WebSocket URLs for GraphQL subscriptions

imtservergql Module:

• CSettingsControllerComp exposes IServerConnectionInterface via GraphQL API
• Server settings can be queried and modified through GraphQL mutations
• WebSocket URLs are generated for GraphQL subscription endpoints

imtqml Module:

• CGqlQuickObjectComp observes IServerConnectionInterface for configuration changes
• QML applications receive reactive updates when connection parameters change
• Enables dynamic server switching in client applications

imtauthgui Module:

• GUI components for server connection editing (CServerConnectionEditorComp)
• Administration observers monitor connection changes
• Login GUI components use connection status for availability feedback

imthttp Module:

• CHttpFileTransfer implements IFileTransfer interface
• Uses IServerConnectionInterface for file upload/download endpoints

imtservice Module:

• IConnectionCollection manages multiple server connections
• Supports multi-server architectures with connection pooling

Supported Protocols

The module supports four primary communication protocols via the ProtocolType enumeration:

Protocol	Enum Value	Typical Port	Use Case
HTTP	PT_HTTP	9001 (default)	REST API, traditional web services
WebSocket	PT_WEBSOCKET	9000 (default)	Real-time bidirectional communication, GraphQL subscriptions
gRPC	PT_GRPC	50101 (default)	High-performance RPC, microservices
File	PT_FILE	N/A	File-based communication, local protocols

Each protocol can be independently configured with custom ports and security settings. The CF_SECURE flag determines whether HTTPS/WSS is used instead of HTTP/WS.

SSL/TLS Security

The module provides comprehensive SSL/TLS support with:

Protocols:

• TLS 1.0 through TLS 1.3 (TLS 1.2+ recommended)
• DTLS 1.0 through DTLS 1.2
• Deprecation warnings for older protocols

Key Algorithms:

• RSA (Rivest–Shamir–Adleman)
• DSA (Digital Signature Algorithm)
• EC (Elliptic Curve)
• DH (Diffie-Hellman)
• OPAQUE (black box keys)

Encoding Formats:

• PEM (Privacy Enhanced Mail) - text-based, default
• DER (Distinguished Encoding Rules) - binary

Peer Verification Modes:

• PVM_NONE: No verification, encryption only
• PVM_QUERY: Request certificate, don't validate (server default)
• PVM_VERIFY: Require valid certificate (client default)
• PVM_AUTO_VERIFY: Automatic selection based on client/server role

Testing Utilities

The module includes several testing and diagnostic components:

• CRequestSender: Synchronous HTTP helper for testing endpoints
• CInternetConnectionCheckerComp: Validates internet availability
• CAsyncConnectionCheckerComp: Periodic health checks with retry logic
• CSimpleConnectionCheckerComp: Application-level connectivity validation

These components support configurable timeouts, retry counts, and check intervals, making them suitable for both development diagnostics and production monitoring.

Module Dependencies

ACF Framework Dependencies:

• icomp (component framework)
• iser (serialization)
• istd (standard interfaces: IPolymorphic, IChangeable)
• iprm (parameter management)
• ilog (logging framework)

ImtCore Module Dependencies:

• imtrest (server implementations)
• imtbase (URL parameters, system status)
• imtclientgql (GraphQL client for health checks)
• imthttp (file transfer implementations)

Qt Framework Dependencies:

• QtCore (QUrl, QString, QByteArray, QMap)
• QtNetwork (QSslConfiguration, QSslSocket, QNetworkRequest)

Best Practices

Connection Configuration:

• Always use CServerConnectionInterfaceParamComp for consistent defaults
• Set CF_SECURE flag for production deployments
• Use GetUrl() to generate protocol-specific URLs with proper scheme handling

Server Management:

• Check GetServerStatus() before calling StopServer()
• Handle StartServer() failures gracefully with appropriate error reporting
• Use GetSupportedProtocols() to validate protocol availability

SSL/TLS Configuration:

• Prefer TLS 1.2 or later (SP_TLS_V1_2_OR_LATER, SP_TLS_V1_3_OR_LATER)
• Use PVM_VERIFY for client connections requiring secure communication
• Load CA certificates for proper certificate chain validation
• Protect private key passphrases, never hardcode in source

Connection Monitoring:

• Implement retry logic with exponential backoff
• Use appropriate check intervals to balance responsiveness and resource usage
• Subscribe to IChangeable notifications for reactive status updates

See Also

Related ImtCore modules:

• imtrest - REST Server Framework
• imtclientgql - GraphQL Client
• imtservergql - GraphQL Server
• imthttp - HTTP Client
• imtbase - Base Utilities

Author

ImtCore Development Team

Version

1.0

Date

2024-2026