Connectivity and security

The KubeMQ STOMP connector is an embedded STOMP server inside kubemq-server with its own dedicated listeners — plain TCP 61613 (default) and TLS 61614 (default). An existing STOMP application connects to it by changing only the broker address. This guide covers the connection URL convention, the CONNECT handshake, heartbeats, TLS, and the connection limit.

KUBEMQ_STOMP_URL — the connection convention

The connector reads KUBEMQ_STOMP_URL (default tcp://localhost:61613) and dials it. The URL scheme selects the transport:

export KUBEMQ_STOMP_URL="tcp://localhost:61613"        # default — plain TCP listener (port 61613)
# export KUBEMQ_STOMP_URL="tls://kubemq.example:61614" # TLS listener (port 61614, see below)

The connector binds all interfaces (:<port>), not just localhost. Both ports are configurable via the connector configuration.

The CONNECT handshake

Every connection opens with the same CONNECT frame and reads the negotiated CONNECTED headers back:

CONNECT
accept-version:1.2          # highest common of 1.0/1.1/1.2; absent/empty → 1.0
heart-beat:10000,10000      # client cx,cy in ms; server advertises sx=sy=HeartbeatMs (default 10000)
login:my-app                # freeform (session id fallback when no JWT claims)
passcode:                   # empty/any in the default no-auth mode

^@

The CONNECTED reply carries:

CONNECTED headers are never escaped (handshake exemption). The handshake order is: version negotiation → broker-ready gate → max-connections check → auth → derive client id → heartbeat negotiation → send CONNECTED.

Heartbeats and the 2x dead-peer cutoff

Heartbeats keep the TCP connection alive and let the connector detect a dead peer.

• The client sends heart-beat:cx,cy (ms). The server advertises sx = sy = HeartbeatMs (default 10000; 0 disables the server side).
• Effective client→server interval = maxNonZero(cx, sy); server→client = maxNonZero(sx, cy) — where maxNonZero(a, b) is 0 if either side is 0 (that direction is disabled), otherwise max(a, b).
• Parsing is lenient: a missing, non-numeric, negative, or 3-field value becomes 0,0.

Recommendation: send heart-beat:10000,10000 (matches the server default). With a 10 s client→server interval the cutoff is 20 s — a client must send a frame or a bare \n before that window elapses.

TLS

export KUBEMQ_STOMP_URL="tls://kubemq.example.com:61614"

• The TLS listener is the default port 61614 (tls://...).
• It is active only when the TLS port is configured and the server-wide Security block resolves to non-nil TLS. If the Security mode is none, the TLS port is silently skipped.
• TLS has no STOMP-specific config. The certificate material, mTLS, and minimum version all come from the server-wide Security block — the connector owns only whether the TLS port is open. mTLS requires and verifies the client certificate; the minimum is TLS 1.2.

For the shared KubeMQ JWT model and TLS/mTLS concepts across connectors, see Auth & security.

WebSocket is not supported in V1

Connection limit

The connector enforces a maximum connection count (default 1000; 0 = unlimited). The slot is counted at accept — a raw TCP socket that never sends CONNECT still consumes a slot — but the over-limit ERROR "connection limit reached" is deferred to the handshake so the client receives a proper frame.

Errors are terminal

Every protocol error produces an ERROR frame followed by a socket close. The message is sanitized — internal error text never crosses the wire. Treat every ERROR frame as terminal in client code, and reconnect if appropriate.

Related