feat(events/gitlab): add GitLabEventRouter

Add an event router for GitLab
which handles events from the topic `gitlab`
and re-publishes events under their more specific topic
based on the `$.event_name` payload field
like e.g., `gitlab.push`.

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

.changeset/small-months-call.md

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

.github/CODEOWNERS

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

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

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

@@ -0,0 +1,42 @@
+# events-backend-module-gitlab
+
+Welcome to the `events-backend-module-gitlab` backend plugin!
+
+This plugin is a module for the `events-backend` backend plugin
+and extends it with an `GitlabEventRouter`.
+
+The event router will subscribe to the topic `gitlab`
+and route the events to more concrete topics based on the value
+of the provided `$.event_name` payload field.
+
+Examples:
+
+| `$.event_name`  | topic                  |
+| --------------- | ---------------------- |
+| `push`          | `gitlab.push`          |
+| `merge_request` | `gitlab.merge_request` |
+
+Please find all possible webhook event types at the
+[official documentation](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html).
+
+## 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-gitlab
+```
+
+Add the event router to the `EventsBackend`:
+
+```diff
++const gitlabEventRouter = new GitlabEventRouter();
+
+ EventsBackend
++  .addPublishers(gitlabEventRouter)
++  .addSubscribers(gitlabEventRouter);
+// [...]
+```

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

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

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

@@ -0,0 +1,40 @@
+{
+  "name": "@backstage/plugin-events-backend-module-gitlab",
+  "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-gitlab/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 "gitlab" for the Backstage backend plugin "events-backend"
+ * adding an event router for GitLab.
+ *
+ * @packageDocumentation
+ */
+
+export { GitlabEventRouter } from './router/GitlabEventRouter';
+export { gitlabEventRouterEventsModule } from './service/GitlabEventRouterEventsModule';

plugins/events-backend-module-gitlab/src/router/GitlabEventRouter.test.ts

@@ -0,0 +1,50 @@
+/*
+ * 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 { GitlabEventRouter } from './GitlabEventRouter';
+
+describe('GitlabEventRouter', () => {
+  const eventRouter = new GitlabEventRouter();
+  const topic = 'gitlab';
+  const eventPayload = { event_name: 'test_type', test: 'payload' };
+  const metadata = {};
+
+  it('no $.event_name', () => {
+    const eventBroker = new TestEventBroker();
+    eventRouter.setEventBroker(eventBroker);
+
+    eventRouter.onEvent({
+      topic,
+      eventPayload: { invalid: 'payload' },
+      metadata,
+    });
+
+    expect(eventBroker.published).toEqual([]);
+  });
+
+  it('with $.event_name', () => {
+    const eventBroker = new TestEventBroker();
+    eventRouter.setEventBroker(eventBroker);
+
+    eventRouter.onEvent({ topic, eventPayload, metadata });
+
+    expect(eventBroker.published.length).toBe(1);
+    expect(eventBroker.published[0].topic).toEqual('gitlab.test_type');
+    expect(eventBroker.published[0].eventPayload).toEqual(eventPayload);
+    expect(eventBroker.published[0].metadata).toEqual(metadata);
+  });
+});

plugins/events-backend-module-gitlab/src/router/GitlabEventRouter.ts

@@ -0,0 +1,42 @@
+/*
+ * 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 `gitlab` topic
+ * and publishes the events under the more concrete sub-topic
+ * depending on the `$.event_name` field provided.
+ *
+ * @public
+ */
+export class GitlabEventRouter extends SubTopicEventRouter {
+  constructor() {
+    super('gitlab');
+  }
+
+  protected determineSubTopic(params: EventParams): string | undefined {
+    if ('event_name' in (params.eventPayload as object)) {
+      const payload = params.eventPayload as { event_name: string };
+      return payload.event_name;
+    }
+
+    return undefined;
+  }
+}

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

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

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

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