- Python 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
* review * add background to usecase specific considerations * Simplify main proposal for widget api usage * make `future_group_id` server generated and small adjustments * review * user scoping details * Update proposals/4140-delayed-events-futures.md Co-authored-by: Andrew Ferrazzutti <af_0_af@hotmail.com> * add rate limiting section * rename `/futures` to `/future` * Update everything to v1 and use proper msc number in unstable prefix section. * Update proposals/4140-delayed-events-futures.md Co-authored-by: Travis Ralston <travisr@matrix.org> * review * Swap the alternative of reusing the send and state request with the main proposal of `send_future` and `state_future`. * add reference to MSC4143 (MatrixRTC) * Meeting feedback: - remove token concept for authed EDU - authenticated delegation - simplified group_id + tokens into just one future_id - Mention "Last Will" mental model * remove parent concept. * Refactor + unstable prefixes * Update to GET /futures * Standardise endpoint for interacting with futures * Make it clear that events can be cancelled * Make wording more authoritative * Remove erroneous old example * Take view that clients don't act on behalf of a user * Use name delay_id and delayed_events * Clean up more references to future * event_type => type * Tidying * Pagination on GET endpoint * Add alternative of M_INVALID_PARAM * change order of manage <-> get sections * Obey lint rules and more renames * TOC update * Additional notes on security considerations * Add rate limiting requirements * Describe MatrixRTC use case in terms of heartbeats Remove SFU delegation reference. * "leave" => "hangup" for consistency * Wording clarification * Additional reference to heartbeat * TOC update (use monospace and dont list msc title * be consistent with "restart" wording (we used reset, refresh and restart before) * Add compatibility with Cryptographic Identities to potenail issues * Add placeholder for MSC3277 * Add note about MSC2716 batch sending * Add alternative of not providing a send action * Add alternative of using DELETE HTTP method * Add clarification about regular/non-state events not getting cancelled * Clarify contents of content field on GET response * Expose transaction ID in GET response * Add context on MSC3277 alternative * Add more context to MQTT style alternative * Add alternative of typing notifications * Update TOC * Fix TOC * Note on alternative names for `running_since` * Revert "Expose transaction ID in GET response" This reverts commit 772590f6bac61bd026e8a60dc055b76637cce8f7. Clients should keep track of transaction IDs themselves. * Scope GET to only the requesting user's events * remove all references to future (except where we actually talk about the future and not future_events) * add terminated events section to GET endpoint * use case specific considerations details * remove batch sending endpoint since that does not make sense in the short term and longer term send_pdus is the better solution. * Clean up iteration with two significant changes: - we have two GET endpoints `/shedueled` `/terminated` now. - The rule for when a state delayed event is cancelled changed to include a sender user condition. * terminated -> finalised * andrews changes * requried -> required * Change example of "canceled" outcome to "cancel" * Minor formatting changes * Allow servers to discard returned finalised events * Define finalised events for /sync & /transactions Also define a sync filter * use current MatrixRTC MSC types. * review trivial changes * Add rate limit section to `GET` `finalized` and `scheduled` endpoint * clarify why there is no rate limiting for the delayed event management endpoint. * remove `on push` delayed event finilization section * formatting/cleanup * fix synapse and MSC inconsistency * Constrain delay value to >0ms Co-authored-by: Travis Ralston <travisr@matrix.org> * Editorial fixes * remove link to MSC4143 text that will probably break when the MSC is merged * add missing words to M_NOT_FOUND case * allow ratelimiting on management endpoints * mandate limits without mandating using a config file * add stable feature flag * allow rounding delays Signed-off-by: Tulir Asokan <tulir@maunium.net> * Remove optional wording of limits They're mandated by the security considerations section Signed-off-by: Tulir Asokan <tulir@maunium.net> * Add syncing failed delayed events to alternatives Signed-off-by: Tulir Asokan <tulir@maunium.net> * Define retrying and responses for managing delayed events Signed-off-by: Tulir Asokan <tulir@maunium.net> * Specify delay_id grammar * Specify missing HTTP response codes * Explain `outcome` and `reason` on finalised events * Merge GET endpoints to avoid namespace clash * Add send time as alternative to `running_since` * Use opaque identifier grammar for delay_id * Merge /scheduled and /finalised as query params * Allow GET endpoint to filter on ID * Tweak wording/spelling/format * Move delayed state event cancelling to alternative * Move M_CANCELLED_BY_STATE_UPDATE out of main spec * Tweak spelling/format * Remove rendundant & stale table of contents Redundant because GitHub's Markdown viewer provides its own ToC. Stale because some of the headings refered to absent sections. * Tweak formatting & wording of `status` section * Don't return 400 for multiple `status` parameters * Reduce emphasis on state events but state events are still used in the MatrixRTC section * Fix swapped links to /send and /state * Update all spec links to v1.16 * Fix typo * Always require origin_server_ts on finalised evts It is either the send time, or the cancel/error time * Limit cached finalised events per user, not global * Apply batch size to not just finalised events * Note deviations in Synapse implementation * Reintroduce unauthed management for delegation Also: - split them into one endpoint per management action - propose alternative of OAuth 2.0 scoped access for the endpoints * Mention single-URL management as an alternative and list it as what the Synapse implementation currently uses * Use correct version for event sending endpoints * Use dedicated endpoint for delayed event creation Keep prior approach of extending send/state endpoints as an alternative * Update all spec links to v1.17 * Specify unstable version of new endpoint path and remove the now-unused unstable query parameter * Prefer M_RESOURCE_LIMIT_EXCEEDED over a new error Keep the prior custom error as an alternative * Fix typo * Add "`delay_id` in `unsigned` sync field" section * Do not use M_RESOURCE_LIMIT_EXCEEDED It is the wrong error type. It is used for servers reaching (compute) resource limits. Per user based limit logic will be communicated use M_LIMIT_EXCEEDED * update error code prefix * M_LIMIT_EXCEEDED -> M_USER_LIMIT_EXCEEDED * Update proposals/4140-delayed-events-futures.md Co-authored-by: Travis Ralston <travisr@matrix.org> * Use unstable prefix for unsigned data key * Tweak when to include `delay_id` in `unsigned` - Allow including it for more than just `/sync` - Forbid including it for non-senders in all cases - Use similar wording as §10.2.2.2. Local Echo in the spec when referring to events that arrive through `/sync` * Revert "M_LIMIT_EXCEEDED -> M_USER_LIMIT_EXCEEDED" This reverts commit 642b09eaf238bc4f4fa97bee6615bb68481bae8d. M_USER_LIMIT_EXCEEDED is designed to be a "pay to get rid of the error" kind of problem, and there is currently no plan to make delayed event quotas a paid feature. Since delayed events expire over time, treat exhaustion of the delayed event quota as a "rate limit class"-error. * Restore "in the proposal stage" -> "unstable" * Put delay_id in unsigned for all event renderings Still only for the sender, of course * Mention security requirement for `delay_id` * Use M_LIMIT_EXCEEDED with 429 and Retry-After Set Retry-After value to the time until the next event is sent, as was originally proposed along with the idea of using M_LIMIT_EXCEEDED * Update all spec links to v1.18 * Wrap all lines to 120 characters maximum * Move "`delay_id` in `unsigned` event data" section It shouldn't be in the "Retrieving delayed events" section. Put it under "Homeserver implementation details" instead. * Capitalize Client-Server API; server -> homeserver * Clarify authentication & scheduled delayed events * Clarify error responses * Support timestamp massaging * Tweak management endpoints - Return success on any redundant action, not just `send` - Return 409 Conflict on any conflicting action - Don't finalise on `send` if an error prevents the send - Tweak wording * Add single-item lookup, tweak multi-item lookup - Remove `outcome` and `reason` fields from retrieved items, as they are redundant with the presence/absence of `event_id` and `error` - Have the multi-item lookup use the same array for both scheduled and finalised delayed events, to simplify pagination & filtering - Give a better description of what makes a delayed event finalised, to give more context for fields of retrieved finalised delayed events - Move blurb on retention of finalised delayed events into a subsection of the section on both retrieval endpoints * Suggest to not reschedule events on failure And explain why this is solved by being able to look up failed finalised delayed events * Some more rewording & clarification * Minor rewording & reformatting * Update proposals/4140-delayed-events-futures.md Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org> * Update proposals/4140-delayed-events-futures.md Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org> * Update proposals/4140-delayed-events-futures.md Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org> * Update proposals/4140-delayed-events-futures.md Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org> * Update proposals/4140-delayed-events-futures.md Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org> * Update proposals/4140-delayed-events-futures.md Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org> * Update proposals/4140-delayed-events-futures.md Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org> * Update proposals/4140-delayed-events-futures.md Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org> * Shorten alternatives (#4479) Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org> * *MSC4140: Convert cancelling delayed state events alternative into briefer potential issue (#4477) * Convert cancelling delayed state events alternative into briefer potential issue Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org> * Fix grammar Co-authored-by: Andrew Ferrazzutti <af_0_af@hotmail.com> --------- Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org> Co-authored-by: Andrew Ferrazzutti <af_0_af@hotmail.com> * latest to versioned spec link Co-authored-by: Travis Ralston <travisr@matrix.org> * Remove implementation TODOs Will be tracked in MSC comments instead Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org> * Discuss `M_MAX_DELAYED_EVENTS_EXCEEDED` Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org> * Fix links to management section * Clarify that delegation is for scheduled events * Update proposals/4140-delayed-events-futures.md * Trade `M_MAX_DELAY_EXCEEDED` for a capability Use a capability to advertise server-configured limits on delayed events * Rename finalised time field to `finalised_ts` Rename it from `origin_server_ts`, which shares a name with a similar but unrelated field belonging to sent events * Add & explain alternatives to `running_since` * Minor tweaks * Explain how to determine status from fields * Minor formatting * Add missing brace * Simplify the bulk retrieval endpoint * Warn about heartbeat ratelimits Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org> * Remove (intentional) misspelling to pass CI * *MSC4140: Blend use case specific considerations into the introduction directly (#4478) Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org> * Use consistent grammar for status types Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org> * Elaborate on why `/sync` isn't supported yet * Move filtering & pagination to MSC4486 Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org> * Add missing MSC link * Generalize event availability statement * Shorten MSC4018 alternative * Shorten summary of federation alternative * Fix typo * Use proper sentence case * Shorten formulation * Fix typo * Emphasize reason for crypto-secure delay_id * Use consistent style for introducing new endpoints * Clarify the endpoints for delegated management * Note properties now absent from bulk lookup items The bulk lookup no longer includes finalised delayed events, so note that the returned items won't have fields exclusive to finalised events. * Don't say bulk lookup may discard finalised events The bulk lookup no longer includes finalised delayed events, so don't include it in the regex of endpoints that may discard a finalised event upon retrieving it. Now only the single-item lookup may do this. * Small wording & grammar adjustment * Add special-case error for disabled delayed events * Remove batch size for now-removed bulk endpoint * Wrap more lines to 120 characters * Add delayed event persistence & startup send * Rename `send_time` alternative to `send_ts` to be consistent with how most other specced timestamp-valued fields have a name ending in `_ts` * Append "_ms" to delay-related field names This targets: - the "delay" field of the POST request body - the "delay" field of the GET response body - the "max_delay" field of the capability object * Rename `running_since` to `scheduled_at` Also update the section on alternatives to that field * Use /v1.18 rather than /latest Co-authored-by: Travis Ralston <travisr@matrix.org> * User `/v1.18` rather than `/latest` Co-authored-by: Travis Ralston <travisr@matrix.org> * Clarify maximum delay Co-authored-by: Travis Ralston <travisr@matrix.org> * Use `/v1.18` rather than `/latest` Co-authored-by: Travis Ralston <travisr@matrix.org> * Use `/v1.18` rather than `/latest` Co-authored-by: Travis Ralston <travisr@matrix.org> * Use `/v1.18` rather than `/latest` Co-authored-by: Travis Ralston <travisr@matrix.org> * Use `/v1.18` rather than `/latest` Co-authored-by: Travis Ralston <travisr@matrix.org> * Use `/v1.18` rather than `/latest` Co-authored-by: Travis Ralston <travisr@matrix.org> * Shorten consideration of compatibility with MSC4080 Co-authored-by: Travis Ralston <travisr@matrix.org> * Link to MQTT spec for will messages Co-authored-by: Travis Ralston <travisr@matrix.org> * Remove filtering claim for query parameter alternative * Elaborate & link to criticism of shared endpoint * Use M_FORBIDDEN/403 for disallowed delayed events * Use M_FORBIDDEN/403 for exceeding the max delay Also reword the special case error response now that only the 0-limit case is special * Add example for other required details for delegation * Fix leftover conversion from /refresh to /restart * Clarify uniqueness of delay IDs * Clarify security aspects of delayed event delegation * Reword rules on access of GET /{delay_id} * Clarify when to include `delay_id` in `unsigned` Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org> * Drop delegation; require auth on management Move delegation to an alternative. It is planned to be given its own MSC. * Remove tea timer usecase Due to batch sending, scheduled send times are allowed to be delayed somewhat, making delayed events unreliable for timer usecases. * Clarify that enforced limits must be in capability i.e. the MUST is not just one way around * Rephrase sentence Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com> * Remove section on conflicting delayed state events as it no longer has a planned use case and is thus not worth mentioning, even as an alternative * Remove special case for delayed event limit of 0 * Avoid describe homeserver implementation details * Use a new M_DELAY_TOO_LARGE error code and HTTP 400 * Clarify that the endpoints are scoped to users * Rename `scheduled_at` to `delayed_since_ts` Also update the section on alternatives to that field (again) * Move finalised properties into its own sub-object * Enforce schedule-time event validation check * Add other fields that prevent eventID calculation * Pick up link to SFU definition * Clarify chronological ordering * Say that usual rate limits on event sending apply * Add unstable version of M_DELAY_TOO_LARGE * Collapse "querying finalised" events into "filtering" * Delegation also helps when the client is under adverse network conditions but not entirely disconnected * Remove mention of adding lag for batch sending * Update `send` error to match non-delayed `/send` Use spec-provided example of an invalid `/send` request * Move bulk lookup to MSC4486 * Mention why servers shouldn't handle retries * Don't enforce `M_UNKNOWN` for the 409 response * Explicitly omit `transaction_id` from `unsigned` * Restrict value type of capability fields * Move capability-related limits next to each other * Mention delayed event limit being in a capability * Update spec links to v1.19 Kept you waiting, huh? * Fix egregious typo Section used the opposite term that it should have used * Explain purpose of retaining finalised events * Always use term of "finalised delayed events" Never say just "finalised events" * Replace "MUST NOT" with "SHOULD NOT" re: txnid No need to be strict, but still be clear that there is not much use in including the `transaction_id` field * Add back special case of disabled delayed events Highlight that using the M_FORBIDDEN response is optional (with MAY). Also restore version of the special case that considers both the max delay limit & max scheduled limit, now that the former went back to using an errcode distinct from M_FORBIDDEN. * Reword special case to be more general Co-Authored-By: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Add example use cases for delayed state events * Remove example with M_DUPLICATE_ANNOTATION Instead just say more clearly that the error returned is the same as what would have been returned for a non-delayed event request * Revert allowing to discard finalised events on GET Network errors on the endpoint would cause responses to be lost if they were to be discarded by the server * Add issue of server config blocking some use cases * Evaluate auth rules at schedule time Evaluate at both schedule & send time Co-authored-by: Erik Johnston <erik@matrix.org> * Specify meaning of absent capability & 0 limits * "error code" -> errcode for the sake of consistency * Cross reference delegation mechanism from MSC4195 * Clarify behaviour on account deactivation and suspension --------- Signed-off-by: Tulir Asokan <tulir@maunium.net> Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org> Co-authored-by: Andrew Ferrazzutti <af_0_af@hotmail.com> Co-authored-by: Travis Ralston <travisr@matrix.org> Co-authored-by: Hugh Nimmo-Smith <hughns@element.io> Co-authored-by: Andrew Ferrazzutti <andrewf@element.io> Co-authored-by: Tulir Asokan <tulir@maunium.net> Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org> Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com> Co-authored-by: Robin <robin@robin.town> Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Co-authored-by: Erik Johnston <erik@matrix.org> |
||
| .github | ||
| proposals | ||
| .editorconfig | ||
| .gitignore | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| MSC_CHECKLIST.md | ||
| README.md | ||
Matrix Specification Proposals
This repository contains proposals for changes to the Matrix
Protocol, aka "Matrix Spec Changes" (MSCs). The
proposals directory contains MSCs which have been accepted.
See below for instructions for creating new proposals. See also https://spec.matrix.org/proposals/ for more information on the MSC process, in particular https://spec.matrix.org/proposals/#process.
The source of the Matrix specification itself is maintained at https://github.com/matrix-org/matrix-spec.
The Matrix Spec Process
An MSC is meant to be a technical document that unambiguously describes a change to the Matrix Spec, while also justifying why the change should be made.
The document is used both to judge whether the change should be made as described and by developers to actually implement the changes. This is why it's important for an MSC to be fully fleshed out in technical detail, as once merged it's immediately part of the formal spec (even though it still needs to be transcribed into the actual spec itself).
What changes need to follow this process?
In most cases a change to the Matrix protocol will require an MSC. Changes that would not require an MSC are typically small and uncontentious, or are simply clarifications to the spec. Fixing typos in the spec do not require an MSC. In most cases, removing ambiguities do not either. The exception may be if implementations in the ecosystem have differing views on clarifying the ambiguity. In that case, an MSC is typically the best place to reach consensus.
Ultimately, the Spec Core Team have the final say on this, but generally if the change would require updates to a non-insignificant portion of the Matrix implementation ecosystem or would be met with contention, an MSC is the best route to take. You can also ask in the Matrix Spec or Office of the Spec Core Team Matrix rooms for clarification.
Summary of the process
The MSC process consists of three basic steps:
- Write up the proposal in a markdown document. (There's a proposal template, but don't feel bound by it.)
- Submit it as a Pull Request to this repo, marking it as a draft until it's ready for wider review.
- Seek review from the community. Once people are generally happy with it, ask the Spec Core Team to look at it in the Office of the SCT Matrix room. When the SCT are happy with the proposal, and after a successful voting process, your pull request is merged and the MSC is now officially accepted as part of the Matrix Spec and can be used 🎉
For simple changes this is really all you need to know. For larger or more controversial changes, getting an MSC merged can take more time and effort, but the overall process remains the same.
Below is various guidance to try and help make the experience smoother.
Guidance on the process
1. Writing the proposal
Come up with an idea. The idea can be for anything, but the solution (MSC) needs to benefit the Matrix ecosystem rather than yourself (or your company) specifically. Sometimes this means that the solution needs to be more generic than the specific itch that you are trying to scratch.
Remember that an MSC is a formal technical document which will be used by others in the wider community to judge if the proposal should be accepted and to actually implement the changes in clients and servers. This means that for an MSC to be accepted it should include justifications and describe the technical changes unambiguously, including specifying what happens in any and all edge cases.
There's a proposal template under
docs/0000-proposal.md, but you don't necessarily need to use it. Covering the
same major points is fine.
- Note: At this stage, you won't have an MSC number, so feel free to use
0000,XXXX, or whatever other placeholder you feel comfortable with.
Some tips for MSC writing:
- Please wrap your lines to 120 characters maximum. This allows readers to review your markdown without needing to horizontally scroll back and forth. Many markdown text editors have this feature.
- If you are referencing an existing endpoint in the spec, or another MSC, it
is very helpful to add a link to them so the reader does not need to search
themselves. Examples:
- "This MSC proposals an alternative to MSC3030."
- "A new field will be added to the response body of
/_matrix/client/v3/sync".- Note: it is best to link to the latest stable version of the spec (e.g. /v1.3, not /latest) - failing that, /unstable if the change is not yet in a released spec version.
- GitHub supports rendering fancy diagrams from text with very little effort using Mermaid. See this guide for more information.
- Take a look at the MSC Checklist. When it comes time for the Spec Core Team to review your MSC for acceptance, they'll use the items on this checklist as a guide.
2. Submitting a Pull Request
- Open a Pull
Request
to add your proposal document to the
proposalsdirectory. Note that this will require a GitHub account.- Mark your Pull Request as a draft for now.
- The MSC number is the number of the pull request that is automatically assigned by GitHub. Go back through and edit the document accordingly. Don't forget the file name itself!
- Edit the pull request title to fit the format "MSC1234: Your proposal title".
- Once your proposal is correctly formatted and ready for review from the wider ecosystem, take your Pull Request out of draft status.
The Spec Core Team will notice this and apply various labels/status tracking to your MSC, which will announce it to the wider world.
3. Seeking review
Seek review from the Matrix community. Generally this will happen naturally, but if you feel that your proposal is lacking review then ask for people's opinion in the Matrix Spec room on Matrix.
Reviews can take many forms, and do not need to be done solely by members of the Spec Core Team. Getting other people who are familiar with the area of Matrix you are proposing changes to is a great first step; especially those who may be implementing these changes in clients and/or homeservers.
While the proposal is a work in progress, it's fine for it to be high level and hand-wavy in places, but remember that before it can be accepted it needs to be expanded to fully flesh out all the technical detail and edge cases.
At this stage the proposal should also be implemented as a proof of concept somewhere to show that it actually works in practice. This can be done on any client or server and doesn't need to be merged or released.
4. Entering Final Comment Period
After the MSC has been implemented, fully fleshed out, and generally feels ready for final review, you should ask a member of the Spec Core Team to review it in the public Spec Core Team Office room on Matrix. Someone from the SCT will then review it, and if all looks well will propose FCP to start.
At this point, other members of the SCT will look at the proposal and consider it for inclusion in the spec.
After enough SCT members have approved the proposal, the MSC will enter something called Final Comment Period. This is a 5 calendar day countdown to give anyone one last chance to raise any blockers or concerns about the proposed change. Typically MSCs pass this stage without incident, but it nevertheless serves as a safeguard.
5. The MSC is accepted
Once FCP has ended and the MSC pull request is merged, the proposed change is considered officially part of the spec. Congratulations!
Clients and servers can now start using the change, even though at this stage it still needs to be transcribed into the spec document. This happens over in https://github.com/matrix-org/matrix-spec/ and you are very welcome to do it yourself! Otherwise it will be handled by a Spec Core Team member. If you would like help with writing spec PRs, feel free to join and ask questions in the Matrix Spec and Docs Authoring Room on Matrix.
Other useful information
Unstable prefixes
"Unstable prefixes" are the namespaces which are used by implementations while an MSC is not yet accepted.
For instance, an MSC might propose that a m.space
event type or an /_matrix/client/v1/account/whoami endpoint should exist.
However, implementations cannot use these stable identifiers until the MSC
has been accepted, as the underlying design may change at any time; the design is
unstable.
Instead, an MSC can define a namespace such as org.matrix.msc1234 (using the real
MSC number once known) which is added to the stable identifier, allowing for
breaking changes between edits of the MSC itself, and preventing clashes with other
MSCs that might attempt to add the same stable identifiers.
For the above examples, this would mean using org.matrix.msc1234.space and
/_matrix/client/unstable/org.matrix.msc1234/account/whoami. It is also fine to
use more traditional forms of namespace prefixes, such as com.example.* (e.g.
com.example.space).
Note: not all MSCs need to make use of unstable prefixes. They are only needed if implementations of your MSC need to exist in the wild before your MSC is accepted, and the MSC defines new endpoints, field names, etc.
Unstable feature flags
It is common when implementing support for an MSC that a client may wish to check
if the homeserver it is communicating with supports an MSC.
Typically, this is handled by the MSC defining an
entry in the unstable_features dictionary of the
/_matrix/client/versions
endpoint, in the form of a new entry:
{
"unstable_features": {
"org.matrix.msc1234": true
}
}
... with a value of true indicating that the feature is supported, and false
or lack of the field altogether indicating the feature is not supported.
When can I use stable identifiers?
According to the spec process: once an MSC has been accepted, implementations are allowed to switch to stable identifiers. However, the MSC is still not yet part of a released spec version.
In most cases, this is not an issue. For instance, if your MSC specifies a new event type, you can now start sending events with those types!
Some MSCs introduce functionality where coordination between implementations is needed. For instance, a client may want to know whether a homeserver supports the stable version of a new endpoint before actually attempting to request it. Or perhaps the new event type you're trying to send relies on the homeserver recognising that new event type, and doing some work when it sees it.
At this point, it may be best to wait until a new spec version is released with
your changes. Homeservers that support the changes will eventually advertise
that spec version under /versions, and your client can check for that.
But if you really can't wait, then there is another option: the homeserver can
tell clients that it supports stable identifiers for your MSC before it
enters a spec version, using yet another unstable_features flag:
{
"unstable_features": {
"org.matrix.msc1234": true,
"org.matrix.msc1234.stable": true
}
}
If a client sees that org.matrix.msc1234.stable is true, it knows that it
can start using stable identifiers for the new MSC, and the homeserver will
accept and act on them accordingly.
Note: While the general pattern of using the text ".stable" has emerged from previous MSCs, you can pick any name you like. You need only to clearly state their meaning, usually under an "Unstable prefixes" header in your MSC.
See MSC3827 for a good example of an MSC that wanted to use such a flag to speed up implementation rollout, and how it did so.
Room versions
To summarize the spec on room versions: they are how servers agree upon algorithms in a decentralized world like ours. Examples of changes that require a new room version include anything that changes:
- The format of the core event structure (such as renaming a top-level field, or modifying the redaction algorithm), therefore altering the reference hash of an event.
- The authorisation of events (such as changes to power levels).
Unstable prefixes (see above) for room versions work the same as they do for other identifiers; your unstable room version may be called "org.matrix.msc1234".
In order for the changes to end up in a "real" room version (the ones listed in the spec), it will need a second MSC which aggregates a bunch of functionality from various MSCs into a single room version. Typically these sorts of curating MSCs are written by the Spec Core Team given the complexity in wording, but you're more than welcome to bring an MSC forward which makes the version real.
For an example of what introducing a new room version-required feature can look like, see MSC3667. For an example of what making a new "real" room version looks like, see MSC3604.
Ownership of MSCs and closing them
If an author decides that they would no longer like to pursue their MSC, they can either pass ownership of it off to someone else, or close it themselves.
-
The author of an MSC can close their MSC at any time before FCP by simply closing the pull request.
-
To appoint another user as an author of the MSC (either to replace the author entirely or to provide additional help), make a note in the MSC's PR description by writing the following on its own line:
Author: @usernamewhere
@usernameis a valid GitHub username. Multiple such lines can be added.Finally, give that user access to write to your fork of matrix-spec-proposals on GitHub, which your PR originates from. This will allow them to change the text of your MSC.
Similar to accepting an MSC, the Spec Core Team may propose a Final Comment Period with a disposition of "close". This can happen if the MSC appears abandoned by its author, or the idea is widely rejected by the community. A vote and final comment period will still be required for the motion to pass.
Additionally, FCP can be also proposed with a disposition of "postpone". This may be done for MSCs for which the proposed changes do not make sense for the current state of the ecosystem, but may make sense further down the road.
Asking for help
The Matrix community and members of the Spec Core Team are here to help guide you through the process!
If you'd just like to get initial feedback about an idea that's not fully fleshed out yet, creating an issue at https://github.com/matrix-org/matrix-spec/issues is a great place to start. Be sure to search for any existing issues first to see if someone has already had the same idea!
A few official rooms exist on Matrix where your questions can be answered, or feedback on your proposal can be requested:
- #matrix-spec:matrix.org - General chat for MSCs, the spec, and pretty much anything in that sphere.
- #sct-office:matrix.org - Where the Spec Core Team hangs out and is available. This room is intended to have extremely high signal and low noise, primarily to ensure that MSCs are not falling through the cracks. If an MSC requires attention or comment from Spec Core Team members, bring it up here.
- #matrix-spec-process:matrix.org - A room dedicated to the spec process itself. If you have any questions about or suggestions to improve the Matrix Spec process, ask them here.
- #matrix-docs:matrix.org - A quieter room for discussion of the formal spec text and matrix.org website.