Skip to content
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.

Sign up for GitHub

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

Require explicit un-banning #264

Merged
merged 1 commit into from
Jan 15, 2016
Merged

Require explicit un-banning #264

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 53 additions & 1 deletion api/client-server/banning.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ paths:
description: |-
Ban a user in the room. If the user is currently in the room, also kick them.

When a user is banned from a room, they may not join it until they are unbanned.
When a user is banned from a room, they may not join it or be invited to it until they are unbanned.

The caller must have the required power level in order to perform this operation.
security:
Expand Down Expand Up @@ -76,3 +76,55 @@ paths:
}
tags:
- Room membership
"/rooms/{roomId}/unban":
post:
summary: Unban a user from the room.
description: |-
Unban a user from the room. This allows them to be invited to the room,
and join if they would otherwise be allowed to join according to its join rules.

The caller must have the required power level in order to perform this operation.
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room identifier (not alias) from which the user should be unbanned.
required: true
x-example: "!e42d8c:matrix.org"
- in: body
name: body
required: true
schema:
type: object
example: |-
{
"user_id": "@cheeky_monkey:matrix.org"
}
properties:
user_id:
type: string
description: The fully qualified user ID of the user being unbanned.
required: ["user_id"]
responses:
200:
description: The user has been unbanned from the room.
examples:
application/json: |-
{}
schema:
type: object
403:
description: |-
You do not have permission to unban the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:

- The unbanner's power level is insufficient to unban users from the room.
examples:
application/json: |-
{
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to unban from this room."
}
tags:
- Room membership
77 changes: 77 additions & 0 deletions api/client-server/kicking.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
swagger: '2.0'
info:
title: "Matrix Client-Server Room Kicking API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
- application/json
securityDefinitions:
accessToken:
type: apiKey
description: The user_id or application service access_token
name: access_token
in: query
paths:
"/rooms/{roomId}/kick":
post:
summary: Kick a user from the room.
description: |-
Kick a user from the room.

The caller must have the required power level in order to perform this operation.
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room identifier (not alias) from which the user should be kicked.
required: true
x-example: "!e42d8c:matrix.org"
- in: body
name: body
required: true
schema:
type: object
example: |-
{
"reason": "Telling unfunny jokes",
"user_id": "@cheeky_monkey:matrix.org"
}
properties:
user_id:
type: string
description: The fully qualified user ID of the user being kicked.
reason:
type: string
description: The reason the user has been kicked.
required: ["user_id"]
responses:
200:
description: The user has been kicked from the room.
examples:
application/json: |-
{}
schema:
type: object
403:
description: |-
You do not have permission to kick the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:

- The kicker is not currently in the room.
- The kickee is not currently in the room.
- The kicker's power level is insufficient to kick users from the room.
examples:
application/json: |-
{
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to kick from this room."
}
tags:
- Room membership
41 changes: 39 additions & 2 deletions specification/client_server_api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -914,10 +914,42 @@ following values:
``invite``
This room can only be joined if you were invited.

The allowable state transitions of membership are::

/ban
+------------------------------------------------------+
| |
| +----------------+ +----------------+ |
| | /leave | | | |
| | v v | |
/invite +--------+ +-------+ | |
------------>| invite |<----------| leave |----+ | |
+--------+ /invite +-------+ | | |
| | ^ | | |
| | | | | |
/join | +---------------+ | | | |
| | /join if | | | |
| | join_rules | | /ban | /unban |
| | public /leave | | | |
v v or | | | |
+------+ /kick | | | |
------------>| join |-------------------+ | | |
/join +------+ v | |
if | +-----+ | |
join_rules +-------------------------->| ban |-----+ |
public /ban +-----+ |
^ ^ |
| | |
----------------------------------------------+ +----------------------+
/ban
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like your graph, but I'm confused by it. So I like it less. I dislike how you combine arrows into one (e.g. START /ban BAN and INVITE /ban BAN transitions. I dislike them because it when you're following the arrow with your eye and it forks, you don't know which fork is the one you should go down until you get to the end and do not see an arrowhead. This makes reading this graph slow at best, misleading at worst. I almost posted a line comment saying "What the hell does the transition INVITE /leave /unban BAN mean?!" until I realised the lack of arrowheads. Please don't merge them like this. There is enough room to not do this.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done



{{inviting_http_api}}

{{joining_http_api}}

{{kicking_http_api}}

{{banning_http_api}}

Leaving rooms
Expand Down Expand Up @@ -947,8 +979,7 @@ to |/rooms/<room_id>/ban|_ with::
"reason": "string: <reason for the ban>"
}

Banning a user adjusts the banned member's membership state to ``ban`` and
adjusts the power level of this event to a level higher than the banned person.
Banning a user adjusts the banned member's membership state to ``ban``.
Like with other membership changes, a user can directly adjust the target
member's state, by making a request to
``/rooms/<room id>/state/m.room.member/<user id>``::
Expand All @@ -957,6 +988,9 @@ member's state, by making a request to
"membership": "ban"
}

A user must be explicitly unbanned with a request to |/rooms/<room_id>/unban|_
before they can re-join the room or be re-invited.

Listing rooms
~~~~~~~~~~~~~

Expand Down Expand Up @@ -1048,3 +1082,6 @@ have to wait in milliseconds before they can try again.
.. |/rooms/<room_id>/ban| replace:: ``/rooms/<room_id>/ban``
.. _/rooms/<room_id>/ban: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-ban

.. |/rooms/<room_id>/unban| replace:: ``/rooms/<room_id>/unban``
.. _/rooms/<room_id>/unban: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-unban