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 10 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.
81 changes: 74 additions & 7 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.
`GET` requests will be handled directly while `POST` and `PUT` requests will be
clokep marked this conversation as resolved.
Show resolved Hide resolved
proxied to the proper worker. See the [stream writers](#stream-writers) section
below for more information.

# Sync requests
^/_matrix/client/(v2_alpha|r0|v3)/sync$
Expand Down Expand Up @@ -238,6 +240,10 @@ expressions:
^/_matrix/client/(api/v1|r0|v3|unstable)/joined_rooms$
^/_matrix/client/(api/v1|r0|v3|unstable)/search$

# Encryption requests
^/_matrix/client/(api/v1|r0|v3|unstable)/keys/claim
^/_matrix/client/(api/v1|r0|v3|unstable)/room_keys

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

# Typing requests
^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/typing
clokep marked this conversation as resolved.
Show resolved Hide resolved

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

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

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

# Presence requests
^/_matrix/client/(api/v1|r0|v3|unstable)/presence/.*/status$
clokep marked this conversation as resolved.
Show resolved Hide resolved

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 +353,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 +368,15 @@ stream_writers:
events: event_persister1
```

Each of the streams have associated endpoints which should have `POST` and `PUT`
requests routed to the workers handling that stream. Otherwise, those requests
will be proxied to the proper worker.
Copy link
Member

Choose a reason for hiding this comment

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

Sadly, I don't think this is correct. Examples:

  • if you send a PUT /typing request to the wrong worker, it will 500.
  • if you send a PUT /sendToDevice request or a POST /receipt request to the wrong worker... I dunno. I think it will still work? It won't proxy it, anyway.

I think it's roughly correct for account_data, tags and presence

Copy link
Member Author

Choose a reason for hiding this comment

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

That's quite confusing! My initial thought -- is this a bug? Are those supposed to be proxied to the proper workers and we just don't? It would be much clearer to document if the various endpoints behaved the same.

Copy link
Member

Choose a reason for hiding this comment

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

yeah. No idea what the intention is here.

Copy link
Member Author

Choose a reason for hiding this comment

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

@erikjohnston Any idea what's supposed to happen here?

Copy link
Member

Choose a reason for hiding this comment

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

Ideally I think we want requests to be proxied to the right worker, so that the end game supports load balancers just round robining all requests to all workers (even if that is not the most efficient way of doing it).


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 +389,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/.*/status$

#### Background tasks

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