@backstage/plugin-signals-node 0.0.0-nightly-20240118021622

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @backstage/plugin-signals-node
+
+## 0.0.0-nightly-20240118021622
+
+### Patch Changes
+
+- 047bead: Add support to subscribe and publish messages through signals plugins
+- Updated dependencies
+  - @backstage/backend-common@0.0.0-nightly-20240118021622
+  - @backstage/config@1.1.1
+  - @backstage/plugin-auth-node@0.0.0-nightly-20240118021622
+  - @backstage/backend-plugin-api@0.0.0-nightly-20240118021622
+  - @backstage/types@1.1.1
+  - @backstage/plugin-events-node@0.0.0-nightly-20240118021622

package/README.md

@@ -0,0 +1,86 @@
+# @backstage/plugin-signals-node
+
+Welcome to the Node.js library package for the signals plugin!
+
+Signals plugin allows backend plugins to publish messages to frontend plugins.
+
+## Getting started
+
+Add SignalService to your plugin environment in `packages/backend/src/types.ts`:
+
+```ts
+import { SignalService } from '@backstage/plugin-signals-node';
+
+export type PluginEnvironment = {
+  // ...
+  signalService: SignalService;
+};
+```
+
+Add it also to your `makeCreateEnv` to allow access from the other plugins:
+
+```ts
+import { SignalService } from '@backstage/plugin-signals-node';
+import { DefaultEventBroker } from '@backstage/plugin-events-backend';
+
+function makeCreateEnv(config: Config) {
+  // ...
+
+  const eventBroker = new DefaultEventBroker(root.child({ type: 'plugin' }));
+  const signalService = DefaultSignalService.create({
+    eventBroker,
+  });
+
+  return (plugin: string): PluginEnvironment => {
+    const logger = root.child({ type: 'plugin', plugin });
+    return {
+      logger,
+      eventBroker,
+      signalService,
+      // ...
+    };
+  };
+}
+```
+
+To allow connections from the frontend, you should also install the `@backstage/plugin-signals-backend`.
+
+## Using the service
+
+Once you have both of the backend plugins installed, you can utilize the signal service by calling the
+`publish` method. This will publish the message to all subscribers in the frontend. To send message to
+all subscribers, you can use `null` as `recipients` parameter.
+
+```ts
+// Periodic sending example
+setInterval(async () => {
+  await signalService.publish({
+    recipients: null,
+    channel: 'my_plugin',
+    message: {
+      message: 'hello world',
+    },
+  });
+}, 5000);
+```
+
+To receive this message in the frontend, check the documentation of `@backstage/plugin-signals` and
+`@backstage/plugin-signals-react`.
+
+## Using event broker directly
+
+Other way to send signals is to utilize the `EventBroker` directly. This requires that the payload is correct for it
+to work:
+
+```ts
+eventBroker.publish({
+  topic: 'signals',
+  eventPayload: {
+    recipients: ['user:default/user1'],
+    message: {
+      message: 'hello world',
+    },
+    channel: 'my_plugin',
+  },
+});
+```

package/dist/index.cjs.js

