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.

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

Spec for MSC3981 #1746

Merged
merged 11 commits into from
Mar 19, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
1 change: 1 addition & 0 deletions changelogs/client_server/newsfragments/1746.feature
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Add support for recursion on the /relations endpoints (MSC3981).
Copy link
Member

Choose a reason for hiding this comment

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

I've applied the change to main as part of release checklist steps, but for future PRs please use a consistent changelog style (and apologies if these aren't documented anywhere - we should fix that if undocumented).

  • Use backticks around endpoints, and indicate the request method.
  • Use , as per [MSC3981](...). at the end of your changelog, linking to the MSC in question.
Add support for recursion on the `GET /relations` endpoints, as per [MSC3981](https://github.com/matrix-org/matrix-spec-proposals/pull/3981).

13 changes: 13 additions & 0 deletions content/client-server-api/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2156,6 +2156,19 @@ following endpoint.
This endpoint is particularly useful if the client has lost context on the aggregation for
a parent event and needs to rebuild/verify it.

When using the `recurse` parameter, note that there no way for a client to
control how far the server recurses. If the client decides that the server's
recursion level is insufficient, it could, for example, perform the recursion
itself, or disable whatever feature requires more recursion.

Filters specified via `event_type` or `rel_type` will be applied to all events
returned, whether direct or indirect relations. Events that would match the filter,
but whose only relation to the original given event is through a non-matching
intermediate event, will not be included. This means that supplying a `rel_type`
parameter of `m.thread` is not appropriate for fetching all events in a thread since
relations to the threaded events would be filtered out. For this purpose, clients should
omit the `rel_type` parameter and perform any necessary filtering on the client side.

{{% boxes/note %}}
Because replies do not use `rel_type`, they will not be accessible via this API.
{{% /boxes/note %}}
Expand Down
32 changes: 31 additions & 1 deletion data/api/client-server/relations.yaml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Copyright 2022 The Matrix.org Foundation C.I.C.
# Copyright 2022,2024 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
Expand Down Expand Up @@ -39,6 +39,7 @@ paths:
- $ref: '#/components/parameters/to'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/dir'
- $ref: '#/components/parameters/recurse'
responses:
# note: this endpoint deliberately does not support rate limiting, therefore a
# 429 error response is not included.
Expand Down Expand Up @@ -96,6 +97,7 @@ paths:
- $ref: '#/components/parameters/to'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/dir'
- $ref: '#/components/parameters/recurse'
responses:
# note: this endpoint deliberately does not support rate limiting, therefore a
# 429 error response is not included.
Expand Down Expand Up @@ -167,6 +169,7 @@ paths:
- $ref: '#/components/parameters/to'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/dir'
- $ref: '#/components/parameters/recurse'
responses:
# note: this endpoint deliberately does not support rate limiting, therefore a
# 429 error response is not included.
Expand Down Expand Up @@ -294,6 +297,27 @@ components:
example: org.example.my_relation
schema:
type: string
recurse:
in: query
name: recurse
x-addedInMatrixVersion: "1.10"
required: false
description: |-
Whether to additionally include events which only relate indirectly to the
given event, i.e. events related to the given event via two or more direct relationships.

If set to `false`, only events which have direct a relation with the given
event will be included.

If set to `true`, all events which relate to the given event, or relate to
events that relate to the given event, will be included.

It is recommended that homeservers traverse at least 3 levels of relationships.
Implementations may perform more but should be careful to not infinitely recurse.

The default value is `false`.
schema:
type: boolean
schemas:
response:
type: object
Expand All @@ -308,6 +332,12 @@ components:
description: |-
An opaque string representing a pagination token. The absence of this token
means this is the start of the result set, i.e. this is the first batch/page.
recursion_depth:
type: integer
description: |-
If the `recurse` parameter was supplied by the client, this response field is
mandatory and gives the actual depth to which the server recursed. If the client
did not specify the `recurse` parameter, this field must be absent.
responses:
"404":
description: |-
Expand Down
Loading