Skip to content

Latest commit

 

History

History
125 lines (85 loc) · 5.77 KB

README.adoc

File metadata and controls

125 lines (85 loc) · 5.77 KB

Transport & Session Layer (uP-L1)

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)

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.

1. Overview

Transport & Session Layer is responsible for connecting uEs together for bidirectional point-2-point communication.

Specifications are organized by the transport types where each transport shall define the following requirements:

  • Session & Transport Binding

    • How connections are established and managed between uEs (over the transport)

  • uP-L2 Protocol Binding

    • How uP-L2 messages (CloudEvents) are carried over the various transports

Note
 Not all transports are the same, some map CE headers into their transport headers while others place the entire CE into transport’s payload.

  • CloudEvent Format

    • Encoding (format) of both the CloudEvent and payload for a given transport

Note
 Some protocols/implementations require a specific content type while others are flexible (i.e. there is a data content type attribute in the transport’s header). See CloudEvent Format vs Data Format for more information

2. Transport Protocols

Table below provides a breakdown of the various transport specific specifications with links to their detailed specifications.

Table 1. Transport Layers
Protocol Description Format(s) Examples

Binder

Androids IPC & RPC communication transport, used for uprotocol-android uE-2-uE transport

Protobuf

uprotocol-android

MQTT

Device-2-Cloud & Cloud-2-Device Communication

JSON

uprotocol-android

HTTP/2

Cloud intra-Device uE-2-uE transport

JSON or Protobuf

Coming soon

SOME/IP

uDevice to mDevice communication to bridge uProtocol to SOME/IP

SOME/IP message format (translated from CloudEvents)

Coming soon

3. uLink API

uLink is the uProtocol transport layer API responsible for point-2-point communication. The interface provides basic functionality to connect() & disconnect() to the other uE as well as send() & receive() of CEs between software components.

  • All transports MUST implement the APIs declared below

  • Additional APIs MAY be added to simplify sending and receiving of messages (ex. InvokeMethod() to handle correlation between request and response messages)

Note
 Given implementation of uLink is language and transport specific, we describe the interface in uLink API below in lieu of in an IDL.
Table 2. uP-L1 API Definition
Method Description

connect(String clientUri, in Any clientToken, in IEventListener listener);

Create a point-2-point connection with an event dispatcher uE (ex. uBus, uStreamer, etc…​). Passed parameters are the clients uProtocol URI, a deployment specific identity token (used to confirm the identity of the connecting client), and an event listener if the event delivery is push method (ex. Android Binder)

disconnect()

Terminate the connection to the dispatcher

send(CloudEvent message)

Send a uP-L2 Message to the dispatcher

CloudEvent pull(String uri, int count)

Fetch the latest message from the dispatcher, used for pull event method

4. Message Delivery

4.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

  • 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

4.1.1. Method

  • Transport MUST support either push or pull delivery method

  • MAY support both push or pull CE 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