hmq Documentation

hmq supports shared subscriptions using the $share/<group>/<topic> syntax. This allows multiple clients in a group to share the load of a topic.

Pattern:

• Topic format: $share/<group>/topic
• Subscribe command: mosquitto_sub -t '$share/<group>/topic'
• Publish command: mosquitto_pub -t 'topic'

| Prefix              | Examples                                  | Publish                      |
| -------------------| ----------------------------------------- | ---------------------------- |
| $share/<group>/topic | mosquitto_sub -t ‘$share/<group>/topic’ | mosquitto_pub -t ‘topic’     |

hmq processes ACL rules using a sequential matching strategy. When a client attempts an action, the broker checks the client against the rules in the order they are defined in the configuration file.

1. The client is compared against Rule 1.
2. If Rule 1 matches, the action (allow or deny) is applied immediately, and no further rules are checked.
3. If Rule 1 does not match, the client is compared against Rule 2, and so on.
4. If no rules match, the default behavior is determined by the final state of the matching logic (typically implicit deny if no allow rules match).

To install and run the hmq broker from source, use the following commands:

$ go get github.com/fhmq/hmq
$ cd $GOPATH/github.com/fhmq/hmq
$ go run main.go

hmq is compatible with the Eclipse Paho client and mosquitto-client.

To run hmq in a cluster, you must first start a router.

1. Start the router:

   $ go get github.com/fhmq/router
   $ cd $GOPATH/github.com/fhmq/router
   $ go run main.go

2. Configure hmq: In your hmq.config file, set the router field to the router's address (e.g., "router": "127.0.0.1:9888").

1, start router for hmq  (https://github.com/fhmq/router.git)
	$ go get github.com/fhmq/router
	$ cd $GOPATH/github.com/fhmq/router
	$ go run main.go
2, config router in hmq.config  ("router": "127.0.0.1:9888")

The CSVLog plugin allows you to log MQTT messages to a CSV file at runtime for debugging, monitoring, or auditing. Configuration is handled via the csvBridgeConfig structure.

Key configuration options include:

• FileName: The output destination. Use a specific path, or one of the special tokens: {LOG} (to the system log), {STDOUT} (to standard output), or {NULL} (to discard messages).
• LogFileMaxSizeMB: Size in MB for log rotation.
• LogFileMaxFiles: Number of rotated files to keep.
• WriteIntervalSecs: Delay before flushing pending writes to the file.
• CommandTopic: The MQTT topic used to send control commands to the plugin (e.g., bridge/CSVLOG/command).
• Filters: An array of topic filters. If empty, all messages are bridged (defaults to #).

hmq supports MQTT Shared Subscriptions using a specific topic prefix. When a client subscribes to a topic starting with $share/, the broker treats it as a shared subscription group.

The topic format is: $share/<group_name>/<topic>.

Example topic: $share/my-group/sensors/temperature

• groupName: my-group
• topic: sensors/temperature

When messages are published to sensors/temperature, the broker will distribute them among the clients subscribed to the shared group using a load-balancing approach (random selection from the queue of subscribers).

The hmq broker distinguishes between different types of connections using the following constants. Understanding the client type is crucial as it determines how the broker processes publishes, subscribes, and cluster communications:

• CLIENT (0): A standard end-user MQTT client.
• ROUTER (1): Another router within the hmq cluster.
• REMOTE (2): A router connecting to a different cluster.
• CLUSTER (3): A connection used for cluster-wide operations.

const (
	CLIENT = 0
	ROUTER = 1
	REMOTE  = 2
	CLUSTER = 3
)

Custom topic providers are managed via a global registry. You can register your implementation using Register(name string, provider TopicsProvider) and then instantiate a Manager to interact with it using NewManager(providerName string).

1. Register: Call Register with a unique name and your implementation. Note that registering the same name twice or registering a nil provider will cause a panic.
2. Initialize: Use NewManager with the registered name to get a *Manager instance.
3. Operate: Use the Manager methods (Subscribe, Unsubscribe, Retain, etc.) to perform topic operations. The Manager acts as a proxy to your registered provider.

You can register a custom SessionsProvider implementation using the Register function, making it available to the Manager by a unique name. Once registered, you can instantiate a Manager to interact with that provider.

Note on Panics:

• Calling Register with a nil provider will cause a panic.
• Calling Register twice with the same name will cause a panic.