davsclaus opened a new pull request, #3194:
URL: https://github.com/apache/camel-kamelets/pull/3194
Part of #3170: `mqtt-source`, `mqtt-sink`, `mqtt5-source` and `mqtt5-sink`
take the quality of service, the sinks can retain messages, and all four can
trust a broker certificate from a private certificate authority.
### The options
| Option | Kamelets | Template mapping |
|---|---|---|
| `qos` (integer, 0, 1 or 2) | all four | `qos: "{{?qos}}"` |
| `retained` (boolean) | `mqtt-sink`, `mqtt5-sink` | `retained:
"{{?retained}}"` |
| `sslTruststoreLocation` | all four |
`"sslClientProps[com.ibm.ssl.trustStore]": "{{?sslTruststoreLocation}}"` |
| `sslTruststorePassword` (`format: password`) | all four |
`"sslClientProps[com.ibm.ssl.trustStorePassword]":
"RAW({{?sslTruststorePassword}})"` |
- **The `qos` gap is smaller than #3170 says.** camel-paho and
camel-paho-mqtt5 both default `qos` to 2, so the Kamelets already published and
subscribed with QoS 2, and the descriptions said so. What was missing is the
way to *lower* it to 0 or 1, for example for frequent sensor readings where a
lost one does not matter. On a source, `qos` is the highest QoS of the
subscription: a message arrives with the lower of it and the QoS it was
published with, as the `CamelMqttQoS` header already tells.
- **`retained`** makes the broker keep the last message of the topic and
give it to every client that subscribes later, such as the last known state of
a device.
- **TLS:** Paho takes its TLS settings as a `java.util.Properties`
(`sslClientProps`) with the keys `com.ibm.ssl.trustStore` and
`com.ibm.ssl.trustStorePassword`. Camel binds an entry of a Map or Properties
option from the URI as `sslClientProps[key]`, so the Kamelet needs no bean. The
trust store can be JKS or PKCS12. With it set, the Kamelet trusts the
authorities in that file **instead of** the ones Java trusts by default. The
certificate and the host name of the broker are still checked. The trust store
is only used with an `ssl://` address.
- None of the options has a `default`. When they are not set, the optional
placeholders drop them, so the endpoint URI is exactly today's. A `default: 2`
for `qos` or `default: false` for `retained` would only repeat the component
default, and it would override a value set on the paho component, which is
where a user would set it today. The descriptions say what applies when an
option is not set.
- **Validator:** the Kamelet validator in `kamelets-maven-plugin` rejected
`sslClientProps[com.ibm.ssl.trustStore]` as an unknown endpoint option. It now
accepts `option[key]` when `option` is an endpoint option of type
`java.util.Properties` or `java.util.Map`, in the same way it accepts the
entries of a multi-value prefix option.
- The "Good to know" paragraphs, the `brokerUrl` descriptions and the four
partial pages are updated, with an example of QoS 1, `retained` and a trust
store. The examples were run against the test broker.
Not in this PR: a client certificate (mutual TLS). It would work the same
way with `com.ibm.ssl.keyStore` and `com.ibm.ssl.keyStorePassword`, but it was
not asked for or tested. The other MQTT items in #3170 (`cleanSession`,
`cleanStart`, `sessionExpiryInterval`, `clientId` on the sinks,
`automaticReconnect`) are also left for later.
### Verification
Tested with Camel JBang 4.24.0-SNAPSHOT (`camel run
--local-kamelet-dir=kamelets`) against Eclipse Mosquitto 2.1 in Docker, with a
plain listener and a TLS listener. The TLS listener's certificate was signed by
a self-signed test CA, for `localhost` and `127.0.0.1`. The QoS and the retain
flag were read from the broker log (`Received PUBLISH ... (d0, qN, rN, ...)`
and `Received SUBSCRIBE ... (QoS N)`). The trust store password was
`p@ss&w+rd=1`, to check that `RAW()` passes it through. Each case was run on
both the MQTT 3.1.1 and the MQTT 5 Kamelets.
| Case | Sinks (`mqtt-sink`, `mqtt5-sink`) | Sources (`mqtt-source`,
`mqtt5-source`) |
|---|---|---|
| Options unset, endpoint URI from `main` and from this PR | Same:
`paho://<topic>?brokerUrl=tcp://...`, no extra parameter | Same |
| Options unset | Published with q2, r0 | Subscribed with QoS 2; a QoS 2
message arrives with `CamelMqttQoS` 2 |
| `qos: 0` | Published with q0 | Subscribed with QoS 0; a QoS 2 message
arrives with QoS 0 |
| `qos: 1` | Published with q1 | Subscribed with QoS 1; a QoS 2 message
arrives with QoS 1 |
| `qos: 2` | Published with q2 | Subscribed with QoS 2; a QoS 2 message
arrives with 2, a QoS 1 message with 1 |
| `retained: true` (also with `qos: 1`) | Published with r1. A
`mosquitto_sub` that connects afterwards receives the message. | - |
| `retained: false`, and unset | Published with r0. A later subscriber
receives nothing. | - |
| A source that subscribes after a retained message was published | - |
Receives the retained message |
| `ssl://`, trust store with the test CA (JKS) | Sent over TLS 1.3 |
Receives |
| `ssl://`, the same CA as a PKCS12 trust store | Sent | - |
| `ssl://`, trust store without `sslTruststorePassword` (JKS) | Sent | - |
| `ssl://`, no trust store (as on `main`) | Fails to start: `PKIX path
building failed` | The same |
| `ssl://`, trust store with another CA | Fails to start: `PKIX path
building failed` | The same |
| `ssl://`, trusted CA, broker addressed by an IP address that is not in the
certificate | Fails to start: `No subject alternative names matching IP
address` | The same |
| `ssl://`, wrong trust store password | Fails to start: `Keystore was
tampered with, or password was incorrect` | The same |
| `tcp://` with a trust store set | Sent; the trust store is not used | - |
| JVM trusts the test CA (`-Djavax.net.ssl.trustStore`), no Kamelet trust
store | Sent | - |
| JVM trusts the test CA, Kamelet trust store with another CA | Fails: the
Kamelet trust store replaces the JVM's | - |
| Partial-page examples (sink with QoS 1, retained and a trust store;
sources with QoS 1, `sensors/#`) | Published with q1, r1 | Subscribed with QoS
1 and received |
`./mvnw clean verify -DskipTests` and `./mvnw clean verify` from the root
both pass. The generated `kamelets-index.json` and the `library/camel-kamelets`
copies of the Kamelets were regenerated and are committed. The copies are made
in the `install` phase, so I ran that build step with `./mvnw -pl
library/camel-kamelets resources:copy-resources@copy-resource-one`. The MQTT 5
Citrus test (`mqtt5-sink-to-source-route.citrus.it.yaml`) was already disabled,
and no Citrus test was added.
_Claude Code on behalf of Claus Ibsen_
🤖 Generated with [Claude Code](https://claude.com/claude-code)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]