Merge pull request #24982 from drodil/user_settings_signals

feat: use signals to update user settings over sessions

plugins/user-settings-backend/README.md

@@ -6,13 +6,26 @@ authorization token.
 
 ## Setup backend
 
-1. Install the backend plugin:
+Install the backend plugin
 
 ```bash
 # From your Backstage root directory
 yarn --cwd packages/backend add @backstage/plugin-user-settings-backend
 ```
 
+### New backend
+
+Add the plugin to your backend in `packages/backend/src/index.ts`:
+
+```ts
+backend.add(import('@backstage/plugin-user-settings-backend/alpha'));
+```
+
+To get real-time updates of the user settings across different user sessions, you must also install
+the `@backstage/plugin-signals-backend` plugin.
+
+### Old backend
+
 1. Configure the routes by adding a new `userSettings.ts` file in
    `packages/backend/src/plugins/`:
 
@@ -29,7 +42,7 @@ export default async function createPlugin(env: PluginEnvironment) {
 }
 ```
 
-3. Add the new routes to your backend by modifying `packages/backend/src/index.ts`:
+2. Add the new routes to your backend by modifying `packages/backend/src/index.ts`:
 
 ```diff
  // packages/backend/src/index.ts
@@ -58,6 +71,7 @@ To make use of the user settings backend, replace the `WebStorage` with the
 +  storageApiRef,
  } from '@backstage/core-plugin-api';
 +import { UserSettingsStorage } from '@backstage/plugin-user-settings';
++import { signalApiRef } from '@backstage/plugin-signals-react';
 
  export const apis: AnyApiFactory[] = [
 +  createApiFactory({
@@ -66,7 +80,8 @@ To make use of the user settings backend, replace the `WebStorage` with the
 +      discoveryApi: discoveryApiRef,
 +      errorApi: errorApiRef,
 +      fetchApi: fetchApiRef,
-+      identityApi: identityApiRef
++      identityApi: identityApiRef,
++      signalApi: signalApiRef, // Optional
 +    },
 +    factory: deps => UserSettingsStorage.create(deps),
 +  }),

plugins/user-settings-backend/api-report.md

@@ -6,6 +6,7 @@
 import express from 'express';
 import { IdentityApi } from '@backstage/plugin-auth-node';
 import { PluginDatabaseManager } from '@backstage/backend-common';
+import { SignalsService } from '@backstage/plugin-signals-node';
 
 // @public
 export function createRouter(options: RouterOptions): Promise<express.Router>;
@@ -16,6 +17,8 @@ export interface RouterOptions {
   database: PluginDatabaseManager;
   // (undocumented)
   identity: IdentityApi;
+  // (undocumented)
+  signals?: SignalsService;
 }
 
 // (No @packageDocumentation comment for this package)

plugins/user-settings-backend/package.json

@@ -51,6 +51,8 @@
     "@backstage/config": "workspace:^",
     "@backstage/errors": "workspace:^",
     "@backstage/plugin-auth-node": "workspace:^",
+    "@backstage/plugin-signals-node": "workspace:^",
+    "@backstage/plugin-user-settings-common": "workspace:^",
     "@backstage/types": "workspace:^",
     "@types/express": "^4.17.6",
     "express": "^4.17.1",

plugins/user-settings-backend/src/alpha.ts

@@ -15,10 +15,11 @@
  */
 
 import {
-  createBackendPlugin,
   coreServices,
+  createBackendPlugin,
 } from '@backstage/backend-plugin-api';
 import { createRouter } from './service/router';
