From Passive Acceptance to Active Defense: smart-mqtt v1.5.5 Introduces Connection Flapping Protection

Release Overview

After the enterprise‑level connection authentication upgrade in version 1.5.4, smart‑mqtt v1.5.5 is officially released. This version introduces the FlappingDetector connection‑debounce detection mechanism, which employs a sliding time window and automatic ban policy to actively defend against "flapping clients" that can generate connection‑storm pressure on the broker.

Core Highlight: Connection Debounce Detection

Version 1.5.5 brings a three‑in‑one connection governance solution: real‑time detection, automatic ban, and active defense.

Technical Features

Sliding Time Window : millisecond‑level precision for statistical counting of connection events.

High‑Performance Concurrent Design : uses ConcurrentHashMap + ConcurrentLinkedDeque to ensure thread‑safe operation.

Lazy Expiration Cleanup : automatically lifts expired bans and runs background tasks to clean redundant data.

Core Algorithm

In a specified time window T, if a client’s connection count exceeds threshold N:
├── Classify as "Flapping Client"
├── Automatically ban the client for duration B
└── Reject connection requests during the ban period

This mechanism directly blocks abnormal clients, protecting the broker’s core services. Even when hundreds of abnormal clients launch a reconnection storm simultaneously, the broker maintains normal service capability.

Configuration Example

flapping:
  enable: true
  # Time window: 60 seconds
  thresholdDuration: 60
  # Threshold: 10 connections
  thresholdCount: 10
  # Ban duration: 300 seconds (5 minutes)
  banTime: 300

If a client connects more than 10 times within 60 seconds, the system automatically bans the client for 5 minutes.

If a client exceeds 10 connections in 60 seconds, it is automatically banned for 5 minutes.

Log Output During Ban

WARN  FlappingDetector - Client device_001 is in banned state, connection rejected
WARN  FlappingDetector - Client device_001 connected 15 times in 60 seconds, exceeding threshold 10, classified as flapping client, banned for 300 seconds

Why Connection Debounce Is Needed

Connection debouncing is an essential baseline protection capability for IoT platforms. Typical scenarios include massive reconnection attempts from faulty devices that can overwhelm the broker.

Future Outlook

Multi‑Dimensional Identification : support detection based on IP, ClientId, username, and other combinations.

Hierarchical Ban Strategy : adjust ban duration according to severity—short bans for first offenses, longer bans for repeated offenses.

Observation Dashboard : display flapping client statistics and ban trends in the management console.

IP‑Level Protection : defend against abnormal connections from entire IP segments.

Whitelist Mechanism : allow trusted clients to bypass detection, preventing accidental bans of critical devices.

WebHook Notifications : actively callback business systems when a flapping client is detected, forming a closed‑loop governance.

Acquisition and Quick Start

GitHub Releases: https://github.com/smartboot/smart-mqtt/releases/tag/v1.5.5

Gitee Releases: https://gitee.com/smartboot/smart-mqtt/releases/v1.5.5

Docker One‑Click Deployment

docker run --name smart-mqtt \
  -p 1883:1883 \
  -p 18083:18083 \
  -d smartboot/smart-mqtt:latest

Rapid Local Startup

# Download and unzip
curl -LO https://gitee.com/smartboot/smart-mqtt/releases/download/v1.5.5/smart-mqtt-full-v1.5.5.zip
unzip smart-mqtt-full-v1.5.5.zip -d smart-mqtt && cd smart-mqtt

# Start service
./start.sh