uStreamer Documentation #64
Conversation
…ansport interface. Currently a WiP.
|
|
||
| NOTE: Dispatcher and router shall be used For the remainder of this document we will use the term dispatcher and router interchangeably. | ||
|
|
||
| The header contains information for routing as well as metadata (of the data). One of the core principles of uProtocol is that the data portion of CE *MUST* be untouched by message routers, this is very similar to how most Internet standards work today. Only the source who generated the CE and the sink who will consume the CE needs to understand/analyze the payload of the CE. | ||
| The header contains information for routing as well as metadata (of the data). One of the core principles of uProtocol is that the data portion of UMessage *MUST* be untouched by message routers, this is very similar to how most Internet standards work today. Only the source who generated the UMessage and the sink who will consume the UMessage needs to understand/analyze the payload of the UMessage. |
There was a problem hiding this comment.
May be good to clarify we're talking specifically about a UPayload here? I.e. we shall not touch / read / modify UPayload.
|
|
||
| NOTE: Dispatcher and router shall be used For the remainder of this document we will use the term dispatcher and router interchangeably. | ||
|
|
||
| The header contains information for routing as well as metadata (of the data). One of the core principles of uProtocol is that the data portion of CE *MUST* be untouched by message routers, this is very similar to how most Internet standards work today. Only the source who generated the CE and the sink who will consume the CE needs to understand/analyze the payload of the CE. | ||
| The header contains information for routing as well as metadata (of the data). One of the core principles of uProtocol is that the data portion of UMessage *MUST* be untouched by message routers, this is very similar to how most Internet standards work today. Only the source who generated the UMessage and the sink who will consume the UMessage needs to understand/analyze the payload of the UMessage. |
There was a problem hiding this comment.
We can read, but also should not be modifying the UUri and UAttributes in order to perform routing. Not sure if we have to explicitly state that in the spec. Feels like better to be clear on that point tho. WDYT?
There was a problem hiding this comment.
I'd agree that we shouldn't modify source/destination UURis and existing uAttributes. We might need to add an attribute in the chain of transport.
I was going to say in accepting a SOME/IP message into the uProtocol universe there is the need to add an attribute saying whether any MAC protection checks happened and passed. But that happens at the protocol boundary, so really isn't the same thing. This might be useful between devices inside the same domain if MAC checks are included and messages not passing the MAC testing on ingestion aren't just dropped.
Is there any transport special "events" that might want us to add a hint to a message as an attribute? Perhaps messages there were queued from the previous power cycle would benefit from a hint to the destination (if they care to look for it) saying "this message was delayed in being delivered". This might trigger special handling at the sink.
| @@ -64,16 +64,16 @@ In this section we will elaborate on the requirements of the platform Dispatcher | |||
|
|
|||
| NOTE: These communication layer requirements are still for point-2-point uE communication to and from a dispatcher | |||
|
|
|||
| * *MUST* support At-least-once delivery policy, this means that the dispatcher will make every attempt to dispatch the CE to the intended Receiver | |||
| * *MUST* support At-least-once delivery policy, this means that the dispatcher will make every attempt to dispatch the UMessage to the intended Receiver | |||
There was a problem hiding this comment.
I got really hung up on this section a while ago. Maybe others reading the spec can get this but I couldn't.
Would suggest adding some verbiage like:
- If a transport level protocol being used has an at-least-once delivery policy, this requirement is satisfied for that transport protocol.
There was a problem hiding this comment.
Maybe something like: This requirement can be met with a combination of uProtocol layers and the transport protocol used.
Also, while the uProtocol design and implementation MUST have design elements to do this, there are edge cases such as uProtocol stack or host device unexpected shutting down or crashing without warning that result in data loss. These are beyond this guarantee.
| * *MAY* support additional CE delivery policies in general or per topic in the future | ||
| * *SHOULD* dispatch in order that it received the CE | ||
| * *MAY* support additional UMessage delivery policies in general or per topic in the future | ||
| * *SHOULD* dispatch in order that it received the UMessage | ||
| * *MAY* batch CEs when delivering to the Receiver | ||
| * CEs that cannot be delivered *MUST* be sent to the Dead Letter topic (DLT) |
| * *MAY* support additional CE delivery policies in general or per topic in the future | ||
| * *SHOULD* dispatch in order that it received the CE | ||
| * *MAY* support additional UMessage delivery policies in general or per topic in the future | ||
| * *SHOULD* dispatch in order that it received the UMessage | ||
| * *MAY* batch CEs when delivering to the Receiver |
|
|
||
| == Overview | ||
|
|
||
| The streamer is a uProtocol dispatcher responsible to route messages to/from the local link:../../up-l1/README.adoc[uTransport] to one or more remote uTransports. Local uTransport refers to the transport implementation that the streamer is running on (the transport for the device that the streamer is deployed to). Remote UTransports are any non-local transports that messages need to be forwarded to. |
There was a problem hiding this comment.
Think something got lost here?
Local uTransport refers to the transport implementation that the streamer is running on (the transport for the device that the streamer is deployed to).
Maybe:
Local uTransport refers to the transport implementation that the streamer is using to communicate messages to uEs within the device.
There was a problem hiding this comment.
I like the proposed alternate text. "running on" can mean the OS and/or the actual IPC transport.
| Below is an example of a simple routing configuration to connect a single local transport with a remote transport. for the purpose of this example, the local device will have UAuthority `uLocal` and the remote device will be have the UAuthority `URemote`. | ||
|
|
||
| ``` | ||
| yes one sec |
There was a problem hiding this comment.
Maybe this is the @stevenhartley equivalent of a TODO 🙂, otherwise I'm unsure of what this is.
|
See comments... |
| ** *MUST* attempt to retry transmission of the CE. Retry policy is specific to the dispatcher implementation | ||
| ** Dispatcher *MUST NOT* discard CEs unless either CE has expired (CE.ttl), or the egress queue is full. CEs that cannot be delivered are sent to a Dead Letter Office Topic | ||
| ** *MUST* attempt to retry transmission of the UMessage. Retry policy is specific to the dispatcher implementation | ||
| ** Dispatcher *MUST NOT* discard CEs unless either UMessage has expired (UMessage.ttl), or the egress queue is full. CEs that cannot be delivered are sent to a Dead Letter Office Topic |
stevenhartley
added
documentation
Provide more details of how to implement uStreamer using only the uTransport interface.
Currently a WiP.