Skip to content

Latest commit

 

History

History
254 lines (158 loc) · 9.04 KB

README.adoc

File metadata and controls

254 lines (158 loc) · 9.04 KB
Raw

Transport & Session Layer (uP-L1) Specifications

Table of Contents

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in IETF BCP14 (RFC2119 & RFC8174)

Copyright (c) 2023 General Motors GTO LLC

Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.

SPDX-FileType: DOCUMENTATION
SPDX-FileCopyrightText: 2023 General Motors GTO LLC
SPDX-License-Identifier: Apache-2.0
Important
 This specification is a work in progress and needs to be updated to uProtocol 1.5 (uAttributes, uPayload, , etc…​)

Transport & Session Layer is responsible for bidirectional point-2-point communication between uEs. What gets sent between uEs vary considerably depending on the type of payload (Safety, Security, fire & forget, etc…​) as well as the deployment environment where the uEs are located (Android, Linux, MCU, etc…​).

The Purpose of this layer of the protocol is to define a common ubiquitous language for sending and receiving a messages in a common way across transports, heterogeneous system the uEs are deployed on, or the programming language used.

This specification shall define the data models (types) and interfaces.

uProtocol programming language specific libraries (SDKs) declare the transport layer interfaces and define the data model, while transport technologies (ex. Binder, MQTT, Zenoh, SOME/IP, DDS, HTTP, etc…​) implement said interfaces per language.

Note
 We will define the various interfaces in this specification using pseudo code in lieu of a particular IDL such as protobuf as we expect the implementations of this spec to vary slightly between languages.

We will use the following terminology during this document:

Table 1. API Definition Terminology
Term Description

IN

Input parameter

OUT

Output parameter

IN/OUT

Input/output parameter

&

Parameter passed by reference

Future

Language specific mechanism to access the result of asynchronous operations, ex. std::future for C++, CompletableFuture for Java, etc…​
Note
 uProtocol data model used by the uTransport interface are declared in uprotocol-core-api

1. UListener

UListener is an interface used for receiving messages by the client uE from the uTransport layer. Listeners are used for receiving messages asynchronously by the uTransport layer.

  • Type name MUST be UListener

  • MUST contain the method UStatus onReceive(UUri&, UPayload&, UAttributes&) that is called by the Transport to notify (callback) the client

2. uTransport Interface

The transport layer API responsible for point-2-point communication. The interface provides common functionality across all transport implementations.

  • MUST implement all APIs defined in this section

2.1. Authenticate()

API used to verify the identity of the calling uE by confirming that the passed [UEntity] matches that of the transport layer specific identity required for Code-Based Access Permissions (CAPs).

OUT UStatus authenticate(IN UEntity)

2.1.1. Parameters

Table 2. Register Parameters
Parameter Description

UEntity

uProtocol UEntity name and version used for identification verification

  • MUST be called before any other uTransport APIs

  • MUST be idempotent, subsequent calls to the API return the same value

  • MUST authenticate client uE identity by ensuring that the UEntity matches the transport specific identity mechanism.

  • Non authenticated uEs MUST be returned UNAUTHENTICATED status code

2.2. Send()

Publish/send UPayload and UAttributes to a UUri (topic).

Communication protocols (a.k.a. uProtocol Transports) define their own Protocol Data Unit (PDU) that comprises of header and payload. Some transports header parameters map already to uProtocol UAttributes. Sending UAttributes in the transport’s payload as well as in the header increases overhead for little to no gain. To address this issue, Send() allows flexibility for uTransport implementers to define however they see fit what gets mapped into their transport header vs payload.

For example, if HartleyTransport can map only UPriority to its PDU header, then HartleyTransport would define a PDU payload type that includes UPayload and all the other UAttributes and send that new type in its PDU payload such that the receiver will not loose any metadata.

The API signature:

OUT UStatus send(UUri&, IN UPayload&, IN UAttributes&)

2.2.1. Parameters

Table 3. Send Parameters
Parameter Description

UUri

Destination for the UPayload

UPayload

Data and metadata to be sent

  • MUST be passed by reference

UAttributes

Communication protocol attributes

  • MUST be passed by reference

  • All UAttribute metadata MUST be preserved during transmission and available to the receiver

  • MUST not manipulate the UPayload data during transmission

  • Transport MAY modify the UUri& to set the transportId

2.3. RegisterListener()

Register a UListener to receive message(s) for a given UUri (topic). This API is used to implement the push Delivery Method.

API Signature:

OUT UStatus registerListener(IN UUri, IN UListener&)

  • MUST support registering more than one listener per topic

  • MUST support registering more than one topic per listener

  • Transport implementations MUST declare the maximum number of listeners per topic that it can support. If the maximum number of listeners is reached, the transport MUST return RESOURCE_EXHAUSTED status code

2.3.1. Parameters

Table 4. RegisterListener Parameters
Parameter Description

UUri

Topic to register the listener for

UListener

Listener to be registered

2.4. UnregisterListener()

API used to unregister a UListener for a given topic.

API Signature:

OUT [UStatus] unregisterListener(IN UUri, IN UListener&)

2.4.1. Parameters

Table 5. UnregisterListener Parameters
Parameter Description

UUri

Topic to unregister the listener for

UListener

Listener to be unregistered

2.5. Receive()

Implements the pull Delivery Method to fetch a message from the transport for a given UUri (topic).

OUT [UStatus] receive(IN UUri, OUT UPayload&, OUT UAttributes&)

2.5.1. Parameters

Table 6. Receive Parameters
Parameter Description

UUri

Topic to receive the message from

UPayload

Data and metadata received

  • MUST be passed by reference

UAttributes

Message metadata

  • MUST be passed by reference

  • MUST return NOT_FOUND if there are no messages for the given topic

2.6. Message Delivery

2.6.1. Policy

  • Transport MUST support At-least-once delivery policy, this means that a sender MUST have a way to guarantee that the CE was successfully received by the Receiver (through the returned [UStatus])

  • Transport MUST support retransmission of CEs that are no able to be sent

If the uP-L1 transport layer is above OSI Session layer 5:

  • MUST use Transmission Control Protocols (TCP) and MUST NOT User Datagram Protocol (UDP) for message delivery

2.6.2. Delivery Method

  • Transport MUST support either push or pull delivery method

  • MAY support both push or pull delivery methods between uEs

  • Delivery method SHOULD be known by uEs at design time

  • Receivers MAY select which delivery method they prefer if the transport between sender and receiver supports more than one delivery method

Note
 Delivery method advertising shall be defined later

3. Transport Specifics

Below is an non-exhausted list of transport specific requirements to ensure consistency across implementations of the same or different languages: