feat(events/http): add HTTP endpoint-based event publisher

This plugin adds an event publisher which receives events via (an) HTTP endpoint(s)
and can be used as destination at webhook subscriptions.

Relates-to: #11082
Signed-off-by: Patrick Jungermann <Patrick.Jungermann@gmail.com>

plugins/events-node/src/api/http/HttpPostIngressOptions.ts

@@ -0,0 +1,25 @@
+/*
+ * 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 { RequestValidator } from './validation';
+
+/**
+ * @public
+ */
+export interface HttpPostIngressOptions {
+  topic: string;
+  validator?: RequestValidator;
+}

plugins/events-node/src/api/http/index.ts

@@ -0,0 +1,18 @@
+/*
+ * 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.
+ */
+
+export type { HttpPostIngressOptions } from './HttpPostIngressOptions';
+export * from './validation';

plugins/events-node/src/api/http/validation/RequestRejectionDetails.ts

@@ -0,0 +1,26 @@
+/*
+ * 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.
+ */
+
+/**
+ * Details for how to respond to the rejection
+ * of the received HTTP request transmitting an event payload.
+ *
+ * @public
+ */
+export interface RequestRejectionDetails {
+  status: number;
+  payload: unknown;
+}

plugins/events-node/src/api/http/validation/RequestValidationContext.ts

@@ -0,0 +1,32 @@
+/*
+ * 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 { RequestRejectionDetails } from './RequestRejectionDetails';
+
+/**
+ * Passed context for the validation
+ * at which rejections can be expressed.
+ *
+ * @public
+ */
+export interface RequestValidationContext {
+  /**
+   * Rejects the validated request
+   *
+   * @param details - Optional details about the rejection which will be provided to the sender.
+   */
+  reject(details?: Partial<RequestRejectionDetails>): void;
+}

plugins/events-node/src/api/http/validation/RequestValidator.ts

@@ -0,0 +1,34 @@
+/*
+ * 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 { Request } from 'express';
+import { RequestValidationContext } from './RequestValidationContext';
+
+/**
+ * Validator used to check the received HTTP request
+ * transmitting an event payload.
+ *
+ * E.g., it can be used for signature verification like
+ * for GitHub webhook events
+ * (https://docs.github.com/en/developers/webhooks-and-events/webhooks/creating-webhooks#secret)
+ * or other kinds of checks.
+ *
+ * @public
+ */
+export type RequestValidator = (
+  request: Request,
+  context: RequestValidationContext,
+) => Promise<void>;

plugins/events-node/src/api/http/validation/index.ts

@@ -0,0 +1,19 @@
+/*
+ * 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.
+ */
+
+export type { RequestRejectionDetails } from './RequestRejectionDetails';
+export type { RequestValidationContext } from './RequestValidationContext';
+export type { RequestValidator } from './RequestValidator';

plugins/events-node/src/api/index.ts

@@ -19,4 +19,5 @@ export type { EventParams } from './EventParams';
 export type { EventPublisher } from './EventPublisher';
 export { EventRouter } from './EventRouter';
 export type { EventSubscriber } from './EventSubscriber';
+export * from './http';
 export { SubTopicEventRouter } from './SubTopicEventRouter';

plugins/events-node/src/extensions.ts

@@ -15,7 +15,12 @@
  */
 
 import { createExtensionPoint } from '@backstage/backend-plugin-api';
-import { EventBroker, EventPublisher, EventSubscriber } from './api';
+import {
+  EventBroker,
+  EventPublisher,
+  EventSubscriber,
+  HttpPostIngressOptions,
+} from './api';
 
 /**
  * @alpha
@@ -30,6 +35,8 @@ export interface EventsExtensionPoint {
   addSubscribers(
     ...subscribers: Array<EventSubscriber | Array<EventSubscriber>>
   ): void;
+
+  addHttpPostIngress(options: HttpPostIngressOptions): void;
 }
 
 /**