@backstage/plugin-events-node 0.2.20 → 0.3.0-next.0

package/CHANGELOG.md

@@ -1,11 +1,115 @@
 # @backstage/plugin-events-node
 
-## 0.2.20
+## 0.3.0-next.0
 
-### Patch Changes
+### Minor Changes
 
-- Updated dependencies
-  - @backstage/backend-plugin-api@0.6.11
+- eff3ca9: BREAKING CHANGE: Migrate `EventRouter` implementations from `EventBroker` to `EventsService`.
+
+  `EventRouter` uses the new `EventsService` instead of the `EventBroker` now,
+  causing a breaking change to its signature.
+
+  All of its extensions and implementations got adjusted accordingly.
+  (`SubTopicEventRouter`, `AzureDevOpsEventRouter`, `BitbucketCloudEventRouter`,
+  `GerritEventRouter`, `GithubEventRouter`, `GitlabEventRouter`)
+
+  Required adjustments were made to all backend modules for the new backend system,
+  now also making use of the `eventsServiceRef` instead of the `eventsExtensionPoint`.
+
+  **Migration:**
+
+  Example for implementations of `SubTopicEventRouter`:
+
+  ```diff
+    import {
+      EventParams,
+  +   EventsService,
+      SubTopicEventRouter,
+    } from '@backstage/plugin-events-node';
+
+    export class GithubEventRouter extends SubTopicEventRouter {
+  -   constructor() {
+  -     super('github');
+  +   constructor(options: { events: EventsService }) {
+  +     super({
+  +       events: options.events,
+  +       topic: 'github',
+  +     });
+      }
+
+  +   protected getSubscriberId(): string {
+  +     return 'GithubEventRouter';
+  +   }
+  +
+      // ...
+    }
+  ```
+
+  Example for a direct extension of `EventRouter`:
+
+  ```diff
+    class MyEventRouter extends EventRouter {
+  -   constructor(/* ... */) {
+  +   constructor(options: {
+  +     events: EventsService;
+  +     // ...
+  +   }) {
+  -     super();
+        // ...
+  +     super({
+  +       events: options.events,
+  +       topics: topics,
+  +     });
+      }
+  +
+  +   protected getSubscriberId(): string {
+  +     return 'MyEventRouter';
+  +   }
+  -
+  -   supportsEventTopics(): string[] {
+  -     return this.topics;
+  -   }
+    }
+  ```
+
+### Patch Changes
+
+- 56969b6: Add new `EventsService` as well as `eventsServiceRef` for the new backend system.
+
+  **Summary:**
+
+  - new:
+    `EventsService`, `eventsServiceRef`, `TestEventsService`
+  - deprecated:
+    `EventBroker`, `EventPublisher`, `EventSubscriber`, `DefaultEventBroker`, `EventsBackend`,
+    most parts of `EventsExtensionPoint` (alpha),
+    `TestEventBroker`, `TestEventPublisher`, `TestEventSubscriber`
+
+  Add the `eventsServiceRef` as dependency to your backend plugins
+  or backend plugin modules.
+
+  **Details:**
+
+  The previous implementation using the `EventsExtensionPoint` was added in the early stages
+  of the new backend system and does not respect the plugin isolation.
+  This made it not compatible anymore with the new backend system.
+
+  Additionally, the previous interfaces had some room for simplification,
+  supporting less exposure of internal concerns as well.
+
+  Hereby, this change adds a new `EventsService` interface as replacement for the now deprecated `EventBroker`.
+  The new interface does not require any `EventPublisher` or `EventSubscriber` interfaces anymore.
+  Instead, it is expected that the `EventsService` gets passed into publishers and subscribers,
+  and used internally. There is no need to expose anything of that at their own interfaces.
+
+  Most parts of `EventsExtensionPoint` (alpha) are deprecated as well and were not usable
+  (by other plugins or their modules) anyway.
+
+  The `DefaultEventBroker` implementation is deprecated and wraps the new `DefaultEventsService` implementation.
+  Optionally, an instance can be passed as argument to allow mixed setups to operate alongside.
+
+- Updated dependencies
+  - @backstage/backend-plugin-api@0.6.13-next.0
 
 ## 0.2.19
 

package/README.md

@@ -1,3 +1,82 @@
-# plugin-events-node
+# `@backstage/plugin-events-node`
 
