Destination mapping

The STOMP destination is the single most important mental model in this connector. A destination's first segment selects the KubeMQ pattern; the remaining segments are slash→dot joined into the KubeMQ channel. This is how an unmodified STOMP application reaches all five KubeMQ patterns by changing only the address it dials.

The grammar

The connector resolves a destination in these steps:

1. The raw destination length is checked first — ≤ 512 bytes, on the raw string before the leading-slash strip.
2. Strip exactly one leading / (both /queue/x and queue/x are accepted).
3. Split on /. Any empty segment (from //, a trailing /, etc.) is rejected as invalid destination.
4. The first segment selects the pattern via a case-sensitive map.
5. The remaining segments are .-joined into the KubeMQ channel.
6. An unknown first segment falls back to DefaultPattern (see below).

Primary prefix → pattern → channel

Lead with these primary names in every application and example:

Slash → dot, and the literal-dot trap

The channel join is slash→dot: /topic/a/b/c → channel a.b.c. Egress reverses it: channel a.b.c → /topic/a/b/c. A literal . inside a segment passes through unchanged — which makes it lossy.

SEND  /topic/a.b   ─┐
                    ├─►  channel "a.b"  ─►  MESSAGE destination /topic/a/b
SEND  /topic/a/b   ─┘

MQTT-name aliases (never lead with them)

For migration convenience, each primary prefix has an MQTT-style alias. They route identically, but egress always canonicalizes to the primary name — a subscriber never sees the alias on the delivered MESSAGE destination.

The aliases exist only so an in-flight migration from MQTT-style naming keeps working; because egress canonicalizes, a fleet that subscribes via /events/x and a fleet that subscribes via /topic/x both receive /topic/x on the wire. Always lead docs, examples, and application code with the primary names.

DefaultPattern (bare destinations)

A destination whose first segment is not a known prefix is treated as bare and routed by the connector's DefaultPattern config:

There is no commands / queries default — a bare destination can never resolve to an RPC pattern.

Wildcards — Events only, subscribe only

Wildcards are pass-through to the message broker's native wildcard syntax — the connector does not translate them:

• * matches one segment, in any position.
• > matches the tail, and must be the final segment.

SUBSCRIBE  /topic/orders/*    → channel filter "orders.*"  (Events, OK)
SUBSCRIBE  /topic/orders/>    → channel filter "orders.>"  (> must be final, OK)
SEND       /topic/orders/*    → invalid destination
SUBSCRIBE  /queue/jobs/*      → invalid destination

# Egress delivers the concrete channel:
SUBSCRIBE  /topic/orders/*  ──►  MESSAGE destination /topic/orders/eu   (NOT /topic/orders/*)

Slash→dot still applies inside wildcard filters: /topic/a/*/c → a.*.c. Wildcards do not apply to Events-Store.

Header ⇄ tag interop

The body is byte-exact in both directions (the writer always stamps content-length on egress, so it is binary-safe). Metadata is mapped between STOMP headers and KubeMQ Tags by a precise convention.

The five standard headers ↔ reserved stomp.* tags

These five round-trip in both directions:

A SEND content-type:application/json becomes Tag stomp.content-type=application/json; on egress that tag is restored to a content-type header.

Custom headers pass through as tags

Any header not in the standard set and not protocol machinery passes through name-as-is as a KubeMQ tag. A custom x-trace:abc on SEND becomes Tag x-trace=abc, delivered back as an x-trace header. Duplicate header names are first-wins.

Collision rule, machinery headers, and the spoofing guard

• Collision rule — stomp.* wins. If a native producer sets both a bare content-type tag and a stomp.content-type tag, the stomp.* tag wins on egress, and exactly one content-type header is emitted.
• Machinery headers never become tags: destination, receipt, transaction, content-length, message-id, subscription, ack, id, timeout.
• Spoofing guard. A client cannot inject stomp.* tags directly. On ingress, any header whose name starts with stomp. or equals x-kubemq-metadata is silently stripped — the only way to set a stomp.* tag is through the corresponding standard header.
• x-kubemq-metadata is egress-only. STOMP ingress never sets the KubeMQ Metadata field. On egress, if a native producer left a non-empty Metadata, it surfaces as a read-only x-kubemq-metadata header. A STOMP client can observe it but cannot write it.

Egress representability per version

Not every header value can be serialized on every negotiated STOMP version. The connector drops unrepresentable headers on egress rather than corrupting the frame:

Destination errors (all sanitized)

Internal error text never crosses the wire — every destination error surfaces as the single sanitized invalid destination message.

Related