Implement MSC 1929 Homeserver Admin Contact (#1931)

* Implement MSC 1929 Homeserver Admin Contact
Fixes #1612

For details to the proposed (not accepted yet) MSC, see:
https://github.com/matrix-org/matrix-spec-proposals/blob/hs/proposal-admin-contact-1/proposals/1929-admin-contact.md

* Implement feedback from PR #1931

* Implement feedback from PR #1931

* Fix mixed indentation

docs/configuring-well-known.md

@@ -36,6 +36,33 @@ However, this playbook installs your Matrix server on another domain (e.g. `matr
 To learn how to set it up, read the Installing section below.
 
 
+## (Optional) Introduction to Homeserver Admin Contact and Support page
+
+[MSC 1929](https://github.com/matrix-org/matrix-spec-proposals/pull/1929) specifies a way to add contact details of admins, as well as a link to a support page for users who are having issues with the service.
+
+This MSC did not get accepted yet, but we think it might already be useful to Homeserver admins who wish to provide this information to end-users.
+
+The two playbook variables that you could look for, if you're interested in being an early adopter, are: `matrix_homeserver_admin_contacts` and `matrix_homeserver_support_url`.
+
+Example snippet for `vars.yml`:
+```
+# Homeserver admin contacts as per MSC 1929 https://github.com/matrix-org/matrix-spec-proposals/pull/1929
+matrix_homeserver_admin_contacts:
+  - matrix_id: @admin1:domain.tld
+    email_address: admin@domain.tld
+    role: admin
+  - matrix_id: @admin2:domain.tld
+    email_address: admin@domain.tld
+    role: admin
+  - email_address: security@domain.tld
+    role: security
+
+matrix_homeserver_support_url: "https://example.domain.tld/support"
+```
+
+To learn how to set up `/.well-known/matrix/support` for the base domain, read the Installing section below.
+
+
 ## Installing well-known files on the base domain's server
 
 To implement the two service discovery mechanisms, your base domain's server (e.g. `example.com`) needs to run an HTTPS-capable webserver.
@@ -185,5 +212,6 @@ No matter which method you've used to set up the well-known files, if you've don
 
 - `https://<domain>/.well-known/matrix/server`
 - `https://<domain>/.well-known/matrix/client`
+- `https://<domain>/.well-known/matrix/support`
 
 You can also check if everything is configured correctly, by [checking if services work](maintenance-checking-services.md).

roles/matrix-base/defaults/main.yml

@@ -12,6 +12,19 @@ matrix_domain: ~
 # Example value: "@someone:{{ matrix_domain }}"
 matrix_admin: ''
 
+# Homeserver admin contacts and support page as per MSC 1929
+# See: https://github.com/matrix-org/matrix-spec-proposals/pull/1929
+# Users in form:
+# matrix_homeserver_admin_contacts:
+#   - matrix_id: @admin:domain.tld
+#     email_address: admin@domain.tld
+#     role: admin
+#   - email_address: security@domain.tld
+#     role: security
+matrix_homeserver_admin_contacts: []
+# Url string like https://domain.tld/support.html
+matrix_homeserver_support_url: ''
+
 # This will contain the homeserver implementation that is in use.
 # Valid values: synapse, dendrite
 #
@@ -225,6 +238,18 @@ matrix_well_known_matrix_server_configuration_extension: "{{ matrix_well_known_m
 # You most likely don't need to touch this variable. Instead, see `matrix_well_known_matrix_server_configuration_default` and `matrix_well_known_matrix_server_configuration_extension_json`.
 matrix_well_known_matrix_server_configuration: "{{ matrix_well_known_matrix_server_configuration_default|combine(matrix_well_known_matrix_server_configuration_extension, recursive=True) }}"
 
+# The side-effect of this lookup is that Ansible would even parse the JSON for us, returning a dict.
+# This is unlike what it does when looking up YAML template files (no automatic parsing there).
+matrix_well_known_matrix_support_configuration_default: "{{ lookup('template', 'templates/static-files/well-known/matrix-support.j2') }}"
+
+matrix_well_known_matrix_support_configuration_extension_json: '{}'
+
+matrix_well_known_matrix_support_configuration_extension: "{{ matrix_well_known_matrix_support_configuration_extension_json|from_json if matrix_well_known_matrix_support_configuration_extension_json|from_json is mapping else {} }}"
+
+# Holds the final `/.well-known/matrix/support` configuration (a combination of the default and its extension).
+# You most likely don't need to touch this variable. Instead, see `matrix_well_known_matrix_support_configuration_default` and `matrix_well_known_matrix_support_configuration_extension_json`.
+matrix_well_known_matrix_support_configuration: "{{ matrix_well_known_matrix_support_configuration_default|combine(matrix_well_known_matrix_support_configuration_extension, recursive=True) }}"
+
 # The Docker network that all services would be put into
 matrix_docker_network: "matrix"
 

roles/matrix-base/tasks/setup_well_known.yml

@@ -35,3 +35,11 @@
     path: "{{ matrix_static_files_base_path }}/.well-known/matrix/server"
     state: absent
   when: "not matrix_well_known_matrix_server_enabled|bool"
+
+- name: Ensure Matrix /.well-known/matrix/support file configured
+  copy:
+    content: "{{ matrix_well_known_matrix_support_configuration|to_nice_json }}"
+    dest: "{{ matrix_static_files_base_path }}/.well-known/matrix/support"
+    mode: 0644
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"

roles/matrix-base/templates/static-files/well-known/matrix-support.j2

@@ -0,0 +1,7 @@
+#jinja2: lstrip_blocks: "True"
+{
+    "admins": {{ matrix_homeserver_admin_contacts|to_json }}
+    {% if matrix_homeserver_support_url %},
+        "support_page": "{{ matrix_homeserver_support_url|to_json }}"
+    {% endif %}
+}