-Houses types and utilities for building events-related modules.
+This package defined basic types for event-based interactions inside of Backstage.
+
+Additionally, it provides the core event service `eventsServiceRef` of type `EventsService`
+with its default implementation that uses the `DefaultEventsService` implementation.
+
+`DefaultEventsService` is a simple in-memory implementation
+that requires the co-deployment of producers and consumers of events.
+
+## Installation
+
+Add `@backstage/plugin-events-node` as dependency to your plugin or plugin module package
+to which you want to add event support.
+
+Use `eventsServiceRef` as a dependency at your plugin or plugin module.
+
+### Legacy Backend System
+
+Create an `EventsService` instance and add it to the environment.
+
+```ts
+// packages/backend/src/plugins/events.ts
+import { DefaultEventsService } from '@backstage/plugin-events-node';
+
+// ...
+
+function makeCreateEnv(config: Config) {
+  // ...
+  const eventsService = DefaultEventsService.create({ logger: root });
+  // ...
+  return (plugin: string): PluginEnvironment => {
+    // ...
+    return {
+      // ...
+      events: eventsService,
+      // ...
+    };
+  };
+}
+```
+
+Use the `events` from the `PluginEnvironment` as desired:
+
+```ts
+// packages/backend/src/plugins/events.ts
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
+  // ...
+  env.events; // ...
+  // ...
+}
+```
+
+## Use Case
+
+### Exchange service implementation
+
+Create your custom service factory implementation:
+
+```ts
+import { eventsServiceRef } from '@backstage/plugin-events-node';
+// ...
+export const customEventsServiceFactory = createServiceFactory({
+  service: eventsServiceRef,
+  deps: {
+    // add needed dependencies here
+  },
+  async factory({ logger }) {
+    // add your custom logic here
+    return customEventsService;
+  },
+});
+```
+
+and your custom implementation:
+
+```diff
+// packages/backend/src/index.ts
++  backend.add(customEventsServiceFactory());
+```

package/alpha/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-events-node",
-  "version": "0.2.20",
+  "version": "0.3.0-next.0",
   "main": "../dist/alpha.cjs.js",
   "types": "../dist/alpha.d.ts"
 }

package/dist/alpha.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"alpha.cjs.js","sources":["../src/extensions.ts"],"sourcesContent":["/*\n * Copyright 2022 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 */\n\nimport { createExtensionPoint } from '@backstage/backend-plugin-api';\nimport {\n  EventBroker,\n  EventPublisher,\n  EventSubscriber,\n  HttpPostIngressOptions,\n} from '@backstage/plugin-events-node';\n\n/**\n * @alpha\n */\nexport interface EventsExtensionPoint {\n  setEventBroker(eventBroker: EventBroker): void;\n\n  addPublishers(\n    ...publishers: Array<EventPublisher | Array<EventPublisher>>\n  ): void;\n\n  addSubscribers(\n    ...subscribers: Array<EventSubscriber | Array<EventSubscriber>>\n  ): void;\n\n  addHttpPostIngress(options: HttpPostIngressOptions): void;\n}\n\n/**\n * @alpha\n */\nexport const eventsExtensionPoint = createExtensionPoint<EventsExtensionPoint>({\n  id: 'events',\n});\n"],"names":["createExtensionPoint"],"mappings":";;;;;;AA4CO,MAAM,uBAAuBA,qCAA2C,CAAA;AAAA,EAC7E,EAAI,EAAA,QAAA;AACN,CAAC;;;;"}
+{"version":3,"file":"alpha.cjs.js","sources":["../src/extensions.ts"],"sourcesContent":["/*\n * Copyright 2022 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 */\n\nimport { createExtensionPoint } from '@backstage/backend-plugin-api';\nimport {\n  EventBroker,\n  EventPublisher,\n  EventSubscriber,\n  HttpPostIngressOptions,\n} from '@backstage/plugin-events-node';\n\n/**\n * @alpha\n */\nexport interface EventsExtensionPoint {\n  /**\n   * @deprecated use `eventsServiceRef` and `eventsServiceFactory` instead\n   */\n  setEventBroker(eventBroker: EventBroker): void;\n\n  /**\n   * @deprecated use `EventsService.publish` instead\n   */\n  addPublishers(\n    ...publishers: Array<EventPublisher | Array<EventPublisher>>\n  ): void;\n\n  /**\n   * @deprecated use `EventsService.subscribe` instead\n   */\n  addSubscribers(\n    ...subscribers: Array<EventSubscriber | Array<EventSubscriber>>\n  ): void;\n\n  addHttpPostIngress(options: HttpPostIngressOptions): void;\n}\n\n/**\n * @alpha\n */\nexport const eventsExtensionPoint = createExtensionPoint<EventsExtensionPoint>({\n  id: 'events',\n});\n"],"names":["createExtensionPoint"],"mappings":";;;;;;AAqDO,MAAM,uBAAuBA,qCAA2C,CAAA;AAAA,EAC7E,EAAI,EAAA,QAAA;AACN,CAAC;;;;"}