+import { signalsServiceRef } from '@backstage/plugin-signals-node';
 
 /**
  * The user settings backend plugin.
@@ -33,9 +34,10 @@ export default createBackendPlugin({
         database: coreServices.database,
         identity: coreServices.identity,
         httpRouter: coreServices.httpRouter,
+        signals: signalsServiceRef,
       },
-      async init({ database, identity, httpRouter }) {
-        httpRouter.use(await createRouter({ database, identity }));
+      async init({ database, identity, httpRouter, signals }) {
+        httpRouter.use(await createRouter({ database, identity, signals }));
       },
     });
   },

plugins/user-settings-backend/src/service/router.test.ts

@@ -22,6 +22,7 @@ import express from 'express';
 import request from 'supertest';
 import { UserSettingsStore } from '../database/UserSettingsStore';
 import { createRouterInternal } from './router';
+import { SignalsService } from '@backstage/plugin-signals-node';
 
 describe('createRouter', () => {
   const userSettingsStore: jest.Mocked<UserSettingsStore> = {
@@ -36,6 +37,9 @@ describe('createRouter', () => {
   const identityApi: jest.Mocked<Partial<IdentityApi>> = {
     getIdentity: getIdentityMock,
   };
+  const signalService: jest.Mocked<SignalsService> = {
+    publish: jest.fn(),
+  };
 
   let app: express.Express;
 
@@ -43,6 +47,7 @@ describe('createRouter', () => {
     const router = await createRouterInternal({
       userSettingsStore,
       identity: identityApi as IdentityApi,
+      signals: signalService as SignalsService,
     });
 
     app = express().use(router);
@@ -118,6 +123,11 @@ describe('createRouter', () => {
         bucket: 'my-bucket',
         key: 'my-key',
       });
+      expect(signalService.publish).toHaveBeenCalledWith({
+        recipients: { type: 'user', entityRef: 'user-1' },
+        channel: `user-settings`,
+        message: { type: 'key-deleted', key: 'my-key' },
+      });
     });
 
     it('returns an error if the Authorization header is missing', async () => {
@@ -167,6 +177,11 @@ describe('createRouter', () => {
         bucket: 'my-bucket',
         key: 'my-key',
       });
+      expect(signalService.publish).toHaveBeenCalledWith({
+        recipients: { type: 'user', entityRef: 'user-1' },
+        channel: `user-settings`,
+        message: { type: 'key-changed', key: 'my-key' },
+      });
     });
 
     it('returns an error if the value is not given', async () => {

plugins/user-settings-backend/src/service/router.ts

@@ -21,6 +21,8 @@ import express, { Request } from 'express';
 import Router from 'express-promise-router';
 import { DatabaseUserSettingsStore } from '../database/DatabaseUserSettingsStore';
 import { UserSettingsStore } from '../database/UserSettingsStore';
+import { SignalsService } from '@backstage/plugin-signals-node';
+import { UserSettingsSignal } from '@backstage/plugin-user-settings-common';
 
 /**
  * @public
@@ -28,6 +30,7 @@ import { UserSettingsStore } from '../database/UserSettingsStore';
 export interface RouterOptions {
   database: PluginDatabaseManager;
   identity: IdentityApi;
+  signals?: SignalsService;
 }
 
 /**
@@ -45,12 +48,14 @@ export async function createRouter(
   return await createRouterInternal({
     userSettingsStore,
     identity: options.identity,
+    signals: options.signals,
   });
 }
 
 export async function createRouterInternal(options: {
   identity: IdentityApi;
   userSettingsStore: UserSettingsStore;
+  signals?: SignalsService;
 }): Promise<express.Router> {
   const router = Router();
   router.use(express.json());
@@ -104,6 +109,14 @@ export async function createRouterInternal(options: {
       key,
     });
 
+    if (options.signals) {
+      await options.signals.publish<UserSettingsSignal>({
+        recipients: { type: 'user', entityRef: userEntityRef },
+        channel: `user-settings`,
+        message: { type: 'key-changed', key },
+      });
+    }
+
     res.json(setting);
   });
 
@@ -113,6 +126,13 @@ export async function createRouterInternal(options: {
     const { bucket, key } = req.params;
 
     await options.userSettingsStore.delete({ userEntityRef, bucket, key });
+    if (options.signals) {
+      await options.signals.publish<UserSettingsSignal>({
+        recipients: { type: 'user', entityRef: userEntityRef },
+        channel: 'user-settings',
+        message: { type: 'key-deleted', key },
+      });
+    }
 
     res.status(204).end();
   });