examples/

README

comqttauth integration examples

Each subdirectory is a runnable comqtt broker wired with comqttauth in coexist mode:

• Upstream comqtt auth hook handles connection authentication (OnConnectAuthenticate).
• comqttauth.Hook handles regex authorization (OnACLCheck).
• Both read the same storage, in the same wire format comqtt expects, so the broker behaves identically with or without this library installed.

The four examples differ only in which backend they configure; the seeded users, rules, and exercise commands are identical.

Start here

Example	When to pick it	External infra
file	Quickstart — no infra, single YAML on disk	none
redis	Production-shaped, lightest setup, bcrypt	redis
mysql	SQL with the broadest hosting ecosystem	mysql 8+
postgres	SQL with stronger typing and JSONB headroom	postgres 14+

Seeded credentials (all examples)

User	Password	Connects?	Regex rule
alice	wonderland	yes	allow pub telemetry/${username}/#
bob	builder	yes	deny pub forbidden/#
eve	(any)	no	— (no user record)

Auth model

client connect
   │
   ▼
┌──────────────────────────────────┐
│ comqtt upstream auth hook        │   reads users from backend
│  OnConnectAuthenticate           │   (file YAML / redis / sql)
└──────────────────────────────────┘
   │ accepted
   ▼
┌──────────────────────────────────┐  ┌──────────────────────────────────┐
│ comqtt upstream auth hook        │  │ comqttauth.Hook                  │
│  OnACLCheck (legacy topic ACLs)  │  │  OnACLCheck (regex rules)        │
└──────────────────────────────────┘  └──────────────────────────────────┘
            └────────── AND ──────────┘
                       ▼
               publish/subscribe allowed

comqtt's hook chain AND-combines verdicts: either hook can deny; both must allow. comqttauth.Hook returns true (allow) on no-rule-match so it doesn't false-deny traffic upstream already permitted — see hook.go for the contract.

Caveats

• The file example uses HashType: HashNone (plaintext) because upstream mqtt/hooks/auth.Hook compares passwords as plaintext only. The other three backends use bcrypt via pa.CompareHash.
• The file upstream hook caches its ledger at startup and does not reload. Users added after the broker boots are only visible to comqttauth.Hook (which reloads every ACL check), not to the upstream auth path. Restart to refresh.
• Examples bind a TCP listener only. No TLS, WebSockets, or clustering — those are out of scope; see comqtt's own cmd/single / cmd/cluster for production wiring patterns.