feat(events/bitbucketCloud): add BitbucketCloudEventRouter

Add an event router for Bitbucket Cloud
which handles events from the topic `bitbucketCloud`
and re-publishes events under their more specific topic
based on the `x-event-key` metadata
like e.g., `bitbucketCloud.repo:push`.

Signed-off-by: Patrick Jungermann <Patrick.Jungermann@gmail.com>

.changeset/blue-papayas-relax.md

@@ -0,0 +1,14 @@
+---
+'@backstage/plugin-events-backend-module-bitbucket-cloud': minor
+---
+
+Adds a new module `bitbucket-cloud` to plugin-events-backend.
+
+The module adds a new event router `BitbucketCloudEventRouter`.
+
+The event router will re-publish events received at topic `bitbucketCloud`
+under a more specific topic depending on their `x-event-key` value
+(e.g., `bitbucketCloud.repo:push`).
+
+Please find more information at
+https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-bitbucket-cloud/README.md.

.github/CODEOWNERS

@@ -38,6 +38,7 @@ yarn.lock                                           @backstage/reviewers @backst
 /plugins/cost-insights-*                            @backstage/reviewers @backstage/silver-lining
 /plugins/events-backend                             @backstage/reviewers @pjungermann
 /plugins/events-backend-module-aws-sqs              @backstage/reviewers @pjungermann
+/plugins/events-backend-module-bitbucket-cloud      @backstage/reviewers @pjungermann
 /plugins/events-backend-test-utils                  @backstage/reviewers @pjungermann
 /plugins/events-node                                @backstage/reviewers @pjungermann
 /plugins/explore                                    @backstage/reviewers @backstage/sda-se-reviewers

plugins/events-backend-module-bitbucket-cloud/.eslintrc.js

@@ -0,0 +1 @@
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);

plugins/events-backend-module-bitbucket-cloud/README.md

