From 2366c1f70698288db5afe2536cdb6a35235d8a7f Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 21 Nov 2024 12:49:34 +0000 Subject: [PATCH 1/8] Placeholder for animated image flag msc --- proposals/xxxx-animated-image-flag.md | 117 ++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 proposals/xxxx-animated-image-flag.md diff --git a/proposals/xxxx-animated-image-flag.md b/proposals/xxxx-animated-image-flag.md new file mode 100644 index 00000000000..41f76d2159b --- /dev/null +++ b/proposals/xxxx-animated-image-flag.md @@ -0,0 +1,117 @@ +# MSC0000: Template for new MSCs + +*Note: Text written in italics represents notes about the section or proposal process. This document +serves as an example of what a proposal could look like (in this case, a proposal to have a template) +and should be used where possible.* + +*In this first section, be sure to cover your problem and a broad overview of the solution. Covering +related details, such as the expected impact, can also be a good idea. The example in this document +says that we're missing a template and that things are confusing and goes on to say the solution is +a template. There's no major expected impact in this proposal, so it doesn't list one. If your proposal +was more invasive (such as proposing a change to how servers discover each other) then that would be +a good thing to list here.* + +*If you're having troubles coming up with a description, a good question to ask is "how +does this proposal improve Matrix?" - the answer could reveal a small impact, and that is okay.* + +There can never be enough templates in the world, and MSCs shouldn't be any different. The level +of detail expected of proposals can be unclear - this is what this example proposal (which doubles +as a template itself) aims to resolve. + + +## Proposal + +*Here is where you'll reinforce your position from the introduction in more detail, as well as cover +the technical points of your proposal. Including rationale for your proposed solution and detailing +why parts are important helps reviewers understand the problem at hand. Not including enough detail +can result in people guessing, leading to confusing arguments in the comments section. The example +here covers why templates are important again, giving a stronger argument as to why we should have +a template. Afterwards, it goes on to cover the specifics of what the template could look like.* + +Having a default template that everyone can use is important. Without a template, proposals would be +all over the place and the minimum amount of detail may be left out. Introducing a template to the +proposal process helps ensure that some amount of consistency is present across multiple proposals, +even if each author decides to abandon the template. + +The default template should be a markdown document because the MSC process requires authors to write +a proposal in markdown. Using other formats wouldn't make much sense because that would prevent authors +from copy/pasting the template. + +The template should have the following sections: + +* **Introduction** - This should cover the primary problem and broad description of the solution. +* **Proposal** - The gory details of the proposal. +* **Potential issues** - This is where problems with the proposal would be listed, such as changes + that are not backwards compatible. +* **Alternatives** - This section lists alternative solutions to the same + problem which have been considered and dismsissed. +* **Security considerations** - Discussion of what steps were taken to avoid security issues in the + future and any potential risks in the proposal. + +Furthermore, the template should not be required to be followed. However it is strongly recommended to +maintain some sense of consistency between proposals. + + +## Potential issues + +*Not all proposals are perfect. Sometimes there's a known disadvantage to implementing the proposal, +and they should be documented here. There should be some explanation for why the disadvantage is +acceptable, however - just like in this example.* + +Someone is going to have to spend the time to figure out what the template should actually have in it. +It could be a document with just a few headers or a supplementary document to the process explanation, +however more detail should be included. A template that actually proposes something should be considered +because it not only gives an opportunity to show what a basic proposal looks like, it also means that +explanations for each section can be described. Spending the time to work out the content of the template +is beneficial and not considered a significant problem because it will lead to a document that everyone +can follow. + + +## Alternatives + +*This is where alternative solutions could be listed. There's almost always another way to do things +and this section gives you the opportunity to highlight why those ways are not as desirable. The +argument made in this example is that all of the text provided by the template could be integrated +into the proposals introduction, although with some risk of losing clarity.* + +Instead of adding a template to the repository, the assistance it provides could be integrated into +the proposal process itself. There is an argument to be had that the proposal process should be as +descriptive as possible, although having even more detail in the proposals introduction could lead to +some confusion or lack of understanding. Not to mention if the document is too large then potential +authors could be scared off as the process suddenly looks a lot more complicated than it is. For those +reasons, this proposal does not consider integrating the template in the proposals introduction a good +idea. + + +## Security considerations + +**All proposals must now have this section, even if it is to say there are no security issues.** + +*Think about how to attack your proposal, using lists from sources like +[OWASP Top Ten](https://owasp.org/www-project-top-ten/) for inspiration.* + +*Some proposals may have some security aspect to them that was addressed in the proposed solution. This +section is a great place to outline some of the security-sensitive components of your proposal, such as +why a particular approach was (or wasn't) taken. The example here is a bit of a stretch and unlikely to +actually be worthwhile of including in a proposal, but it is generally a good idea to list these kinds +of concerns where possible.* + +MSCs can drastically affect the protocol. The authors of MSCs may not have a security background. If they +do not consider vulnerabilities with their design, we rely on reviewers to consider vulnerabilities. This +is easy to forget, so having a mandatory 'Security Considerations' section serves to nudge reviewers +into thinking like an attacker. + +## Unstable prefix + +*If a proposal is implemented before it is included in the spec, then implementers must ensure that the +implementation is compatible with the final version that lands in the spec. This generally means that +experimental implementations should use `/unstable` endpoints, and use vendor prefixes where necessary. +For more information, see [MSC2324](https://github.com/matrix-org/matrix-doc/pull/2324). This section +should be used to document things such as what endpoints and names are being used while the feature is +in development, the name of the unstable feature flag to use to detect support for the feature, or what +migration steps are needed to switch to newer versions of the proposal.* + +## Dependencies + +This MSC builds on MSCxxxx, MSCyyyy and MSCzzzz (which at the time of writing have not yet been accepted +into the spec). From f2d9f021a300ddd1335099f2db3948fcd485a94a Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 21 Nov 2024 16:57:38 +0000 Subject: [PATCH 2/8] First draft --- proposals/4230-animated-image-flag.md | 75 +++++++++++++++++ proposals/xxxx-animated-image-flag.md | 117 -------------------------- 2 files changed, 75 insertions(+), 117 deletions(-) create mode 100644 proposals/4230-animated-image-flag.md delete mode 100644 proposals/xxxx-animated-image-flag.md diff --git a/proposals/4230-animated-image-flag.md b/proposals/4230-animated-image-flag.md new file mode 100644 index 00000000000..ebac9ca73ab --- /dev/null +++ b/proposals/4230-animated-image-flag.md @@ -0,0 +1,75 @@ +# MSC4230: 'Animated' flag for images + +Since animated images are thumbnailed to a still image, clients need to download the full +image in order to display it animated. However, there is currently no way of telling that +an image is animated without downloading the original image. This means that clients wishing +to display the image as animated must download the original image for any image format which +is capabale of being animated. This means they download the full size image for non-animated +images even when the user never chooses to enlarge the image. + +Even clients that animate images on hover must pre-fetch the full size image if they want the +animation to start without a delay while it's downloaded. + +## Proposal + +We add an optional boolean flag to the `info` object of image events indicating if the image is +animated or not. This SHOULD match whether the original image contains animation. Note that this +will require clients probe the image file for animation. Simpler clients may, therefore, choose to +not send this value at all, or always set it to false, meaning receiving clients are likley to render +the image as non-animated. + +Example: + +```json5 +{ + "body": "partyparrot.gif", + "file": { + [...] + }, + "info": { + "w": 640, + "h": 480, + "mimetype": "image/gif", + "size": 35295, + "animated": "true", + } +``` + +If this flag is `false`, receiving clients can assume that the image is not animated. If `true`, they should +assume that it is. + +Behaviour when the field is omitted is left up to the client. They might choose to behave as if it is present +and set to `true`, ensuring backwards compatibility whilst still saving bandwidth for images where the flag +is present and set to `false`. Perhaps they might decide to change this behaviour once more clients start +sending the flag. + +## Potential issues + +Clients may lie about the flag which would cause unexpected behaviour, for example, an image which +was not presented might then animate when the user clicks to enlarge it, allowing for 'jump scares' +or similar. Clients may wish to prevent images from being animated if the flag is set to false. + +As above, supporting animated images becomes harder for sending clients because they must work out if +an image is animated in order to set the flag. + +## Alternatives + +We could specify that clients behave as if the flag is set to true if it's absent. This would mean +clients that didn't want to probe images on upload could omit the flag, at the expense of receiving +clients needing to download the original to probe for animation. + +We could require that servers, or clients in the case of encrypted rooms, preserve animation on +thumbnailing. This is quite a burden for clients and would make thumbnails larger. + +## Security considerations + +Potential for clients to lie about the flag and cause unexpected animation is covered in 'Potential +Problems'. + +## Unstable prefix + +Until stable, the flag will be `org.matrix.animated`. + +## Dependencies + +None. diff --git a/proposals/xxxx-animated-image-flag.md b/proposals/xxxx-animated-image-flag.md deleted file mode 100644 index 41f76d2159b..00000000000 --- a/proposals/xxxx-animated-image-flag.md +++ /dev/null @@ -1,117 +0,0 @@ -# MSC0000: Template for new MSCs - -*Note: Text written in italics represents notes about the section or proposal process. This document -serves as an example of what a proposal could look like (in this case, a proposal to have a template) -and should be used where possible.* - -*In this first section, be sure to cover your problem and a broad overview of the solution. Covering -related details, such as the expected impact, can also be a good idea. The example in this document -says that we're missing a template and that things are confusing and goes on to say the solution is -a template. There's no major expected impact in this proposal, so it doesn't list one. If your proposal -was more invasive (such as proposing a change to how servers discover each other) then that would be -a good thing to list here.* - -*If you're having troubles coming up with a description, a good question to ask is "how -does this proposal improve Matrix?" - the answer could reveal a small impact, and that is okay.* - -There can never be enough templates in the world, and MSCs shouldn't be any different. The level -of detail expected of proposals can be unclear - this is what this example proposal (which doubles -as a template itself) aims to resolve. - - -## Proposal - -*Here is where you'll reinforce your position from the introduction in more detail, as well as cover -the technical points of your proposal. Including rationale for your proposed solution and detailing -why parts are important helps reviewers understand the problem at hand. Not including enough detail -can result in people guessing, leading to confusing arguments in the comments section. The example -here covers why templates are important again, giving a stronger argument as to why we should have -a template. Afterwards, it goes on to cover the specifics of what the template could look like.* - -Having a default template that everyone can use is important. Without a template, proposals would be -all over the place and the minimum amount of detail may be left out. Introducing a template to the -proposal process helps ensure that some amount of consistency is present across multiple proposals, -even if each author decides to abandon the template. - -The default template should be a markdown document because the MSC process requires authors to write -a proposal in markdown. Using other formats wouldn't make much sense because that would prevent authors -from copy/pasting the template. - -The template should have the following sections: - -* **Introduction** - This should cover the primary problem and broad description of the solution. -* **Proposal** - The gory details of the proposal. -* **Potential issues** - This is where problems with the proposal would be listed, such as changes - that are not backwards compatible. -* **Alternatives** - This section lists alternative solutions to the same - problem which have been considered and dismsissed. -* **Security considerations** - Discussion of what steps were taken to avoid security issues in the - future and any potential risks in the proposal. - -Furthermore, the template should not be required to be followed. However it is strongly recommended to -maintain some sense of consistency between proposals. - - -## Potential issues - -*Not all proposals are perfect. Sometimes there's a known disadvantage to implementing the proposal, -and they should be documented here. There should be some explanation for why the disadvantage is -acceptable, however - just like in this example.* - -Someone is going to have to spend the time to figure out what the template should actually have in it. -It could be a document with just a few headers or a supplementary document to the process explanation, -however more detail should be included. A template that actually proposes something should be considered -because it not only gives an opportunity to show what a basic proposal looks like, it also means that -explanations for each section can be described. Spending the time to work out the content of the template -is beneficial and not considered a significant problem because it will lead to a document that everyone -can follow. - - -## Alternatives - -*This is where alternative solutions could be listed. There's almost always another way to do things -and this section gives you the opportunity to highlight why those ways are not as desirable. The -argument made in this example is that all of the text provided by the template could be integrated -into the proposals introduction, although with some risk of losing clarity.* - -Instead of adding a template to the repository, the assistance it provides could be integrated into -the proposal process itself. There is an argument to be had that the proposal process should be as -descriptive as possible, although having even more detail in the proposals introduction could lead to -some confusion or lack of understanding. Not to mention if the document is too large then potential -authors could be scared off as the process suddenly looks a lot more complicated than it is. For those -reasons, this proposal does not consider integrating the template in the proposals introduction a good -idea. - - -## Security considerations - -**All proposals must now have this section, even if it is to say there are no security issues.** - -*Think about how to attack your proposal, using lists from sources like -[OWASP Top Ten](https://owasp.org/www-project-top-ten/) for inspiration.* - -*Some proposals may have some security aspect to them that was addressed in the proposed solution. This -section is a great place to outline some of the security-sensitive components of your proposal, such as -why a particular approach was (or wasn't) taken. The example here is a bit of a stretch and unlikely to -actually be worthwhile of including in a proposal, but it is generally a good idea to list these kinds -of concerns where possible.* - -MSCs can drastically affect the protocol. The authors of MSCs may not have a security background. If they -do not consider vulnerabilities with their design, we rely on reviewers to consider vulnerabilities. This -is easy to forget, so having a mandatory 'Security Considerations' section serves to nudge reviewers -into thinking like an attacker. - -## Unstable prefix - -*If a proposal is implemented before it is included in the spec, then implementers must ensure that the -implementation is compatible with the final version that lands in the spec. This generally means that -experimental implementations should use `/unstable` endpoints, and use vendor prefixes where necessary. -For more information, see [MSC2324](https://github.com/matrix-org/matrix-doc/pull/2324). This section -should be used to document things such as what endpoints and names are being used while the feature is -in development, the name of the unstable feature flag to use to detect support for the feature, or what -migration steps are needed to switch to newer versions of the proposal.* - -## Dependencies - -This MSC builds on MSCxxxx, MSCyyyy and MSCzzzz (which at the time of writing have not yet been accepted -into the spec). From 7a54973e0833177deddbe7d809b97a71a222cd3c Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 21 Nov 2024 17:02:36 +0000 Subject: [PATCH 3/8] Get the prefixed flag right --- proposals/4230-animated-image-flag.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4230-animated-image-flag.md b/proposals/4230-animated-image-flag.md index ebac9ca73ab..354e2d0c900 100644 --- a/proposals/4230-animated-image-flag.md +++ b/proposals/4230-animated-image-flag.md @@ -68,7 +68,7 @@ Problems'. ## Unstable prefix -Until stable, the flag will be `org.matrix.animated`. +Until stable, the flag will be `org.matrix.msc4230.animated`. ## Dependencies From 694fe6d0a54b0f805dc30583a6d32630b274cd72 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 21 Nov 2024 17:04:36 +0000 Subject: [PATCH 4/8] Use is_animated because that's what michael's impl uses --- proposals/4230-animated-image-flag.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/proposals/4230-animated-image-flag.md b/proposals/4230-animated-image-flag.md index 354e2d0c900..e5a3c8b631b 100644 --- a/proposals/4230-animated-image-flag.md +++ b/proposals/4230-animated-image-flag.md @@ -12,11 +12,11 @@ animation to start without a delay while it's downloaded. ## Proposal -We add an optional boolean flag to the `info` object of image events indicating if the image is -animated or not. This SHOULD match whether the original image contains animation. Note that this -will require clients probe the image file for animation. Simpler clients may, therefore, choose to -not send this value at all, or always set it to false, meaning receiving clients are likley to render -the image as non-animated. +We add an optional boolean flag, `ia_animated` to the `info` object of image events indicating if +the image is animated or not. This SHOULD match whether the original image contains animation. Note +that this will require clients probe the image file for animation. Simpler clients may, therefore, +choose to not send this value at all, or always set it to false, meaning receiving clients are +likley to render the image as non-animated. Example: @@ -31,7 +31,7 @@ Example: "h": 480, "mimetype": "image/gif", "size": 35295, - "animated": "true", + "is_animated": "true", } ``` @@ -68,7 +68,7 @@ Problems'. ## Unstable prefix -Until stable, the flag will be `org.matrix.msc4230.animated`. +Until stable, the flag will be `org.matrix.msc4230.is_animated`. ## Dependencies From 5e16aa6f56afc331e141ac4bda9ebd1b60d1ff02 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 21 Nov 2024 17:05:54 +0000 Subject: [PATCH 5/8] One day I will learn how to spell this word Today is not that day. --- proposals/4230-animated-image-flag.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4230-animated-image-flag.md b/proposals/4230-animated-image-flag.md index e5a3c8b631b..890cd8f0aa0 100644 --- a/proposals/4230-animated-image-flag.md +++ b/proposals/4230-animated-image-flag.md @@ -16,7 +16,7 @@ We add an optional boolean flag, `ia_animated` to the `info` object of image eve the image is animated or not. This SHOULD match whether the original image contains animation. Note that this will require clients probe the image file for animation. Simpler clients may, therefore, choose to not send this value at all, or always set it to false, meaning receiving clients are -likley to render the image as non-animated. +likely to render the image as non-animated. Example: From d0771f616c2286dd9c7f50b3cceb73332ebeb10b Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 22 Nov 2024 10:02:12 +0000 Subject: [PATCH 6/8] Use specific image type --- proposals/4230-animated-image-flag.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/proposals/4230-animated-image-flag.md b/proposals/4230-animated-image-flag.md index 890cd8f0aa0..a1e0571f7c4 100644 --- a/proposals/4230-animated-image-flag.md +++ b/proposals/4230-animated-image-flag.md @@ -12,7 +12,7 @@ animation to start without a delay while it's downloaded. ## Proposal -We add an optional boolean flag, `ia_animated` to the `info` object of image events indicating if +We add an optional boolean flag, `ia_animated` to the `info` object of `m.image` events indicating if the image is animated or not. This SHOULD match whether the original image contains animation. Note that this will require clients probe the image file for animation. Simpler clients may, therefore, choose to not send this value at all, or always set it to false, meaning receiving clients are @@ -61,6 +61,8 @@ clients needing to download the original to probe for animation. We could require that servers, or clients in the case of encrypted rooms, preserve animation on thumbnailing. This is quite a burden for clients and would make thumbnails larger. +This could also potentially be extended to `m.sticker` events. + ## Security considerations Potential for clients to lie about the flag and cause unexpected animation is covered in 'Potential From 4078173011f24e792021181dc8b496b6edafcb8c Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 22 Nov 2024 15:12:42 +0000 Subject: [PATCH 7/8] Typo Co-authored-by: R Midhun Suresh --- proposals/4230-animated-image-flag.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4230-animated-image-flag.md b/proposals/4230-animated-image-flag.md index a1e0571f7c4..b30ef5a4462 100644 --- a/proposals/4230-animated-image-flag.md +++ b/proposals/4230-animated-image-flag.md @@ -12,7 +12,7 @@ animation to start without a delay while it's downloaded. ## Proposal -We add an optional boolean flag, `ia_animated` to the `info` object of `m.image` events indicating if +We add an optional boolean flag, `is_animated` to the `info` object of `m.image` events indicating if the image is animated or not. This SHOULD match whether the original image contains animation. Note that this will require clients probe the image file for animation. Simpler clients may, therefore, choose to not send this value at all, or always set it to false, meaning receiving clients are From e550201a1336d726a196fef748e7ddde463cd004 Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 6 Dec 2024 16:30:19 +0000 Subject: [PATCH 8/8] Not a string Co-authored-by: Will Hunt --- proposals/4230-animated-image-flag.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4230-animated-image-flag.md b/proposals/4230-animated-image-flag.md index b30ef5a4462..0c5f6eb1898 100644 --- a/proposals/4230-animated-image-flag.md +++ b/proposals/4230-animated-image-flag.md @@ -31,7 +31,7 @@ Example: "h": 480, "mimetype": "image/gif", "size": 35295, - "is_animated": "true", + "is_animated": true, } ```