From 3cc00bc58caeb0b03777cdccea450dc7fc58182b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sat, 12 Nov 2022 18:24:07 +0000 Subject: [PATCH] Support content blocks system --- proposals/3551-extensible-events-files.md | 147 ++++++---------------- 1 file changed, 41 insertions(+), 106 deletions(-) diff --git a/proposals/3551-extensible-events-files.md b/proposals/3551-extensible-events-files.md index bdab9486..cfab848e 100644 --- a/proposals/3551-extensible-events-files.md +++ b/proposals/3551-extensible-events-files.md @@ -1,16 +1,16 @@ # MSC3551: Extensible Events - Files [MSC1767](https://github.com/matrix-org/matrix-doc/pull/1767) describes Extensible Events in detail, -though deliberately does not include schemas for non-text messaging types. This MSC covers just file -uploads, which is further used as a base for images, videos, etc. +though deliberately does not include schemas for some messaging types. This MSC covers only regular +file uploads. *Rationale*: Splitting the MSCs down into individual parts makes it easier to implement and review in -stages without blocking other pieces of the overall idea. For example, an issue with the way images +stages without blocking other pieces of the overall idea. For example, an issue with the way files are represented should not block the overall schema from going through. ## Proposal -Using [MSC1767](https://github.com/matrix-org/matrix-doc/pull/1767)'s system, a new `m.file` primary +Using [MSC1767](https://github.com/matrix-org/matrix-doc/pull/1767)'s system, a new `m.file` event type is introduced to describe generic file uploads (PDFs, documents, etc). An example is: @@ -19,33 +19,14 @@ An example is: { "type": "m.file", "content": { - "m.text": "Upload: foo.pdf (12 KB)", // or other m.message-like event + "m.markup": [ + // Format of the fallback is not defined, but should have enough information for a text-only + // client to do something with the file. + {"body": "matrix.pdf (12 KB) https://example.org/_matrix/media/v3/download/example.org/abcd1234"} + ], "m.file": { "url": "mxc://example.org/abcd1234", - "name": "foo.pdf", - "mimetype": "application/pdf", - "size": 12345 - } - } -} -``` - -This incorporates the intended schema for the [`m.file`](https://spec.matrix.org/v1.1/client-server-api/#mfile) -`msgtype` (minus the spurious thumbnail schema). - -Note that a file event requires a text fallback of `m.text`, `m.html`, or other `m.message`-compatible -event. - -An encrypted file would appear as such: - -```json5 -{ - "type": "m.file", - "content": { - "m.text": "Upload: foo.pdf (12 KB)", // or other m.message-like event - "m.file": { - "url": "mxc://example.org/abcd1234", - "name": "foo.pdf", + "name": "matrix.pdf", "mimetype": "application/pdf", "size": 12345, @@ -62,100 +43,54 @@ An encrypted file would appear as such: "sha256": "fdSLu/YkRx3Wyh3KQabP3rd6+SFiKg5lsJZQHtkSAYA" }, "v": "v2" - } + }, } } ``` -The presence of a `key` JWT denotes the file is encrypted. +The reusable `m.file` content block describes the actual file, with the following properties: -## Potential issues +* `uri` - Required MXC URI for the file itself. +* `name` - Required name of the file, with extension (if applicable). +* `mimetype` - Optional (but recommended) mimetype for the file that was uploaded. +* `size` - Optional (but recommended) size in bytes for the file that was uploaded. -The schema duplicates some of the information into the text fallback, though this is unavoidable. +If the file is encrypted, the following fields additionally apply. All fields are to support the +`EncryptedFile` object described by the [encryption module](https://spec.matrix.org/v1.1/client-server-api/#sending-encrypted-attachments). -## Alternatives +* `key` - Required JSON Web Key. The presence of this field indicates the file is encrypted. +* `iv` - Required serialized initialization vector. +* `hashes` - Required hashes object. +* `v` - Required version string. -No significant alternatives known. +This structure covers the existing [`m.file`](https://spec.matrix.org/v1.1/client-server-api/#mfile) +`msgtype` (minus the spurious thumbnail schema). -## Security considerations +Together with content blocks from other proposals, an `m.file` is described as: -The same considerations which currently apply to files and extensible events also apply here. +* **Required** - An `m.markup` block to act as a fallback for clients which can't process files. +* **Required** - An `m.file` to describe the actual file. -## Transition +The above describes the minimum requirements for sending an `m.file` event. Senders can add additional +blocks, however as per the extensible events system, receivers should not honour them. -The same transition introduced by extensible events is also applied here: +## Potential issues -```json5 -{ - "type": "m.room.message", - "content": { - "msgtype": "m.file", - "body": "foo.pdf", - "info": { - "size": 774, - "mimetype": "application/pdf" - }, - "file": { - "url": "mxc://example.org/f91dce7b060ed4c8f094cd3ecb498aa621bbe242", - "key": { - "kty": "oct", - "key_ops": ["encrypt", "decrypt"], - "alg": "A256CTR", - "k": "TLlG_OpX807zzQuuwv4QZGJ21_u7weemFGYJFszMn9A", - "ext": true - }, - "iv": "S22dq3NAX8wAAAAAAAAAAA", - "hashes": { - "sha256": "aWOHudBnDkJ9IwaR1Nd8XKoI7DOrqDTwt6xDPfVGN6Q" - }, - "v": "v2" - }, +The schema duplicates some of the information into the text fallback, though this is unavoidable +and intentional for fallback considerations. - // Extensible Events - "m.text": "foo.pdf", - "m.file": { - "url": "mxc://example.org/f91dce7b060ed4c8f094cd3ecb498aa621bbe242", - "name": "foo.pdf", - "mimetype": "application/pdf", - "size": 774, - "key": { - "kty": "oct", - "key_ops": ["encrypt", "decrypt"], - "alg": "A256CTR", - "k": "TLlG_OpX807zzQuuwv4QZGJ21_u7weemFGYJFszMn9A", - "ext": true - }, - "iv": "S22dq3NAX8wAAAAAAAAAAA", - "hashes": { - "sha256": "aWOHudBnDkJ9IwaR1Nd8XKoI7DOrqDTwt6xDPfVGN6Q" - }, - "v": "v2" - } - } -} -``` +## Alternatives + +No significant alternatives known. + +## Security considerations -The event details are copied and quite verbose, however this is best to ensure compatibility with the -extensible events format. +The same considerations which currently apply to files and extensible events also apply here. ## Unstable prefix -While this MSC is not considered stable, implementations should use `org.matrix.msc1767.file` in place -of `m.file` throughout this proposal. Note that this uses the namespace of the parent MSC rather than +While this MSC is not considered stable, implementations should use `org.matrix.msc1767.*` as a prefix in +place of `m.*` throughout this proposal. Note that this uses the namespace of the parent MSC rather than the namespace of this MSC - this is deliberate. -Example: -```json5 -{ - "type": "org.matrix.msc1767.file", - "content": { - "org.matrix.msc1767.text": "Upload: foo.pdf (12 KB)", // or other org.matrix.msc1767.message-like event - "org.matrix.msc1767.file": { - "url": "mxc://example.org/abcd1234", - "name": "foo.pdf", - "mimetype": "application/pdf", - "size": 12345 - } - } -} -``` +Note that extensible events should only be used in an appropriate room version as well.