MSC4224: CBOR Serialization

proposals/4224-cbor-serialization.md

@@ -0,0 +1,72 @@
+# 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.
+
+## 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.msc4224` flag in `unstable_features`
+on `/versions`.