node-red-contrib-tcp-client-server-avd 1.0.0

package/NodeRedTCP/SPECIFICATIE.md

@@ -0,0 +1,460 @@
+# Specificatie: Node-RED TCP Client/Server Node
+
+## 1. Inleiding
+
+Dit document beschrijft de specificatie voor een Node-RED node die in staat is om als TCP client en/of TCP server te functioneren. De node moet flexibel zijn en beide modi ondersteunen, zodat gebruikers TCP-communicatie kunnen implementeren in hun Node-RED flows.
+
+## 2. Doelstelling
+
+Het doel is om een robuuste, gebruiksvriendelijke Node-RED node te ontwikkelen die:
+- Fungeert als TCP client (uitgaande verbindingen)
+- Fungeert als TCP server (inkomende verbindingen)
+- Beide modi ondersteunt in één node
+- Foutafhandeling en herconnectie biedt
+- Verschillende dataformaten ondersteunt (string, buffer, JSON, etc.)
+- Gebruikersvriendelijke configuratie heeft
+
+## 3. Functionele Eisen
+
+### 3.1 Algemene Functionaliteit
+
+- De node moet configureerbaar zijn als client, server, of beide
+- Ondersteuning voor zowel IPv4 als IPv6
+- Mogelijkheid om meerdere verbindingen te beheren (server mode)
+- Ondersteuning voor verschillende data encoding/decoding methoden
+- Real-time status feedback (verbonden, verbroken, fout)
+
+### 3.2 TCP Client Mode
+
+#### 3.2.1 Verbindingsbeheer
+- Automatisch verbinden bij flow start (optioneel)
+- Handmatig verbinden via input message
+- Automatische herconnectie bij verbroken verbinding (configureerbaar)
+- Configureerbare reconnect interval en max aantal pogingen
+- Timeout configuratie voor connectiepogingen
+
+#### 3.2.2 Data Transmissie
+- Verzenden van data via input messages
+- Ontvangen van data via output messages
+- Ondersteuning voor verschillende dataformaten:
+  - String (verschillende encodings: UTF-8, ASCII, etc.)
+  - Buffer (raw binary data)
+  - JSON (geformatteerd)
+  - Hex string
+- Configureerbare delimiter voor message framing (optioneel)
+- Keep-alive optie
+
+#### 3.2.3 Configuratie Opties
+- Hostname of IP adres
+- Poort nummer
+- Protocol (TCP)
+- Local address binding (optioneel)
+- Local port binding (optioneel)
+- Connection timeout
+- Reconnect settings
+
+### 3.3 TCP Server Mode
+
+#### 3.3.1 Server Beheer
+- Server starten bij flow start (optioneel)
+- Luisteren op geconfigureerde poort
+- Accepteren van meerdere gelijktijdige client verbindingen
+- Unieke identificatie van elke client verbinding
+- Server stoppen via input message
+
+#### 3.3.2 Data Transmissie
+- Verzenden naar specifieke client of alle clients
+- Ontvangen van data per client verbinding
+- Zelfde dataformaat ondersteuning als client mode
+- Client identificatie in output messages
+
+#### 3.3.3 Configuratie Opties
+- Luister poort
+- Bind address (standaard: alle interfaces)
+- Max aantal gelijktijdige verbindingen
+- Connection timeout voor client verbindingen
+- Data formatting opties
+
+### 3.4 Gecombineerde Mode (Client + Server)
+
+- Mogelijkheid om zowel client als server functionaliteit te gebruiken
+- Aparte configuratie voor client en server delen
+- Onafhankelijke status voor beide modi
+
+## 4. Message Structure
+
+### 4.1 Input Messages (naar Node)
+
+#### 4.1.1 Client Mode - Verbinding Beheer
+```javascript
+// Verbinden
+{ topic: "connect" }
+
+// Verbreken
+{ topic: "disconnect" }
+
+// Data verzenden
+{
+  topic: "send",
+  payload: "data om te verzenden" // string, buffer, of object
+}
+```
+
+#### 4.1.2 Server Mode - Server Beheer
+```javascript
+// Server starten
+{ topic: "start" }
+
+// Server stoppen
+{ topic: "stop" }
+
+// Data verzenden naar specifieke client
+{
+  topic: "send",
+  clientId: "client-unique-id",
+  payload: "data om te verzenden"
+}
+
+// Data verzenden naar alle clients
+{
+  topic: "broadcast",
+  payload: "data om te verzenden"
+}
+```
+
+### 4.2 Output Messages (van Node)
+
+#### 4.2.1 Client Mode
+```javascript
+// Verbindingsstatus
+{
+  topic: "status",
+  payload: "connected" | "disconnected" | "error",
+  status: "connected" | "disconnected" | "error",
+  error: "error message (indien van toepassing)"
+}
+
+// Ontvangen data
+{
+  topic: "data",
+  payload: "ontvangen data",
+  timestamp: "ISO timestamp"
+}
+```
+
+#### 4.2.2 Server Mode
+```javascript
+// Server status
+{
+  topic: "status",
+  payload: "listening" | "stopped" | "error",
+  port: 1234,
+  error: "error message (indien van toepassing)"
+}
+
+// Client verbinding
+{
+  topic: "client/connected",
+  clientId: "unique-client-id",
+  remoteAddress: "client-ip",
+  remotePort: "client-port"
+}
+
+// Client verbreking
+{
+  topic: "client/disconnected",
+  clientId: "unique-client-id"
+}
+
+// Ontvangen data
+{
+  topic: "data",
+  payload: "ontvangen data",
+  clientId: "unique-client-id",
+  remoteAddress: "client-ip",
+  timestamp: "ISO timestamp"
+}
+```
+
+## 5. Node Configuratie UI
+
+### 5.1 Basis Configuratie
+
+#### Mode Selectie
+- **Type**: Dropdown selectie
+- **Opties**: 
+  - "TCP Client"
+  - "TCP Server"
+  - "TCP Client & Server"
+- **Standaard**: "TCP Client"
+
+#### Node Name
+- Standaard Node-RED node naam veld
+- Optioneel label voor UI
+
+### 5.2 Client Configuratie (indien client mode actief)
+
+#### Verbindings Instellingen
+- **Host**: Text input (standaard: "localhost")
+- **Port**: Number input (standaard: 8080)
+- **Protocol**: Read-only (TCP)
+- **IPv4/IPv6**: Toggle (standaard: IPv4)
+
+#### Verbindings Gedrag
+- **Auto Connect**: Checkbox (standaard: true)
+- **Reconnect**: Checkbox (standaard: true)
+- **Reconnect Interval**: Number input in seconden (standaard: 5)
+- **Max Reconnect Attempts**: Number input (standaard: 0 = oneindig)
+- **Connection Timeout**: Number input in seconden (standaard: 10)
+
+#### Data Instellingen
+- **Input Format**: Dropdown
+  - "String"
+  - "Buffer"
+  - "JSON"
+  - "Hex String"
+- **Output Format**: Dropdown (zelfde opties)
+- **Encoding**: Dropdown (UTF-8, ASCII, Latin1, etc.) - alleen voor string format
+- **Message Delimiter**: Text input (optioneel, voor message framing)
+- **Keep-Alive**: Checkbox (standaard: false)
+
+### 5.3 Server Configuratie (indien server mode actief)
+
+#### Server Instellingen
+- **Listen Port**: Number input (standaard: 8080)
+- **Bind Address**: Text input (standaard: "0.0.0.0" = alle interfaces)
+- **Protocol**: Read-only (TCP)
+- **IPv4/IPv6**: Toggle (standaard: IPv4)
+
+#### Verbindings Beheer
+- **Auto Start**: Checkbox (standaard: true)
+- **Max Connections**: Number input (standaard: 0 = onbeperkt)
+- **Connection Timeout**: Number input in seconden (standaard: 600)
+- **Keep-Alive**: Checkbox (standaard: false)
+
+#### Data Instellingen
+- **Input Format**: Dropdown (zelfde als client)
+- **Output Format**: Dropdown (zelfde als client)
+- **Encoding**: Dropdown (zelfde als client)
+- **Message Delimiter**: Text input (optioneel)
+
+## 6. Status Weergave
+
+### 6.1 Status Iconen en Kleuren
+
+#### Client Mode
+- **Groen (verbonden)**: Succesvol verbonden met server
+- **Rood (fout)**: Verbindingsfout of verbreken
+- **Grijs (niet verbonden)**: Niet verbonden
+- **Geel (verbinden)**: Verbinding wordt tot stand gebracht
+
+#### Server Mode
+- **Groen (luisterend)**: Server luistert actief op poort
+- **Rood (gestopt/fout)**: Server is gestopt of fout opgetreden
+- **Blauw (actief)**: Server actief met X verbindingen
+
+### 6.2 Status Tekst
+- Dynamische status tekst onder het node icoon
+- Toon relevante informatie (IP:Port, aantal verbindingen, etc.)
+
+## 7. Foutafhandeling
+
+### 7.1 Client Mode Fouten
+- **Connection refused**: Server niet bereikbaar
+- **Connection timeout**: Timeout bij verbinden
+- **Network error**: Netwerkproblemen
+- **Socket closed**: Verbinding gesloten door server
+- **Invalid data format**: Data formaat fout
+
+### 7.2 Server Mode Fouten
+- **Port in use**: Poort al in gebruik
+- **Permission denied**: Geen rechten om op poort te luisteren
+- **Bind error**: Fout bij binden aan adres
+- **Client connection error**: Fout bij accepteren client
+
+### 7.3 Error Messages
+- Alle fouten moeten worden gemeld via output messages
+- Status node moet foutstatus tonen
+- Optioneel: error logging naar console
+
+## 8. Technische Details
+
+### 8.1 Implementatie
+- Gebruik Node.js `net` module voor TCP functionaliteit
+- Node-RED node development framework gebruiken
+- Asynchrone I/O voor betere performance
+- Event-driven architecture
+
+### 8.2 Dependencies
+- Node.js `net` module (built-in)
+- Node-RED runtime
+- EventEmitter patterns
+
+### 8.3 Performance Overwegingen
+- Efficiënte buffer handling
+- Memory management voor lange verbindingen
+- Throttling opties voor hoge data volumes
+- Connection pooling waar mogelijk
+
+### 8.4 Security Overwegingen
+- Input validation
+- Rate limiting opties (toekomstig)
+- TLS/SSL ondersteuning (toekomstig, indien gewenst)
+- Sanitize user input voor veiligheid
+
+### 8.5 Package Structuur
+- **Package naam**: `node-red-contrib-tcp-client-server-avd`
+- **Node type**: `tcp-client-server-avd`
+- **Bestandsstructuur**:
+  ```
+  node-red-contrib-tcp-client-server-avd/
+  ├── package.json
+  ├── README.md
+  ├── SPECIFICATIE.md
+  └── nodes/
+      ├── tcp-client-server-avd.js
+      └── tcp-client-server-avd.html
+  ```
+- **package.json configuratie**:
+  - `main`: "nodes/tcp-client-server-avd.js"
+  - `node-red.nodes`: verwijst naar "nodes/tcp-client-server-avd.js"
+  - Node-RED vindt automatisch het HTML bestand met dezelfde naam
+  - `files` veld specificeert welke bestanden in het package worden opgenomen
+
+## 9. Gebruiksvoorbeelden
+
+### 9.1 Basis TCP Client
+```
+Input → TCP Client Node → Output
+- Client verbindt automatisch met server
+- Verzendt data van input
+- Output ontvangen data
+```
+
+### 9.2 Basis TCP Server
+```
+TCP Server Node → Output
+- Server start automatisch
+- Luistert op poort 8080
+- Output ontvangen data van clients
+```
+
+### 9.3 Client met Reconnect
+```
+Input → TCP Client (met reconnect) → Output
+- Automatische herconnectie bij verbreken
+- Reconnect interval: 5 seconden
+- Max attempts: oneindig
+```
+
+### 9.4 Server met Meerdere Clients
+```
+TCP Server → Function Node → TCP Server
+- Server ontvangt data van meerdere clients
+- Function node verwerkt data
+- Verzendt response terug naar specifieke client
+```
+
+## 10. Toekomstige Uitbreidingen (Optioneel)
+
+- TLS/SSL ondersteuning voor beveiligde verbindingen
+- UDP protocol ondersteuning
+- WebSocket ondersteuning
+- Serial port ondersteuning
+- Data transformation nodes (JSON, XML, etc.)
+- Rate limiting en throttling
+- Connection statistics en monitoring
+- Message queue voor offline scenarios
+- Compression ondersteuning
+
+## 11. Test Scenario's
+
+### 11.1 Client Mode Tests
+- Verbinden met geldige server
+- Verbinden met ongeldige server (foutafhandeling)
+- Data verzenden en ontvangen
+- Automatische reconnect functionaliteit
+- Verbinding verbreken en handmatig reconnecten
+- Verschillende dataformaten testen
+
+### 11.2 Server Mode Tests
+- Server starten en stoppen
+- Meerdere clients accepteren
+- Data ontvangen en verzenden per client
+- Broadcast naar alle clients
+- Server restart met actieve verbindingen
+- Max connections limiet
+
+### 11.3 Integratie Tests
+- Client-Server communicatie
+- Lange verbindingen (stability)
+- Hoge data volumes
+- Foutscenario's (netwerk onderbrekingen)
+- Performance onder belasting
+
+## 12. Documentatie Vereisten
+
+- README met installatie instructies
+- Gebruikershandleiding met voorbeelden
+- API documentatie voor message formaten
+- Troubleshooting gids
+- Change log voor versies
+
+### 12.1 Installatie Methoden
+
+#### Via npm (aanbevolen)
+```bash
+npm install node-red-contrib-tcp-client-server-avd
+```
+
+#### Via Node-RED Manage Palette (tgz bestand)
+1. Open Node-RED webinterface
+2. Ga naar Menu → Manage palette
+3. Klik op Install tab
+4. Upload het `.tgz` bestand of geef het pad op
+5. Klik op Install
+
+#### Handmatige installatie
+1. Download of clone het project
+2. Kopieer de map naar Node-RED `nodes` directory (`~/.node-red/nodes/`)
+3. Installeer dependencies: `npm install`
+4. Herstart Node-RED
+
+### 12.2 Package Distributie
+- Het package wordt gedistribueerd als `.tgz` bestand
+- Gebruik `npm pack` om een distributie-bestand te maken
+- Het package bevat alleen essentiële bestanden (nodes/, README.md)
+- Bestandsnamen moeten consistent zijn met de node type naam
+
+## 13. Versie Beheer
+
+### Versie 1.0.0 (Initieel)
+- Basis TCP client functionaliteit
+- Basis TCP server functionaliteit
+- String en Buffer data formaten
+- Basis foutafhandeling
+- JSON en Hex format ondersteuning
+- Geavanceerde reconnect logica
+- Message delimiter ondersteuning
+- Keep-alive optie
+- IPv4 en IPv6 ondersteuning
+- Meerdere client verbindingen (server mode)
+- Package structuur geoptimaliseerd voor Node-RED installatie:
+  - Bestandsnamen aangepast naar `tcp-client-server-avd.js/html` voor consistentie
+  - `package.json` bijgewerkt met `main` en `files` velden
+  - Node configuratie vereenvoudigd (automatische HTML detectie)
+  - Distributie via `npm pack` voor correcte package structuur
+
+### Toekomstige Versies
+- Performance verbeteringen
+- TLS/SSL ondersteuning
+- Rate limiting en throttling
+- Connection statistics en monitoring
+- Message queue voor offline scenarios
+- Compression ondersteuning
+
+---
+
+**Document Versie**: 1.1  
+**Laatste Update**: Januari 2025  
+**Status**: Actueel