Add the `update_user_directory_from_worker` configuration option (superseding `update_user_directory`) to allow a generic worker to be designated as the worker to update the user directory. (#12654)

Co-authored-by: Shay <hillerys@element.io>

2 files changed, 39 insertions, 12 deletions

diff --git a/docs/upgrade.md b/docs/upgrade.md
index 18c33a4198..fa4b3ef590 100644
--- a/docs/upgrade.md
+++ b/docs/upgrade.md
@@ -101,29 +101,36 @@ To re-enable this functionality, set the
 homeserver config option to `true`.
 
 
-## Deprecation of the `synapse.app.appservice` worker application type
+## Deprecation of the `synapse.app.appservice` and `synapse.app.user_dir` worker application types
 
 The `synapse.app.appservice` worker application type allowed you to configure a
 single worker to use to notify application services of new events, as long
 as this functionality was disabled on the main process with `notify_appservices: False`.
+Further, the `synapse.app.user_dir` worker application type allowed you to configure
+a single worker to be responsible for updating the user directory, as long as this
+was disabled on the main process with `update_user_directory: False`.
 
 To unify Synapse's worker types, the `synapse.app.appservice` worker application
 type and the `notify_appservices` configuration option have been deprecated.
+The `synapse.app.user_dir` worker application type and `update_user_directory`
+configuration option have also been deprecated.
 
-To get the same functionality, it's now recommended that the `synapse.app.generic_worker`
-worker application type is used and that the `notify_appservices_from_worker` option
-is set to the name of a worker.
+To get the same functionality as was provided by the deprecated options, it's now recommended that the `synapse.app.generic_worker`
+worker application type is used and that the `notify_appservices_from_worker` and/or
+`update_user_directory_from_worker` options are set to the name of a worker.
 
-For the time being, `notify_appservices_from_worker` can be used alongside
-`synapse.app.appservice` and `notify_appservices` to make it easier to transition
-between the two configurations, however please note that:
+For the time being, the old options can be used alongside the new options to make
+it easier to transition between the two configurations, however please note that:
 
 - the options must not contradict each other (otherwise Synapse won't start); and
-- the `notify_appservices` option will be removed in a future release of Synapse.
+- the `notify_appservices` and `update_user_directory` options will be removed in a future release of Synapse.
 
-Please see [the relevant section of the worker documentation][v1_59_notify_ases_from] for more information.
+Please see the [*Notifying Application Services*][v1_59_notify_ases_from] and
+[*Updating the User Directory*][v1_59_update_user_dir] sections of the worker
+documentation for more information.
 
 [v1_59_notify_ases_from]: workers.md#notifying-application-services
+[v1_59_update_user_dir]: workers.md#updating-the-user-directory
 
 
 # Upgrading to v1.58.0
diff --git a/docs/workers.md b/docs/workers.md
index 1d049b6c4f..553792d238 100644
--- a/docs/workers.md
+++ b/docs/workers.md
@@ -426,7 +426,7 @@ the shared configuration would include:
 run_background_tasks_on: background_worker
 ```
 
-You might also wish to investigate the `update_user_directory` and
+You might also wish to investigate the `update_user_directory_from_worker` and
 `media_instance_running_background_jobs` settings.
 
 An example for a dedicated background worker instance:
@@ -435,9 +435,26 @@ An example for a dedicated background worker instance:
 {{#include systemd-with-workers/workers/background_worker.yaml}}
 ```
 
+#### Updating the User Directory
+
+You can designate one generic worker to update the user directory.
+
+Specify its name in the shared configuration as follows:
+
+```yaml
+update_user_directory_from_worker: worker_name
+```
+
+This work cannot be load-balanced; please ensure the main process is restarted
+after setting this option in the shared configuration!
+
+This style of configuration supersedes the legacy `synapse.app.user_dir`
+worker application type.
+
+
 #### Notifying Application Services
 
-You can designate one worker to send output traffic to Application Services.
+You can designate one generic worker to send output traffic to Application Services.
 
 Specify its name in the shared configuration as follows:
 
@@ -470,7 +487,7 @@ pusher_instances:
 
 ### `synapse.app.appservice`
 
-**Deprecated as of Synapse v1.58.** [Use `synapse.app.generic_worker` with the
+**Deprecated as of Synapse v1.59.** [Use `synapse.app.generic_worker` with the
 `notify_appservices_from_worker` option instead.](#notifying-application-services)
 
 Handles sending output traffic to Application Services. Doesn't handle any
@@ -540,6 +557,9 @@ Note that if a reverse proxy is used , then `/_matrix/media/` must be routed for
 
 ### `synapse.app.user_dir`
 
+**Deprecated as of Synapse v1.59.** [Use `synapse.app.generic_worker` with the
+`update_user_directory_from_worker` option instead.](#updating-the-user-directory)
+
 Handles searches in the user directory. It can handle REST endpoints matching
 the following regular expressions: