Dan ae16db4898 Refresh musiclink integration docs and tooling

Use local musiclink flake input with Go 1.24.

Add matterbridge patch, routing docs, and deploy check script.

2026-01-21 22:52:39 -08:00

3.3 KiB

Raw Blame History

RFC: MusicLink Room Routing and Fan-Out Behavior

Summary

MusicLink is deployed via Matterbridge as a Matrix-mediated bridge for Slack rooms. We observed that messages from one Slack room are reposted by MusicLink into other Matrix portal rooms (including DMs). This is caused by Matterbridge’s gateway fan-out behavior when multiple Matrix rooms are configured as inout in the same gateway.

This RFC documents the issue, impact, and options for isolation while keeping multi-room coverage.

Current Architecture

Slack Room (e.g. #music)
  -> mautrix-slack (Matrix portal room)
  -> Matterbridge (single gateway)
  -> MusicLink (API)
  -> Matterbridge (same gateway)
  -> All other Matrix rooms in the gateway

Current Matterbridge Gateway

In modules/musiclink.nix, multiple Matrix rooms are configured as [[gateway.inout]] under the same musiclink-gateway:

!whU7Geg7JPrBL5wHcW:clarun.xyz
!dT40EUcemb8e6bPiig:clarun.xyz (Dan/Vlad DM portal)
!DPQveBnfuDrbgOe6dm:clarun.xyz (#music portal)

Matterbridge treats a gateway as a fan-out bus: any message arriving from one room is broadcast to every other room in that gateway (except the source). This is expected behavior and not a MusicLink feature.

Observed Issue

A reply in the Slack #music thread was bridged into the Matrix portal for #music. Matterbridge then broadcast that message into the Dan/Vlad DM portal room, appearing as though MusicLink “reposted” a random message.

Root Cause

Matterbridge lacks per-room routing rules within a gateway. It cannot forward only to the originating Slack room. When multiple Matrix rooms share the same gateway, cross-posting is unavoidable.

Constraints

We must route everything through a single Slack login/token (one Slack user identity). Multiple Slack app tokens or per-room Slack identities are not available.

Options

Option A: Keep Current Fan-Out Behavior

Pros: Single service, simplest configuration.
Cons: Cross-posting between rooms/DMs continues.

Option B: One Gateway Per Room (Recommended)

Create separate Matterbridge gateways (or instances) per Matrix portal room.
Each gateway connects to its own MusicLink instance (or a shared MusicLink if it can target a gateway/room).
Pros: No cross-posting; clean isolation.
Cons: More configuration and systemd units.

Option C: Replace Matterbridge With Direct Multi-Room Support

Modify MusicLink to join Matrix rooms directly and post responses only in the originating room.
Pros: Correct routing without fan-out.
Cons: Requires changes to MusicLink code and Matrix auth handling.

Option D: Investigate Matterbridge Routing Extensions

Explore upstream support for per-room routing rules or custom patches.
Pros: Potentially retains single gateway.
Cons: No known support today; likely requires upstream changes.

Recommendation

Adopt Option B (one gateway per room) to preserve multi-room coverage without cross-posting. This keeps MusicLink behavior predictable and avoids DM leakage. If MusicLink can be updated to support multiple rooms directly, Option C could supersede this.

Open Questions

How many Slack rooms require MusicLink coverage in the near term?
Are we willing to run multiple MusicLink instances, or should we refactor MusicLink to support per-room targeting?

3.3 KiB Raw Blame History Unescape Escape