Initial (not yet enabled) work on Heisenbridge handling media requests at `matrix.DOMAIN/heisenbridge/*`

Related to:

- https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3470
- https://github.com/hifi/heisenbridge/releases/tag/v1.15.0

During testing, it appears that Heisenbridge generated media URLs
that look like this: `{media_url}/_matrix/media/v3/download/DOMAIN/FILE_ID/FILE_NAME`.

This seems off. We were expecting `{media_url}/_heisenbridge/media/something`
(e.g. `https://matrix.DOMAIN/heisenbridge/_heisenbridge/media/something`, leading to its own media proxy),
but Heisenbridge still seems to be generating URLs destined for the homeserver's Media API.

Until we figure out why that is, `media_url` remains pointed to the homeserver URL (just like before),
so that the bot can continue operating like before.

docs/configuring-playbook-bridge-heisenbridge.md

@@ -22,6 +22,8 @@ matrix_heisenbridge_owner: "@you:your-homeserver"
 matrix_heisenbridge_identd_enabled: true
 ```
 
+By default, Heisenbrdige would be exposed on the Matrix domain (`matrix.DOMAIN`, as specified in `matrix_server_fqn_matrix`) under the `/heisenbridge` path prefix. It would handle media requests there (see the [release notes for Heisenbridge v1.15.0](https://github.com/hifi/heisenbridge/releases/tag/v1.15.0)).
+
 That's it! A registration file is automatically generated during the setup phase.
 
 Setting the owner is optional as the first local user to DM `@heisenbridge:your-homeserver` will be made the owner.

group_vars/matrix_servers

@@ -1934,6 +1934,8 @@ matrix_sms_bridge_homeserver_token: "{{ '%s' | format(matrix_homeserver_generic_
 # We don't enable bridges by default.
 matrix_heisenbridge_enabled: false
 
+matrix_heisenbridge_scheme: "{{ 'https' if matrix_playbook_ssl_enabled else 'http' }}"
+
 matrix_heisenbridge_systemd_required_services_list_auto: |
   {{
     matrix_addons_homeserver_systemd_services_list
@@ -1943,9 +1945,18 @@ matrix_heisenbridge_container_network: "{{ matrix_addons_container_network }}"
 
 matrix_heisenbridge_container_additional_networks_auto: |-
   {{
-    ([] if matrix_addons_homeserver_container_network == '' else [matrix_addons_homeserver_container_network])
+    (
+      ([] if matrix_addons_homeserver_container_network == '' else [matrix_addons_homeserver_container_network])
+      +
+      [matrix_playbook_reverse_proxyable_services_additional_network] if (matrix_heisenbridge_container_labels_traefik_enabled and matrix_playbook_reverse_proxyable_services_additional_network) else []
+    ) | unique
   }}
 
+matrix_heisenbridge_container_labels_traefik_enabled: "{{ matrix_playbook_reverse_proxy_type in ['playbook-managed-traefik', 'other-traefik-container'] }}"
+matrix_heisenbridge_container_labels_traefik_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}"
+matrix_heisenbridge_container_labels_traefik_entrypoints: "{{ devture_traefik_entrypoint_primary }}"
+matrix_heisenbridge_container_labels_traefik_tls_certResolver: "{{ devture_traefik_certResolver_primary }}"
+
 matrix_heisenbridge_appservice_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'heisen.as.tok', rounds=655555) | to_uuid }}"
 
 matrix_heisenbridge_homeserver_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'heisen.hs.tok', rounds=655555) | to_uuid }}"

roles/custom/matrix-bridge-heisenbridge/defaults/main.yml

@@ -4,6 +4,10 @@
 
 matrix_heisenbridge_enabled: true
 
+matrix_heisenbridge_scheme: https
+matrix_heisenbridge_hostname: "{{ matrix_server_fqn_matrix }}"
+matrix_heisenbridge_path_prefix: "/heisenbridge"
+
 # renovate: datasource=docker depName=hif1/heisenbridge
 matrix_heisenbridge_version: 1.15.0
 matrix_heisenbridge_docker_image: "{{ matrix_container_global_registry_prefix }}hif1/heisenbridge:{{ matrix_heisenbridge_version }}"
@@ -27,6 +31,37 @@ matrix_heisenbridge_container_additional_networks_custom: []
 # We use a small value here, because this container does not seem to handle the SIGTERM signal.
 matrix_heisenbridge_container_stop_grace_time_seconds: 1
 
+# matrix_heisenbridge_container_labels_traefik_enabled controls whether labels to assist a Traefik reverse-proxy will be attached to the container.
+# See `../templates/labels.j2` for details.
+#
+# To inject your own other container labels, see `matrix_heisenbridge_container_labels_additional_labels`.
+matrix_heisenbridge_container_labels_traefik_enabled: true
+matrix_heisenbridge_container_labels_traefik_docker_network: "{{ matrix_heisenbridge_container_network }}"
+matrix_heisenbridge_container_labels_traefik_hostname: "{{ matrix_heisenbridge_hostname }}"
+matrix_heisenbridge_container_labels_traefik_path_prefix: "{{ matrix_heisenbridge_path_prefix }}"
+matrix_heisenbridge_container_labels_traefik_entrypoints: web-secure
+matrix_heisenbridge_container_labels_traefik_tls_certResolver: default  # noqa var-naming
+
+# Controls if the media router is enabled
+matrix_heisenbridge_container_labels_traefik_media_enabled: true
+matrix_heisenbridge_container_labels_traefik_media_hostname: "{{ matrix_heisenbridge_container_labels_traefik_hostname }}"
+# The path prefix must either be `/` or not end with a slash (e.g. `/heisenbridge`).
+matrix_heisenbridge_container_labels_traefik_media_path_prefix: "{{ '/_heisenbridge/media' if matrix_heisenbridge_container_labels_traefik_path_prefix == '/' else (matrix_heisenbridge_container_labels_traefik_path_prefix + '/_heisenbridge/media') }}"
+matrix_heisenbridge_container_labels_traefik_media_rule: "Host(`{{ matrix_heisenbridge_container_labels_traefik_media_hostname }}`){% if matrix_heisenbridge_container_labels_traefik_media_path_prefix != '/' %} && PathPrefix(`{{ matrix_heisenbridge_container_labels_traefik_media_path_prefix }}`){% endif %}"
+matrix_heisenbridge_container_labels_traefik_media_priority: 0
+matrix_heisenbridge_container_labels_traefik_media_entrypoints: "{{ matrix_heisenbridge_container_labels_traefik_entrypoints }}"
+matrix_heisenbridge_container_labels_traefik_media_tls: "{{ matrix_heisenbridge_container_labels_traefik_media_entrypoints != 'web' }}"
+matrix_heisenbridge_container_labels_traefik_media_tls_certResolver: "{{ matrix_heisenbridge_container_labels_traefik_tls_certResolver }}"
+
+# matrix_heisenbridge_container_labels_additional_labels contains a multiline string with additional labels to add to the container label file.
+# See `../templates/labels.j2` for details.
+#
+# Example:
+# matrix_heisenbridge_container_labels_additional_labels: |
+#   my.label=1
+#   another.label="here"
+matrix_heisenbridge_container_labels_additional_labels: ''
+
 # A list of extra arguments to pass to the container
 matrix_heisenbridge_container_extra_arguments: []
 
@@ -44,11 +79,20 @@ matrix_heisenbridge_homeserver_url: ""
 matrix_heisenbridge_appservice_token: ''
 matrix_heisenbridge_homeserver_token: ''
 
-matrix_heisenbridge_config_media_url: "{{ matrix_homeserver_url }}"
+# In light of Synapse sunsetting unauthenticated media, we'd like to move to Heisenbridge's media proxy,
+# announced here: https://github.com/hifi/heisenbridge/releases/tag/v1.15.0
+#
+# It seems like the media proxy is not working as expected, so we're disabling it for now and falling back to our old media URL (pointing Heisenbridge to the homeserver URL).
+# Right now, Heisenbridge is still generating URLs like `{media_url}/_matrix/media/v3/download/DOMAIN/FILE_ID/FILE_NAME`,
+# so pointing `media_url` to the homeserver is a good fit.
+# matrix_heisenbridge_config_media_url: "{{ matrix_heisenbridge_scheme }}://{{ matrix_heisenbridge_hostname }}{{ matrix_heisenbridge_path_prefix }}"
+matrix_heisenbridge_config_media_url: "{{ matrix_heisenbridge_scheme }}://{{ matrix_heisenbridge_hostname }}"
+matrix_heisenbridge_config_media_key: "{{ matrix_heisenbridge_homeserver_token }}"
 matrix_heisenbridge_config_displayname: "Heisenbridge"
 
 matrix_heisenbridge_registration_yaml_heisenbridge:
   media_url: "{{ matrix_heisenbridge_config_media_url }}"
+  media_key: "{{ matrix_heisenbridge_config_media_key }}"
   displayname: "{{ matrix_heisenbridge_config_displayname }}"
 
 # Default registration file consumed by both the homeserver and Heisenbridge.

roles/custom/matrix-bridge-heisenbridge/tasks/setup_install.yml

@@ -29,6 +29,16 @@
     owner: "{{ matrix_user_username }}"
     group: "{{ matrix_user_groupname }}"
 
+- name: Ensure heisenbridge support files installed
+  ansible.builtin.template:
+    src: "{{ role_path }}/templates/{{ item }}.j2"
+    dest: "{{ matrix_heisenbridge_base_path }}/{{ item }}"
+    mode: 0640
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  with_items:
+    - labels
+
 - name: Ensure heisenbridge container network is created
   community.general.docker_network:
     enable_ipv6: "{{ devture_systemd_docker_base_ipv6_enabled }}"

roles/custom/matrix-bridge-heisenbridge/templates/labels.j2

@@ -0,0 +1,52 @@
+{% if matrix_heisenbridge_container_labels_traefik_enabled %}
+traefik.enable=true
+
+{% if matrix_heisenbridge_container_labels_traefik_docker_network %}
+traefik.docker.network={{ matrix_heisenbridge_container_labels_traefik_docker_network }}
+{% endif %}
+
+traefik.http.services.matrix-heisenbridge.loadbalancer.server.port=9898
+
+{% set middlewares = [] %}
+
+{% if matrix_heisenbridge_container_labels_traefik_path_prefix != '/' %}
+traefik.http.middlewares.matrix-heisenbridge-strip-prefix.stripprefix.prefixes={{ matrix_heisenbridge_container_labels_traefik_path_prefix }}
+{% set middlewares = middlewares + ['matrix-heisenbridge-strip-prefix'] %}
+{% endif %}
+
+{% if matrix_heisenbridge_container_labels_traefik_media_enabled %}
+##########################################################################
+#                                                                        #
+# Media                                                                  #
+#                                                                        #
+##########################################################################
+
+traefik.http.routers.matrix-heisenbridge-media.rule={{ matrix_heisenbridge_container_labels_traefik_media_rule }}
+
+{% if matrix_heisenbridge_container_labels_traefik_media_priority | int > 0 %}
+traefik.http.routers.matrix-heisenbridge-media.priority={{ matrix_heisenbridge_container_labels_traefik_media_priority }}
+{% endif %}
+
+{% if middlewares | length > 0 %}
+traefik.http.routers.matrix-heisenbridge-media.middlewares={{ middlewares | join(',') }}
+{% endif %}
+
+traefik.http.routers.matrix-heisenbridge-media.service=matrix-heisenbridge
+traefik.http.routers.matrix-heisenbridge-media.entrypoints={{ matrix_heisenbridge_container_labels_traefik_entrypoints }}
+
+traefik.http.routers.matrix-heisenbridge-media.tls={{ matrix_heisenbridge_container_labels_traefik_media_tls | to_json }}
+{% if matrix_heisenbridge_container_labels_traefik_media_entrypoints %}
+traefik.http.routers.matrix-heisenbridge-media.tls.certResolver={{ matrix_heisenbridge_container_labels_traefik_media_tls_certResolver }}
+{% endif %}
+
+##########################################################################
+#                                                                        #
+# /Media                                                                 #
+#                                                                        #
+##########################################################################
+{% endif %}
+
+
+{% endif %}
+
+{{ matrix_heisenbridge_container_labels_additional_labels }}

roles/custom/matrix-bridge-heisenbridge/templates/systemd/matrix-heisenbridge.service.j2

@@ -27,6 +27,7 @@ ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} create \
 			-p 113:13113 \
 			{% endif %}
 			--mount type=bind,src={{ matrix_heisenbridge_base_path }},dst=/config \
+			--label-file={{ matrix_heisenbridge_base_path }}/labels \
 			{% for arg in matrix_heisenbridge_container_extra_arguments %}
 			{{ arg }} \
 			{% endfor %}