SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation See the NOTICE file(s) distributed with this work for additional information regarding copyright ownership. This program and the accompanying materials are made available under the terms of the Apache License Version 2.0 which is available at https://www.apache.org/licenses/LICENSE-2.0 SPDX-FileType: DOCUMENTATION SPDX-License-Identifier: Apache-2.0
This document contains information regarding some design decisions made for the implementation of the transport.
The MQTT 5 standard does not define any mechanism for message prioritization. All messages are being processed with the same priority. Consequently, the MQTT 5 transport provided by this crate simply ignores the service class set on a uProtocol message being sent.
All messages are being received by means of subscribing to relevant topics on the MQTT broker and delivering the messages to listeners that have been registered via up_rust::UTransport::register_listener.
The transport spawns a dedicated [tokio task](https://tokio.rs/tokio/tutorial/spawning#tasks) that listens for incoming messages and dispatches them to the registered listeners on the same thread that the message handling task runs on.
Rationale: The MQTT 5 standard does not provide means to poll the broker for messages but only supports the push model by means of clients subscribing to topic filters.
The transport requires a tokio runtime to execute but does not make any implicit assumption regarding the availability and size of thread pools. This provides for flexibility regarding the environment that the transport can be deployed to but also requires application developers to take care when implementing message listeners, making sure to not block the transport’s incoming message handler when processing a dispatched message.
This crate provides an implementation of the uProtocol Transport Layer API. This API can be used by client code (uEntities) for sending and/or receiving messages to/from other uEntities. In general, this crate does not impose any restrictions on a message’s source and sink addresses when handling messages. In particular, the crate itself does not verify a uEntity’s identity nor checks a uEntity’s authority to send and/or receive messages using particular addresses (UUris).
However, the transport implementation provided by this crate supports the configuration of client credentials (username/password and/or X.509 certificate) for authenticating to an MQTT 5 broker during connection establishment.
When a uEntity using this transport tries to connect to a broker using invalid credentials, the broker will return an MQTT CONNACK packet including a corresponding Reason Code back to the client (see section 3.2.2.2 of the MQTT 5 specification for details). This transport’s function for connecting to the broker will fail with a UStatus error having a UCode as defined in Mapping of MQTT 5 Reason Codes to UCodes.
Most MQTT brokers allow the configuration of Access Control Lists (ACL), which can be used to restrict a client identity’s access to certain MQTT topic patterns only. Given a set of ACLs for a uEntity using this transport implementation:
-
When the uEntity tries to send a message using a source and/or sink address which map to an MQTT topic that the client is not authorized to publish to, the broker will return an MQTT PUBACK packet including a corresponding failure Reason Code to the client (see section 3.4.2.1 of the MQTT 5 specification for details).
-
When a uEntity tries to subscribe to messages using a source and/or sink address pattern which results in an MQTT topic that the client is not authorized to subscribe to, the broker will return a corresponding Reason Code in its MQTT SUBACK packet sent back to the client (see section 3.9.3 of the MQTT 5 specification for details).
The transport implementation will fail the invoked function with a UStatus error having a UCode as defined in Mapping of MQTT 5 Reason Codes to UCodes.
This transport maps Reason Codes from MQTT 5 packets to uProtocol `UCode`s as follows
| Reason Code | UCode |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
All other (error) reason codes > 0x80 are mapped to INTERNAL.