@@ -0,0 +1,59 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var backendPluginApi = require('@backstage/backend-plugin-api');
+
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+class DefaultSignalService {
+  constructor(options) {
+    // TODO: Remove this to be optional when events-backend has eventBroker as service
+    __publicField(this, "eventBroker");
+    ({ eventBroker: this.eventBroker } = options);
+  }
+  static create(options) {
+    return new DefaultSignalService(options);
+  }
+  /**
+   * Publishes a message to user refs to specific topic
+   * @param recipients - string or array of user ref strings to publish message to
+   * @param topic - message topic
+   * @param message - message to publish
+   */
+  async publish(signal) {
+    var _a;
+    const { recipients, channel, message } = signal;
+    await ((_a = this.eventBroker) == null ? void 0 : _a.publish({
+      topic: "signals",
+      eventPayload: {
+        recipients,
+        message,
+        channel
+      }
+    }));
+  }
+}
+
+const signalService = backendPluginApi.createServiceRef({
+  id: "signals.service",
+  scope: "plugin",
+  defaultFactory: async (service) => backendPluginApi.createServiceFactory({
+    service,
+    deps: {
+      // TODO: EventBroker. It is optional for now but it's actually required so waiting for the new backend system
+      //       for the events-backend for this to work.
+    },
+    factory({}) {
+      return DefaultSignalService.create({});
+    }
+  })
+});
+
+exports.DefaultSignalService = DefaultSignalService;
+exports.signalService = signalService;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":["../src/DefaultSignalService.ts","../src/lib.ts"],"sourcesContent":["/*\n * Copyright 2023 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { EventBroker } from '@backstage/plugin-events-node';\nimport { SignalPayload, SignalServiceOptions } from './types';\nimport { SignalService } from './SignalService';\n\n/** @public */\nexport class DefaultSignalService implements SignalService {\n  // TODO: Remove this to be optional when events-backend has eventBroker as service\n  private eventBroker?: EventBroker;\n\n  static create(options: SignalServiceOptions) {\n    return new DefaultSignalService(options);\n  }\n\n  private constructor(options: SignalServiceOptions) {\n    ({ eventBroker: this.eventBroker } = options);\n  }\n\n  /**\n   * Publishes a message to user refs to specific topic\n   * @param recipients - string or array of user ref strings to publish message to\n   * @param topic - message topic\n   * @param message - message to publish\n   */\n  async publish(signal: SignalPayload) {\n    const { recipients, channel, message } = signal;\n    await this.eventBroker?.publish({\n      topic: 'signals',\n      eventPayload: {\n        recipients,\n        message,\n        channel,\n      },\n    });\n  }\n}\n","/*\n * Copyright 2023 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport {\n  createServiceFactory,\n  createServiceRef,\n} from '@backstage/backend-plugin-api';\nimport { DefaultSignalService } from './DefaultSignalService';\nimport { SignalService } from './SignalService';\n\n/** @public */\nexport const signalService = createServiceRef<SignalService>({\n  id: 'signals.service',\n  scope: 'plugin',\n  defaultFactory: async service =>\n    createServiceFactory({\n      service,\n      deps: {\n        // TODO: EventBroker. It is optional for now but it's actually required so waiting for the new backend system\n        //       for the events-backend for this to work.\n      },\n      factory({}) {\n        return DefaultSignalService.create({});\n      },\n    }),\n});\n"],"names":["createServiceRef","createServiceFactory"],"mappings":";;;;;;;;;;;;AAoBO,MAAM,oBAA8C,CAAA;AAAA,EAQjD,YAAY,OAA+B,EAAA;AANnD;AAAA,IAAQ,aAAA,CAAA,IAAA,EAAA,aAAA,CAAA,CAAA;AAON,IAAA,CAAC,EAAE,WAAA,EAAa,IAAK,CAAA,WAAA,EAAgB,GAAA,OAAA,EAAA;AAAA,GACvC;AAAA,EANA,OAAO,OAAO,OAA+B,EAAA;AAC3C,IAAO,OAAA,IAAI,qBAAqB,OAAO,CAAA,CAAA;AAAA,GACzC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,MAAM,QAAQ,MAAuB,EAAA;AAtCvC,IAAA,IAAA,EAAA,CAAA;AAuCI,IAAA,MAAM,EAAE,UAAA,EAAY,OAAS,EAAA,OAAA,EAAY,GAAA,MAAA,CAAA;AACzC,IAAM,OAAA,CAAA,EAAA,GAAA,IAAA,CAAK,WAAL,KAAA,IAAA,GAAA,KAAA,CAAA,GAAA,EAAA,CAAkB,OAAQ,CAAA;AAAA,MAC9B,KAAO,EAAA,SAAA;AAAA,MACP,YAAc,EAAA;AAAA,QACZ,UAAA;AAAA,QACA,OAAA;AAAA,QACA,OAAA;AAAA,OACF;AAAA,KACF,CAAA,CAAA,CAAA;AAAA,GACF;AACF;;AC1BO,MAAM,gBAAgBA,iCAAgC,CAAA;AAAA,EAC3D,EAAI,EAAA,iBAAA;AAAA,EACJ,KAAO,EAAA,QAAA;AAAA,EACP,cAAA,EAAgB,OAAM,OAAA,KACpBC,qCAAqB,CAAA;AAAA,IACnB,OAAA;AAAA,IACA,IAAM,EAAA;AAAA;AAAA;AAAA,KAGN;AAAA,IACA,OAAA,CAAQ,EAAI,EAAA;AACV,MAAO,OAAA,oBAAA,CAAqB,MAAO,CAAA,EAAE,CAAA,CAAA;AAAA,KACvC;AAAA,GACD,CAAA;AACL,CAAC;;;;;"}

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import * as _backstage_backend_plugin_api from '@backstage/backend-plugin-api';
+import { EventBroker } from '@backstage/plugin-events-node';
+import { JsonObject } from '@backstage/types';
+
+/**
+ * @public
+ */
+type SignalServiceOptions = {
+    eventBroker?: EventBroker;
+};
+/** @public */
+type SignalPayload = {
+    recipients: string[] | null;
+    channel: string;
+    message: JsonObject;
+};
+
+/** @public */
+type SignalService = {
+    /**
+     * Publishes a message to user refs to specific topic
+     */
+    publish(signal: SignalPayload): Promise<void>;
+};
+
+/** @public */
+declare const signalService: _backstage_backend_plugin_api.ServiceRef<SignalService, "plugin">;
+
+/** @public */
+declare class DefaultSignalService implements SignalService {
+    private eventBroker?;
+    static create(options: SignalServiceOptions): DefaultSignalService;
+    private constructor();
+    /**
+     * Publishes a message to user refs to specific topic
+     * @param recipients - string or array of user ref strings to publish message to
+     * @param topic - message topic
+     * @param message - message to publish
+     */
+    publish(signal: SignalPayload): Promise<void>;
+}
+
+export { DefaultSignalService, SignalPayload, SignalService, SignalServiceOptions, signalService };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@backstage/plugin-signals-node",
+  "description": "Node.js library for the signals plugin",
+  "version": "0.0.0-nightly-20240118021622",
+  "main": "dist/index.cjs.js",
+  "types": "dist/index.d.ts",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "node-library"
+  },
+  "scripts": {
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "clean": "backstage-cli package clean",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack"
+  },
+  "devDependencies": {
+    "@backstage/cli": "^0.0.0-nightly-20240118021622",
+    "@types/express": "^4.17.21"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@backstage/backend-common": "^0.0.0-nightly-20240118021622",
+    "@backstage/backend-plugin-api": "^0.0.0-nightly-20240118021622",
+    "@backstage/config": "^1.1.1",
+    "@backstage/plugin-auth-node": "^0.0.0-nightly-20240118021622",
+    "@backstage/plugin-events-node": "^0.0.0-nightly-20240118021622",
+    "@backstage/types": "^1.1.1",
+    "express": "^4.17.1",
+    "uuid": "^8.0.0",
+    "ws": "^8.14.2"
+  }
+}