From 18fadea3a07fe2584b8746810de32c08113fb6fd Mon Sep 17 00:00:00 2001 From: Steven Hartley Date: Thu, 16 May 2024 12:52:15 -0400 Subject: [PATCH] Remove uPayload (#145) * Remove uPayload The following change removes the unused UPayload protobuf object and places the format in UAttributes. #144 * Missed the data_content_type from UAttributes!! * Update basics/uattributes.adoc Co-authored-by: Pete LeVasseur * switch back to UPayloadFormat to avoid unnecessary changes and since we refer to payload everywhere in the specs * Incorporated feedback from reviewers * Add back link in README.adoc to upayloadformat.adoc * add missing cloudevent mapping --------- Co-authored-by: Pete LeVasseur --- basics/README.adoc | 2 +- basics/uattributes.adoc | 5 ++ basics/umessage.adoc | 2 +- basics/{upayload.adoc => upayloadformat.adoc} | 13 ++-- up-core-api/uprotocol/uattributes.proto | 34 ++++++++++ up-core-api/uprotocol/umessage.proto | 9 ++- up-core-api/uprotocol/upayload.proto | 63 ------------------- up-l1/cloudevents.adoc | 5 ++ 8 files changed, 55 insertions(+), 78 deletions(-) rename basics/{upayload.adoc => upayloadformat.adoc} (86%) delete mode 100644 up-core-api/uprotocol/upayload.proto diff --git a/basics/README.adoc b/basics/README.adoc index af85742..ae9570b 100644 --- a/basics/README.adoc +++ b/basics/README.adoc @@ -28,7 +28,7 @@ The following are the foundational requirements for uProtocol specifications: * *link:qos.adoc[Quality of Service & Priority (UPriority)]* * *link:uattributes.adoc[uProtocol Attributes (UAttributes)]* * *link:umessage.adoc[uProtocol Message (UMessage)]* -* *link:upayload.adoc[uProtocol Payload (UPayload)]* +* *link:upayloadformat.adoc[uProtocol Payload Format (UPayloadFormat)]* * *link:delivery.adoc[Event Delivery]* * *link:permissions.adoc[Permissions]* diff --git a/basics/uattributes.adoc b/basics/uattributes.adoc index cb32f2b..864a585 100644 --- a/basics/uattributes.adoc +++ b/basics/uattributes.adoc @@ -78,6 +78,11 @@ stem:[t_{current} > t_{id} + ttl] |no |A tracing identifier to use for correlating messages across the system. Intended to be compatible with https://github.com/cloudevents/spec/blob/main/cloudevents/extensions/distributed-tracing.md[CloudEvents distributed tracing extension]. +|`payload format` +|link:upayloadformat.adoc[UPayloadFormat] +|no +|The format of the payload (data). + |=== [#publish-attributes] diff --git a/basics/umessage.adoc b/basics/umessage.adoc index cd35b91..27219da 100644 --- a/basics/umessage.adoc +++ b/basics/umessage.adoc @@ -20,6 +20,6 @@ SPDX-License-Identifier: Apache-2.0 == Overview -UMessage is the top-level message type for the uProtocol. It consists of link:uattributes.adoc[message metadata] and (optional) link:upayload.adoc[payload]. UMessage is the common way to represent messages sent between uEntities over any communication protocol/middleware. +UMessage is the top-level message type for the uProtocol. It consists of link:uattributes.adoc[message metadata] and (optional) data (payload). NOTE: Please refer to link:../up-core-api/uprotocol/umessage.proto[umessage.proto] for more details. diff --git a/basics/upayload.adoc b/basics/upayloadformat.adoc similarity index 86% rename from basics/upayload.adoc rename to basics/upayloadformat.adoc index 1af5d23..6a5e02a 100644 --- a/basics/upayload.adoc +++ b/basics/upayloadformat.adoc @@ -1,4 +1,4 @@ -= uProtocol Payload (uPayload) += uProtocol Payload Format :toc: :sectnums: @@ -18,13 +18,7 @@ SPDX-FileType: DOCUMENTATION SPDX-License-Identifier: Apache-2.0 ---- -== Overview - -UPayload is a wrapper around a message's payload data, either by value or reference, as well as some metadata describing the payload like format, size, etc. - -NOTE: Please refer to link:../up-core-api/uprotocol/upayload.proto[upayload.proto] for more details - -== Payload Format +== Overview The following table provides an overview of the payload formats supported by uProtocol. @@ -60,4 +54,7 @@ The following table provides an overview of the payload formats supported by uPr |`text/plain` |The message payload *MUST* be the network byte order UTF-8 encoding of a unicode string representing the payload data. +|`UPAYLOAD_FORMAT_SHM` +|`application/x-shm` +|The message payload *MUST* be the network byte order address of a shared memory segment. |=== diff --git a/up-core-api/uprotocol/uattributes.proto b/up-core-api/uprotocol/uattributes.proto index 6bf0000..b6ed431 100644 --- a/up-core-api/uprotocol/uattributes.proto +++ b/up-core-api/uprotocol/uattributes.proto @@ -61,6 +61,9 @@ message UAttributes { // A tracing identifier to use for correlating messages across the system. // Intended to be compatible with https://github.com/cloudevents/spec/blob/main/cloudevents/extensions/distributed-tracing.md optional string traceparent = 11; + + // The format for the data stored in the UMessage. + UPayloadFormat payload_format = 12; } @@ -118,3 +121,34 @@ enum UPriority { // Network control such as Safety Critical UPRIORITY_CS6 = 7 [(uprotocol.ce_name) = "CS6"]; } + +// The format for the data stored in the UMessage. +enum UPayloadFormat { + // Payload format was not is not set, + // per specification, assumption is UPAYLOAD_FORMAT_PROTOBUF_WRAPPED_IN_ANY + UPAYLOAD_FORMAT_UNSPECIFIED = 0; + + // Payload is an Any protobuf message that contains the packed payload + UPAYLOAD_FORMAT_PROTOBUF_WRAPPED_IN_ANY = 1 [ (uprotocol.mime_type) = "application/x-protobuf" ]; + + // Protobuf serialization format + UPAYLOAD_FORMAT_PROTOBUF = 2 [ (uprotocol.mime_type) = "application/protobuf" ]; + + // JSON serialization format + UPAYLOAD_FORMAT_JSON = 3 [ (uprotocol.mime_type) = "application/json" ]; + + // Basic SOME/IP serialization format + UPAYLOAD_FORMAT_SOMEIP = 4 [ (uprotocol.mime_type) = "application/x-someip" ]; + + // SOME/IP TLV format + UPAYLOAD_FORMAT_SOMEIP_TLV = 5 [ (uprotocol.mime_type) = "application/x-someip_tlv" ]; + + // RAW (binary) format + UPAYLOAD_FORMAT_RAW = 6 [ (uprotocol.mime_type) = "application/octet-stream" ]; + + // Text format + UPAYLOAD_FORMAT_TEXT = 7 [ (uprotocol.mime_type) = "text/plain" ]; + + // Shared memory format + UPAYLOAD_FORMAT_SHM = 8 [ (uprotocol.mime_type) = "application/x-shm" ]; +} diff --git a/up-core-api/uprotocol/umessage.proto b/up-core-api/uprotocol/umessage.proto index ab6adbe..151bd9a 100644 --- a/up-core-api/uprotocol/umessage.proto +++ b/up-core-api/uprotocol/umessage.proto @@ -16,19 +16,18 @@ syntax = "proto3"; package uprotocol.v1; import "uattributes.proto"; -import "upayload.proto"; option java_package = "org.eclipse.uprotocol.v1"; option java_outer_classname = "UMessageProto"; option java_multiple_files = true; // UMessage is the top-level message type for the uProtocol. -// It contains a header (UAttributes), and payload (UPayload) and is a way of representing a +// It contains a header (UAttributes), and payload and is a way of representing a // message that would be sent between two uEs. message UMessage { // uProtocol mandatory and optional attributes UAttributes attributes = 1; - // Optional message payload containing the data to be sent - UPayload payload = 2; -} \ No newline at end of file + // Optional message payload + optional bytes payload = 2; +} diff --git a/up-core-api/uprotocol/upayload.proto b/up-core-api/uprotocol/upayload.proto deleted file mode 100644 index 55f4252..0000000 --- a/up-core-api/uprotocol/upayload.proto +++ /dev/null @@ -1,63 +0,0 @@ -/* - * SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation - * - * See the NOTICE file(s) distributed with this work for additional - * information regarding copyright ownership. - * - * This program and the accompanying materials are made available under - * the terms of the Apache License Version 2.0 which is available at - * https://www.apache.org/licenses/LICENSE-2.0 - * - * SPDX-FileType: SOURCE - * SPDX-License-Identifier: Apache-2.0 - */ -syntax = "proto3"; - -package uprotocol.v1; - -import "uprotocol_options.proto"; - -option java_package = "org.eclipse.uprotocol.v1"; -option java_outer_classname = "UPayloadProto"; -option java_multiple_files = true; - - -// UPayload Message
-// UPayload is the data model for storing the data and metadata for what is being sent -// between uEs. -message UPayload { - // Data that is passed by value (copy inside of data) - bytes data = 1; - - // Serialization format of the data - UPayloadFormat format = 2; - -} - -// The Serialization format for the data stored in uPayload. -enum UPayloadFormat { - // Payload format was not is not set, - // per specification, assumption is UPAYLOAD_FORMAT_PROTOBUF_WRAPPED_IN_ANY - UPAYLOAD_FORMAT_UNSPECIFIED = 0; - - // Payload is an Any protobuf message that contains the packed payload - UPAYLOAD_FORMAT_PROTOBUF_WRAPPED_IN_ANY = 1 [ (uprotocol.mime_type) = "application/x-protobuf" ]; - - // Protobuf serialization format - UPAYLOAD_FORMAT_PROTOBUF = 2 [ (uprotocol.mime_type) = "application/protobuf" ]; - - // JSON serialization format - UPAYLOAD_FORMAT_JSON = 3 [ (uprotocol.mime_type) = "application/json" ]; - - // Basic SOME/IP serialization format - UPAYLOAD_FORMAT_SOMEIP = 4 [ (uprotocol.mime_type) = "application/x-someip" ]; - - // SOME/IP TLV format - UPAYLOAD_FORMAT_SOMEIP_TLV = 5 [ (uprotocol.mime_type) = "application/x-someip_tlv" ]; - - // RAW (binary) format - UPAYLOAD_FORMAT_RAW = 6 [ (uprotocol.mime_type) = "application/octet-stream" ]; - - // Text format - UPAYLOAD_FORMAT_TEXT = 7 [ (uprotocol.mime_type) = "text/plain" ]; -} \ No newline at end of file diff --git a/up-l1/cloudevents.adoc b/up-l1/cloudevents.adoc index dea5f6a..54eecd0 100644 --- a/up-l1/cloudevents.adoc +++ b/up-l1/cloudevents.adoc @@ -155,6 +155,11 @@ a|A code indicating an error that has occurred during the delivery of either an |String |A tracing identifier to use for correlating messages across the system. +|`payload_format` +|`pformat` +|Integer +|The value of the UPayloadFormat that is used to indicate the encoding of the payload + |=== [#ce-formats]