How drmagice/gmqtt works
1. Overall shape
- This repository is an MQTT broker written in Go, centered around a runtime broker process plus a set of pluggable subsystems.
- The main architectural boundary is between the core broker (server/) and the extensions/plugins (plugin/), with shared protocol/state packages underneath.
2. Process entrypoints
- cmd/gmqttd is the broker daemon. It boots the server, loads configuration, starts network listeners, and wires in plugins.
- cmd/gmqctl is a separate operator CLI, mainly for administrative/plugin-related workflows such as plugin generation.
- cmd/gmqttd/default_config.yml and related config files define the broker’s runtime composition.
3. Core broker runtime
- server/ is the orchestrator: it owns client lifecycle, publish/subscribe flow, hook dispatch, rate limiting, metrics/stats, plugin registration, and API registration.
- This package is the central integration point where incoming packets are turned into broker actions and outgoing deliveries are scheduled.
4. Client and packet flow
- pkg/packets/ contains MQTT protocol types and codecs for CONNECT, PUBLISH, SUBSCRIBE, ACKs, disconnects, auth, and properties.
- Network traffic enters as protocol packets, is parsed into these types, then passed through server logic and hooks before being routed or acknowledged.
- message.go, session.go, and subscription.go define shared domain concepts used across the broker.
5. Subscription and publish routing
- Subscription matching is handled in the persistence/subscription layer, with an in-memory trie implementation and a Redis-backed option.
- Publish processing fans out to matching subscribers, applies topic alias logic (server/topic_alias.go, topicalias/), and then enqueues deliveries according to QoS semantics.
- Retained messages are managed separately under retained/, with trie-based storage for retained-topic lookup.
6. QoS state and delivery durability
- The persistence/queue/ and persistence/unack/ packages track in-flight QoS state, delivery queues, and acknowledgements.
- These subsystems are what let the broker resume or retry message delivery correctly, especially for QoS 1/2 flows.
- persistence/encoding/ provides the storage encoding layer used by Redis-backed persistence.
7. Session persistence
- persistence/session/ abstracts session storage, with both memory and Redis implementations.
- The broker can run with ephemeral sessions in-memory or with Redis for restart-resilient session state.
- persistence/ is therefore a major infrastructure boundary: the broker core depends on the abstraction, not a concrete store.
8. Plugin system
- plugin/ is a first-class extension boundary. The core broker exposes hooks so plugins can observe or alter connection, auth, subscription, publish, delivery, and shutdown events.
- Hooks are defined and invoked from the server layer; plugins can also register APIs and interact with broker state through exported server interfaces.
9. Built-in plugins
- Auth plugin: provides username/password authentication and account management.
- Admin plugin: exposes operational APIs over gRPC and REST, with generated protobuf, grpc-gateway, and Swagger artifacts.
- Prometheus plugin: exports metrics.
- Federation plugin: experimental clustering/membership and inter-node coordination, with protobuf/gRPC surfaces and peer logic.
- These plugins are not just observers; some can actively publish messages, manage subscriptions, and mutate broker state.
10. External integrations
- Redis is the primary external datastore used for persistence backends and some plugin storage.
- HTTP/gRPC are used by the admin and federation surfaces.
- Prometheus is the metrics sink exposed by the metrics plugin.
- The broker also supports TLS/SSL and WebSocket endpoints, which affects the network entry layer in cmd/gmqttd and server/.
11. Configuration and platform concerns
- config/ models broker, MQTT, persistence, API, and topic-alias configuration, with tests and defaults.
- Platform-specific code in cmd/gmqttd/config_*.go and pkg/pidfile/ handles OS differences and process management details.
- server/limiter.go and hooks support operational controls such as connection throttling and ACL-like behavior.
12. Testing and generated artifacts
- The repo is heavily test-oriented, with package-level tests and shared test suites for persistence/session/subscription behavior.
- A number of .pb.go, grpc, gateway, and swagger files are generated artifacts that define the broker’s plugin-facing APIs rather than core runtime logic.
- plugin_generate.go and the plugin scaffolding files indicate that extension modules are meant to be generated and composed consistently.
Main entry points: server.go Server · main.go gmqttd · config.go Config · hook.go Hooks
Components 20
Broker runtime
Process entrypoints and the core server that orchestrates MQTT traffic and plugins.
- gmqttd · Main broker process that loads config, starts listeners, and wires plugins.
cmd/gmqttd/main.go - gmqctl · Administrative command-line tool, including plugin generation workflows.
cmd/gmqctl/main.go - Server · Central orchestrator for client lifecycle, hook dispatch, routing, metrics, and plugin registration.
server/server.go - Clients · Client lifecycle, connection handling, and packet-facing broker state.
server/client.go - Publish path · Publish processing, QoS handling, topic aliasing, and delivery scheduling.
server/publish_service.go - Hooks · Hook registration and event dispatch used by plugins and broker policies.
server/hook.go - API registrar · Registers plugin-facing APIs onto the broker services.
server/api_registrar.go
Persistence
Session, subscription, queue, unack, retained, and encoding backends.
- Sessions · Session abstraction with memory and Redis implementations.
persistence/session/session.go - Subscriptions · Topic subscription storage and matching, including trie and Redis backends.
persistence/subscription/subscription.go - Queues · In-flight delivery queues and delivery ordering for QoS flows.
persistence/queue/queue.go - Unacked · Tracks acknowledgements and retry state for durable delivery semantics.
persistence/unack/unack.go - Retained · Retained-message storage and trie-based topic lookup.
retained/interface.go
Plugins
Built-in extension modules and their generated API surfaces.
- Auth plugin · Username/password authentication and account management plugin.
plugin/auth/auth.go - Admin plugin · Operational APIs over gRPC, REST gateway, and Swagger artifacts.
plugin/admin/admin.go - Prometheus · Exports broker metrics for Prometheus scraping.
plugin/prometheus/prometheus.go - Federation · Experimental inter-node membership and coordination layer.
plugin/federation/federation.go
Shared packages
Protocol types, domain objects, and small shared utilities.
- Config · Broker, MQTT, persistence, API, and topic-alias configuration models.
config/config.go - Packets · MQTT packet types and encoding/decoding for connect, publish, subscribe, ack, and auth flows.
pkg/packets/packets.go - Domain models · Message, session, and subscription abstractions shared across broker subsystems.
message.go - Topic alias · Topic-alias helpers used by publish routing.
topicalias/fifo/fifo.go
Connections 32
- gmqttd → Config: loads · Broker daemon reads runtime configuration before starting services.
- gmqttd → Server: starts · Daemon boots the broker server and network listeners.
- gmqttd → Auth plugin: enables · Daemon composes built-in plugins into the broker process.
- gmqttd → Admin plugin: enables · Daemon composes built-in plugins into the broker process.
- gmqttd → Prometheus: enables · Daemon composes built-in plugins into the broker process.
- gmqttd → Federation: enables · Daemon composes built-in plugins into the broker process.
- gmqctl → Admin plugin: operates · CLI supports admin and plugin-related workflows.
- gmqctl → Auth plugin: operates · CLI supports admin and plugin-related workflows.
- Server → Clients: owns · Core server manages client lifecycle and connection state.
- Server → Publish path: routes · Core server drives publish fan-out and delivery coordination.
- Server → Hooks: dispatches · Core server emits lifecycle and message hooks.
- Server → API registrar: registers · Core server exposes plugin APIs through a registrar.
- Server → Sessions: uses · Server depends on abstract session storage.
- Server → Subscriptions: uses · Server depends on subscription matching and storage.
- Server → Queues: uses · Server relies on queue state for QoS delivery.
- Server → Unacked: uses · Server relies on acknowledgement tracking for retries.
- Server → Retained: uses · Server consults retained-message storage during routing.
- Publish path → Packets: parses · Publish flow consumes and emits MQTT packets.
- Publish path → Topic alias: applies · Publish pipeline resolves topic aliases.
- Clients → Packets: parses · Client I/O turns network bytes into protocol packets.
- Clients → Domain models: tracks · Client state uses shared message and session concepts.
- Sessions → Config: configured by · Session backend selection and options come from config.
- Subscriptions → Config: configured by · Subscription backend selection and options come from config.
- Queues → Config: configured by · Queue backend selection and options come from config.
- Unacked → Config: configured by · Ack-tracking backend selection and options come from config.
- Auth plugin → Hooks: hooks · Auth plugin plugs into connection and authentication events.
- Admin plugin → API registrar: registers · Admin plugin exposes APIs through the broker registrar.
- Prometheus → Hooks: hooks · Metrics plugin observes broker events via hooks.
- Federation → Hooks: hooks · Federation plugin participates through server hook events.
- Federation → API registrar: registers · Federation plugin exposes management or coordination APIs.
- Retained → Packets: stores · Retained messages are populated from publish packets.
- Server → Config: reads · Server behavior is governed by broker configuration.