From 73b932ff47c6a7457cbd1d2eb6bbfad80a018721 Mon Sep 17 00:00:00 2001 From: Dan Date: Tue, 20 Jan 2026 14:42:00 -0800 Subject: [PATCH] docs: add worklog and final musiclink config fixes --- .beads/last-touched | 2 +- .../2026-01-20-musiclink-bot-integration.org | 82 +++++++++++++++++++ hosts/ops-jrz1.nix | 3 + modules/musiclink.nix | 28 +++---- secrets/secrets.yaml | 5 +- 5 files changed, 100 insertions(+), 20 deletions(-) create mode 100644 docs/worklogs/2026-01-20-musiclink-bot-integration.org diff --git a/.beads/last-touched b/.beads/last-touched index 1b9fc85..7097e0d 100644 --- a/.beads/last-touched +++ b/.beads/last-touched @@ -1 +1 @@ -ops-jrz1-k3e0 +ops-jrz1-zr0q diff --git a/docs/worklogs/2026-01-20-musiclink-bot-integration.org b/docs/worklogs/2026-01-20-musiclink-bot-integration.org new file mode 100644 index 0000000..c7bd981 --- /dev/null +++ b/docs/worklogs/2026-01-20-musiclink-bot-integration.org @@ -0,0 +1,82 @@ +#+TITLE: MusicLink Bot Integration and Matterbridge Matrix Pivot +#+DATE: 2026-01-20 +#+KEYWORDS: musiclink, matterbridge, matrix, slack-bridge, mautrix-slack, conduwuit, sops-nix +#+COMMITS: 2 +#+COMPRESSION_STATUS: uncompressed + +* Session Summary +** Date: 2026-01-20 +** Focus Area: Integration of MusicLink bot into ops-jrz1 infrastructure + +* Accomplishments +- [X] Analyzed and cloned =musiclink= source code from =ops-jrz1= to local dev environment. +- [X] Integrated =musiclink= as a Nix Flake input in =flake.nix=. +- [X] Created =modules/musiclink.nix= to manage systemd services for the bot and its Matterbridge adapter. +- [X] Extended =services.dev-platform= in =modules/dev-services.nix= to include MusicLink configuration. +- [X] Migrated Slack tokens to =sops-nix= and added new =musiclink-matrix-token=. +- [X] Provisioned =@musiclink:clarun.xyz= user on the homeserver via Matrix API. +- [X] Successfully deployed the configuration to =ops-jrz1= VPS. +- [X] Verified VM integration tests pass with the new module. +- [X] Granted server admin privileges to =@musiclink:clarun.xyz= to facilitate room management. + +* Key Decisions + +** Decision 1: Pivot to Matrix-mediated bridging +- Context: =musiclink= requires Matterbridge WebSocket API. Matterbridge (stable) lacks Slack Socket Mode support, which our Slack App requires. +- Options considered: + 1. Patch Matterbridge to support Socket Mode (high effort). + 2. Use Slack Events API (requires public ingress/TLS management). + 3. Route via Matrix using =mautrix-slack= as the gateway (Matrix-native approach). +- Rationale: Matrix-mediated routing leverages existing infrastructure (=mautrix-slack=) and treats Matrix as the universal communication bus. +- Impact: =MusicLink= -> =Matterbridge= -> =Matrix= -> =mautrix-slack= -> =Slack=. + +** Decision 2: Read-only listener for Slack-bridged rooms +- Context: Safety constraint to prevent the bot from posting test/automated messages back to Slack during initial setup. +- Rationale: Configured Matterbridge gateway as =[[gateway.in]]= for the Matrix side. +- Impact: The bot can see and process links from Slack but cannot post back to the channel. + +** Decision 3: Use local file path for Flake input (Workaround) +- Context: =nix flake check= failed to authenticate with =git.clarun.xyz= via HTTPS/SSH. +- Rationale: Cloned the repo locally and used =git+file:///home/dan/proj/musiclink= to unblock development. +- Impact: Filed beads issue =ops-jrz1-zr0q= to resolve permanent git access. + +* Problems & Solutions +| Problem | Solution | Learning | +|---------+----------+----------| +| Matterbridge failed with =not_allowed_token_type= on Slack | Pivoted to Matrix bridge; Matterbridge RTM is incompatible with modern Socket Mode apps | Matterbridge Slack support is lagging behind Slack API changes | +| MusicLink crashed with "malformed ws URL" | Changed protocol from =http://= to =ws://= in bot config | WebSocket clients are strict about the =ws://= scheme | +| Matterbridge failed Matrix login with =missing field password= | Added =MxID= to config to trigger token-based auth bypass | Matterbridge needs explicit User ID to use an existing access token | +| =M_FORBIDDEN= when joining portal room | Granted server admin to bot via =conduwuit --execute= command | Admin status alone doesn't bypass invite-only rules for standard =/join= calls | + +* Technical Details + +** Code Changes +- =modules/musiclink.nix=: Defines systemd services with =DynamicUser= and =LoadCredential= for secret safety. +- =hosts/ops-jrz1.nix=: Enabled MusicLink, disabled Maubot, added sops secrets. +- =flake.nix=: Wired up the new input and passed it to configurations and tests. + +** Commands Used +#+BEGIN_SRC bash +# Register Matrix user +curl -s -X POST -H "Content-Type: application/json" \ + -d '{"username":"musiclink", "password":"...", "auth":{"type":"m.login.registration_token", "token":"..."}}' + http://127.0.0.1:8008/_matrix/client/v3/register + +# Grant admin status via Conduwuit console +conduwuit -c continuwuity.toml --execute "admin users make-user-admin @musiclink:clarun.xyz" + +# Find Room ID from mautrix-slack DB +sudo -u postgres psql mautrix_slack -c 'SELECT id, mxid, name FROM portal;' +#+END_SRC + +* Process and Workflow +- Used =nix flake check= and VM integration tests to verify module structure before deployment. +- Incremental deployment via =nixos-rebuild switch= allowed catching configuration mismatches (=http= vs =ws=, =MxID= requirement). +- Conscious pivot from a blocked path (Matterbridge Slack) to a viable one (Matrix mediation). + +* Next Steps +- [ ] User to invite =@musiclink:clarun.xyz= to the =#music= Matrix room. +- [ ] Verify message flow: Slack -> Matrix -> MusicLink. +- [ ] Enable outbound posting (=gateway.out=) once processing logic is verified. +- [ ] Resolve git access issue for the musiclink flake input. +- [ ] Close beads task =ops-jrz1-k3e0= (AGENTS.md review). diff --git a/hosts/ops-jrz1.nix b/hosts/ops-jrz1.nix index 8d74695..199b4eb 100644 --- a/hosts/ops-jrz1.nix +++ b/hosts/ops-jrz1.nix @@ -57,6 +57,9 @@ # Forgejo API token for dev user provisioning (root only) forgejo-api-token.mode = "0400"; + + # Matrix token for MusicLink bot + musiclink-matrix-token.mode = "0400"; }; }; diff --git a/modules/musiclink.nix b/modules/musiclink.nix index 2c8c707..507bb95 100644 --- a/modules/musiclink.nix +++ b/modules/musiclink.nix @@ -56,30 +56,23 @@ in { # Secrets LoadCredential = [ - "slack-bot-token:/run/secrets/slack-bot-token" - "slack-app-token:/run/secrets/slack-app-token" + "musiclink-matrix-token:/run/secrets/musiclink-matrix-token" ]; ExecStartPre = pkgs.writeShellScript "generate-matterbridge-config" '' set -euo pipefail - SLACK_TOKEN=$(cat $CREDENTIALS_DIRECTORY/slack-bot-token) - SLACK_APP_TOKEN=$(cat $CREDENTIALS_DIRECTORY/slack-app-token) + MATRIX_TOKEN=$(cat $CREDENTIALS_DIRECTORY/musiclink-matrix-token) cat > /var/lib/musiclink-matterbridge/matterbridge.toml < /var/lib/musiclink/config.toml <