archive
/
matrix-spec-proposals
mirror of https://github.com/matrix-org/matrix-spec-proposals
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Support content blocks system

Browse Source
travis/msc/extev/files
Travis Ralston 2 years ago
parent 5bf2118e8a
commit 3cc00bc58c
1 changed files with 41 additions and 106 deletions
Show Stats Download Patch File Download Diff File

147
proposals/3551-extensible-events-files.md
Unescape Escape View File

@ -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.

Write Preview
Loading…
Cancel
Save