Skip to content
This repository has been archived by the owner on Apr 26, 2024. It is now read-only.

Add documentation for missing worker types. #11599

Merged
merged 22 commits into from
Feb 23, 2022
Merged

Add documentation for missing worker types. #11599

Show file tree
Hide file tree
Changes from 18 commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
b84f9d8
Add documentation for missing worker types.
clokep Dec 17, 2021
2945710
Try to clarify how to route to workers.
clokep Dec 17, 2021
71a5001
Document presence worker.
clokep Dec 17, 2021
5ad39a4
Newsfragment
clokep Dec 17, 2021
55365e0
Clarify GET vs. PUT/POST requests.
clokep Dec 20, 2021
5a8b385
Rework the endpoints for stream writers.
clokep Dec 28, 2021
c97d9b6
Merge remote-tracking branch 'origin/develop' into clokep/worker-docs
clokep Dec 28, 2021
4aab90e
Fix typos.
clokep Jan 6, 2022
1dfd364
Fix more typos.
clokep Jan 6, 2022
ac9cae4
Event persisters don't need to handle endpoints.
clokep Jan 6, 2022
1c03c57
Route all of /presence to workers.
clokep Feb 9, 2022
1ff6714
Consolidate some of the endpoints.
clokep Feb 9, 2022
1139eed
Merge remote-tracking branch 'origin/develop' into clokep/worker-docs
clokep Feb 9, 2022
7e4920d
Merge remote-tracking branch 'origin/develop' into clokep/worker-docs
clokep Feb 22, 2022
44853ea
Remove incorrect prefixes.
clokep Feb 22, 2022
00dad02
Clarify how endpoints are used.
clokep Feb 22, 2022
a529487
Remove typing from generic worker -- it does not get proxied.
clokep Feb 22, 2022
fcebe0b
Talk less about POST/PUT.
clokep Feb 22, 2022
9c2f941
Clarify documentation.
clokep Feb 23, 2022
7fb4566
Add end of string to regex.
clokep Feb 23, 2022
b3dad90
Apply suggestions from code review
clokep Feb 23, 2022
793548a
Consistent line wrapping.
clokep Feb 23, 2022
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 changelog.d/11599.doc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Document support for the `to_device`, `account_data`, `receipts`, and `presence` stream writers for workers.
89 changes: 75 additions & 14 deletions docs/workers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,8 +178,10 @@ recommend the use of `systemd` where available: for information on setting up

### `synapse.app.generic_worker`

