eclipse-uprotocol / eclipse-uprotocol/up-spec
Add UMessageBuilder based L1 API
- Dominant language
- Gherkin
- Stars
- 43
- Forks
- 29
- Avg merge
- 20m
- Merged PRs (30d)
- 3
Description
While thinking about introducing a hierarchy of UMessage traits that would reflect the different types of messages that uProtocol supports, like _Publish_ or _RPC Request_, I was wondering if it would make sense to extend (or alter) the L1 UTransport API to use traits instead of structs as parameter types.
For example, instead of having `UTransport::send(UMessage)` where `UMessage` is the struct from up_rust, I can imagine something like
```rust
message_to_send: PublishBuilder = UTransport::publish_builder(source: UUri);
message_to_send.with_ttl(5000).send_with_payload(payload: Bytes, payload_format: UPayloadFormat);
```
where PublishBuilder would be a trait from up_rust that is implemented by the transport library.
This way, the transport can implement the message creation in the most effective way for the type of transport protocol it uses. For example the MQTT 5 transport could let its builder write all properties directly into a newly created MQTT message object instead of having to map the UMessage instance to an MQTT message instance.
Similarly, an iceoryx2 transport could have its builder allocate the shared memory during builder instantiation and then also have it write all attributes directly into the shared memory.
At the receiving end, we could replace `UListener::on_receive(UMessage)` where UMessage is a struct, with something like
```
pub trait UMessage {
fn source() => UUri;
....
}
pub trait UListener {
async fn on_receive(T);
}
```
In this case, the transport could pass its implementation of `UMessage` into the listener, which might simply be a _view_ on the underlying MQTT message struct, or it could be a view on the shared-memory segment that has been used to transmit the message.
The up_rust crate would still provide the `UAttributesValidator` in order to make sure that transports always provide valid UMessage instances.
@PLeVasseur @AnotherDaniel WDYT?
Contributor guide
Research direction
Start by reviewing the L1 UTransport and UListener APIs described in the issue, along with the up_rust UMessage and UAttributesValidator concepts. Compare the proposed builder and trait-based interfaces with the current struct-based approach. Done means reaching and documenting an agreed API direction for message construction and reception.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- api, backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100