Merge 4ceec843a9 into be21886a73

changelogs/client_server/newsfragments/2311.feature

@@ -1 +0,0 @@
-`/_matrix/client/v3/rooms/{roomId}/report` and `/_matrix/client/v3/rooms/{roomId}/report/{eventId}` may respond with HTTP 200 regardless of the reported subject's existence or add a random delay when generating responses as per [MSC4277](https://github.com/matrix-org/matrix-spec-proposals/pull/4277).

changelogs/client_server/newsfragments/2311.removal

@@ -1 +0,0 @@
-The `score` request parameter on `/_matrix/client/v3/rooms/{roomId}/report/{eventId}` was removed as per [MSC4277](https://github.com/matrix-org/matrix-spec-proposals/pull/4277).

changelogs/internal/newsfragments/2323.clarification

@@ -1 +0,0 @@
-Render error code sections as definition lists to improve readability.

content/client-server-api/_index.md

@@ -94,50 +94,50 @@ request being made was invalid.
 These error codes can be returned by any API endpoint:
 
 `M_FORBIDDEN`
-: Forbidden access, e.g. joining a room without permission, failed login.
+Forbidden access, e.g. joining a room without permission, failed login.
 
 `M_UNKNOWN_TOKEN`
-: The access or refresh token specified was not recognised.
+The access or refresh token specified was not recognised.
 
-: An additional response parameter, `soft_logout`, might be present on the
+An additional response parameter, `soft_logout`, might be present on the
 response for 401 HTTP status codes. See [the soft logout
 section](#soft-logout) for more information.
 
 `M_MISSING_TOKEN`
-: No access token was specified for the request.
+No access token was specified for the request.
 
 `M_USER_LOCKED`
-: The account has been [locked](#account-locking) and cannot be used at this time.
+The account has been [locked](#account-locking) and cannot be used at this time.
 
 `M_USER_SUSPENDED`
-: The account has been [suspended](#account-suspension) and can only be used for
+The account has been [suspended](#account-suspension) and can only be used for
 limited actions at this time.
 
 `M_BAD_JSON`
-: Request contained valid JSON, but it was malformed in some way, e.g.
+Request contained valid JSON, but it was malformed in some way, e.g.
 missing required keys, invalid values for keys.
 
 `M_NOT_JSON`
-: Request did not contain valid JSON.
+Request did not contain valid JSON.
 
 `M_NOT_FOUND`
-: No resource was found for this request.
+No resource was found for this request.
 
 `M_LIMIT_EXCEEDED`
-: Too many requests have been sent in a short period of time. Wait a while
+Too many requests have been sent in a short period of time. Wait a while
 then try again. See [Rate limiting](#rate-limiting).
 
 `M_UNRECOGNIZED`
-: The server did not understand the request. This is expected to be returned with
+The server did not understand the request. This is expected to be returned with
 a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status
 code if the endpoint is implemented, but the incorrect HTTP method is used.
 
 `M_UNKNOWN_DEVICE`
-: {{% added-in v="1.17" %}} The device ID supplied by the application service does
+{{% added-in v="1.17" %}} The device ID supplied by the application service does
 not belong to the user ID during [identity assertion](/application-service-api/#identity-assertion).
 
 `M_RESOURCE_LIMIT_EXCEEDED`
-: The request cannot be completed because the homeserver has reached a
+The request cannot be completed because the homeserver has reached a
 resource limit imposed on it. For example, a homeserver held in a shared
 hosting environment may reach a resource limit if it starts using too
 much memory or disk space. The error MUST have an `admin_contact` field
@@ -148,7 +148,7 @@ only read state (e.g.: [`/sync`](#get_matrixclientv3sync),
 [`/user/{userId}/account_data/{type}`](#get_matrixclientv3useruseridaccount_datatype), etc).
 
 `M_UNKNOWN`
-: An unknown error has occurred.
+An unknown error has occurred.
 
 #### Other error codes
 
@@ -157,90 +157,90 @@ The following error codes are specific to certain endpoints.
 <!-- TODO: move them to the endpoints that return them -->
 
 `M_UNAUTHORIZED`
-: The request was not correctly authorized. Usually due to login failures.
+The request was not correctly authorized. Usually due to login failures.
 
 `M_USER_DEACTIVATED`
-: The user ID associated with the request has been deactivated. Typically
+The user ID associated with the request has been deactivated. Typically
 for endpoints that prove authentication, such as [`/login`](#get_matrixclientv3login).
 
 `M_USER_IN_USE`
-: Encountered when trying to register a user ID which has been taken.
+Encountered when trying to register a user ID which has been taken.
 
 `M_INVALID_USERNAME`
-: Encountered when trying to register a user ID which is not valid.
+Encountered when trying to register a user ID which is not valid.
 
 `M_ROOM_IN_USE`
-: Sent when the room alias given to the `createRoom` API is already in
+Sent when the room alias given to the `createRoom` API is already in
 use.
 
 `M_INVALID_ROOM_STATE`
-: Sent when the initial state given to the `createRoom` API is invalid.
+Sent when the initial state given to the `createRoom` API is invalid.
 
 `M_THREEPID_IN_USE`
-: Sent when a threepid given to an API cannot be used because the same
+Sent when a threepid given to an API cannot be used because the same
 threepid is already in use.
 
 `M_THREEPID_NOT_FOUND`
-: Sent when a threepid given to an API cannot be used because no record
+Sent when a threepid given to an API cannot be used because no record
 matching the threepid was found.
 
 `M_THREEPID_AUTH_FAILED`
-: Authentication could not be performed on the third-party identifier.
+Authentication could not be performed on the third-party identifier.
 
 `M_THREEPID_DENIED`
-: The server does not permit this third-party identifier. This may happen
+The server does not permit this third-party identifier. This may happen
 if the server only permits, for example, email addresses from a
 particular domain.
 
 `M_SERVER_NOT_TRUSTED`
-: The client's request used a third-party server, e.g. identity server,
+The client's request used a third-party server, e.g. identity server,
 that this server does not trust.
 
 `M_UNSUPPORTED_ROOM_VERSION`
-: The client's request to create a room used a room version that the
+The client's request to create a room used a room version that the
 server does not support.
 
 `M_INCOMPATIBLE_ROOM_VERSION`
-: The client attempted to join a room that has a version the server does
+The client attempted to join a room that has a version the server does
 not support. Inspect the `room_version` property of the error response
 for the room's version.
 
 `M_BAD_STATE`
-: The state change requested cannot be performed, such as attempting to
+The state change requested cannot be performed, such as attempting to
 unban a user who is not banned.
 
 `M_GUEST_ACCESS_FORBIDDEN`
-: The room or resource does not permit guests to access it.
+The room or resource does not permit guests to access it.
 
 `M_CAPTCHA_NEEDED`
-: A Captcha is required to complete the request.
+A Captcha is required to complete the request.
 
 `M_CAPTCHA_INVALID`
-: The Captcha provided did not match what was expected.
+The Captcha provided did not match what was expected.
 
 `M_MISSING_PARAM`
-: A required parameter was missing from the request.
+A required parameter was missing from the request.
 
 `M_INVALID_PARAM`
-: A parameter that was specified has the wrong value. For example, the
+A parameter that was specified has the wrong value. For example, the
 server expected an integer and instead received a string.
 
 `M_TOO_LARGE`
-: The request or entity was too large.
+The request or entity was too large.
 
 `M_EXCLUSIVE`
-: The resource being requested is reserved by an application service, or
+The resource being requested is reserved by an application service, or
 the application service making the request has not created the resource.
 
 `M_CANNOT_LEAVE_SERVER_NOTICE_ROOM`
-: The user is unable to reject an invite to join the server notices room.
+The user is unable to reject an invite to join the server notices room.
 See the [Server Notices](#server-notices) module for more information.
 
 `M_THREEPID_MEDIUM_NOT_SUPPORTED`
-: The homeserver does not support adding a third party identifier of the given medium.
+The homeserver does not support adding a third party identifier of the given medium.
 
 `M_THREEPID_IN_USE`
-: The third party identifier specified by the client is not acceptable because it is
+The third party identifier specified by the client is not acceptable because it is
 already in use in some way.
 
 #### Rate limiting

content/identity-service-api.md

@@ -71,53 +71,53 @@ the keys `error` and `errcode` MUST always be present.
 Some standard error codes are below:
 
 `M_NOT_FOUND`
-: The resource requested could not be located.
+The resource requested could not be located.
 
 `M_MISSING_PARAMS`
-: The request was missing one or more parameters.
+The request was missing one or more parameters.
 
 `M_INVALID_PARAM`
-: The request contained one or more invalid parameters.
+The request contained one or more invalid parameters.
 
 `M_SESSION_NOT_VALIDATED`
-: The session has not been validated.
+The session has not been validated.
 
 `M_NO_VALID_SESSION`
-: A session could not be located for the given parameters.
+A session could not be located for the given parameters.
 
 `M_SESSION_EXPIRED`
-: The session has expired and must be renewed.
+The session has expired and must be renewed.
 
 `M_INVALID_EMAIL`
-: The email address provided was not valid.
+The email address provided was not valid.
 
 `M_EMAIL_SEND_ERROR`
-: There was an error sending an email. Typically seen when attempting to
+There was an error sending an email. Typically seen when attempting to
 verify ownership of a given email address.
 
 `M_INVALID_ADDRESS`
-: The provided third-party address was not valid.
+The provided third-party address was not valid.
 
 `M_SEND_ERROR`
-: There was an error sending a notification. Typically seen when
+There was an error sending a notification. Typically seen when
 attempting to verify ownership of a given third-party address.
 
 `M_UNRECOGNIZED`
-: The request contained an unrecognised value, such as an unknown token or
+The request contained an unrecognised value, such as an unknown token or
 medium.
 
-: This is also used as the response if a server did not understand the request.
+This is also used as the response if a server did not understand the request.
 This is expected to be returned with a 404 HTTP status code if the endpoint is
 not implemented or a 405 HTTP status code if the endpoint is implemented, but
 the incorrect HTTP method is used.
 
 `M_THREEPID_IN_USE`
-: The third-party identifier is already in use by another user. Typically
+The third-party identifier is already in use by another user. Typically
 this error will have an additional `mxid` property to indicate who owns
 the third-party identifier.
 
 `M_UNKNOWN`
-: An unknown error has occurred.
+An unknown error has occurred.
 
 ## Privacy
 

data/api/client-server/report_content.yaml

@@ -25,15 +25,6 @@ paths:
         the appropriate people. How such information is delivered is left up to
         implementations. The caller is not required to be joined to the room to
         report it.
-
-        Clients could infer whether a reported room exists based on the 404 response.
-        Homeservers that wish to conceal this information MAY return 200 responses
-        regardless of the existence of the reported room.
-
-        Furthermore, it might be possible for clients to deduce whether a reported
-        room exists by timing the response. This is because only a report for an
-        existing room will require the homeserver to do further processing. To
-        combat this, homeservers MAY add a random delay when generating a response.
       operationId: reportRoom
       parameters:
         - in: path
@@ -61,11 +52,6 @@ paths:
       security:
         - accessTokenQuery: []
         - accessTokenBearer: []
-      x-changedInMatrixVersion:
-        1.18: |
-          Servers MAY prevent room ID enumeration by using the 200 response
-          regardless of the existence of the reported room and/or by adding
-          a random delay when generating responses.
       responses:
         "200":
           description: The room has been reported successfully.
@@ -105,10 +91,6 @@ paths:
         the appropriate people. The caller must be joined to the room to report
         it.
 
-        Clients could infer whether a reported event or room exists based on the 404
-        response. Homeservers that wish to conceal this information MAY return 200
-        responses regardless of the existence of the reported event or room.
-
         Furthermore, it might be possible for clients to deduce whether a reported
         event exists by timing the response. This is because only a report for an
         existing event will require the homeserver to do further processing. To
@@ -135,9 +117,15 @@ paths:
             schema:
               type: object
               example: {
+                "score": -100,
                 "reason": "this makes me sad"
               }
               properties:
+                score:
+                  type: integer
+                  description: |-
+                    The score to rate this content as where -100 is most offensive
+                    and 0 is inoffensive.
                 reason:
                   type: string
                   description: The reason the content is being reported.
@@ -148,10 +136,6 @@ paths:
       x-changedInMatrixVersion:
         1.8: |
           This endpoint now requires the user to be joined to the room.
-        1.18: |
-          The `score` request parameter was removed. Additionally, servers
-          may prevent event/room ID enumeration by using the 200 response
-          regardless of the existence of the reported event/room.
       responses:
         "200":
           description: The event has been reported successfully.