@@ -0,0 +1,43 @@
+# events-backend-module-bitbucket-cloud
+
+Welcome to the `events-backend-module-bitbucket-cloud` backend plugin!
+
+This plugin is a module for the `events-backend` backend plugin
+and extends it with an `BitbucketCloudEventRouter`.
+
+The event router will subscribe to the topic `bitbucketCloud`
+and route the events to more concrete topics based on the value
+of the provided `x-event-key` metadata field.
+
+Examples:
+
+| x-event-key           | topic                                |
+| --------------------- | ------------------------------------ |
+| `repo:push`           | `bitbucketCloud.repo:push`           |
+| `repo:updated`        | `bitbucketCloud.repo:updated`        |
+| `pullrequest:created` | `bitbucketCloud.pullrequest:created` |
+
+Please find all possible webhook event types at the
+[official documentation](https://support.atlassian.com/bitbucket-cloud/docs/event-payloads/).
+
+## Installation
+
+Install the [`events-backend` plugin](../events-backend/README.md).
+
+Install this module:
+
+```bash
+# From your Backstage root directory
+yarn add --cwd packages/backend @backstage/plugin-events-backend-module-bitbucket-cloud
+```
+
+Add the event router to the `EventsBackend`:
+
+```diff
++const bitbucketCloudEventRouter = new BitbucketCloudEventRouter();
+
+ EventsBackend
++  .addPublishers(bitbucketCloudEventRouter)
++  .addSubscribers(bitbucketCloudEventRouter);
+// [...]
+```

plugins/events-backend-module-bitbucket-cloud/api-report.md

@@ -0,0 +1,21 @@
+## API Report File for "@backstage/plugin-events-backend-module-bitbucket-cloud"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { BackendFeature } from '@backstage/backend-plugin-api';
+import { EventParams } from '@backstage/plugin-events-node';
+import { SubTopicEventRouter } from '@backstage/plugin-events-node';
+
+// @public
+export class BitbucketCloudEventRouter extends SubTopicEventRouter {
+  constructor();
+  // (undocumented)
+  protected determineSubTopic(params: EventParams): string | undefined;
+}
+
+// @alpha
+export const bitbucketCloudEventRouterEventsModule: (
+  options?: undefined,
+) => BackendFeature;
+```

plugins/events-backend-module-bitbucket-cloud/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@backstage/plugin-events-backend-module-bitbucket-cloud",
+  "version": "0.0.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "alphaTypes": "dist/index.alpha.d.ts",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "backend-plugin-module"
+  },
+  "scripts": {
+    "start": "backstage-cli package start",
+    "build": "backstage-cli package build --experimental-type-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"
+  },
+  "dependencies": {
+    "@backstage/backend-plugin-api": "workspace:^",
+    "@backstage/plugin-events-node": "workspace:^",
+    "winston": "^3.2.1"
+  },
+  "devDependencies": {
+    "@backstage/backend-test-utils": "workspace:^",
+    "@backstage/cli": "workspace:^",
+    "@backstage/plugin-events-backend-test-utils": "workspace:^",
+    "supertest": "^6.1.3"
+  },
+  "files": [
+    "alpha",
+    "dist"
+  ]
+}

plugins/events-backend-module-bitbucket-cloud/src/index.ts

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2020 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * The module "bitbucket-cloud" for the Backstage backend plugin "events-backend"
+ * adding an event router for Bitbucket Cloud.
+ *
+ * @packageDocumentation
+ */
+
+export { BitbucketCloudEventRouter } from './router/BitbucketCloudEventRouter';
+export { bitbucketCloudEventRouterEventsModule } from './service/BitbucketCloudEventRouterEventsModule';

plugins/events-backend-module-bitbucket-cloud/src/router/BitbucketCloudEventRouter.test.ts

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { TestEventBroker } from '@backstage/plugin-events-backend-test-utils';
+import { BitbucketCloudEventRouter } from './BitbucketCloudEventRouter';
+
+describe('BitbucketCloudEventRouter', () => {
+  const eventRouter = new BitbucketCloudEventRouter();
+  const topic = 'bitbucketCloud';
+  const eventPayload = { test: 'payload' };
+  const metadata = { 'x-event-key': 'test:type' };
+
+  it('no x-event-key', () => {
+    const eventBroker = new TestEventBroker();
+    eventRouter.setEventBroker(eventBroker);
+
+    eventRouter.onEvent({ topic, eventPayload });
+
+    expect(eventBroker.published).toEqual([]);
+  });
+
+  it('with x-event-key', () => {
+    const eventBroker = new TestEventBroker();
+    eventRouter.setEventBroker(eventBroker);
+
+    eventRouter.onEvent({ topic, eventPayload, metadata });
+
+    expect(eventBroker.published.length).toBe(1);
+    expect(eventBroker.published[0].topic).toEqual('bitbucketCloud.test:type');
+    expect(eventBroker.published[0].eventPayload).toEqual(eventPayload);
+    expect(eventBroker.published[0].metadata).toEqual(metadata);
+  });
+});

plugins/events-backend-module-bitbucket-cloud/src/router/BitbucketCloudEventRouter.ts

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  EventParams,
+  SubTopicEventRouter,
+} from '@backstage/plugin-events-node';
+
+/**
+ * Subscribes to the generic `bitbucketCloud` topic
+ * and publishes the events under the more concrete sub-topic
+ * depending on the `x-event-key` provided.
+ *
+ * @public
+ */
+export class BitbucketCloudEventRouter extends SubTopicEventRouter {
+  constructor() {
+    super('bitbucketCloud');
+  }
+
+  protected determineSubTopic(params: EventParams): string | undefined {
+    return params.metadata?.['x-event-key'] as string | undefined;
+  }
+}

plugins/events-backend-module-bitbucket-cloud/src/service/BitbucketCloudEventRouterEventsModule.test.ts

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { startTestBackend } from '@backstage/backend-test-utils';
+import { eventsExtensionPoint } from '@backstage/plugin-events-node';
+import { bitbucketCloudEventRouterEventsModule } from './BitbucketCloudEventRouterEventsModule';
+import { BitbucketCloudEventRouter } from '../router/BitbucketCloudEventRouter';
+
+describe('bitbucketCloudEventRouterEventsModule', () => {
+  it('should be correctly wired and set up', async () => {
+    let addedPublisher: BitbucketCloudEventRouter | undefined;
+    let addedSubscriber: BitbucketCloudEventRouter | undefined;
+    const extensionPoint = {
+      addPublishers: (publisher: any) => {
+        addedPublisher = publisher;
+      },
+      addSubscribers: (subscriber: any) => {
+        addedSubscriber = subscriber;
+      },
+    };
+
+    await startTestBackend({
+      extensionPoints: [[eventsExtensionPoint, extensionPoint]],
+      services: [],
+      features: [bitbucketCloudEventRouterEventsModule()],
+    });
+
+    expect(addedPublisher).not.toBeUndefined();
+    expect(addedPublisher).toBeInstanceOf(BitbucketCloudEventRouter);
+    expect(addedSubscriber).not.toBeUndefined();
+    expect(addedSubscriber).toBeInstanceOf(BitbucketCloudEventRouter);
+  });
+});

plugins/events-backend-module-bitbucket-cloud/src/service/BitbucketCloudEventRouterEventsModule.ts

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { createBackendModule } from '@backstage/backend-plugin-api';
+import { eventsExtensionPoint } from '@backstage/plugin-events-node';
+import { BitbucketCloudEventRouter } from '../router/BitbucketCloudEventRouter';
+
+/**
+ * Module for the events-backend plugin, adding an event router for Bitbucket Cloud.
+ *
+ * Registers the {@link BitbucketCloudEventRouter}.
+ *
+ * @alpha
+ */
+export const bitbucketCloudEventRouterEventsModule = createBackendModule({
+  pluginId: 'events',
+  moduleId: 'bitbucketCloudEventRouter',
+  register(env) {
+    env.registerInit({
+      deps: {
+        events: eventsExtensionPoint,
+      },
+      async init({ events }) {
+        const eventRouter = new BitbucketCloudEventRouter();
+
+        events.addPublishers(eventRouter);
+        events.addSubscribers(eventRouter);
+      },
+    });
+  },
+});

plugins/events-backend-module-bitbucket-cloud/src/setupTests.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2020 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export {};

yarn.lock

@@ -6336,6 +6336,20 @@ __metadata:
   languageName: unknown
   linkType: soft
 
+"@backstage/plugin-events-backend-module-bitbucket-cloud@workspace:plugins/events-backend-module-bitbucket-cloud":
+  version: 0.0.0-use.local
+  resolution: "@backstage/plugin-events-backend-module-bitbucket-cloud@workspace:plugins/events-backend-module-bitbucket-cloud"
+  dependencies:
+    "@backstage/backend-plugin-api": "workspace:^"
+    "@backstage/backend-test-utils": "workspace:^"
+    "@backstage/cli": "workspace:^"
+    "@backstage/plugin-events-backend-test-utils": "workspace:^"
+    "@backstage/plugin-events-node": "workspace:^"
+    supertest: ^6.1.3
+    winston: ^3.2.1
+  languageName: unknown
+  linkType: soft
+
 "@backstage/plugin-events-backend-test-utils@workspace:^, @backstage/plugin-events-backend-test-utils@workspace:plugins/events-backend-test-utils":
   version: 0.0.0-use.local
   resolution: "@backstage/plugin-events-backend-test-utils@workspace:plugins/events-backend-test-utils"