From 70802900a752984645968ee10d248616652b2960 Mon Sep 17 00:00:00 2001 From: Alexander Ivanov Date: Thu, 7 Nov 2024 01:32:10 +0800 Subject: [PATCH 1/4] WIP: CBOR Serialization --- proposals/0000-cbor-serialization.md | 40 ++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 proposals/0000-cbor-serialization.md diff --git a/proposals/0000-cbor-serialization.md b/proposals/0000-cbor-serialization.md new file mode 100644 index 00000000000..d1d043017f0 --- /dev/null +++ b/proposals/0000-cbor-serialization.md @@ -0,0 +1,40 @@ +# MSC0000: Initial support for CBOR serialization + +This proposal introduces support for CBOR (Concise Binary Object Representation) as an optional serialization format for the Client-Server API. CBOR, a binary format standardized by [RFC 8949](https://datatracker.ietf.org/doc/html/rfc8949), is designed for efficient data encoding and processing, offering a more compact alternative to JSON. By providing optional CBOR support, this proposal aims to improve the performance for devices with constrained resources and enhance overall efficiency. + +This proposal is inspired by [MSC3079](https://github.com/matrix-org/matrix-spec-proposals/pull/3079), which at the time of writing is too complex to implement and have not yet been accepted into the spec, this proposal focuses on CBOR serialization part of it. + +## Proposal + +This MSC proposes supporting CBOR encoding as an optional format for Matrix API requests and responses. CBOR encoding should be an additional format that implementations can negotiate to use, with JSON remaining as the default. To ensure backward compatibility, clients and servers must be able to indicate whether they support CBOR and negotiate which encoding to use. + +### Content Negotiation + +Clients MUST set the `Content-Type` header to `application/cbor` when sending CBOR objects. Similarly, servers MUST set the `Content-Type` header to `application/cbor` when responding with CBOR to requests. Servers MUST NOT respond to requests with `Content-Type: application/json` with CBOR, unless the `Accept` header in the client's request includes `application/cbor`. + +### Encoding + +CBOR objects are encoded and represented identically from JSON, with exception of binary data, such as public keys or signatures. Given that unlike JSON, CBOR can safely represent raw binary data, all binary data MUST be encoded and represented as binary strings with tag 22, as described in RFC 8949 [Section 3.4.5.2](https://www.rfc-editor.org/rfc/rfc8949.html#section-3.4.5.2). Tagging is required for compatibility with generic CBOR-to-JSON converters. + +Example object would be encoded like this: +``` +D6 # tag(22) + 50 # bytes(16) + 03082C12C0053C1EC80BD712ACED1E0A # "AwgsEsAFPB7IC9cSrO0eCg" in base64 +``` + +## Potential issues + +At the time of writing, this proposal doesn't provide a integer mapping for string keys and static string values, which leaves out encoding efficiency. Identifiers also can be encoded more efficiently by using the assumptions provided by specification, such as that they utilize way less than 128 characters. + +## Alternatives + +[MessagePack](https://github.com/msgpack/msgpack/blob/master/spec.md) was considered first, but in discussion CBOR was favored due to standardised specification while having on-par performance. + +## Security considerations + +This proposal does not provide any new endpoints. Security of CBOR, just like with JSON, depends on implementation. + +## Unstable prefix + +Clients should check for server support before using the features proposed by this MSC. Before this MSC gets merged, to detect server support, clients MUST check for the presence of the `org.matrix.msc0000` flag in `unstable_features` on `/versions`. From 9fa8279ce3ff3fa857eda6c06ae086c2ad1edf44 Mon Sep 17 00:00:00 2001 From: Alexander Ivanov Date: Thu, 7 Nov 2024 01:33:43 +0800 Subject: [PATCH 2/4] MSC4224: CBOR Serialization --- proposals/0000-cbor-serialization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/0000-cbor-serialization.md b/proposals/0000-cbor-serialization.md index d1d043017f0..2178c4751eb 100644 --- a/proposals/0000-cbor-serialization.md +++ b/proposals/0000-cbor-serialization.md @@ -1,4 +1,4 @@ -# MSC0000: Initial support for CBOR serialization +# MSC4224: Initial support for CBOR serialization This proposal introduces support for CBOR (Concise Binary Object Representation) as an optional serialization format for the Client-Server API. CBOR, a binary format standardized by [RFC 8949](https://datatracker.ietf.org/doc/html/rfc8949), is designed for efficient data encoding and processing, offering a more compact alternative to JSON. By providing optional CBOR support, this proposal aims to improve the performance for devices with constrained resources and enhance overall efficiency. @@ -37,4 +37,4 @@ This proposal does not provide any new endpoints. Security of CBOR, just like wi ## Unstable prefix -Clients should check for server support before using the features proposed by this MSC. Before this MSC gets merged, to detect server support, clients MUST check for the presence of the `org.matrix.msc0000` flag in `unstable_features` on `/versions`. +Clients should check for server support before using the features proposed by this MSC. Before this MSC gets merged, to detect server support, clients MUST check for the presence of the `org.matrix.msc4224` flag in `unstable_features` on `/versions`. From f7ce86e12b2aeb83a5ce89cdda182f369d13d3a0 Mon Sep 17 00:00:00 2001 From: Alexander Ivanov Date: Thu, 7 Nov 2024 01:34:53 +0800 Subject: [PATCH 3/4] Rename to 4224-cbor-serialization.md --- .../{0000-cbor-serialization.md => 4224-cbor-serialization.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename proposals/{0000-cbor-serialization.md => 4224-cbor-serialization.md} (100%) diff --git a/proposals/0000-cbor-serialization.md b/proposals/4224-cbor-serialization.md similarity index 100% rename from proposals/0000-cbor-serialization.md rename to proposals/4224-cbor-serialization.md From 55b712bd670807dff210494d87e0dd707ceace14 Mon Sep 17 00:00:00 2001 From: Alexander Ivanov Date: Fri, 8 Nov 2024 17:25:46 +0800 Subject: [PATCH 4/4] MSC4224: Lines wrapped --- proposals/4224-cbor-serialization.md | 52 ++++++++++++++++++++++------ 1 file changed, 42 insertions(+), 10 deletions(-) diff --git a/proposals/4224-cbor-serialization.md b/proposals/4224-cbor-serialization.md index 2178c4751eb..6bb48658e69 100644 --- a/proposals/4224-cbor-serialization.md +++ b/proposals/4224-cbor-serialization.md @@ -1,20 +1,42 @@ # MSC4224: Initial support for CBOR serialization -This proposal introduces support for CBOR (Concise Binary Object Representation) as an optional serialization format for the Client-Server API. CBOR, a binary format standardized by [RFC 8949](https://datatracker.ietf.org/doc/html/rfc8949), is designed for efficient data encoding and processing, offering a more compact alternative to JSON. By providing optional CBOR support, this proposal aims to improve the performance for devices with constrained resources and enhance overall efficiency. - -This proposal is inspired by [MSC3079](https://github.com/matrix-org/matrix-spec-proposals/pull/3079), which at the time of writing is too complex to implement and have not yet been accepted into the spec, this proposal focuses on CBOR serialization part of it. +This proposal introduces support for CBOR (Concise Binary Object Representation) +as an optional serialization format for the Client-Server API. CBOR, a binary +format standardized by [RFC +8949](https://datatracker.ietf.org/doc/html/rfc8949), is designed for efficient +data encoding and processing, offering a more compact alternative to JSON. By +providing optional CBOR support, this proposal aims to improve the performance +for devices with constrained resources and enhance overall efficiency. + +This proposal is inspired by +[MSC3079](https://github.com/matrix-org/matrix-spec-proposals/pull/3079), which +at the time of writing is too complex to implement and have not yet been +accepted into the spec, this proposal focuses on CBOR serialization part of it. ## Proposal -This MSC proposes supporting CBOR encoding as an optional format for Matrix API requests and responses. CBOR encoding should be an additional format that implementations can negotiate to use, with JSON remaining as the default. To ensure backward compatibility, clients and servers must be able to indicate whether they support CBOR and negotiate which encoding to use. +This MSC proposes supporting CBOR encoding as an optional format for Matrix API +requests and responses. CBOR encoding should be an additional format that +implementations can negotiate to use, with JSON remaining as the default. To +ensure backward compatibility, clients and servers must be able to indicate +whether they support CBOR and negotiate which encoding to use. ### Content Negotiation -Clients MUST set the `Content-Type` header to `application/cbor` when sending CBOR objects. Similarly, servers MUST set the `Content-Type` header to `application/cbor` when responding with CBOR to requests. Servers MUST NOT respond to requests with `Content-Type: application/json` with CBOR, unless the `Accept` header in the client's request includes `application/cbor`. +Clients MUST set the `Content-Type` header to `application/cbor` when sending +CBOR objects. Similarly, servers MUST set the `Content-Type` header to +`application/cbor` when responding with CBOR to requests. Servers MUST NOT +respond to requests with `Content-Type: application/json` with CBOR, unless the +`Accept` header in the client's request includes `application/cbor`. ### Encoding -CBOR objects are encoded and represented identically from JSON, with exception of binary data, such as public keys or signatures. Given that unlike JSON, CBOR can safely represent raw binary data, all binary data MUST be encoded and represented as binary strings with tag 22, as described in RFC 8949 [Section 3.4.5.2](https://www.rfc-editor.org/rfc/rfc8949.html#section-3.4.5.2). Tagging is required for compatibility with generic CBOR-to-JSON converters. +CBOR objects are encoded and represented identically from JSON, with exception +of binary data, such as public keys or signatures. Given that unlike JSON, CBOR +can safely represent raw binary data, all binary data MUST be encoded and +represented as binary strings with tag 22, as described in RFC 8949 [Section +3.4.5.2](https://www.rfc-editor.org/rfc/rfc8949.html#section-3.4.5.2). Tagging +is required for compatibility with generic CBOR-to-JSON converters. Example object would be encoded like this: ``` @@ -25,16 +47,26 @@ D6 # tag(22) ## Potential issues -At the time of writing, this proposal doesn't provide a integer mapping for string keys and static string values, which leaves out encoding efficiency. Identifiers also can be encoded more efficiently by using the assumptions provided by specification, such as that they utilize way less than 128 characters. +At the time of writing, this proposal doesn't provide a integer mapping for +string keys and static string values, which leaves out encoding efficiency. +Identifiers also can be encoded more efficiently by using the assumptions +provided by specification, such as that they utilize way less than 128 +characters. ## Alternatives -[MessagePack](https://github.com/msgpack/msgpack/blob/master/spec.md) was considered first, but in discussion CBOR was favored due to standardised specification while having on-par performance. +[MessagePack](https://github.com/msgpack/msgpack/blob/master/spec.md) was +considered first, but in discussion CBOR was favored due to standardised +specification while having on-par performance. ## Security considerations -This proposal does not provide any new endpoints. Security of CBOR, just like with JSON, depends on implementation. +This proposal does not provide any new endpoints. Security of CBOR, just like +with JSON, depends on implementation. ## Unstable prefix -Clients should check for server support before using the features proposed by this MSC. Before this MSC gets merged, to detect server support, clients MUST check for the presence of the `org.matrix.msc4224` flag in `unstable_features` on `/versions`. +Clients should check for server support before using the features proposed by +this MSC. Before this MSC gets merged, to detect server support, clients MUST +check for the presence of the `org.matrix.msc4224` flag in `unstable_features` +on `/versions`.