WebSockets & MQTT Event Streaming

Execute REST requests securely over full-duplex WebSocket connections or subscribe to async CRUD event streaming.

1. REST-over-WS Dispatcher

Instead of traditional HTTP, you can pass highly efficient "Traced Envelopes" through our WebSocket endpoint at ws://localhost:8080/ws. The GO-DUCK generated engine unpacks the WS payload and routes it natively through Gin.

Note: Token validation is done via query-param out of necessity due to websocket protocol limitations.

Browser/JS Connection Spec

const token = "eyJhbGciOi..."; // Valid Keycloak Access Token

// Phase 1: Authentication happens precisely on the handshake (WSS Handshake via query param)
const ws = new WebSocket(\`ws://localhost:8080/ws?token=\${token}\`);

ws.onopen = () => {
  // Phase 2: Send HMAC-SHA256 Encrypted / Signed Messages!
  ws.send(JSON.stringify({
    TraceID: "uuid-v4-frontend-req",
    Method: "GET",
    Path: "/api/entitys",
    Payload: "{}",
    Signature: "2d7a221f7dbb2..." // Signature ensures Message Integrity
  }));
};

ws.onmessage = (event) => console.log("Received via WS:", event.data);

2. Asynchronous MQTT Streaming

Rather than relying entirely on synchronous API calls, every successful CREATE / UPDATE / DELETE on any GDL generated model emits an event to the unified MQTT broker configured in the `docker-compose.yml`.

How to listen for specific webhooks

# mosquitto_sub listening to any mutation globally inside the microservice
mosquitto_sub -h localhost -p 1883 -t "go-duck/events/#" -u dev_user -P dev_password

# To listen ONLY when the Entity object gets created
mosquitto_sub -h localhost -p 1883 -t "go-duck/events/entity/CREATE" -u dev_user -P dev_password