How hivemq/hivemq-community-edition works
Project type and purpose
• HiveMQ CE is a Java-based, open-source, monolithic MQTT broker (server) implementing MQTT 3.x and 5.0.
• It can run standalone (distro or Docker), or be embedded via its Java API.
Key architectural components (derived from src/main/java packages and README)
A. Network Ingress Layer
• Listeners: TCP, TLS, WebSocket, WSS (src/main/java/com/hivemq/bootstrap/netty/initializer)
• Netty event-loop and pipeline (ChannelInitializerFactory, ChannelDependencies, ExceptionHandler)
B. Protocol Codec Layer
• MQTT decoders and encoders for MQTT 3.x & 5.0 (src/main/java/com/hivemq/codec/decoder & encoder)
C. MQTT Core Handler Layer
• Handlers for CONNECT, CONNACK, PUBLISH, SUBSCRIBE, etc. (src/main/java/com/hivemq/mqtt/handler)
• Internal services: PublishService, PublishDistributor, SubscribeService, etc.
D. Session & Subscription Management
• ClientSessionPersistence, SubscriptionStore, TopicTree (src/main/java/com/hivemq/persistence & mqtt/topic/tree)
E. Persistence Layer
• In-memory, File, Xodus, RocksDB backends (configured via Guice PersistenceModules)
• Entities: client queues, retained messages, payloads
F. Extension Framework
• ExtensionLoader, ClassServiceLoader, ExtensionBootstrap
• Extension SDK: interceptors, authenticators, authorizers, client initializers (com.hivemq/extensions)
G. Configuration & Dependency Injection
• Reads XML config, merges environment vars/system props (src/main/java/com/hivemq/configuration)
• Guice DI modules: bootstrap, netty, configuration, persistence, mqtt, extensions, security, metrics, throttling
H. Observability & Lifecycle
• Metrics (JMX, internal gauges), diagnostic mode, logging (SLF4J/Logback)
• Startup/shutdown hooks, health verification
I. Embedded Mode API
• EmbeddedHiveMQBuilder and EmbeddedExtensionBuilder for programmatic integration
Relationships and data flows
1) Clients → Network Listeners → Netty Pipeline
2) Byte streams → MQTTDecoder → MQTTMessage objects
3) MQTTMessage → CoreHandlers → InternalServices
– CONNECT → SessionManager
– PUBLISH → PublishService + Persist/PersistedStores
– SUBSCRIBE → TopicTree lookup → Distribution
4) CoreHandlers fire extension events (interceptors, auth) → ExtensionFramework
5) Persistence I/O abstracts to multiple backends via DI
6) Responses traverse reverse path: CoreHandlers → MQTTEncoder → Netty → Client
7) ConfigurationService and DI bootstrap assemble modules at startup
8) Metrics & Diagnostic modules observe internal events and expose via JMX/log
Architectural patterns and principles
• Modular layering (Network → Codec → Core → Persistence → Extensions)
• IoC/DI via Google Guice for pluggability and testability
• Event-driven, non-blocking I/O (Netty)
• Plugin/Extension classloader isolation
• Separation of concerns: protocol vs. business logic vs. storage vs. extensions
Technologies and frameworks
• Netty (networking)
• Guice (DI)
• Xodus / RocksDB / File / In-memory (persistence)
• SLF4J + Logback (logging)
• JMX (metrics)
• Java 11+
• Docker (distribution)