From 4143e2f632493cef05391f6bc92b2c411e7002b2 Mon Sep 17 00:00:00 2001 From: Catalan Lover Date: Thu, 10 Aug 2023 16:42:08 +0200 Subject: [PATCH 1/6] Initial Commit --- proposals/XXXX-presence-override-api.md | 81 +++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 proposals/XXXX-presence-override-api.md diff --git a/proposals/XXXX-presence-override-api.md b/proposals/XXXX-presence-override-api.md new file mode 100644 index 000000000..957bcd2da --- /dev/null +++ b/proposals/XXXX-presence-override-api.md @@ -0,0 +1,81 @@ +# MSC0000: Presence Override API + +In current matrix there exists no mechanism that is reliable to override the supposed to exist totem pole +for presence. Where more important states overrule less important ones. This proposal fixes that. + +This proposal proposes a new API that you can call to set a authoritative presence state for your account. This +state is always used negating all other ways to set presence. So if you set your state to `disabled` from +MSC_disabled_presence_state then well then your state would always be `disabled`. + +Using a new API for this instead of recycling some old method does come at the benefit of that this just works. + +No existing code can mess up and use this wrong to effectively ruin the whole point of this system because its new. + +Being able to set your authoritative presence state is seen as beneficial due to that it allows users to have full +control over their presence status instead of having to rely on all clients on their account collaborating to not +ruin the intention of the user. + +## Proposal + +To set a new presence override you call the new `/_matrix/client/v1/presence/{userId}/override` endpoint +using a PUT request. Using a payload that can look like the example below. + +```json +{ + "presence_override": "online" +} +``` + +The `presence_override` key used is whatever you want to force your presence to be. + +If you want to ask for what your current override is you simply make a GET request to the same endpoint. + +And you will get back a response that is like the example below if your override is `offline`. + +```json +{ + "presence_override": "offline" +} +``` + +As for error codes this is currently WIP but it follows a similar pattern to the current `/_matrix/client/v3/presence/{userId}/status` +endpoint. With minor reasonable adaptations like how presence is replaced with presence override where sensible. + +## Potential issues + +Other than this functionality being duplicate the author does not foresee any potential issues other than +that clients that don't support this feature will not be able to set the override status for the user. + +## Alternatives + +There are talks about that certain existing presence mechanisms might have this as their intended functionality but +as is addressed at the top of this proposal they have a viability problem in the fact that they are all existing +mechanisms. Existing mechanisms being reused can lead to clients with bad implementations misusing them +causing the mechanism to be rendered useless. + +A completely new API comes with the benefit that no legacy implementations can ruin everyone's experience. + +## Security considerations + +This proposal should not as far as the author is aware have security implications that are negative. The primary +positive effect is privacy related not strictly security in that users can cloak their presence state reliably. + +## 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._ + +While this proposal is unstable instead of using `/_matrix/client/v1/presence/{userId}/override` you use +`/_matrix/client/unstable/support.feline.mscAAAA.v1/override` + +And unstable feature flag used is `support.feline.mscAAAA.v1` + +## Dependencies + +This MSC has MSC_disabled_presence_state as a soft dependency as its a very useful state to override to. +This MSC has no hard dependencies and can be used on its own and merged on its own. \ No newline at end of file From 82302d7edee1c7bf911729a37ff5726753c84a61 Mon Sep 17 00:00:00 2001 From: Catalan Lover <48515417+FSG-Cat@users.noreply.github.com> Date: Thu, 10 Aug 2023 17:18:40 +0200 Subject: [PATCH 2/6] remove leftover template text from unstable section --- proposals/XXXX-presence-override-api.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/proposals/XXXX-presence-override-api.md b/proposals/XXXX-presence-override-api.md index 957bcd2da..ab5d170a1 100644 --- a/proposals/XXXX-presence-override-api.md +++ b/proposals/XXXX-presence-override-api.md @@ -62,14 +62,6 @@ positive effect is privacy related not strictly security in that users can cloak ## 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._ - While this proposal is unstable instead of using `/_matrix/client/v1/presence/{userId}/override` you use `/_matrix/client/unstable/support.feline.mscAAAA.v1/override` @@ -78,4 +70,4 @@ And unstable feature flag used is `support.feline.mscAAAA.v1` ## Dependencies This MSC has MSC_disabled_presence_state as a soft dependency as its a very useful state to override to. -This MSC has no hard dependencies and can be used on its own and merged on its own. \ No newline at end of file +This MSC has no hard dependencies and can be used on its own and merged on its own. From f880934b99cb2983e713ae6a86c230bee0d3b1e5 Mon Sep 17 00:00:00 2001 From: Catalan Lover Date: Thu, 10 Aug 2023 17:44:37 +0200 Subject: [PATCH 3/6] Rename MSC and update MSC to use MSC numbers instead of placeholders --- ...e-override-api.md => 4043-presence-override-api.md} | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) rename proposals/{XXXX-presence-override-api.md => 4043-presence-override-api.md} (89%) diff --git a/proposals/XXXX-presence-override-api.md b/proposals/4043-presence-override-api.md similarity index 89% rename from proposals/XXXX-presence-override-api.md rename to proposals/4043-presence-override-api.md index ab5d170a1..585a77dfa 100644 --- a/proposals/XXXX-presence-override-api.md +++ b/proposals/4043-presence-override-api.md @@ -1,11 +1,11 @@ -# MSC0000: Presence Override API +# MSC4043: Presence Override API In current matrix there exists no mechanism that is reliable to override the supposed to exist totem pole for presence. Where more important states overrule less important ones. This proposal fixes that. This proposal proposes a new API that you can call to set a authoritative presence state for your account. This state is always used negating all other ways to set presence. So if you set your state to `disabled` from -MSC_disabled_presence_state then well then your state would always be `disabled`. +MSC4042 then well then your state would always be `disabled`. Using a new API for this instead of recycling some old method does come at the benefit of that this just works. @@ -63,11 +63,11 @@ positive effect is privacy related not strictly security in that users can cloak ## Unstable prefix While this proposal is unstable instead of using `/_matrix/client/v1/presence/{userId}/override` you use -`/_matrix/client/unstable/support.feline.mscAAAA.v1/override` +`/_matrix/client/unstable/support.feline.msc4043.v1/override` -And unstable feature flag used is `support.feline.mscAAAA.v1` +And unstable feature flag used is `support.feline.msc4043.v1` ## Dependencies -This MSC has MSC_disabled_presence_state as a soft dependency as its a very useful state to override to. +This MSC has MSC4042 as a soft dependency as its a very useful state to override to. This MSC has no hard dependencies and can be used on its own and merged on its own. From fda11ae996b475ba1b44fd98ab518f265ed352ed Mon Sep 17 00:00:00 2001 From: Catalan Lover <48515417+FSG-Cat@users.noreply.github.com> Date: Fri, 11 Aug 2023 20:02:33 +0200 Subject: [PATCH 4/6] Add Empty Key to disable override section --- proposals/4043-presence-override-api.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/proposals/4043-presence-override-api.md b/proposals/4043-presence-override-api.md index 585a77dfa..10599026e 100644 --- a/proposals/4043-presence-override-api.md +++ b/proposals/4043-presence-override-api.md @@ -38,6 +38,14 @@ And you will get back a response that is like the example below if your override } ``` +And to disable override you send a payload with a empty `presence_override` key like the example below. + +```json +{ + "presence_override": "" +} +``` + As for error codes this is currently WIP but it follows a similar pattern to the current `/_matrix/client/v3/presence/{userId}/status` endpoint. With minor reasonable adaptations like how presence is replaced with presence override where sensible. From e622c5b2acfc9a6454fcc4dd8c9c80d6ba899d7e Mon Sep 17 00:00:00 2001 From: Catalan Lover <48515417+FSG-Cat@users.noreply.github.com> Date: Sat, 19 Aug 2023 18:33:36 +0200 Subject: [PATCH 5/6] Fix unstable API path oversight Co-authored-by: Will Hunt --- proposals/4043-presence-override-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4043-presence-override-api.md b/proposals/4043-presence-override-api.md index 10599026e..d4eea501b 100644 --- a/proposals/4043-presence-override-api.md +++ b/proposals/4043-presence-override-api.md @@ -71,7 +71,7 @@ positive effect is privacy related not strictly security in that users can cloak ## Unstable prefix While this proposal is unstable instead of using `/_matrix/client/v1/presence/{userId}/override` you use -`/_matrix/client/unstable/support.feline.msc4043.v1/override` +`/_matrix/client/unstable/support.feline.msc4043.v1/presence/{userId}/override` And unstable feature flag used is `support.feline.msc4043.v1` From 7d1b014ec3a1bacabaee0122f2d48f37e41308a2 Mon Sep 17 00:00:00 2001 From: Catalan Lover <48515417+FSG-Cat@users.noreply.github.com> Date: Mon, 19 Feb 2024 20:54:51 +0100 Subject: [PATCH 6/6] Update reference to MSC4042 to be a link Co-authored-by: Hubert Chathi --- proposals/4043-presence-override-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4043-presence-override-api.md b/proposals/4043-presence-override-api.md index d4eea501b..29bfaadef 100644 --- a/proposals/4043-presence-override-api.md +++ b/proposals/4043-presence-override-api.md @@ -5,7 +5,7 @@ for presence. Where more important states overrule less important ones. This pro This proposal proposes a new API that you can call to set a authoritative presence state for your account. This state is always used negating all other ways to set presence. So if you set your state to `disabled` from -MSC4042 then well then your state would always be `disabled`. +[MSC4042](https://github.com/matrix-org/matrix-spec-proposals/pull/4042) then well then your state would always be `disabled`. Using a new API for this instead of recycling some old method does come at the benefit of that this just works.