uPClient Interface (uP-L2)

[stevenhartley]

We have now concluded clear interface and data model definitions for the transport layer (Layer 1) with UUri, UAttributes, UPayload, UMessage and UTransport.

The purpose of Layer 2 in the uProtocol stack is to handle the communication patterns for RPC, pub/sub, and notifications however all we had so far is RpcClient for client-side RPC but there is no interface for server-side RPC, pub/sub, and notifications. uSubscription has been defined at L3 as it defines the protobuf messages that are sent between client and server (inside UPayload of a UMessage).

After creating numerous implementations of uProtocol across 5 different programming languages, we've noticed that no 2 L2 interfaces for the communication patterns are defined the same as each programmer would like to leverage language specific features like Flows for Kotlin, or certain traits in Rust.

The purpose of this issue shall be to provide a place to discuss and propose the minimum requirements for what uP-L2 client facing APIs should be extending/clarifying what is in https://github.com/eclipse-uprotocol/up-spec/tree/main/up-l2 and https://github.com/eclipse-uprotocol/up-spec/blob/main/upclient.adoc. Depending on the feedback for the proposal below, the contents of up-l1 folder and upclient.adoc will be updated.

NOTE: uP-L1 interfaces implements the core uProtocol (across the communication middlewares) and uP-L2 API are the client-facing APIs that wrap the transport functionality into easy to use APIs to do the most common functionality of the protocol (subscribe, publish, notify, invoke a Method, or handle RPC requests).

UPClient API

Below lists the high level APIs and their purpose that will be implemented per programming language. The signature of said APIs are left up to the language library implementer to define.

API Name	Pattern	Description
subscribe()	pub/sub	Subscribe to a given topic (regardless of the location of the publisher). API must be able to optimally receive the message (ex. passing UListener for handling in a callback)
publish()	pub/sub	Publish to a given topic a message
notify()	Notification	Send a notification message to a given topic
invoke_method()	RPC	Client-side API for RPC to send a request and receive a reply
register_method_listener()	RPC	Server-side API for services to receive the request and send a reply

[PLeVasseur]

I think these APIs are reasonable.

A couple of suggestions (these may already be on your todo list :) )

• Would be good to flesh out the APIs a little more with what parameters they take and what return types are.
• Would be good to map how the uP-L2 APIs map down into uP-L1 APIs
  • i.e. we had some lengthy discussions about how for different message types we would register on various things

[stevenhartley]

completed