From 4c22eb86b50d1fb6bd28d98d9c29037aba2b2cac Mon Sep 17 00:00:00 2001 From: "Olivier Wilkinson (reivilibre)" Date: Mon, 29 Jul 2019 16:30:25 +0100 Subject: [PATCH 1/8] MSC for Search Filtering in Federation /publicRooms Signed-off-by: Olivier Wilkinson (reivilibre) --- ...search_filter_in_federation_publicrooms.md | 108 ++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 proposals/2197-search_filter_in_federation_publicrooms.md diff --git a/proposals/2197-search_filter_in_federation_publicrooms.md b/proposals/2197-search_filter_in_federation_publicrooms.md new file mode 100644 index 00000000000..60d3533395f --- /dev/null +++ b/proposals/2197-search_filter_in_federation_publicrooms.md @@ -0,0 +1,108 @@ +# MSC2197 – Search Filtering in Public Room Directory over Federation + +This MSC proposes introducing the `POST` method to the `/publicRooms` Federation API endpoint, +including a `filter` argument which allows server-side filtering of rooms. + +We are motivated by the opportunity to make searching the public Room Directory more efficient over +Federation. + +## Motivation + +Although the Client-Server API includes the filtering capability in `/publicRooms`, the Federation API +currently does not. + +This leads to a situation that is wasteful of effort and network traffic for both homeservers; searching +a remote server involves first downloading its entire room list and then filtering afterwards. + +## Proposal + +Having a filtered `/publicRooms` API endpoint means that irrelevant or uninteresting rooms can be +excluded from a room directory query response. In turn, this means that these room directory query +responses can be generated more quickly and then, due to their smaller size, transmitted over the network more quickly, owing to their +smaller size. + +These benefits have been exploited in the Client-Server API, which implements search filtering +using the `filter` JSON body parameter in the `POST` method on the `/publicRooms` endpoint. + +It should be noted that the Client-Server and Federation APIs both currently possess `/publicRooms` +endpoints which, whilst similar, are not equivalent. + +Ignoring the `server` parameter in the Client-Server API, the following specific differences are +noticed: + +* the Federation API endpoint only accepts the `GET` method whereas the Client-Server API accepts + the `POST` method as well. +* the Federation API accepts `third_party_instance_id` and `include_all_networks` parameters through + the `GET` method, whereas the Client-Server API only features these in the `POST` method. + +This MSC proposes to introduce support for the `POST` method in the Federation API's `/publicRooms` +endpoint, with all but one of the parameters from that of the Client-Server API. The copied parameters +shall have the same semantics as they do in the Client-Server API. + +In the interest of clarity, the proposed parameter set is listed below, along with a repetition of the +definitions of used substructures. The response format has been omitted as it is the same as that of +the current Client-Server and Federation APIs, which do not differ in this respect. + +### `POST /_matrix/federation/v1/publicRooms` + +#### Query Parameters + +There are no query parameters. Notably, we intentionally do not inherit the `server` query parameter +from the Client-Server API. + +#### JSON Body Parameters + +* `limit` (`integer`): Limit the number of search results returned. +* `since` (`string`): A pagination token from a previous request, allowing clients to get the next (or previous) batch of rooms. The direction of pagination is specified solely by which token is supplied, rather than via an explicit flag. +* `filter` (`Filter`): Filter to apply to the results. +* `include_all_networks` (`boolean`): Whether or not to include all known networks/protocols from application services on the homeserver. Defaults to false. +* `third_party_instance_id` (`boolean`): The specific third party network/protocol to request from the homeserver. Can only be used if `include_all_networks` is false. + +### `Filter` Parameters + +* `generic_search_term` (`string`): A string to search for in the room metadata, e.g. name, topic, canonical alias etc. (Optional). + +## Tradeoffs + +An alternative approach might be for implementations to carry on as they are but also +cache (and potentially index) remote homeservers' room directories. This would not require +a spec change. + +However, this would be unsatisfactory because it would lead to outdated room directory results and/or +caches that provide no benefit (as room directory searches are generally infrequent enough that a cache +would be outdated before being reused, on small – if not most – homeservers). + +## Potential issues + +### Backwards Compatibility + +After this proposal is implemented, outdated homeservers will still exist which do not support the room +filtering functionality specified in this MSC. In this case, homeservers will have to fall-back to downloading +the entire room directory and performing the filtering themselves, as currently happens. This is not considered +a problem since it will not lead to a situation that is any worse than the current one, and it is expected that +large homeservers – which cause the most work with the current search implementations – would be quick to upgrade +to support this feature once it is available. + +In addition, as the `POST` method was not previously accepted on the `/publicRooms` endpoint over federation, +then it is not a difficult task to use a `405 Method Not Allowed` HTTP response as a signal that fallback is required. + +## Security considerations + +There are no known security considerations. + +## Privacy considerations + +At current, remote homeservers do not learn about what a user has searched for. + +However, under this proposal, in the context of using the Federation API to forward on queries from the Client-Server +API, a client's homeserver would end up sharing the client's search terms with a remote homeserver, which may not be +operated by the same party or even trusted. For example, users' search terms could be logged. + +It is uncertain, to the author of this MSC, what implications this has with regards to legislation, such as GDPR. + +## Conclusion + +By allowing homeservers to pass on search filters, we enable remote homeservers' room directories to be +efficiently searched, because, realistically speaking, only the remote homeserver is in a position to be +able to perform search efficiently, by taking advantage of indexing and other such optimisations. + From 36e43ee32620e6936cfe7d758f6f94390e2929b6 Mon Sep 17 00:00:00 2001 From: "Olivier Wilkinson (reivilibre)" Date: Thu, 1 Aug 2019 09:28:30 +0100 Subject: [PATCH 2/8] Rewrap lines in MSC2917 to 80 chars wide Signed-off-by: Olivier Wilkinson (reivilibre) --- ...search_filter_in_federation_publicrooms.md | 133 ++++++++++-------- 1 file changed, 78 insertions(+), 55 deletions(-) diff --git a/proposals/2197-search_filter_in_federation_publicrooms.md b/proposals/2197-search_filter_in_federation_publicrooms.md index 60d3533395f..04413c869d5 100644 --- a/proposals/2197-search_filter_in_federation_publicrooms.md +++ b/proposals/2197-search_filter_in_federation_publicrooms.md @@ -1,90 +1,109 @@ # MSC2197 – Search Filtering in Public Room Directory over Federation -This MSC proposes introducing the `POST` method to the `/publicRooms` Federation API endpoint, -including a `filter` argument which allows server-side filtering of rooms. +This MSC proposes introducing the `POST` method to the `/publicRooms` Federation +API endpoint, including a `filter` argument which allows server-side filtering +of rooms. -We are motivated by the opportunity to make searching the public Room Directory more efficient over -Federation. +We are motivated by the opportunity to make searching the public Room Directory +more efficient over Federation. ## Motivation -Although the Client-Server API includes the filtering capability in `/publicRooms`, the Federation API -currently does not. +Although the Client-Server API includes the filtering capability in +`/publicRooms`, the Federation API currently does not. -This leads to a situation that is wasteful of effort and network traffic for both homeservers; searching -a remote server involves first downloading its entire room list and then filtering afterwards. +This leads to a situation that is wasteful of effort and network traffic for +both homeservers; searching a remote server involves first downloading its +entire room list and then filtering afterwards. ## Proposal -Having a filtered `/publicRooms` API endpoint means that irrelevant or uninteresting rooms can be -excluded from a room directory query response. In turn, this means that these room directory query -responses can be generated more quickly and then, due to their smaller size, transmitted over the network more quickly, owing to their -smaller size. +Having a filtered `/publicRooms` API endpoint means that irrelevant or +uninteresting rooms can be excluded from a room directory query response. +In turn, this means that these room directory query responses can be generated +more quickly and then, due to their smaller size, transmitted over the network +more quickly, owing to their smaller size. -These benefits have been exploited in the Client-Server API, which implements search filtering -using the `filter` JSON body parameter in the `POST` method on the `/publicRooms` endpoint. +These benefits have been exploited in the Client-Server API, which implements +search filtering using the `filter` JSON body parameter in the `POST` method on +the `/publicRooms` endpoint. -It should be noted that the Client-Server and Federation APIs both currently possess `/publicRooms` -endpoints which, whilst similar, are not equivalent. +It should be noted that the Client-Server and Federation APIs both currently +possess `/publicRooms` endpoints which, whilst similar, are not equivalent. -Ignoring the `server` parameter in the Client-Server API, the following specific differences are -noticed: +Ignoring the `server` parameter in the Client-Server API, the following specific +differences are noticed: -* the Federation API endpoint only accepts the `GET` method whereas the Client-Server API accepts - the `POST` method as well. -* the Federation API accepts `third_party_instance_id` and `include_all_networks` parameters through - the `GET` method, whereas the Client-Server API only features these in the `POST` method. +* the Federation API endpoint only accepts the `GET` method whereas the + Client-Server API accepts the `POST` method as well. +* the Federation API accepts `third_party_instance_id` and + `include_all_networks` parameters through the `GET` method, whereas the + Client-Server API only features these in the `POST` method. -This MSC proposes to introduce support for the `POST` method in the Federation API's `/publicRooms` -endpoint, with all but one of the parameters from that of the Client-Server API. The copied parameters -shall have the same semantics as they do in the Client-Server API. +This MSC proposes to introduce support for the `POST` method in the Federation +API's `/publicRooms` endpoint, with all but one of the parameters from that of +the Client-Server API. The copied parameters shall have the same semantics as +they do in the Client-Server API. -In the interest of clarity, the proposed parameter set is listed below, along with a repetition of the -definitions of used substructures. The response format has been omitted as it is the same as that of -the current Client-Server and Federation APIs, which do not differ in this respect. +In the interest of clarity, the proposed parameter set is listed below, along +with a repetition of the definitions of used substructures. The response format +has been omitted as it is the same as that of the current Client-Server and +Federation APIs, which do not differ in this respect. ### `POST /_matrix/federation/v1/publicRooms` #### Query Parameters -There are no query parameters. Notably, we intentionally do not inherit the `server` query parameter -from the Client-Server API. +There are no query parameters. Notably, we intentionally do not inherit the +`server` query parameter from the Client-Server API. #### JSON Body Parameters * `limit` (`integer`): Limit the number of search results returned. -* `since` (`string`): A pagination token from a previous request, allowing clients to get the next (or previous) batch of rooms. The direction of pagination is specified solely by which token is supplied, rather than via an explicit flag. +* `since` (`string`): A pagination token from a previous request, allowing + clients to get the next (or previous) batch of rooms. The direction of + pagination is specified solely by which token is supplied, rather than via an + explicit flag. * `filter` (`Filter`): Filter to apply to the results. -* `include_all_networks` (`boolean`): Whether or not to include all known networks/protocols from application services on the homeserver. Defaults to false. -* `third_party_instance_id` (`boolean`): The specific third party network/protocol to request from the homeserver. Can only be used if `include_all_networks` is false. +* `include_all_networks` (`boolean`): Whether or not to include all known + networks/protocols from application services on the homeserver. + Defaults to false. +* `third_party_instance_id` (`boolean`): The specific third party + network/protocol to request from the homeserver. + Can only be used if `include_all_networks` is false. ### `Filter` Parameters -* `generic_search_term` (`string`): A string to search for in the room metadata, e.g. name, topic, canonical alias etc. (Optional). +* `generic_search_term` (`string`): A string to search for in the room metadata, +e.g. name, topic, canonical alias etc. (Optional). ## Tradeoffs -An alternative approach might be for implementations to carry on as they are but also -cache (and potentially index) remote homeservers' room directories. This would not require -a spec change. +An alternative approach might be for implementations to carry on as they are but +also cache (and potentially index) remote homeservers' room directories. +This would not require a spec change. -However, this would be unsatisfactory because it would lead to outdated room directory results and/or -caches that provide no benefit (as room directory searches are generally infrequent enough that a cache -would be outdated before being reused, on small – if not most – homeservers). +However, this would be unsatisfactory because it would lead to outdated room +directory results and/or caches that provide no benefit (as room directory +searches are generally infrequent enough that a cache would be outdated before +being reused, on small – if not most – homeservers). ## Potential issues ### Backwards Compatibility -After this proposal is implemented, outdated homeservers will still exist which do not support the room -filtering functionality specified in this MSC. In this case, homeservers will have to fall-back to downloading -the entire room directory and performing the filtering themselves, as currently happens. This is not considered -a problem since it will not lead to a situation that is any worse than the current one, and it is expected that -large homeservers – which cause the most work with the current search implementations – would be quick to upgrade -to support this feature once it is available. +After this proposal is implemented, outdated homeservers will still exist which +do not support the room filtering functionality specified in this MSC. In this +case, homeservers will have to fall-back to downloading the entire room +directory and performing the filtering themselves, as currently happens. +This is not considered a problem since it will not lead to a situation that is +any worse than the current one, and it is expected that large homeservers +– which cause the most work with the current search implementations – +would be quick to upgrade to support this feature once it is available. -In addition, as the `POST` method was not previously accepted on the `/publicRooms` endpoint over federation, -then it is not a difficult task to use a `405 Method Not Allowed` HTTP response as a signal that fallback is required. +In addition, as the `POST` method was not previously accepted on the +`/publicRooms` endpoint over federation, then it is not a difficult task to use +a `405 Method Not Allowed` HTTP response as a signal that fallback is required. ## Security considerations @@ -94,15 +113,19 @@ There are no known security considerations. At current, remote homeservers do not learn about what a user has searched for. -However, under this proposal, in the context of using the Federation API to forward on queries from the Client-Server -API, a client's homeserver would end up sharing the client's search terms with a remote homeserver, which may not be -operated by the same party or even trusted. For example, users' search terms could be logged. +However, under this proposal, in the context of using the Federation API to +forward on queries from the Client-Server API, a client's homeserver would end +up sharing the client's search terms with a remote homeserver, which may not be +operated by the same party or even trusted. For example, users' search terms +could be logged. -It is uncertain, to the author of this MSC, what implications this has with regards to legislation, such as GDPR. +It is uncertain, to the author of this MSC, what implications this has with +regards to legislation, such as GDPR. ## Conclusion -By allowing homeservers to pass on search filters, we enable remote homeservers' room directories to be -efficiently searched, because, realistically speaking, only the remote homeserver is in a position to be -able to perform search efficiently, by taking advantage of indexing and other such optimisations. +By allowing homeservers to pass on search filters, we enable remote homeservers' +room directories to be efficiently searched, because, realistically speaking, +only the remote homeserver is in a position to be able to perform search +efficiently, by taking advantage of indexing and other such optimisations. From 493bb062afb1eef49c9282cc1162e72a022f2ff1 Mon Sep 17 00:00:00 2001 From: "Olivier Wilkinson (reivilibre)" Date: Mon, 5 Aug 2019 09:50:24 +0100 Subject: [PATCH 3/8] MSC2197: update with privacy perspective Includes recommendations for client developers. Signed-off-by: Olivier Wilkinson (reivilibre) --- ...search_filter_in_federation_publicrooms.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/proposals/2197-search_filter_in_federation_publicrooms.md b/proposals/2197-search_filter_in_federation_publicrooms.md index 04413c869d5..bc1a74a9302 100644 --- a/proposals/2197-search_filter_in_federation_publicrooms.md +++ b/proposals/2197-search_filter_in_federation_publicrooms.md @@ -119,8 +119,23 @@ up sharing the client's search terms with a remote homeserver, which may not be operated by the same party or even trusted. For example, users' search terms could be logged. -It is uncertain, to the author of this MSC, what implications this has with -regards to legislation, such as GDPR. +The privacy implications of this proposal are not overly major, as the data +that's being shared is [\[1\]][1]: + +- only covered by GDPR if: + - the search terms contain personal data, or + - the user's homeserver IP address is uniquely identifying (because it's a + single-person homeserver, perhaps) +- likely to be *expected* to be shared with the remote homeserver + +[1]: https://github.com/matrix-org/matrix-doc/pull/2197#issuecomment-517641751 + +For the sake of clarity, clients SHOULD display a warning that a remote search +will take the user's data outside the jurisdiction of their own homeserver, +before using the `server` parameter of the Client-Server API `/publicRooms`, as +it can be assumed that this will lead to the server invoking the Federation +API's `/publicRooms` – on the specified remote server – with the user's search +terms. ## Conclusion From 60cbc4567b62a50f2c10b84525be0efb0452aa3e Mon Sep 17 00:00:00 2001 From: "Olivier Wilkinson (reivilibre)" Date: Fri, 9 Aug 2019 11:21:39 +0100 Subject: [PATCH 4/8] Addresses some of Andrew's comments Signed-off-by: Olivier Wilkinson (reivilibre) --- ...search_filter_in_federation_publicrooms.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/proposals/2197-search_filter_in_federation_publicrooms.md b/proposals/2197-search_filter_in_federation_publicrooms.md index bc1a74a9302..3ac9f3c4123 100644 --- a/proposals/2197-search_filter_in_federation_publicrooms.md +++ b/proposals/2197-search_filter_in_federation_publicrooms.md @@ -22,17 +22,15 @@ Having a filtered `/publicRooms` API endpoint means that irrelevant or uninteresting rooms can be excluded from a room directory query response. In turn, this means that these room directory query responses can be generated more quickly and then, due to their smaller size, transmitted over the network -more quickly, owing to their smaller size. +more quickly. These benefits have been exploited in the Client-Server API, which implements search filtering using the `filter` JSON body parameter in the `POST` method on the `/publicRooms` endpoint. -It should be noted that the Client-Server and Federation APIs both currently -possess `/publicRooms` endpoints which, whilst similar, are not equivalent. - Ignoring the `server` parameter in the Client-Server API, the following specific -differences are noticed: +differences are noticed between the Client-Server and Federation API's +`/publicRooms` endpoints: * the Federation API endpoint only accepts the `GET` method whereas the Client-Server API accepts the `POST` method as well. @@ -42,7 +40,13 @@ differences are noticed: This MSC proposes to introduce support for the `POST` method in the Federation API's `/publicRooms` endpoint, with all but one of the parameters from that of -the Client-Server API. The copied parameters shall have the same semantics as +the Client-Server API. + +The parameter that is intentionally omitted is the `server` query parameter, as +it does not make sense to include it – the requesting homeserver could make a +direct request instead of requesting that a request be relayed. + +The parameters which are copied, however, shall have the same semantics as they do in the Client-Server API. In the interest of clarity, the proposed parameter set is listed below, along @@ -103,7 +107,8 @@ would be quick to upgrade to support this feature once it is available. In addition, as the `POST` method was not previously accepted on the `/publicRooms` endpoint over federation, then it is not a difficult task to use -a `405 Method Not Allowed` HTTP response as a signal that fallback is required. +an `M_UNRECOGNIZED` standard error response `errcode` as a signal that fallback +is required. ## Security considerations From 97f856d70650afdd3e3934e7c4b9780396a40b9b Mon Sep 17 00:00:00 2001 From: "Olivier Wilkinson (reivilibre)" Date: Wed, 14 Aug 2019 11:00:03 +0100 Subject: [PATCH 5/8] Domain name is potentially personally-identifying Thanks to @turt2live Signed-off-by: Olivier Wilkinson (reivilibre) --- proposals/2197-search_filter_in_federation_publicrooms.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2197-search_filter_in_federation_publicrooms.md b/proposals/2197-search_filter_in_federation_publicrooms.md index 3ac9f3c4123..37e3fe7d6ae 100644 --- a/proposals/2197-search_filter_in_federation_publicrooms.md +++ b/proposals/2197-search_filter_in_federation_publicrooms.md @@ -129,8 +129,8 @@ that's being shared is [\[1\]][1]: - only covered by GDPR if: - the search terms contain personal data, or - - the user's homeserver IP address is uniquely identifying (because it's a - single-person homeserver, perhaps) + - the user's homeserver IP address or domain name is uniquely identifying + (because it's a single-person homeserver, perhaps) - likely to be *expected* to be shared with the remote homeserver [1]: https://github.com/matrix-org/matrix-doc/pull/2197#issuecomment-517641751 From 7e85b9d56afb78b8cfd867db30db7d6b70f007d6 Mon Sep 17 00:00:00 2001 From: "Olivier Wilkinson (reivilibre)" Date: Wed, 14 Aug 2019 11:03:55 +0100 Subject: [PATCH 6/8] Acknowledge other potential error responses for fallback Signed-off-by: Olivier Wilkinson (reivilibre) --- .../2197-search_filter_in_federation_publicrooms.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/proposals/2197-search_filter_in_federation_publicrooms.md b/proposals/2197-search_filter_in_federation_publicrooms.md index 37e3fe7d6ae..5d1ae7c1cf4 100644 --- a/proposals/2197-search_filter_in_federation_publicrooms.md +++ b/proposals/2197-search_filter_in_federation_publicrooms.md @@ -106,9 +106,14 @@ any worse than the current one, and it is expected that large homeservers would be quick to upgrade to support this feature once it is available. In addition, as the `POST` method was not previously accepted on the -`/publicRooms` endpoint over federation, then it is not a difficult task to use -an `M_UNRECOGNIZED` standard error response `errcode` as a signal that fallback -is required. +`/publicRooms` endpoint over federation, then it is possible to fall back to the +old behaviour, if one of the following errors is encountered: + +- an `M_UNRECOGNIZED` standard error response `errcode` (this is what would be + typically expected in this situation) +- an `M_NOT_FOUND` standard error response +- a `404 Not Found` HTTP error response +- a `405 Method Not Allowed` HTTP error response ## Security considerations From 4219e272ec5382a7ac0992bc43b9717a72f25ddb Mon Sep 17 00:00:00 2001 From: "Olivier Wilkinson (reivilibre)" Date: Wed, 14 Aug 2019 11:06:45 +0100 Subject: [PATCH 7/8] Drop the hard SHOULD Adopts @turt2live's phrasing Signed-off-by: Olivier Wilkinson (reivilibre) --- .../2197-search_filter_in_federation_publicrooms.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/proposals/2197-search_filter_in_federation_publicrooms.md b/proposals/2197-search_filter_in_federation_publicrooms.md index 5d1ae7c1cf4..b3ce3dc3701 100644 --- a/proposals/2197-search_filter_in_federation_publicrooms.md +++ b/proposals/2197-search_filter_in_federation_publicrooms.md @@ -140,12 +140,12 @@ that's being shared is [\[1\]][1]: [1]: https://github.com/matrix-org/matrix-doc/pull/2197#issuecomment-517641751 -For the sake of clarity, clients SHOULD display a warning that a remote search -will take the user's data outside the jurisdiction of their own homeserver, -before using the `server` parameter of the Client-Server API `/publicRooms`, as -it can be assumed that this will lead to the server invoking the Federation -API's `/publicRooms` – on the specified remote server – with the user's search -terms. +For the sake of clarity, clients are strongly encouraged to display a warning +that a remote search will take the user's data outside the jurisdiction of their +own homeserver, before using the `server` parameter of the Client-Server API +`/publicRooms`, as it can be assumed that this will lead to the server invoking +the Federation API's `/publicRooms` – on the specified remote server – with the +user's search terms. ## Conclusion From 76f9196ff39a00c25423582a215c7017f3c9dc8a Mon Sep 17 00:00:00 2001 From: "Olivier Wilkinson (reivilibre)" Date: Mon, 19 Aug 2019 07:44:37 +0100 Subject: [PATCH 8/8] Address @richvdh's comments --- ...search_filter_in_federation_publicrooms.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/proposals/2197-search_filter_in_federation_publicrooms.md b/proposals/2197-search_filter_in_federation_publicrooms.md index b3ce3dc3701..ef1521d18a0 100644 --- a/proposals/2197-search_filter_in_federation_publicrooms.md +++ b/proposals/2197-search_filter_in_federation_publicrooms.md @@ -24,7 +24,7 @@ In turn, this means that these room directory query responses can be generated more quickly and then, due to their smaller size, transmitted over the network more quickly. -These benefits have been exploited in the Client-Server API, which implements +These benefits have been utilised in the Client-Server API, which implements search filtering using the `filter` JSON body parameter in the `POST` method on the `/publicRooms` endpoint. @@ -105,15 +105,14 @@ any worse than the current one, and it is expected that large homeservers – which cause the most work with the current search implementations – would be quick to upgrade to support this feature once it is available. -In addition, as the `POST` method was not previously accepted on the -`/publicRooms` endpoint over federation, then it is possible to fall back to the -old behaviour, if one of the following errors is encountered: +As the `POST` method was not previously accepted on the `/publicRooms` endpoint +over federation, then requesting servers should fall back to the old behaviour, +if one of the following errors is encountered: -- an `M_UNRECOGNIZED` standard error response `errcode` (this is what would be - typically expected in this situation) -- an `M_NOT_FOUND` standard error response -- a `404 Not Found` HTTP error response -- a `405 Method Not Allowed` HTTP error response +- an HTTP `400` response with an `M_UNRECOGNIZED` standard error response + `errcode` (this is what would be typically expected in this situation) +- a `404` (Not Found) HTTP error response +- a `405` (Method Not Allowed) HTTP error response ## Security considerations @@ -121,7 +120,7 @@ There are no known security considerations. ## Privacy considerations -At current, remote homeservers do not learn about what a user has searched for. +At present, remote homeservers do not learn about what a user has searched for. However, under this proposal, in the context of using the Federation API to forward on queries from the Client-Server API, a client's homeserver would end