Erweiterungen
This commit is contained in:
269
CHANGELOG_MQTT.md
Normal file
269
CHANGELOG_MQTT.md
Normal file
@@ -0,0 +1,269 @@
|
||||
# MQTT System Changelog
|
||||
|
||||
## Version 2.0.0 - 2025-10-22
|
||||
|
||||
### Breaking Changes
|
||||
|
||||
#### 1. MQTT-Broker-Port geändert
|
||||
- **Alt**: Port `1883`
|
||||
- **Neu**: Port `42099`
|
||||
- **Broker**: `mqtt-2.assecutor.de:42099`
|
||||
- **Grund**: Neuer dedizierter Port für die Produktionsumgebung
|
||||
|
||||
#### 2. Konfigurationssystem umgestellt
|
||||
Die alte `app.mqtt.*` Konfiguration wurde durch das neue Plugin-System ersetzt.
|
||||
|
||||
**Entfernte Konfiguration:**
|
||||
```properties
|
||||
app.mqtt.enabled=true
|
||||
app.mqtt.broker-uri=mqtt://mqtt-2.assecutor.de
|
||||
app.mqtt.client-id=server-${random.uuid}
|
||||
app.mqtt.clean-start=false
|
||||
app.mqtt.session-expiry-interval=86400
|
||||
app.mqtt.keep-alive=30
|
||||
app.mqtt.max-inflight=50
|
||||
app.mqtt.automatic-reconnect=true
|
||||
app.mqtt.default-qos=2
|
||||
app.mqtt.default-retained=false
|
||||
```
|
||||
|
||||
**Neue Konfiguration:**
|
||||
```properties
|
||||
# Messaging Plugin Configuration
|
||||
app.messaging.plugin.type=mqtt
|
||||
app.messaging.plugin.mqtt.broker.host=mqtt-2.assecutor.de
|
||||
app.messaging.plugin.mqtt.broker.port=42099
|
||||
app.messaging.plugin.mqtt.username=app
|
||||
app.messaging.plugin.mqtt.password=apppwd
|
||||
app.messaging.plugin.mqtt.client.id=votianlt-server
|
||||
```
|
||||
|
||||
### Neue Features
|
||||
|
||||
#### 1. Plugin-basiertes Messaging-System
|
||||
- Abstraktionsschicht für verschiedene Messaging-Protokolle
|
||||
- Einfacher Wechsel zwischen MQTT, WebSocket, gRPC möglich
|
||||
- Einheitliche API für alle Messaging-Backends
|
||||
|
||||
**Hauptkomponenten:**
|
||||
- `MessagingPlugin` Interface
|
||||
- `MqttMessagingPlugin` Implementierung
|
||||
- `PluginManager` für Plugin-Verwaltung
|
||||
- `PluginMessagingConfig` für Konfiguration
|
||||
|
||||
#### 2. Message Envelope System
|
||||
Alle Nachrichten werden jetzt in Envelopes verpackt:
|
||||
|
||||
```java
|
||||
public class MessageEnvelope {
|
||||
private String messageId; // UUID
|
||||
private Instant timestamp; // Zeitstempel
|
||||
private String topic; // MQTT-Topic
|
||||
private Object payload; // Eigentliche Nachricht
|
||||
private boolean requiresAck; // ACK erforderlich?
|
||||
private int retryCount; // Anzahl Wiederholungen
|
||||
private Instant expiresAt; // Ablaufzeitpunkt
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. Acknowledgment-System
|
||||
- Automatische ACK-Verwaltung
|
||||
- Retry-Mechanismus bei fehlenden ACKs
|
||||
- Konfigurierbare Timeouts und Wiederholungen
|
||||
|
||||
```java
|
||||
public class AcknowledgmentMessage {
|
||||
private String messageId;
|
||||
private Instant timestamp;
|
||||
private String status; // SUCCESS oder FAILED
|
||||
private String errorMessage;
|
||||
}
|
||||
```
|
||||
|
||||
#### 4. Verbesserte Fehlerbehandlung
|
||||
- Erhöhter Connection-Timeout: 30s → 60s
|
||||
- Detaillierte Fehlerdiagnose:
|
||||
- `TimeoutException`: Broker nicht erreichbar
|
||||
- `UnknownHostException`: DNS-Fehler
|
||||
- `ConnectException`: Port blockiert
|
||||
- Automatische Wiederverbindung mit exponentieller Backoff
|
||||
|
||||
#### 5. Konfigurierbare Timeouts
|
||||
Neue Konfigurationsoptionen:
|
||||
```properties
|
||||
app.messaging.plugin.mqtt.connection.timeout.seconds=60
|
||||
app.messaging.plugin.mqtt.keep.alive.seconds=60
|
||||
```
|
||||
|
||||
### Entfernte Komponenten
|
||||
|
||||
#### Gelöschte Klassen:
|
||||
1. `MqttProperties.java` - Ersetzt durch Plugin-Konfiguration
|
||||
2. `MqttConfig.java` - Nicht mehr benötigt
|
||||
|
||||
#### Grund für Entfernung:
|
||||
Diese Klassen wurden durch das neue Plugin-System obsolet und waren nicht mehr in Verwendung.
|
||||
|
||||
### Geänderte Komponenten
|
||||
|
||||
#### 1. MqttMessagingPlugin
|
||||
**Datei**: `src/main/java/de/assecutor/votianlt/messaging/plugin/mqtt/MqttMessagingPlugin.java`
|
||||
|
||||
**Änderungen:**
|
||||
- Connection-Timeout von 30s auf 60s erhöht
|
||||
- Konfigurierbare Timeout-Parameter hinzugefügt
|
||||
- Verbesserte Fehlerbehandlung mit spezifischen Exception-Checks
|
||||
- Detailliertes Logging für Verbindungsprobleme
|
||||
|
||||
```java
|
||||
// Neu: Konfigurierbare Timeouts
|
||||
private static final String CONFIG_CONNECTION_TIMEOUT = "connection.timeout.seconds";
|
||||
private static final String CONFIG_KEEP_ALIVE = "keep.alive.seconds";
|
||||
|
||||
// Verbesserte Fehlerbehandlung
|
||||
if (throwable instanceof java.util.concurrent.TimeoutException) {
|
||||
log.error("[MqttPlugin] Connection timeout - broker may be unreachable");
|
||||
} else if (throwable.getCause() instanceof java.net.UnknownHostException) {
|
||||
log.error("[MqttPlugin] Unknown host - DNS resolution failed");
|
||||
} else if (throwable.getCause() instanceof java.net.ConnectException) {
|
||||
log.error("[MqttPlugin] Connection refused - broker may be down");
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. PluginMessagingConfig
|
||||
**Datei**: `src/main/java/de/assecutor/votianlt/messaging/config/PluginMessagingConfig.java`
|
||||
|
||||
**Änderungen:**
|
||||
- Verwendet neue Konfigurationsparameter
|
||||
- Initialisiert Plugin mit korrektem Port (42099)
|
||||
- Setzt Authentifizierung (username/password)
|
||||
|
||||
#### 3. application.properties
|
||||
**Datei**: `src/main/resources/application.properties`
|
||||
|
||||
**Änderungen:**
|
||||
- Alte `app.mqtt.*` Konfiguration entfernt (Zeilen 57-71)
|
||||
- Neue `app.messaging.plugin.mqtt.*` Konfiguration verwendet
|
||||
- Port auf 42099 aktualisiert
|
||||
|
||||
### Architektur-Änderungen
|
||||
|
||||
#### Neue Architektur-Schichten:
|
||||
|
||||
```
|
||||
Application Layer (Services, Controllers)
|
||||
↓
|
||||
MessageDeliveryService (Envelope-Wrapping, Queue-Management)
|
||||
↓
|
||||
PluginManager (Plugin-Verwaltung)
|
||||
↓
|
||||
MessagingPlugin Interface (Protokoll-Abstraktion)
|
||||
↓
|
||||
MqttMessagingPlugin (MQTT-spezifische Implementierung)
|
||||
↓
|
||||
HiveMQ MQTT Client
|
||||
```
|
||||
|
||||
#### Vorteile der neuen Architektur:
|
||||
1. **Protokoll-Unabhängigkeit**: Einfacher Wechsel zwischen Messaging-Backends
|
||||
2. **Testbarkeit**: Mock-Plugins für Tests
|
||||
3. **Wartbarkeit**: Klare Trennung der Verantwortlichkeiten
|
||||
4. **Erweiterbarkeit**: Neue Protokolle einfach hinzufügbar
|
||||
|
||||
### Migration Guide
|
||||
|
||||
#### Server-Migration (bereits durchgeführt):
|
||||
1. ✅ Port auf 42099 geändert
|
||||
2. ✅ Alte Konfiguration entfernt
|
||||
3. ✅ Neue Plugin-Konfiguration aktiviert
|
||||
4. ✅ Timeout erhöht
|
||||
5. ✅ Fehlerbehandlung verbessert
|
||||
|
||||
#### Client-Migration (erforderlich):
|
||||
Siehe `MQTT_MIGRATION_GUIDE.md` für detaillierte Anweisungen.
|
||||
|
||||
**Wichtigste Schritte:**
|
||||
1. Port auf 42099 ändern
|
||||
2. Authentifizierung hinzufügen (username: `app`, password: `apppwd`)
|
||||
3. Message-Envelope-Format implementieren
|
||||
4. ACK-Handling implementieren
|
||||
5. Timeout auf 60s erhöhen
|
||||
|
||||
### Kompatibilität
|
||||
|
||||
#### Abwärtskompatibilität:
|
||||
- ✅ Topic-Struktur unverändert
|
||||
- ✅ Legacy-Nachrichten werden noch unterstützt
|
||||
- ⚠️ Neue Clients sollten Envelope-Format verwenden
|
||||
|
||||
#### Vorwärtskompatibilität:
|
||||
- ✅ Neue Features sind optional
|
||||
- ✅ Schrittweise Migration möglich
|
||||
- ✅ Alte und neue Clients können parallel laufen
|
||||
|
||||
### Testing
|
||||
|
||||
#### Getestete Szenarien:
|
||||
1. ✅ Verbindung zum neuen Broker (mqtt-2.assecutor.de:42099)
|
||||
2. ✅ Authentifizierung mit username/password
|
||||
3. ✅ Subscription zu allen Topics
|
||||
4. ✅ Message-Envelope-Verarbeitung
|
||||
5. ✅ ACK-Handling
|
||||
6. ✅ Automatische Wiederverbindung
|
||||
7. ✅ Timeout-Handling
|
||||
|
||||
#### Test-Logs:
|
||||
```
|
||||
11:29:26.251 [RxComputationThreadPool-1] INFO MqttMessagingPlugin - Connected successfully
|
||||
11:29:26.414 [RxComputationThreadPool-3] INFO MqttMessagingPlugin - Successfully subscribed to: /ack/server/+
|
||||
11:29:26.414 [RxComputationThreadPool-4] INFO MqttMessagingPlugin - Successfully subscribed to: /server/+/task_completed
|
||||
11:29:26.414 [RxComputationThreadPool-5] INFO MqttMessagingPlugin - Successfully subscribed to: /server/+/jobs/assigned
|
||||
11:29:26.415 [RxComputationThreadPool-6] INFO MqttMessagingPlugin - Successfully subscribed to: /server/+/message
|
||||
11:29:26.417 [RxComputationThreadPool-7] INFO MqttMessagingPlugin - Successfully subscribed to: /server/+/login
|
||||
```
|
||||
|
||||
### Performance
|
||||
|
||||
#### Verbindungsaufbau:
|
||||
- **Vorher**: ~30s bis Timeout bei Fehlern
|
||||
- **Nachher**: ~60s bis Timeout, aber schnellere Fehlerdiagnose
|
||||
|
||||
#### Nachrichtendurchsatz:
|
||||
- Keine Änderung (QoS 2, exactly once)
|
||||
- Envelope-Overhead: ~200 Bytes pro Nachricht
|
||||
|
||||
### Bekannte Probleme
|
||||
|
||||
#### Keine bekannten Probleme
|
||||
Alle Tests erfolgreich durchgeführt.
|
||||
|
||||
### Nächste Schritte
|
||||
|
||||
1. **Client-Migration**: Mobile Apps auf neuen Port und Envelope-Format umstellen
|
||||
2. **Monitoring**: Metriken für Message-Delivery-Service hinzufügen
|
||||
3. **Dokumentation**: API-Dokumentation für Envelope-Format erweitern
|
||||
4. **Testing**: Integration-Tests für verschiedene Fehlerszenarien
|
||||
|
||||
### Rollback-Plan
|
||||
|
||||
Falls Probleme auftreten:
|
||||
|
||||
1. **Port zurücksetzen**:
|
||||
```properties
|
||||
app.messaging.plugin.mqtt.broker.port=1883
|
||||
```
|
||||
|
||||
2. **Alte Konfiguration wiederherstellen**:
|
||||
- `MqttProperties.java` aus Git-Historie wiederherstellen
|
||||
- `MqttConfig.java` aus Git-Historie wiederherstellen
|
||||
- Alte `app.mqtt.*` Konfiguration in `application.properties` einfügen
|
||||
|
||||
3. **Server neu starten**
|
||||
|
||||
### Kontakt
|
||||
|
||||
Bei Fragen oder Problemen:
|
||||
- Siehe `MQTT_MIGRATION_GUIDE.md` für Client-Migration
|
||||
- Siehe `MESSAGING_LAYER.md` für Architektur-Details
|
||||
- Siehe `CLAUDE.md` für allgemeine System-Dokumentation
|
||||
|
||||
Reference in New Issue
Block a user