[ISSUE #305]feat: Introduce Standalone Mode by Allowing Meta Module Disabling

[HeartLinked]

This PR introduces a crucial option to run the RocketMQ-MQTT proxy layer in a configuration that does not depend on an external stateful meta service.

The primary motivation is to simplify deployment and reduce operational overhead for users who do not require stateful features like Retain Messages and Will Messages. By disabling this dependency, users can deploy the stateless MQTT proxy cluster without the need to set up, manage, and operate a separate, Raft-based meta cluster.

Key Changes

This feature is implemented through a series of coordinated changes across the common, ds, and cs modules:

1. New Configuration Options:

• enableMetaModule (in service.conf): A boolean switch (true by default) to enable or disable the entire meta module and its dependent features.
• staticFirstTopics (in service.conf): A comma-separated list of topics, required when enableMetaModule is false.
• localAddress (in service.conf): The address for internal RPC loopback, required when enableMetaModule is false.

2. Conditional Logic in NotifyManager:

The NotifyManager has been refactored to operate in two modes.When meta is disabled, it subscribes to the topics listed in staticFirstTopics at startup, instead of dynamically refreshing from the meta service. The message notification logic (notifyMessage) is adjusted to perform a local RPC loopback to itself, instead of broadcasting to a cluster of nodes.

3. Feature Gates for will and retain Messages:

To ensure system stability, features dependent on the meta module are now gated by the enableMetaModule switch.

• Will Messages: The MqttConnectHandler now checks the switch. If a client attempts to set a Will Message while the meta module is disabled, the server will log an error and close the connection.
• Retain Messages: The PublishProcessor now checks the switch. If a client attempts to publish a message with the retain flag set while the meta module is disabled, the request is actively rejected.

How to Configure and Test Standalone Mode

• In service.conf, set enableMetaModule=false.
• Configure staticFirstTopics with a comma-separated list of all your application's first-level topics (e.g., staticFirstTopics=topicA,iot/devices).
• Configure localAddress (e.g., localAddress=127.0.0.1).
• Start the service using only sh mqtt.sh start. The meta.sh process is not needed.
• To Test Rejection:
  Connect a client with a Will Message set. The server should refuse the connection.
  With an active connection, publish a message with the retain flag set to true. The server should close the connection.

Related Issue

fix #305

[DongyuanPan]

It can't be called a deployment mode.

[DongyuanPan]

mqtt proxy is still deployed in a cluster

[DongyuanPan]

plz commit to the develop branch

[DongyuanPan]

Why do you need staticFirstTopics and localAddress?

[DongyuanPan]

This code can be simplified and less intrusive. For example

if (mqttPublishMessage.fixedHeader().isRetain() && !serviceConf.isEnableMetaModule()) {
logger.error("Client [{}] on topic [{}] tried to publish a Retain Message, but the meta module is disabled. Rejecting request.",
                        context.getClientId(), mqttPublishMessage.variableHeader().topicName());

                MqttRetainException exception = new MqttRetainException("Retain Message feature is disabled.");

                CompletableFuture<StoreResult> failedFuture = new CompletableFuture<>();
                failedFuture.completeExceptionally(exception);
                return failedFuture;
}

[RockteMQ-AI]

Review by github-manager-bot

Summary

Introduces a Standalone Mode for RocketMQ-MQTT that allows running without the external meta service dependency. This simplifies deployment for users who don't need Retain Messages and Will Messages features.

Findings

• [Info] ServiceConf.java — The enableMetaModule switch (default true) with staticFirstTopics and localAddress configuration is a clean approach. Backward compatible since the default preserves existing behavior.

• [Info] MqttConnectHandler.java — Properly gates Will Message feature behind enableMetaModule. The error logging and connection close on attempted Will Message in standalone mode is correct behavior.

• [Info] NotifyManager.java — The dual-mode refactoring (dynamic topic refresh from meta vs. static topic list) is well-structured. The local RPC loopback for standalone mode is a reasonable approach.

• [Warning] MqttPacketDispatcher.java:143-148 — The new PUBLISH rejection logic closes the connection for any failed hook result. This is a behavior change that affects both cluster and standalone modes. Consider whether this is too aggressive — a failed hook might be transient and closing the connection could cause unnecessary client reconnects.

• [Warning] PublishProcessor.java — The retain message rejection when meta is disabled should return a proper MQTT CONNACK/PUBACK error code rather than just logging and silently dropping. MQTT clients expect protocol-level feedback.

• [Info] MqttRetainException.java — New exception class is clean but missing a newline at end of file (checkstyle may flag this).

Suggestions

1. Consider adding integration tests for standalone mode (e.g., verify Will Message is rejected, verify static topics work).
2. The PUBLISH rejection in MqttPacketDispatcher should be reviewed by maintainers to confirm the connection-close behavior is intentional for all hook failure scenarios.
3. Add a configuration validation check at startup: if enableMetaModule=false, verify staticFirstTopics and localAddress are configured.

---

Automated review by github-manager-bot