Change the type name of uProtocol messages

The names defined for the different uProtocol message types have been
changed to allow distinguishing between existing CloudEvents being
exchanged by legacy systems using a predecessor of Eclipse uProtocol
and CloudEvents conforming to the mapping rules defined in the
uProtocol specification.

up-core-api/uprotocol/v1/uattributes.proto

@@ -70,27 +70,32 @@ message UAttributes {
 // uProtocol defines different types of messages.
 // Using the message type, validation can be performed to ensure transport
 // validity of the data in the {@link UAttributes}.
+//
+// The "up-" prefix used in the uprotocol.ce_name options has been introduced
+// to allow distinguishing between existing CloudEvents being exchanged by
+// legacy systems using a predecessor of Eclipse uProtocol and CloudEvents
+// conforming to the mapping rules defined in the Eclipse uProtocol specification.
 enum UMessageType {
     // Unspecified message type
     UMESSAGE_TYPE_UNSPECIFIED = 0;
 
     // Publish
     // A message that is used to notify all interested consumers of an event that has occurred.
-    UMESSAGE_TYPE_PUBLISH = 1 [(uprotocol.ce_name) = "pub.v1"];
+    UMESSAGE_TYPE_PUBLISH = 1 [(uprotocol.ce_name) = "up-pub.v1"];
 
     // RPC Request
     // A message that is used by a service consumer to invoke one of a service provider's methods with some input data, expecting the service
     // provider to reply with a response message.
-    UMESSAGE_TYPE_REQUEST = 2 [(uprotocol.ce_name) = "req.v1"];
+    UMESSAGE_TYPE_REQUEST = 2 [(uprotocol.ce_name) = "up-req.v1"];
 
     // RPC Response
     // A message that is used by a service provider to send the outcome of processing a request message
     // from a servcice consumer.
-    UMESSAGE_TYPE_RESPONSE = 3 [(uprotocol.ce_name) = "res.v1"];
+    UMESSAGE_TYPE_RESPONSE = 3 [(uprotocol.ce_name) = "up-res.v1"];
 
     // Notification
     // A message that is used to inform a specific consumer about an event that has occurred.
-    UMESSAGE_TYPE_NOTIFICATION = 4 [(uprotocol.ce_name) = "not.v1"];
+    UMESSAGE_TYPE_NOTIFICATION = 4 [(uprotocol.ce_name) = "up-not.v1"];
 }
 
 

up-l1/cloudevents.adoc

@@ -285,7 +285,7 @@ The following examples are using the CloudEvent JSON Format.
     "specversion": "1.0",
     "id": "cf8b1bcd-30bd-43be-a8d3-ad1cde652e10",
     "source": "//VCU.VIN/body.access/1/door.front_left#Door",
-    "type": "pub.v1",
+    "type": "up-pub.v1",
     "priority": "CS1",
     "ttl": 10000,
     "pformat": 7,
@@ -301,7 +301,7 @@ The following examples are using the CloudEvent JSON Format.
     "id": "cf8b1bcd-30bd-43be-a8d3-ad1cde652e10",
     "source": "//VCU.VIN/body.access/1/door.front_left#Door",
     "sink": "//VCU.VIN/companion.app/1/status.update",
-    "type": "not.v1",
+    "type": "up-not.v1",
     "pformat": 3,
     "data": {
         "subject": "door.front_left",
@@ -318,7 +318,7 @@ The following examples are using the CloudEvent JSON Format.
     "id": "cf8b1bcd-30bd-43be-a8d3-ad1cde652e10",
     "source": "//VCU.VIN/MyApp/1/rpc.response",
     "sink": "//VCU.VIN/body.access/1/rpc.UpdateDoor",
-    "type": "req.v1",
+    "type": "up-req.v1",
     "priority": "CS4",
     "ttl": 50000,
     "pformat": 1,
@@ -335,7 +335,7 @@ The following examples are using the CloudEvent JSON Format.
     "id": "5b9fe861-8c1c-4899-9b07-ad1cde652e10",
     "source": "//VCU.VIN/body.access/1/rpc.UpdateDoor",
     "sink": "//VCU.VIN/MyApp/1/rpc.response",
-    "type": "res.v1",
+    "type": "up-res.v1",
     "priority": "CS4",
     "reqid": "cf8b1bcd-30bd-43be-a8d3-ad1cde652e10",
     "ttl": 50000,

up-l2/dispatchers/README.adoc

@@ -83,28 +83,28 @@ When a dispatcher is unable to dispatch an event for a given reason (queue full,
 |*google.rpc.Code* |*Reason*
 
 |`*UNAVAILABLE*`
-|The req.v1 has expired due to the downstream uE was unavailable (ex. uDevice was disconnected). uE that issued the req.v1 MAY retry with back-off
+|The service is not available (at the moment), e.g. because the device that the service is deployed to is being restarted. The client MAY retry the request but SHOULD use an exponential back-off for doing so.
 
 |`*DEADLINE_EXCEEDED*`
-|CE has timed out per the ttl attribute specifications defined in req.v1 event
+|The time-to-live set in the client's request has expired.
 
 |`*PERMISSION_DENIED*`
-|source is not permitted to access sink
+|The client is not authorized to invoke the service operation.
 
 |`*UNAUTHENTICATED*`
-|source does not have valid authentication credentials (ex. uE's identity does not match the source attribute)
+|The credentials provided by the client could not be verified, e.g. because the client's identity does not match the source attribute.
 
 |`*RESOURCE_EXHAUSTED*`
-|The dispatcher ran out of resources (buffer full)
+|The dispatcher ran out of resources, e.g. because a message queue's maximum capacity has been reached.
 
 |`*INVALID_ARGUMENT*`
-|Invalid CE header attributes not covered above (ex. any mal-formatted attributes)
+|The service can not process the request message, e.g. because an attribute or the payload does not have the expected format.
 
 |`*UNKNOWN*`
-|An unknown (but not critical) error has occurred
+|An unknown (but not critical) error has occurred.
 
 |`*INTERNAL*`
-|There is a serious error has occurred not described by error codes mentioned above
+|A serious error has occurred that is not covered by any of the error codes mentioned above.
 !===
 
 <<rpc-error-flow>> figure below illustrates the sequence of messages for RPC flows and the role dispatchers play in error handling.

up-l3/README.adoc

@@ -33,10 +33,10 @@ uProtocol supports the architecture patterns defined in the table below to imple
 
 |*RPC* |At-least-once |When uE requires acknowledgement from the receiver  a|
 * If the client-side business logic requires retry policy, it *MUST* implement the retry policy
-* Server-side business logic *MUST* implement Idempotency for remote procedural calls
-* Dispatchers that are unable to deliver req.v1, *MUST* generate a _delivery failure res.v1_ and send it back to the Sender uE
+* Server-side business logic *MUST* implement Idempotency for service operations.
+* Dispatchers that are unable to deliver an RPC request message, *MUST* generate a _delivery failure_ and return it back to the client uE
 
-|*Publication* |At-most-once |When uE wishes to publish an CE to multiple consumers (a.k.a. "fire & forget") a|
+|*Publication* |At-most-once |When uE wishes to publish an CE to multiple consumers (a.k.a. _fire & forget_) a|
 * Dispatcher *MUST* provide access to CEs that have failed to be delivered (DLT defined in a later section), for both the Sender and/or Receiver uE business logic
 
 |*Notification* |At-most-once |When a uE wishes to notify a specific uE (a.k.a a publication with a destination) |