CS-11655: add app.boxel.realm-servers event type + read/write helpers

packages/host/app/services/matrix-service.ts

@@ -55,6 +55,7 @@ import {
   APP_BOXEL_REALM_EVENT_TYPE,
   APP_BOXEL_REALM_SERVER_EVENT_MSGTYPE,
   APP_BOXEL_REALMS_EVENT_TYPE,
+  APP_BOXEL_REALM_SERVERS_EVENT_TYPE,
   APP_BOXEL_WORKSPACE_FAVORITES_EVENT_TYPE,
   APP_BOXEL_ACTIVE_LLM,
   APP_BOXEL_LLM_MODE,
@@ -711,6 +712,44 @@ export default class MatrixService extends Service {
     await this.realmServer.setAvailableRealmIdentifiers(newRealms.map(ri));
   }
 
+  public async getRealmServersFromAccountData(): Promise<string[]> {
+    let { realmServers = [] } =
+      ((await this.client.getAccountDataFromServer(
+        APP_BOXEL_REALM_SERVERS_EVENT_TYPE,
+      )) as { realmServers: string[] }) ?? {};
+    return realmServers;
+  }
+
+  public async setRealmServersInAccountData(
+    realmServers: string[],
+  ): Promise<void> {
+    await this.client.setAccountData(APP_BOXEL_REALM_SERVERS_EVENT_TYPE, {
+      realmServers,
+    });
+  }
+
+  public async appendRealmServerToAccountData(
+    realmServerURLString: string,
+  ): Promise<void> {
+    let realmServers = await this.getRealmServersFromAccountData();
+    if (realmServers.includes(realmServerURLString)) {
+      return;
+    }
+    await this.setRealmServersInAccountData([
+      ...realmServers,
+      realmServerURLString,
+    ]);
+  }
+
+  public async removeRealmServerFromAccountData(
+    realmServerURLString: string,
+  ): Promise<void> {
+    let realmServers = await this.getRealmServersFromAccountData();
+    await this.setRealmServersInAccountData(
+      realmServers.filter((s) => s !== realmServerURLString),
+    );
+  }
+
   public async getWorkspaceFavorites(): Promise<string[]> {
     let { favorites = [] } =
       ((await this.client.getAccountDataFromServer(

packages/host/tests/helpers/mock-matrix.ts

@@ -24,6 +24,7 @@ export interface Config {
   loggedInAs?: string;
   displayName?: string;
   activeRealms?: string[];
+  activeRealmServers?: string[];
   realmPermissions?: Record<string, string[]>;
   expiresInSec?: number;
   autostart?: boolean;

packages/host/tests/helpers/mock-matrix/_client.ts

@@ -17,6 +17,7 @@ import {
   APP_BOXEL_COMMAND_RESULT_EVENT_TYPE,
   APP_BOXEL_DEBUG_MESSAGE_EVENT_TYPE,
   APP_BOXEL_REALMS_EVENT_TYPE,
+  APP_BOXEL_REALM_SERVERS_EVENT_TYPE,
   APP_BOXEL_ROOM_SKILLS_EVENT_TYPE,
   APP_BOXEL_REALM_EVENT_TYPE,
   APP_BOXEL_CODE_PATCH_RESULT_EVENT_TYPE,
@@ -98,6 +99,10 @@ export class MockClient implements ExtendedClient {
       return {
         realms: this.sdkOpts.activeRealms ?? [],
       } as unknown as K;
+    } else if (_eventType === APP_BOXEL_REALM_SERVERS_EVENT_TYPE) {
+      return {
+        realmServers: this.sdkOpts.activeRealmServers ?? [],
+      } as unknown as K;
     } else if (_eventType === APP_BOXEL_SYSTEM_CARD_EVENT_TYPE) {
       return (this.sdkOpts.systemCardAccountData ?? null) as unknown as K;
     } else if (_eventType === APP_BOXEL_WORKSPACE_FAVORITES_EVENT_TYPE) {
@@ -230,6 +235,8 @@ export class MockClient implements ExtendedClient {
   ): Promise<{}> {
     if (type === APP_BOXEL_REALMS_EVENT_TYPE) {
       this.sdkOpts.activeRealms = (data as any).realms;
+    } else if (type === APP_BOXEL_REALM_SERVERS_EVENT_TYPE) {
+      this.sdkOpts.activeRealmServers = (data as any).realmServers;
     } else if (type === 'm.direct') {
       this.sdkOpts.directRooms = (data as any)[this.loggedInAs!];
     } else if (type === APP_BOXEL_SYSTEM_CARD_EVENT_TYPE) {
@@ -632,6 +639,7 @@ export class MockClient implements ExtendedClient {
   private eventHandlerType(type: string) {
     switch (type) {
       case APP_BOXEL_REALMS_EVENT_TYPE:
+      case APP_BOXEL_REALM_SERVERS_EVENT_TYPE:
       case APP_BOXEL_SYSTEM_CARD_EVENT_TYPE:
       case APP_BOXEL_WORKSPACE_FAVORITES_EVENT_TYPE:
       case 'm.direct':

packages/host/tests/integration/matrix-service-realm-servers-test.ts

@@ -0,0 +1,109 @@
+import type { RenderingTestContext } from '@ember/test-helpers';
+
+import { getService } from '@universal-ember/test-support';
+import { module, test } from 'qunit';
+
+import { baseRealm } from '@cardstack/runtime-common';
+
+import type MatrixService from '@cardstack/host/services/matrix-service';
+
+import {
+  testRealmURL,
+  setupIntegrationTestRealm,
+  setupLocalIndexing,
+} from '../helpers';
+
+import { setupBaseRealm } from '../helpers/base-realm';
+
+import { setupMockMatrix } from '../helpers/mock-matrix';
+
+import { setupRenderingTest } from '../helpers/setup';
+
+// CS-11655: the matrix-service exposes read/write helpers for the new
+// `app.boxel.realm-servers` account-data event. These tests round-trip
+// the `{ realmServers }` payload through the mock matrix client and
+// confirm append + remove behave idempotently.
+module(
+  'Integration | matrix-service | realm-servers account data',
+  function (hooks) {
+    setupRenderingTest(hooks);
+    setupLocalIndexing(hooks);
+
+    let mockMatrixUtils = setupMockMatrix(hooks, {
+      loggedInAs: '@testuser:localhost',
+      activeRealms: [baseRealm.url, testRealmURL],
+      autostart: true,
+    });
+
+    setupBaseRealm(hooks);
+
+    hooks.beforeEach(async function (this: RenderingTestContext) {
+      await setupIntegrationTestRealm({
+        mockMatrixUtils,
+        contents: {},
+      });
+    });
+
+    test('get returns empty when no event has been written', async function (assert) {
+      let matrixService = getService('matrix-service') as MatrixService;
+      let servers = await matrixService.getRealmServersFromAccountData();
+      assert.deepEqual(
+        servers,
+        [],
+        'returns an empty array when the event is absent',
+      );
+    });
+
+    test('set then get round-trips the realmServers payload', async function (assert) {
+      let matrixService = getService('matrix-service') as MatrixService;
+      let payload = ['https://server-a.example/', 'https://server-b.example/'];
+
+      await matrixService.setRealmServersInAccountData(payload);
+
+      let read = await matrixService.getRealmServersFromAccountData();
+      assert.deepEqual(read, payload, 'reads back exactly what was written');
+    });
+
+    test('append is idempotent and preserves prior entries', async function (assert) {
+      let matrixService = getService('matrix-service') as MatrixService;
+      let a = 'https://server-a.example/';
+      let b = 'https://server-b.example/';
+
+      await matrixService.appendRealmServerToAccountData(a);
+      await matrixService.appendRealmServerToAccountData(b);
+      // Re-appending an existing server is a no-op.
+      await matrixService.appendRealmServerToAccountData(a);
+
+      assert.deepEqual(
+        await matrixService.getRealmServersFromAccountData(),
+        [a, b],
+        'append preserves order and does not duplicate',
+      );
+    });
+
+    test('remove drops the entry and leaves others intact', async function (assert) {
+      let matrixService = getService('matrix-service') as MatrixService;
+      let a = 'https://server-a.example/';
+      let b = 'https://server-b.example/';
+
+      await matrixService.setRealmServersInAccountData([a, b]);
+      await matrixService.removeRealmServerFromAccountData(a);
+
+      assert.deepEqual(
+        await matrixService.getRealmServersFromAccountData(),
+        [b],
+        'only the targeted server is removed',
+      );
+
+      // Removing something not in the list is a no-op.
+      await matrixService.removeRealmServerFromAccountData(
+        'https://not-present.example/',
+      );
+      assert.deepEqual(
+        await matrixService.getRealmServersFromAccountData(),
+        [b],
+        'removing a non-existent server leaves the list unchanged',
+      );
+    });
+  },
+);

packages/matrix/support/matrix-constants.ts

@@ -11,6 +11,7 @@ export const APP_BOXEL_COMMAND_RESULT_WITH_NO_OUTPUT_MSGTYPE =
 export const APP_BOXEL_REALM_SERVER_EVENT_MSGTYPE =
   'app.boxel.realm-server-event';
 export const APP_BOXEL_REALMS_EVENT_TYPE = 'app.boxel.realms';
+export const APP_BOXEL_REALM_SERVERS_EVENT_TYPE = 'app.boxel.realm-servers';
 export const APP_BOXEL_SYSTEM_CARD_EVENT_TYPE = 'app.boxel.system-card';
 export const APP_BOXEL_CODE_PATCH_CORRECTNESS_MSGTYPE =
   'app.boxel.codePatchCorrectness';

packages/realm-server/handlers/handle-upsert-realm-user-permission.ts

@@ -13,6 +13,7 @@ import {
 import type { CreateRoutesArgs } from '../routes.ts';
 import {
   adminImpersonateUser,
+  appendRealmServerToUserAccountData,
   appendRealmToUserAccountData,
   loginAsMatrixAdmin,
   logoutMatrixAccessToken,
@@ -192,6 +193,19 @@ export default function handleUpsertRealmUserPermission({
             realmURL: normalizedRealmHref,
           });
           appendedToAccountData = !alreadyPresent;
+          // Keep `app.boxel.realm-servers` in lockstep with `app.boxel.realms`
+          // during the source-of-truth transition (CS-11655). Derive the
+          // realm-server origin from the realm URL — the host normalises the
+          // same way via the JWT's `realmServerURL` claim, but JWTs aren't
+          // in scope on this admin-impersonate path.
+          await appendRealmServerToUserAccountData({
+            matrixURL: matrixClient.matrixURL,
+            userId: user,
+            userAccessToken: userToken,
+            realmServerURL: ensureTrailingSlash(
+              new URL(normalizedRealmHref).origin,
+            ),
+          });
         } catch (e: any) {
           matrixAccountDataWarning = `account_data sync failed: ${e?.message ?? String(e)}`;
           log.warn(