feat(events/github): add GithubEventRouter

Add an event router for GitHub
which handles events from the topic `github`
and re-publishes events under their more specific topic
based on the `x-github-event` metadata
like e.g., `github.push`.

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

.changeset/funny-countries-watch.md

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

.github/CODEOWNERS

@@ -39,6 +39,7 @@ yarn.lock                                           @backstage/reviewers @backst
 /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-module-github               @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-github/.eslintrc.js

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

plugins/events-backend-module-github/README.md

@@ -0,0 +1,43 @@
+# events-backend-module-github
+
+Welcome to the `events-backend-module-github` backend plugin!
+
+This plugin is a module for the `events-backend` backend plugin
+and extends it with an `GithubEventRouter`.
+
+The event router will subscribe to the topic `github`
+and route the events to more concrete topics based on the value
+of the provided `x-github-event` metadata field.
+
+Examples:
+
+| `x-github-event` | topic                 |
+| ---------------- | --------------------- |
+| `pull_request`   | `github.pull_request` |
+| `push`           | `github.push`         |
+| `repository`     | `github.repository`   |
+
+Please find all possible webhook event types at the
+[official documentation](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-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-github
+```
+
+Add the event router to the `EventsBackend`:
+
+```diff
++const githubEventRouter = new GithubEventRouter();
+
+ EventsBackend
++  .addPublishers(githubEventRouter)
++  .addSubscribers(githubEventRouter);
+// [...]
+```

plugins/events-backend-module-github/api-report.md

@@ -0,0 +1,21 @@
+## API Report File for "@backstage/plugin-events-backend-module-github"
+
+> 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 GithubEventRouter extends SubTopicEventRouter {
+  constructor();
+  // (undocumented)
+  protected determineSubTopic(params: EventParams): string | undefined;
+}
+
+// @alpha
+export const githubEventRouterEventsModule: (
+  options?: undefined,
+) => BackendFeature;
+```

plugins/events-backend-module-github/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@backstage/plugin-events-backend-module-github",
+  "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-github/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 `github` for the Backstage backend plugin "events-backend"
+ * adding an event router for GitHub.
+ *
+ * @packageDocumentation
+ */
+
+export { GithubEventRouter } from './router/GithubEventRouter';
+export { githubEventRouterEventsModule } from './service/GithubEventRouterEventsModule';

plugins/events-backend-module-github/src/router/GithubEventRouter.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 { GithubEventRouter } from './GithubEventRouter';
+
+describe('GithubEventRouter', () => {
+  const eventRouter = new GithubEventRouter();
+  const topic = 'github';
+  const eventPayload = { test: 'payload' };
+  const metadata = { 'x-github-event': 'test_type' };
+
+  it('no x-github-event', () => {
+    const eventBroker = new TestEventBroker();
+    eventRouter.setEventBroker(eventBroker);
+
+    eventRouter.onEvent({ topic, eventPayload });
+
+    expect(eventBroker.published).toEqual([]);
+  });
+
+  it('with x-github-event', () => {
+    const eventBroker = new TestEventBroker();
+    eventRouter.setEventBroker(eventBroker);
+
+    eventRouter.onEvent({ topic, eventPayload, metadata });
+
+    expect(eventBroker.published.length).toBe(1);
+    expect(eventBroker.published[0].topic).toEqual('github.test_type');
+    expect(eventBroker.published[0].eventPayload).toEqual(eventPayload);
+    expect(eventBroker.published[0].metadata).toEqual(metadata);
+  });
+});

plugins/events-backend-module-github/src/router/GithubEventRouter.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 `github` topic
+ * and publishes the events under the more concrete sub-topic
+ * depending on the `x-github-event` provided.
+ *
+ * @public
+ */
+export class GithubEventRouter extends SubTopicEventRouter {
+  constructor() {
+    super('github');
+  }
+
+  protected determineSubTopic(params: EventParams): string | undefined {
+    return params.metadata?.['x-github-event'] as string | undefined;
+  }
+}

plugins/events-backend-module-github/src/service/GithubEventRouterEventsModule.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 { githubEventRouterEventsModule } from './GithubEventRouterEventsModule';
+import { GithubEventRouter } from '../router/GithubEventRouter';
+
+describe('githubEventRouterEventsModule', () => {
+  it('should be correctly wired and set up', async () => {
+    let addedPublisher: GithubEventRouter | undefined;
+    let addedSubscriber: GithubEventRouter | undefined;
+    const extensionPoint = {
+      addPublishers: (publisher: any) => {
+        addedPublisher = publisher;
+      },
+      addSubscribers: (subscriber: any) => {
+        addedSubscriber = subscriber;
+      },
+    };
+
+    await startTestBackend({
+      extensionPoints: [[eventsExtensionPoint, extensionPoint]],
+      services: [],
+      features: [githubEventRouterEventsModule()],
+    });
+
+    expect(addedPublisher).not.toBeUndefined();
+    expect(addedPublisher).toBeInstanceOf(GithubEventRouter);
+    expect(addedSubscriber).not.toBeUndefined();
+    expect(addedSubscriber).toBeInstanceOf(GithubEventRouter);
+  });
+});

plugins/events-backend-module-github/src/service/GithubEventRouterEventsModule.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 { GithubEventRouter } from '../router/GithubEventRouter';
+
+/**
+ * Module for the events-backend plugin, adding an event router for GitHub.
+ *
+ * Registers the {@link GithubEventRouter}.
+ *
+ * @alpha
+ */
+export const githubEventRouterEventsModule = createBackendModule({
+  pluginId: 'events',
+  moduleId: 'githubEventRouter',
+  register(env) {
+    env.registerInit({
+      deps: {
+        events: eventsExtensionPoint,
+      },
+      async init({ events }) {
+        const eventRouter = new GithubEventRouter();
+
+        events.addPublishers(eventRouter);
+        events.addSubscribers(eventRouter);
+      },
+    });
+  },
+});

plugins/events-backend-module-github/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

@@ -6355,6 +6355,20 @@ __metadata:
   languageName: unknown
   linkType: soft
 
+"@backstage/plugin-events-backend-module-github@workspace:plugins/events-backend-module-github":
+  version: 0.0.0-use.local
+  resolution: "@backstage/plugin-events-backend-module-github@workspace:plugins/events-backend-module-github"
+  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"