-
Notifications
You must be signed in to change notification settings - Fork 412
MSC1772: Matrix spaces #1772
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
MSC1772: Matrix spaces #1772
Changes from 18 commits
Commits
Show all changes
89 commits
Select commit
Hold shift + click to select a range
6c499db
WIP groups as rooms MSC
ara4n 346f7ac
add hyperlinks
ara4n 1e81fbd
md
ara4n a884fd8
wordwrap fix
ara4n 43ae6ad
md
ara4n e00eff5
add thought about splitting events
ara4n cd5a842
flesh out how flair could work
ara4n 19e9420
flesh out state events split per state-key for defining groups
ara4n 010246e
typo
ara4n 88ff3de
spell out deps
ara4n 54bf339
typo
ara4n 1bbe638
typo
ara4n 417501d
various minor edits
richvdh 96cd76c
remove 'one big event' proposal
richvdh 6464e90
Merge branch 'master' into matthew/msc1772
richvdh 0baf49a
We are not considering hidden-membership rooms yet
richvdh 4040254
Update for new terminology and current thinking
richvdh 52853b5
more updates
richvdh c145d39
Notes on propagating PLs etc
richvdh 15f34e5
supporting trad PLs
richvdh e746aa3
Apply suggestions from code review
richvdh 2f557da
Clarifications to room/space relationship
richvdh 11bb604
add an xxx
richvdh d42da58
Apply suggestions from code review
richvdh 1aede33
clarify introduction
richvdh e323ade
Switch to room IDs
richvdh a73dd9c
clarification
richvdh 839ea0e
inheriting join rules
richvdh 109c31c
Avoiding abuse via false `parent` claims
richvdh 06b5c83
notes on children and recursion
richvdh 29b07c1
update power level mappings
richvdh ae71a62
Restricting room membership via spaces
richvdh b40f7da
Record alternatives
richvdh 4e3b0ed
add a length limit to `order`
richvdh 3b2825f
Descope autokick and rename allowed_spaces
richvdh e6a6941
rename allowed_join again
richvdh fbad757
update dependencies links
richvdh 1f1e3c9
MSC1840 is in
richvdh d4abe40
one parent per room
richvdh 39af7f3
Update 1772-groups-as-rooms.md (#2866)
grinapo 45f2608
No cross-room auth
richvdh 6cc3995
explain a bit
richvdh 51aa5e2
Update proposals/1772-groups-as-rooms.md
richvdh 6989758
Update proposals/1772-groups-as-rooms.md
richvdh 037894a
replace 'default' with 'auto_join'
ara4n 803e70a
typo
ara4n 42c332b
fix parent claiming plurality
ara4n 2de3dc4
more plurality fixing
ara4n 302d5d8
clarify autojoin and mention 'suggested' rooms
ara4n a0d06c7
factor out ACLs into a separate MSC
ara4n b8e3a0b
include invite state notes
ara4n f8fb325
replace m.room.parent with m.space.parent for symmetry
ara4n 343e1f6
incorporate @joepie91's clarification on secret rooms
ara4n 97103c4
clarify that auto-joins are not force joins
ara4n 91fe7a7
switch to allowing multiple parents
ara4n b10856d
let's create spaces with `events_default` PL100
ara4n a0f89bd
add XXX about via propagation
ara4n a709671
tie break on multiple parents
ara4n ff85e61
fix dev identifier
ara4n 1cfe6bc
MSC1840 is out again.
richvdh bc14662
related MSCs
richvdh 62b9154
Remove lost footnotes
richvdh 469b64c
rip out m.room.description
richvdh dcb18f0
Move security consideration to MSC2962
richvdh 7d757ce
minor wording tweaks
richvdh acdb6f1
Move "auto-join" out to "future extensions"
richvdh 2e6d7d1
spaces are *primarily* referred to by their room ID.
richvdh 0bdbec2
Accept m.space.parent links if there is a reverse link
richvdh 6c9d469
add an issue about lost parent links
richvdh 8a61ce9
remove 'present' flag
richvdh c0c5138
Move "via" problem to a "potential issue"
richvdh 9ca9423
Suggested rooms
richvdh 5e7ed2b
Tweak wording about lexicographic ordering
richvdh 065b099
Update proposals/1772-groups-as-rooms.md
richvdh e704152
Include `create` in invite_room_state
richvdh 6d007e8
Defer a TODO to the future.
clokep 12d08ca
Consistency and update links.
clokep 00912f9
clarify how to deterministically cut cycles
ara4n f07e82e
clarify the charsets of our lexicographic orderings
ara4n 37e04f7
tiebreak ordered spaces sensibly
ara4n 1e2ed52
add more justification for immutable room types
ara4n 0d71150
remove confusing mention of peeking & dependent MSCs
ara4n 7432d25
incorporate travis feedback
ara4n 2981baa
Update proposals/1772-groups-as-rooms.md
ara4n acdf985
incorporate uhoreg feedback
ara4n 413e346
note the rationale behind using the # sigil
ara4n 757218c
relax requirements on cycle-cutting and link to valere's alg
ara4n c2d0d1e
include m.room.create in knock_state (will be overtaken by MSC3173)
ara4n 9773759
Remove cycle breaking algorithm to be specced in the future, if neces…
clokep File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,240 @@ | ||
# Proposal for Matrix "spaces" (formerly known as "groups as rooms (take 2)") | ||
richvdh marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
richvdh marked this conversation as resolved.
Show resolved
Hide resolved
|
||
This obsoletes [MSC1215](https://github.com/matrix-org/matrix-doc/issues/1215). | ||
richvdh marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
||
## Background and objectives | ||
|
||
Collecting rooms together into groups is useful for a number of | ||
purposes. Examples include: | ||
* Allowing users to discover different rooms related to a particular topic: | ||
for example "official matrix.org rooms". | ||
* Allowing administrators to manage permissions across a number of rooms: for | ||
example "a new employee has joined my company and needs access to all of our | ||
rooms". | ||
* Letting users classify their rooms: for example, separating "work" from | ||
"personal" rooms. | ||
|
||
We refer to such collections of rooms as "spaces". | ||
|
||
Synapse and Element-Web currently implement an unspecced "groups" API which | ||
attempts to provide this functionality (see | ||
[matrix-doc#1513](https://github.com/matrix-org/matrix-doc/issues/1513)). This | ||
API has some serious issues: | ||
* It is a large API surface to implement, maintain and spec - particularly for | ||
all the different clients out there. | ||
* Much of the API overlaps significantly with mechanisms we already have for | ||
managing rooms: | ||
* Tracking membership identity | ||
* Tracking membership hierarchy | ||
* Inviting/kicking/banning user | ||
* Tracking key/value metadata | ||
* There are membership management features which could benefit rooms which | ||
would also benefit groups and vice versa (e.g. "auditorium mode") | ||
* The current implementations on Riot Web/iOS/Android all suffer bugs and | ||
issues which have been solved previously for rooms. | ||
* no local-echo of invites | ||
* failures to set group avatars | ||
* ability to specify multiple admins | ||
* It doesn't support pushing updates to clients (particularly for flair | ||
membership): https://github.com/vector-im/riot-web/issues/5235 | ||
* It doesn't support third-party invites. | ||
* Groups could benefit from other features which already exist today for rooms | ||
* e.g. Room Directories | ||
* Groups are centralised, rather than being replicated across all | ||
participating servers. | ||
|
||
In this document, the existing implementation will be referred to as | ||
"`/r0/groups`". | ||
|
||
This proposal suggests a new approach where spaces are themselves represented | ||
by rooms, rather than a custom first-class entity. This requires few server | ||
changes, other than better support for peeking (see Dependencies below). The | ||
existing `/r0/groups` API would be deprecated in Synapse and remain | ||
unspecified. | ||
|
||
## Proposal | ||
richvdh marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
Each space is represented by its own room, known as a "space-room". The rooms | ||
within the space are determined by state events within the space-room. | ||
|
||
Spaces are referred to primarily by their alias, for example | ||
`#foo:matrix.org`. | ||
|
||
Space-rooms are distinguished from regular messaging rooms by the `m.room.type` | ||
ara4n marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
richvdh marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
richvdh marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
of `m.space` (see [MSC1840](https://github.com/matrix-org/matrix-doc/pull/1840)). | ||
|
||
We introduce an `m.space.child` state event type, which defines the rooms | ||
richvdh marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
within the space. The `state_key` is an alias for a child room, and `present: | ||
true` key is included to distinguish from a deleted state event. Something | ||
like: | ||
|
||
```json | ||
{ | ||
"type": "m.space.child", | ||
"state_key": "#room1:example.com", | ||
richvdh marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
"contents": { | ||
"present": true | ||
richvdh marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
} | ||
} | ||
|
||
{ | ||
"type": "m.space.child", | ||
"state_key": "#room2:example.com", | ||
"contents": { | ||
"present": true, | ||
"autojoin": true // TODO: what does this mean? | ||
} | ||
} | ||
|
||
// no longer a child room | ||
{ | ||
"type": "m.space.child", | ||
"state_key": "#oldroom:example.com", | ||
"contents": {} | ||
} | ||
``` | ||
|
||
Space-rooms may have `m.room.name` and `m.room.topic` state events in the same | ||
way as a normal room. | ||
ara4n marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
||
Normal messages within a space-room are discouraged (but not blocked by the | ||
server): user interfaces are not expected to have a way to enter or display | ||
ara4n marked this conversation as resolved.
Show resolved
Hide resolved
|
||
such messages. | ||
|
||
### Membership of spaces | ||
|
||
Users can be members of spaces (represented by `m.room.member` state events as | ||
normal). Depending on the configuration of the space (in particular whether | ||
`m.room.history_visibility` is set to `world_readable` or otherwise), | ||
membership of the space may be required to view the room list, membership list, | ||
etc. | ||
|
||
"Public" or "community" spaces would be set to `world_readable` to allow clients | ||
ara4n marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
to see the directory of rooms within the space by peeking into the space-room | ||
(thus avoiding the need to add `m.room.member` events to the event graph within | ||
the room). | ||
|
||
Join rules, invites and 3PID invites work as for a normal room. | ||
ara4n marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
||
### Long description | ||
|
||
We would like to allow groups to have a long description using rich | ||
formatting. This will use a new state event type `m.room.description` (with | ||
empty `state_key`) whose content is the same format as `m.room.message` (ie, | ||
contains a `msgtype` and possibly `formatted_body`). | ||
richvdh marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
||
TODO: this could also be done via pinned messages. Failing that | ||
`m.room.description` should probably be a separate MSC. | ||
richvdh marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
richvdh marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
||
### Inheritance of power-levels | ||
|
||
TODO | ||
|
||
### Automated joins/leaves | ||
|
||
TODO | ||
|
||
## Future extensions | ||
|
||
The following sections are not blocking parts of this proposal, but are | ||
included as a useful reference for how we imagine it will be extended in future. | ||
|
||
### Sub-spaces | ||
|
||
richvdh marked this conversation as resolved.
Show resolved
Hide resolved
|
||
Questions to be answered here include: | ||
|
||
* Should membership of a sub-space grant any particular access to the parent | ||
space, or vice-versa? We might need to extend `m.room.history_visibility` to | ||
support more flexibility; fortunately this is not involved in event auth so | ||
does not require new room versions. | ||
|
||
* What happens if somebody defines a cycle? (It's probably fine, but anything | ||
interpreting the relationships needs to be careful to limit recursion.) | ||
|
||
### Restricting access to the spaces membership list | ||
|
||
In the existing `/r0/groups` API, the group server has total control over the | ||
visibility of group membership, as seen by a given querying user. In other | ||
words, arbitrary users can see entirely different views of a group at the | ||
server's discretion. | ||
|
||
Whilst this is very powerful for mapping arbitrary organisational structures | ||
into Matrix, it may be overengineered. Instead, the common case is (we believe) | ||
a space where some users are publicly visible as members, and others are not. | ||
|
||
One way to of achieving this would be to create a separate space for the | ||
private members - e.g. have `#foo:matrix.org` and `#foo-private:matrix.org`. | ||
`#foo-private:matrix.org` is set up with `m.room.history_visibility` to not to | ||
allow peeking; you have to be joined to see the members. | ||
richvdh marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
ara4n marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
### Flair | ||
|
||
("Flair" is a term we use to describe a small badge which appears next to a | ||
user's displayname to advertise their membership of a space.) | ||
|
||
The flair image for a group is given by the room avatar. (In future it might | ||
preferable to use hand-crafted small resolution images: see | ||
[matrix-doc#1778](https://github.com/matrix-org/matrix-doc/issues/1778). | ||
|
||
One way this might be implemented is: | ||
|
||
* User publishes the spaces they wish to announce on their profile | ||
([MSC1769](https://github.com/matrix-org/matrix-doc/issues/1769) | ||
as an `m.flair` state event: it lists the spaces which they are advertising. | ||
|
||
* When a client wants to know the current flair for a set of users (i.e. | ||
those which it is currently displaying in the timeline), it peeks the | ||
profile rooms of those users. (Ideally there would be an API to support | ||
richvdh marked this conversation as resolved.
Show resolved
Hide resolved
|
||
peeking multiple rooms at once to facilitate this.) | ||
|
||
* The client must check that the user is *actually* a member of the advertised | ||
richvdh marked this conversation as resolved.
Show resolved
Hide resolved
|
||
spaces. Nominally it can do this by peeking the membership list of the | ||
space; however for efficiency we could expose a dedicated Client-Server API | ||
to do this check (and both servers and clients can cache the results fairly | ||
aggressively.) | ||
|
||
richvdh marked this conversation as resolved.
Show resolved
Hide resolved
|
||
## Dependencies | ||
richvdh marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
||
* [MSC1840](https://github.com/matrix-org/matrix-doc/pull/1840) for room | ||
types. | ||
|
||
* [MSC1776](https://github.com/matrix-org/matrix-doc/issues/1776) for | ||
effective peeking over the C/S API. | ||
|
||
* [MSC1777](https://github.com/matrix-org/matrix-doc/issues/1777) (or similar) | ||
for effective peeking over Federation. | ||
|
||
These dependencies are shared with profiles-as-rooms | ||
([MSC1769](https://github.com/matrix-org/matrix-doc/issues/1769)). | ||
|
||
## Security considerations | ||
|
||
* The peek server has significant power. TODO: expand. | ||
|
||
## Tradeoffs | ||
|
||
* If the membership of a space would be large (for example: an organisation of | ||
several thousand people), this membership has to copied entirely into the | ||
richvdh marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
room, rather than querying/searching incrementally. | ||
|
||
* If the membership list is based on an external service such as LDAP, it is | ||
hard to keep the space membership in sync with the LDAP directory. In | ||
practice, it might be possible to do so via a nightly "synchronisation" job | ||
which searches the LDAP directory, or via "AD auditing". | ||
|
||
* No allowance is made for exposing different 'views' of the membership list to | ||
different querying users. (It may be possible to simulate this behaviour | ||
using smaller spaces). | ||
|
||
## Unstable prefix | ||
|
||
While this proposal is not in a published version of the specification, | ||
implementations should use `org.matrix.msc1772` to represent the `m` | ||
namespace. For example, `m.space.child` becomes | ||
`org.matrix.msc1772.space.child`. | ||
|
||
|
||
## History | ||
|
||
* This replaces MSC1215: https://docs.google.com/document/d/1ZnAuA_zti-K2-RnheXII1F1-oyVziT4tJffdw1-SHrE | ||
* Other thoughts that led into this are at: https://docs.google.com/document/d/1hljmD-ytdCRL37t-D_LvGDA3a0_2MwowSPIiZRxcabs |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.