package/dist/alpha.d.ts

@@ -5,8 +5,17 @@ import { EventBroker, EventPublisher, EventSubscriber, HttpPostIngressOptions }
  * @alpha
  */
 interface EventsExtensionPoint {
+    /**
+     * @deprecated use `eventsServiceRef` and `eventsServiceFactory` instead
+     */
     setEventBroker(eventBroker: EventBroker): void;
+    /**
+     * @deprecated use `EventsService.publish` instead
+     */
     addPublishers(...publishers: Array<EventPublisher | Array<EventPublisher>>): void;
+    /**
+     * @deprecated use `EventsService.subscribe` instead
+     */
     addSubscribers(...subscribers: Array<EventSubscriber | Array<EventSubscriber>>): void;
     addHttpPostIngress(options: HttpPostIngressOptions): void;
 }

package/dist/index.cjs.js

@@ -2,46 +2,156 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-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);
+var backendPluginApi = require('@backstage/backend-plugin-api');
+
+var __defProp$1 = Object.defineProperty;
+var __defNormalProp$1 = (obj, key, value) => key in obj ? __defProp$1(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$1 = (obj, key, value) => {
+  __defNormalProp$1(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
 };
 class EventRouter {
-  constructor() {
-    __publicField(this, "eventBroker");
+  constructor(options) {
+    __publicField$1(this, "events");
+    __publicField$1(this, "topics");
+    __publicField$1(this, "subscribed", false);
+    this.events = options.events;
+    this.topics = options.topics;
+  }
+  /**
+   * Subscribes itself to the topic(s),
+   * after which events potentially can be received
+   * and processed by {@link EventRouter.onEvent}.
+   */
+  async subscribe() {
+    if (this.subscribed) {
+      return;
+    }
+    this.subscribed = true;
+    await this.events.subscribe({
+      id: this.getSubscriberId(),
+      topics: this.topics,
+      onEvent: this.onEvent.bind(this)
+    });
   }
   async onEvent(params) {
-    var _a;
     const topic = this.determineDestinationTopic(params);
     if (!topic) {
       return;
     }
-    (_a = this.eventBroker) == null ? void 0 : _a.publish({
+    await this.events.publish({
       ...params,
       topic
     });
   }
-  async setEventBroker(eventBroker) {
-    this.eventBroker = eventBroker;
+}
+
+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 DefaultEventsService {
+  constructor(logger) {
+    this.logger = logger;
+    __publicField(this, "subscribers", /* @__PURE__ */ new Map());
+  }
+  static create(options) {
+    return new DefaultEventsService(options.logger);
+  }
+  /**
+   * Returns a plugin-scoped context of the `EventService`
+   * that ensures to prefix subscriber IDs with the plugin ID.
+   *
+   * @param pluginId - The plugin that the `EventService` should be created for.
+   */
+  forPlugin(pluginId) {
+    return {
+      publish: (params) => {
+        return this.publish(params);
+      },
+      subscribe: (options) => {
+        return this.subscribe({
+          ...options,
+          id: `${pluginId}.${options.id}`
+        });
+      }
+    };
+  }
+  async publish(params) {
+    var _a;
+    this.logger.debug(
+      `Event received: topic=${params.topic}, metadata=${JSON.stringify(
+        params.metadata
+      )}, payload=${JSON.stringify(params.eventPayload)}`
+    );
+    if (!this.subscribers.has(params.topic)) {
+      return;
+    }
+    const onEventPromises = [];
+    (_a = this.subscribers.get(params.topic)) == null ? void 0 : _a.forEach((subscription) => {
+      onEventPromises.push(
+        (async () => {
+          try {
+            await subscription.onEvent(params);
+          } catch (error) {
+            this.logger.warn(
+              `Subscriber "${subscription.id}" failed to process event for topic "${params.topic}"`,
+              error
+            );
+          }
+        })()
+      );
+    });
+    await Promise.all(onEventPromises);
+  }
+  async subscribe(options) {
+    options.topics.forEach((topic) => {
+      if (!this.subscribers.has(topic)) {
+        this.subscribers.set(topic, []);
+      }
+      this.subscribers.get(topic).push({
+        id: options.id,
+        onEvent: options.onEvent
+      });
+    });
   }
 }
 
 class SubTopicEventRouter extends EventRouter {
-  constructor(topic) {
-    super();
-    this.topic = topic;
+  constructor(options) {
+    super({
+      events: options.events,
+      topics: [options.topic]
+    });
   }
   determineDestinationTopic(params) {
     const subTopic = this.determineSubTopic(params);
     return subTopic ? `${params.topic}.${subTopic}` : void 0;
   }
-  supportsEventTopics() {
-    return [this.topic];
-  }
 }
 
+const eventsServiceRef = backendPluginApi.createServiceRef({
+  id: "events.service",
+  scope: "plugin",
+  defaultFactory: async (service) => backendPluginApi.createServiceFactory({
+    service,
+    deps: {
+      pluginMetadata: backendPluginApi.coreServices.pluginMetadata,
+      rootLogger: backendPluginApi.coreServices.rootLogger
+    },
+    async createRootContext({ rootLogger }) {
+      return DefaultEventsService.create({ logger: rootLogger });
+    },
+    async factory({ pluginMetadata }, eventsService) {
+      return eventsService.forPlugin(pluginMetadata.getId());
+    }
+  })
+});
+
+exports.DefaultEventsService = DefaultEventsService;
 exports.EventRouter = EventRouter;
 exports.SubTopicEventRouter = SubTopicEventRouter;
+exports.eventsServiceRef = eventsServiceRef;
 //# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs.js","sources":["../src/api/EventRouter.ts","../src/api/SubTopicEventRouter.ts"],"sourcesContent":["/*\n * Copyright 2022 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 */\n\nimport { EventBroker } from './EventBroker';\nimport { EventParams } from './EventParams';\nimport { EventPublisher } from './EventPublisher';\nimport { EventSubscriber } from './EventSubscriber';\n\n/**\n * Subscribes to a topic and - depending on a set of conditions -\n * republishes the event to another topic.\n *\n * @see {@link https://www.enterpriseintegrationpatterns.com/MessageRouter.html | Message Router pattern}.\n * @public\n */\nexport abstract class EventRouter implements EventPublisher, EventSubscriber {\n  private eventBroker?: EventBroker;\n\n  protected abstract determineDestinationTopic(\n    params: EventParams,\n  ): string | undefined;\n\n  async onEvent(params: EventParams): Promise<void> {\n    const topic = this.determineDestinationTopic(params);\n\n    if (!topic) {\n      return;\n    }\n\n    // republish to different topic\n    this.eventBroker?.publish({\n      ...params,\n      topic,\n    });\n  }\n\n  async setEventBroker(eventBroker: EventBroker): Promise<void> {\n    this.eventBroker = eventBroker;\n  }\n\n  abstract supportsEventTopics(): string[];\n}\n","/*\n * Copyright 2022 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 */\n\nimport { EventParams } from './EventParams';\nimport { EventRouter } from './EventRouter';\n\n/**\n * Subscribes to the provided (generic) topic\n * and publishes the events under the more concrete sub-topic\n * depending on the implemented logic for determining it.\n * Implementing classes might use information from `metadata`\n * and/or properties within the payload.\n *\n * @public\n */\nexport abstract class SubTopicEventRouter extends EventRouter {\n  protected constructor(private readonly topic: string) {\n    super();\n  }\n\n  protected abstract determineSubTopic(params: EventParams): string | undefined;\n\n  protected determineDestinationTopic(params: EventParams): string | undefined {\n    const subTopic = this.determineSubTopic(params);\n    return subTopic ? `${params.topic}.${subTopic}` : undefined;\n  }\n\n  supportsEventTopics(): string[] {\n    return [this.topic];\n  }\n}\n"],"names":[],"mappings":";;;;;;;;;;AA4BO,MAAe,WAAuD,CAAA;AAAA,EAAtE,WAAA,GAAA;AACL,IAAQ,aAAA,CAAA,IAAA,EAAA,aAAA,CAAA,CAAA;AAAA,GAAA;AAAA,EAMR,MAAM,QAAQ,MAAoC,EAAA;AAnCpD,IAAA,IAAA,EAAA,CAAA;AAoCI,IAAM,MAAA,KAAA,GAAQ,IAAK,CAAA,yBAAA,CAA0B,MAAM,CAAA,CAAA;AAEnD,IAAA,IAAI,CAAC,KAAO,EAAA;AACV,MAAA,OAAA;AAAA,KACF;AAGA,IAAK,CAAA,EAAA,GAAA,IAAA,CAAA,WAAA,KAAL,mBAAkB,OAAQ,CAAA;AAAA,MACxB,GAAG,MAAA;AAAA,MACH,KAAA;AAAA,KACF,CAAA,CAAA;AAAA,GACF;AAAA,EAEA,MAAM,eAAe,WAAyC,EAAA;AAC5D,IAAA,IAAA,CAAK,WAAc,GAAA,WAAA,CAAA;AAAA,GACrB;AAGF;;AC1BO,MAAe,4BAA4B,WAAY,CAAA;AAAA,EAClD,YAA6B,KAAe,EAAA;AACpD,IAAM,KAAA,EAAA,CAAA;AAD+B,IAAA,IAAA,CAAA,KAAA,GAAA,KAAA,CAAA;AAAA,GAEvC;AAAA,EAIU,0BAA0B,MAAyC,EAAA;AAC3E,IAAM,MAAA,QAAA,GAAW,IAAK,CAAA,iBAAA,CAAkB,MAAM,CAAA,CAAA;AAC9C,IAAA,OAAO,WAAW,CAAG,EAAA,MAAA,CAAO,KAAK,CAAA,CAAA,EAAI,QAAQ,CAAK,CAAA,GAAA,KAAA,CAAA,CAAA;AAAA,GACpD;AAAA,EAEA,mBAAgC,GAAA;AAC9B,IAAO,OAAA,CAAC,KAAK,KAAK,CAAA,CAAA;AAAA,GACpB;AACF;;;;;"}
+{"version":3,"file":"index.cjs.js","sources":["../src/api/EventRouter.ts","../src/api/DefaultEventsService.ts","../src/api/SubTopicEventRouter.ts","../src/service.ts"],"sourcesContent":["/*\n * Copyright 2022 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 */\n\nimport { EventParams } from './EventParams';\nimport { EventsService } from './EventsService';\n\n/**\n * Subscribes to a topic and - depending on a set of conditions -\n * republishes the event to another topic.\n *\n * @see {@link https://www.enterpriseintegrationpatterns.com/MessageRouter.html | Message Router pattern}.\n * @public\n */\nexport abstract class EventRouter {\n  private readonly events: EventsService;\n  private readonly topics: string[];\n  private subscribed: boolean = false;\n\n  protected constructor(options: { events: EventsService; topics: string[] }) {\n    this.events = options.events;\n    this.topics = options.topics;\n  }\n\n  protected abstract getSubscriberId(): string;\n\n  protected abstract determineDestinationTopic(\n    params: EventParams,\n  ): string | undefined;\n\n  /**\n   * Subscribes itself to the topic(s),\n   * after which events potentially can be received\n   * and processed by {@link EventRouter.onEvent}.\n   */\n  async subscribe(): Promise<void> {\n    if (this.subscribed) {\n      return;\n    }\n\n    this.subscribed = true;\n\n    await this.events.subscribe({\n      id: this.getSubscriberId(),\n      topics: this.topics,\n      onEvent: this.onEvent.bind(this),\n    });\n  }\n\n  async onEvent(params: EventParams): Promise<void> {\n    const topic = this.determineDestinationTopic(params);\n\n    if (!topic) {\n      return;\n    }\n\n    // republish to different topic\n    await this.events.publish({\n      ...params,\n      topic,\n    });\n  }\n}\n","/*\n * Copyright 2024 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 */\n\nimport { LoggerService } from '@backstage/backend-plugin-api';\nimport { EventParams } from './EventParams';\nimport { EventsService, EventsServiceSubscribeOptions } from './EventsService';\n\n/**\n * In-process event broker which will pass the event to all registered subscribers\n * interested in it.\n * Events will not be persisted in any form.\n * Events will not be passed to subscribers at other instances of the same cluster.\n *\n * @public\n */\n// TODO(pjungermann): add opentelemetry? (see plugins/catalog-backend/src/util/opentelemetry.ts, etc.)\nexport class DefaultEventsService implements EventsService {\n  private readonly subscribers = new Map<\n    string,\n    Omit<EventsServiceSubscribeOptions, 'topics'>[]\n  >();\n\n  private constructor(private readonly logger: LoggerService) {}\n\n  static create(options: { logger: LoggerService }): DefaultEventsService {\n    return new DefaultEventsService(options.logger);\n  }\n\n  /**\n   * Returns a plugin-scoped context of the `EventService`\n   * that ensures to prefix subscriber IDs with the plugin ID.\n   *\n   * @param pluginId - The plugin that the `EventService` should be created for.\n   */\n  forPlugin(pluginId: string): EventsService {\n    return {\n      publish: (params: EventParams): Promise<void> => {\n        return this.publish(params);\n      },\n      subscribe: (options: EventsServiceSubscribeOptions): Promise<void> => {\n        return this.subscribe({\n          ...options,\n          id: `${pluginId}.${options.id}`,\n        });\n      },\n    };\n  }\n\n  async publish(params: EventParams): Promise<void> {\n    this.logger.debug(\n      `Event received: topic=${params.topic}, metadata=${JSON.stringify(\n        params.metadata,\n      )}, payload=${JSON.stringify(params.eventPayload)}`,\n    );\n\n    if (!this.subscribers.has(params.topic)) {\n      return;\n    }\n\n    const onEventPromises: Promise<void>[] = [];\n    this.subscribers.get(params.topic)?.forEach(subscription => {\n      onEventPromises.push(\n        (async () => {\n          try {\n            await subscription.onEvent(params);\n          } catch (error) {\n            this.logger.warn(\n              `Subscriber \"${subscription.id}\" failed to process event for topic \"${params.topic}\"`,\n              error,\n            );\n          }\n        })(),\n      );\n    });\n\n    await Promise.all(onEventPromises);\n  }\n\n  async subscribe(options: EventsServiceSubscribeOptions): Promise<void> {\n    options.topics.forEach(topic => {\n      if (!this.subscribers.has(topic)) {\n        this.subscribers.set(topic, []);\n      }\n\n      this.subscribers.get(topic)!.push({\n        id: options.id,\n        onEvent: options.onEvent,\n      });\n    });\n  }\n}\n","/*\n * Copyright 2022 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 */\n\nimport { EventParams } from './EventParams';\nimport { EventRouter } from './EventRouter';\nimport { EventsService } from './EventsService';\n\n/**\n * Subscribes to the provided (generic) topic\n * and publishes the events under the more concrete sub-topic\n * depending on the implemented logic for determining it.\n * Implementing classes might use information from `metadata`\n * and/or properties within the payload.\n *\n * @public\n */\nexport abstract class SubTopicEventRouter extends EventRouter {\n  protected constructor(options: { events: EventsService; topic: string }) {\n    super({\n      events: options.events,\n      topics: [options.topic],\n    });\n  }\n\n  protected abstract determineSubTopic(params: EventParams): string | undefined;\n\n  protected determineDestinationTopic(params: EventParams): string | undefined {\n    const subTopic = this.determineSubTopic(params);\n    return subTopic ? `${params.topic}.${subTopic}` : undefined;\n  }\n}\n","/*\n * Copyright 2024 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 */\n\nimport {\n  coreServices,\n  createServiceFactory,\n  createServiceRef,\n} from '@backstage/backend-plugin-api';\nimport { EventsService, DefaultEventsService } from './api';\n\n/**\n * The {@link EventsService} that allows to publish events, and subscribe to topics.\n * Uses the `root` scope so that events can be shared across all plugins, modules, and more.\n *\n * @public\n */\nexport const eventsServiceRef = createServiceRef<EventsService>({\n  id: 'events.service',\n  scope: 'plugin',\n  defaultFactory: async service =>\n    createServiceFactory({\n      service,\n      deps: {\n        pluginMetadata: coreServices.pluginMetadata,\n        rootLogger: coreServices.rootLogger,\n      },\n      async createRootContext({ rootLogger }) {\n        return DefaultEventsService.create({ logger: rootLogger });\n      },\n      async factory({ pluginMetadata }, eventsService) {\n        return eventsService.forPlugin(pluginMetadata.getId());\n      },\n    }),\n});\n"],"names":["__publicField","createServiceRef","createServiceFactory","coreServices"],"mappings":"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"}

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import * as _backstage_backend_plugin_api from '@backstage/backend-plugin-api';
+import { LoggerService } from '@backstage/backend-plugin-api';
+
 /**
  * @public
  */
@@ -16,26 +19,6 @@ interface EventParams<TPayload = unknown> {
     metadata?: Record<string, string | string[] | undefined>;
 }
 
-/**
- * Handles received events.
- * This may include triggering refreshes of catalog entities
- * or other actions to react on events.
- *
- * @public
- */
-interface EventSubscriber {
-    /**
-     * Supported event topics like "github", "bitbucketCloud", etc.
-     */
-    supportsEventTopics(): string[];
-    /**
-     * React on a received event.
-     *
-     * @param params - parameters for the to be received event.
-     */
-    onEvent(params: EventParams): Promise<void>;
-}
-
 /**
  * Allows a decoupled and asynchronous communication between components.
  * Components can publish events for a given topic and
@@ -43,7 +26,7 @@ interface EventSubscriber {
  *
  * @public
  */
-interface EventBroker {
+interface EventsService {
     /**
      * Publishes an event for the topic.
      *
@@ -51,24 +34,27 @@ interface EventBroker {
      */
     publish(params: EventParams): Promise<void>;
     /**
-     * Adds new subscribers for {@link EventSubscriber#supportsEventTopics | interested topics}.
+     * Subscribes to one or more topics, registering an event handler for them.
      *
-     * @param subscribers - interested in events of specified topics.
+     * @param options - event subscription options.
      */
-    subscribe(...subscribers: Array<EventSubscriber | Array<EventSubscriber>>): void;
+    subscribe(options: EventsServiceSubscribeOptions): Promise<void>;
 }
-
 /**
- * Publishes events to be consumed by subscribers for their topic.
- * The events can come from different (external) sources
- * like emitted themselves, received via HTTP endpoint (i.e. webhook)
- * or from event brokers, queues, etc.
- *
  * @public
  */
-interface EventPublisher {
-    setEventBroker(eventBroker: EventBroker): Promise<void>;
-}
+type EventsServiceSubscribeOptions = {
+    /**
+     * Identifier for the subscription. E.g., used as part of log messages.
+     */
+    id: string;
+    topics: string[];
+    onEvent: EventsServiceEventHandler;
+};
+/**
+ * @public
+ */
+type EventsServiceEventHandler = (params: EventParams) => Promise<void>;
 
 /**
  * Subscribes to a topic and - depending on a set of conditions -
@@ -77,12 +63,49 @@ interface EventPublisher {
  * @see {@link https://www.enterpriseintegrationpatterns.com/MessageRouter.html | Message Router pattern}.
  * @public
  */
-declare abstract class EventRouter implements EventPublisher, EventSubscriber {
-    private eventBroker?;
+declare abstract class EventRouter {
+    private readonly events;
+    private readonly topics;
+    private subscribed;
+    protected constructor(options: {
+        events: EventsService;
+        topics: string[];
+    });
+    protected abstract getSubscriberId(): string;
     protected abstract determineDestinationTopic(params: EventParams): string | undefined;
+    /**
+     * Subscribes itself to the topic(s),
+     * after which events potentially can be received
+     * and processed by {@link EventRouter.onEvent}.
+     */
+    subscribe(): Promise<void>;
     onEvent(params: EventParams): Promise<void>;
-    setEventBroker(eventBroker: EventBroker): Promise<void>;
-    abstract supportsEventTopics(): string[];
+}
+
+/**
+ * In-process event broker which will pass the event to all registered subscribers
+ * interested in it.
+ * Events will not be persisted in any form.
+ * Events will not be passed to subscribers at other instances of the same cluster.
+ *
+ * @public
+ */
+declare class DefaultEventsService implements EventsService {
+    private readonly logger;
+    private readonly subscribers;
+    private constructor();
+    static create(options: {
+        logger: LoggerService;
+    }): DefaultEventsService;
+    /**
+     * Returns a plugin-scoped context of the `EventService`
+     * that ensures to prefix subscriber IDs with the plugin ID.
+     *
+     * @param pluginId - The plugin that the `EventService` should be created for.
+     */
+    forPlugin(pluginId: string): EventsService;
+    publish(params: EventParams): Promise<void>;
+    subscribe(options: EventsServiceSubscribeOptions): Promise<void>;
 }
 
 /**
@@ -156,11 +179,83 @@ interface HttpPostIngressOptions {
  * @public
  */
 declare abstract class SubTopicEventRouter extends EventRouter {
-    private readonly topic;
-    protected constructor(topic: string);
+    protected constructor(options: {
+        events: EventsService;
+        topic: string;
+    });
     protected abstract determineSubTopic(params: EventParams): string | undefined;
     protected determineDestinationTopic(params: EventParams): string | undefined;
+}
+
+/**
+ * Handles received events.
+ * This may include triggering refreshes of catalog entities
+ * or other actions to react on events.
+ *
+ * @public
+ * @deprecated use the `EventsService` via the constructor, setter, or other means instead
+ */
+interface EventSubscriber {
+    /**
+     * Supported event topics like "github", "bitbucketCloud", etc.
+     *
+     * @deprecated use the `EventsService` via the constructor, setter, or other means instead
+     */
     supportsEventTopics(): string[];
+    /**
+     * React on a received event.
+     *
+     * @param params - parameters for the to be received event.
+     * @deprecated you are not required to expose this anymore when using `EventsService`
+     */
+    onEvent(params: EventParams): Promise<void>;
+}
+
+/**
+ * Allows a decoupled and asynchronous communication between components.
+ * Components can publish events for a given topic and
+ * others can subscribe for future events for topics they are interested in.
+ *
+ * @public
+ * @deprecated use `EventsService` instead
+ */
+interface EventBroker {
+    /**
+     * Publishes an event for the topic.
+     *
+     * @param params - parameters for the to be published event.
+     */
+    publish(params: EventParams): Promise<void>;
+    /**
+     * Adds new subscribers for {@link EventSubscriber#supportsEventTopics | interested topics}.
+     *
+     * @param subscribers - interested in events of specified topics.
+     */
+    subscribe(...subscribers: Array<EventSubscriber | Array<EventSubscriber>>): void;
+}
+
+/**
+ * Publishes events to be consumed by subscribers for their topic.
+ * The events can come from different (external) sources
+ * like emitted themselves, received via HTTP endpoint (i.e. webhook)
+ * or from event brokers, queues, etc.
+ *
+ * @public
+ * @deprecated use the `EventsService` via the constructor, setter, or other means instead
+ */
+interface EventPublisher {
+    /**
+     * @deprecated use the `EventsService` via the constructor, setter, or other means instead
+     */
+    setEventBroker(eventBroker: EventBroker): Promise<void>;
 }
 
-export { EventBroker, EventParams, EventPublisher, EventRouter, EventSubscriber, HttpPostIngressOptions, RequestDetails, RequestRejectionDetails, RequestValidationContext, RequestValidator, SubTopicEventRouter };
+/**
+ * The {@link EventsService} that allows to publish events, and subscribe to topics.
+ * Uses the `root` scope so that events can be shared across all plugins, modules, and more.
+ *
+ * @public
+ */
+declare const eventsServiceRef: _backstage_backend_plugin_api.ServiceRef<EventsService, "plugin">;
+
+export { DefaultEventsService, EventBroker, EventParams, EventPublisher, EventRouter, EventSubscriber, EventsService, EventsServiceEventHandler, EventsServiceSubscribeOptions, HttpPostIngressOptions, RequestDetails, RequestRejectionDetails, RequestValidationContext, RequestValidator, SubTopicEventRouter, eventsServiceRef };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/plugin-events-node",
   "description": "The plugin-events-node module for @backstage/plugin-events-backend",
-  "version": "0.2.20",
+  "version": "0.3.0-next.0",
   "main": "./dist/index.cjs.js",
   "types": "./dist/index.d.ts",
   "license": "Apache-2.0",
@@ -40,10 +40,11 @@
     "postpack": "backstage-cli package postpack"
   },
   "dependencies": {
-    "@backstage/backend-plugin-api": "^0.6.11"
+    "@backstage/backend-plugin-api": "^0.6.13-next.0"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.25.2"
+    "@backstage/backend-common": "^0.21.3-next.0",
+    "@backstage/cli": "^0.25.3-next.0"
   },
   "files": [
     "dist",