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 Signed Messages
  // The Signature is the HMAC-SHA256 of (Method + Path + Payload) using your API Key
  ws.send(JSON.stringify({
    TraceID: "uuid-v4-frontend-req",
    Method: "GET",
    Path: "/api/entitys",
    Payload: "{}",
    Signature: "2d7a221f7dbb2..." 
  }));
};

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

Message Integrity (HMAC-SHA256)

To prevent man-in-the-middle tampering on full-duplex streams, GO-DUCK requires every WebSocket envelope to be digitally signed.

Algorithm HMAC-SHA256

Signed Data method + path + payload

2. Unified Messaging Hub (MQTT & NATS)

GO-DUCK features a Multi-Broker Messaging Hub. Every successful CREATE / UPDATE / DELETE on any model is simultaneously broadcast to both brokers if enabled.

MQTT (Real-time UI)

Topic Pattern: go-duck/events/{entity}/{action}

# Listen to Car Deletions
mosquitto_sub -t "go-duck/events/car/DELETE"

NATS (High-Perf CQRS)

Subject Pattern: go.duck.events.{entity}.{action}

# Listen to any Car mutations
nats sub "go.duck.events.car.>"