This worker can handle API requests matching the following regular
expressions:
This worker can handle API requests matching the following regular expressions.
These endpoints can be routed to any worker. If a worker is set up to handle a
stream then additional endpoints may be required to route to said worker, refer
clokep marked this conversation as resolved.
Show resolved Hide resolved
to the [stream writers](#stream-writers) section below for further information.
Copy link
Member

Choose a reason for hiding this comment

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

I'm a bit confused about this. Are we saying that sendToDevice and things can go to any generic_worker, unless there is a worker which is defined to handle the to_device stream, in which case you have to route sendToDevice to that specific worker?

Copy link
Member Author

Choose a reason for hiding this comment

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

You can still route them to any worker, but it is more efficient to route them directly. That's my understanding at least.


# Sync requests
^/_matrix/client/(v2_alpha|r0|v3)/sync$
Expand Down Expand Up @@ -225,19 +227,23 @@ expressions:
^/_matrix/client/unstable/org.matrix.msc2946/rooms/.*/spaces$
^/_matrix/client/(v1|unstable/org.matrix.msc2946)/rooms/.*/hierarchy$
^/_matrix/client/unstable/im.nheko.summary/rooms/.*/summary$
^/_matrix/client/(api/v1|r0|v3|unstable)/account/3pid$
^/_matrix/client/(api/v1|r0|v3|unstable)/devices$
^/_matrix/client/(api/v1|r0|v3|unstable)/keys/query$
^/_matrix/client/(api/v1|r0|v3|unstable)/keys/changes$
^/_matrix/client/(r0|v3|unstable)/account/3pid$
^/_matrix/client/(r0|v3|unstable)/devices$
^/_matrix/client/versions$
^/_matrix/client/(api/v1|r0|v3|unstable)/voip/turnServer$
^/_matrix/client/(api/v1|r0|v3|unstable)/joined_groups$
^/_matrix/client/(api/v1|r0|v3|unstable)/publicised_groups$
^/_matrix/client/(api/v1|r0|v3|unstable)/publicised_groups/
^/_matrix/client/(r0|v3|unstable)/joined_groups$
^/_matrix/client/(r0|v3|unstable)/publicised_groups$
^/_matrix/client/(r0|v3|unstable)/publicised_groups/
^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/event/
^/_matrix/client/(api/v1|r0|v3|unstable)/joined_rooms$
^/_matrix/client/(api/v1|r0|v3|unstable)/search$

# Encryption requests
^/_matrix/client/(r0|v3|unstable)/keys/query$
^/_matrix/client/(r0|v3|unstable)/keys/changes$
^/_matrix/client/(r0|v3|unstable)/keys/claim
clokep marked this conversation as resolved.
Show resolved Hide resolved
^/_matrix/client/(r0|v3|unstable)/room_keys
clokep marked this conversation as resolved.
Show resolved Hide resolved

# Registration/login requests
^/_matrix/client/(api/v1|r0|v3|unstable)/login$
^/_matrix/client/(r0|v3|unstable)/register$
Expand All @@ -251,6 +257,20 @@ expressions:
^/_matrix/client/(api/v1|r0|v3|unstable)/join/
^/_matrix/client/(api/v1|r0|v3|unstable)/profile/

# Device requests
^/_matrix/client/(r0|v3|unstable)/sendToDevice/

# Account data requests
^/_matrix/client/(r0|v3|unstable)/.*/tags
^/_matrix/client/(r0|v3|unstable)/.*/account_data

# Receipts requests
^/_matrix/client/(r0|v3|unstable)/rooms/.*/receipt
^/_matrix/client/(r0|v3|unstable)/rooms/.*/read_markers

# Presence requests
^/_matrix/client/(api/v1|r0|v3|unstable)/presence/

erikjohnston marked this conversation as resolved.
Show resolved Hide resolved

Additionally, the following REST endpoints can be handled for GET requests:

Expand Down Expand Up @@ -330,12 +350,10 @@ Additionally, there is *experimental* support for moving writing of specific
streams (such as events) off of the main process to a particular worker. (This
is only supported with Redis-based replication.)

Currently supported streams are `events` and `typing`.

To enable this, the worker must have a HTTP replication listener configured,
have a `worker_name` and be listed in the `instance_map` config. For example to
move event persistence off to a dedicated worker, the shared configuration would
include:
have a `worker_name` and be listed in the `instance_map` config. The same worker
can handle multiple streams. For example, to move event persistence off to a
dedicated worker, the shared configuration would include:

```yaml
instance_map:
Expand All @@ -347,6 +365,12 @@ stream_writers:
events: event_persister1
```

Each of the streams have associated endpoints which should have requests routed
clokep marked this conversation as resolved.
Show resolved Hide resolved
to the workers handling that stream. See below for the currently supported streams
and the endpoints associated with them:

##### The `events` stream

The `events` stream also experimentally supports having multiple writers, where
work is sharded between them by room ID. Note that you *must* restart all worker
instances when adding or removing event persisters. An example `stream_writers`
Expand All @@ -359,6 +383,43 @@ stream_writers:
- event_persister2
```

##### The `typing` stream

The following endpoints should be routed directly to the workers configured as
stream writers for the `typing` stream:

^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/typing

##### The `to_device` stream

The following endpoints should be routed directly to the workers configured as
stream writers for the `to_device` stream:

^/_matrix/client/(api/v1|r0|v3|unstable)/sendToDevice/

##### The `account_data` stream

The following endpoints should be routed directly to the workers configured as
stream writers for the `account_data` stream:

^/_matrix/client/(api/v1|r0|v3|unstable)/.*/tags
^/_matrix/client/(api/v1|r0|v3|unstable)/.*/account_data

##### The `receipts` stream

The following endpoints should be routed directly to the workers configured as
stream writers for the `receipts` stream:

^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/receipt
^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/read_markers

##### The `presence` stream

The following endpoints should be routed directly to the workers configured as
stream writers for the `presence` stream:

^/_matrix/client/(api/v1|r0|v3|unstable)/presence/

#### Background tasks

There is also *experimental* support for moving background tasks to a separate
Expand Down