@backstage/plugin-events-node 0.0.0-nightly-20221115024001
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +32 -0
- package/README.md +3 -0
- package/alpha/package.json +6 -0
- package/dist/index.alpha.d.ts +176 -0
- package/dist/index.beta.d.ts +165 -0
- package/dist/index.cjs.js +45 -0
- package/dist/index.cjs.js.map +1 -0
- package/dist/index.d.ts +165 -0
- package/package.json +38 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# @backstage/plugin-events-node
|
|
2
|
+
|
|
3
|
+
## 0.0.0-nightly-20221115024001
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- dc9da28abd: Support events received via HTTP endpoints at plugin-events-backend.
|
|
8
|
+
|
|
9
|
+
The plugin provides an event publisher `HttpPostIngressEventPublisher`
|
|
10
|
+
which will allow you to receive events via
|
|
11
|
+
HTTP endpoints `POST /api/events/http/{topic}`
|
|
12
|
+
and will publish these to the used event broker.
|
|
13
|
+
|
|
14
|
+
Using a provided custom validator, you can participate in the decision
|
|
15
|
+
which events are accepted, e.g. by verifying the source of the request.
|
|
16
|
+
|
|
17
|
+
Please find more information at
|
|
18
|
+
https://github.com/backstage/backstage/tree/master/plugins/events-backend/README.md.
|
|
19
|
+
|
|
20
|
+
- 7bbd2403a1: Adds a new backend plugin plugin-events-backend for managing events.
|
|
21
|
+
|
|
22
|
+
plugin-events-node exposes interfaces which can be used by modules.
|
|
23
|
+
|
|
24
|
+
plugin-events-backend-test-utils provides utilities which can be used while writing tests e.g. for modules.
|
|
25
|
+
|
|
26
|
+
Please find more information at
|
|
27
|
+
https://github.com/backstage/backstage/tree/master/plugins/events-backend/README.md.
|
|
28
|
+
|
|
29
|
+
### Patch Changes
|
|
30
|
+
|
|
31
|
+
- Updated dependencies
|
|
32
|
+
- @backstage/backend-plugin-api@0.0.0-nightly-20221115024001
|
package/README.md
ADDED
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The events-node module for `@backstage/plugin-events-backend`.
|
|
3
|
+
*
|
|
4
|
+
* @packageDocumentation
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { ExtensionPoint } from '@backstage/backend-plugin-api';
|
|
8
|
+
import { Request as Request_2 } from 'express';
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* Allows a decoupled and asynchronous communication between components.
|
|
12
|
+
* Components can publish events for a given topic and
|
|
13
|
+
* others can subscribe for future events for topics they are interested in.
|
|
14
|
+
*
|
|
15
|
+
* @public
|
|
16
|
+
*/
|
|
17
|
+
export declare interface EventBroker {
|
|
18
|
+
/**
|
|
19
|
+
* Publishes an event for the topic.
|
|
20
|
+
*
|
|
21
|
+
* @param params - parameters for the to be published event.
|
|
22
|
+
*/
|
|
23
|
+
publish(params: EventParams): Promise<void>;
|
|
24
|
+
/**
|
|
25
|
+
* Adds new subscribers for {@link EventSubscriber#supportsEventTopics | interested topics}.
|
|
26
|
+
*
|
|
27
|
+
* @param subscribers - interested in events of specified topics.
|
|
28
|
+
*/
|
|
29
|
+
subscribe(...subscribers: Array<EventSubscriber | Array<EventSubscriber>>): void;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* @public
|
|
34
|
+
*/
|
|
35
|
+
export declare interface EventParams {
|
|
36
|
+
/**
|
|
37
|
+
* Topic for which this event should be published.
|
|
38
|
+
*/
|
|
39
|
+
topic: string;
|
|
40
|
+
/**
|
|
41
|
+
* Event payload.
|
|
42
|
+
*/
|
|
43
|
+
eventPayload: unknown;
|
|
44
|
+
/**
|
|
45
|
+
* Metadata (e.g., HTTP headers and similar for events received from external).
|
|
46
|
+
*/
|
|
47
|
+
metadata?: Record<string, string | string[] | undefined>;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Publishes events to be consumed by subscribers for their topic.
|
|
52
|
+
* The events can come from different (external) sources
|
|
53
|
+
* like emitted themselves, received via HTTP endpoint (i.e. webhook)
|
|
54
|
+
* or from event brokers, queues, etc.
|
|
55
|
+
*
|
|
56
|
+
* @public
|
|
57
|
+
*/
|
|
58
|
+
export declare interface EventPublisher {
|
|
59
|
+
setEventBroker(eventBroker: EventBroker): Promise<void>;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Subscribes to a topic and - depending on a set of conditions -
|
|
64
|
+
* republishes the event to another topic.
|
|
65
|
+
*
|
|
66
|
+
* @see {@link https://www.enterpriseintegrationpatterns.com/MessageRouter.html | Message Router pattern}.
|
|
67
|
+
* @public
|
|
68
|
+
*/
|
|
69
|
+
export declare abstract class EventRouter implements EventPublisher, EventSubscriber {
|
|
70
|
+
private eventBroker?;
|
|
71
|
+
protected abstract determineDestinationTopic(params: EventParams): string | undefined;
|
|
72
|
+
onEvent(params: EventParams): Promise<void>;
|
|
73
|
+
setEventBroker(eventBroker: EventBroker): Promise<void>;
|
|
74
|
+
abstract supportsEventTopics(): string[];
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* @alpha
|
|
79
|
+
*/
|
|
80
|
+
export declare interface EventsExtensionPoint {
|
|
81
|
+
setEventBroker(eventBroker: EventBroker): void;
|
|
82
|
+
addPublishers(...publishers: Array<EventPublisher | Array<EventPublisher>>): void;
|
|
83
|
+
addSubscribers(...subscribers: Array<EventSubscriber | Array<EventSubscriber>>): void;
|
|
84
|
+
addHttpPostIngress(options: HttpPostIngressOptions): void;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* @alpha
|
|
89
|
+
*/
|
|
90
|
+
export declare const eventsExtensionPoint: ExtensionPoint<EventsExtensionPoint>;
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* Handles received events.
|
|
94
|
+
* This may include triggering refreshes of catalog entities
|
|
95
|
+
* or other actions to react on events.
|
|
96
|
+
*
|
|
97
|
+
* @public
|
|
98
|
+
*/
|
|
99
|
+
export declare interface EventSubscriber {
|
|
100
|
+
/**
|
|
101
|
+
* Supported event topics like "github", "bitbucketCloud", etc.
|
|
102
|
+
*/
|
|
103
|
+
supportsEventTopics(): string[];
|
|
104
|
+
/**
|
|
105
|
+
* React on a received event.
|
|
106
|
+
*
|
|
107
|
+
* @param params - parameters for the to be received event.
|
|
108
|
+
*/
|
|
109
|
+
onEvent(params: EventParams): Promise<void>;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/**
|
|
113
|
+
* @public
|
|
114
|
+
*/
|
|
115
|
+
export declare interface HttpPostIngressOptions {
|
|
116
|
+
topic: string;
|
|
117
|
+
validator?: RequestValidator;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* Details for how to respond to the rejection
|
|
122
|
+
* of the received HTTP request transmitting an event payload.
|
|
123
|
+
*
|
|
124
|
+
* @public
|
|
125
|
+
*/
|
|
126
|
+
export declare interface RequestRejectionDetails {
|
|
127
|
+
status: number;
|
|
128
|
+
payload: unknown;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* Passed context for the validation
|
|
133
|
+
* at which rejections can be expressed.
|
|
134
|
+
*
|
|
135
|
+
* @public
|
|
136
|
+
*/
|
|
137
|
+
export declare interface RequestValidationContext {
|
|
138
|
+
/**
|
|
139
|
+
* Rejects the validated request
|
|
140
|
+
*
|
|
141
|
+
* @param details - Optional details about the rejection which will be provided to the sender.
|
|
142
|
+
*/
|
|
143
|
+
reject(details?: Partial<RequestRejectionDetails>): void;
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/**
|
|
147
|
+
* Validator used to check the received HTTP request
|
|
148
|
+
* transmitting an event payload.
|
|
149
|
+
*
|
|
150
|
+
* E.g., it can be used for signature verification like
|
|
151
|
+
* for GitHub webhook events
|
|
152
|
+
* (https://docs.github.com/en/developers/webhooks-and-events/webhooks/creating-webhooks#secret)
|
|
153
|
+
* or other kinds of checks.
|
|
154
|
+
*
|
|
155
|
+
* @public
|
|
156
|
+
*/
|
|
157
|
+
export declare type RequestValidator = (request: Request_2, context: RequestValidationContext) => Promise<void>;
|
|
158
|
+
|
|
159
|
+
/**
|
|
160
|
+
* Subscribes to the provided (generic) topic
|
|
161
|
+
* and publishes the events under the more concrete sub-topic
|
|
162
|
+
* depending on the implemented logic for determining it.
|
|
163
|
+
* Implementing classes might use information from `metadata`
|
|
164
|
+
* and/or properties within the payload.
|
|
165
|
+
*
|
|
166
|
+
* @public
|
|
167
|
+
*/
|
|
168
|
+
export declare abstract class SubTopicEventRouter extends EventRouter {
|
|
169
|
+
private readonly topic;
|
|
170
|
+
protected constructor(topic: string);
|
|
171
|
+
protected abstract determineSubTopic(params: EventParams): string | undefined;
|
|
172
|
+
protected determineDestinationTopic(params: EventParams): string | undefined;
|
|
173
|
+
supportsEventTopics(): string[];
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
export { }
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The events-node module for `@backstage/plugin-events-backend`.
|
|
3
|
+
*
|
|
4
|
+
* @packageDocumentation
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { ExtensionPoint } from '@backstage/backend-plugin-api';
|
|
8
|
+
import { Request as Request_2 } from 'express';
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* Allows a decoupled and asynchronous communication between components.
|
|
12
|
+
* Components can publish events for a given topic and
|
|
13
|
+
* others can subscribe for future events for topics they are interested in.
|
|
14
|
+
*
|
|
15
|
+
* @public
|
|
16
|
+
*/
|
|
17
|
+
export declare interface EventBroker {
|
|
18
|
+
/**
|
|
19
|
+
* Publishes an event for the topic.
|
|
20
|
+
*
|
|
21
|
+
* @param params - parameters for the to be published event.
|
|
22
|
+
*/
|
|
23
|
+
publish(params: EventParams): Promise<void>;
|
|
24
|
+
/**
|
|
25
|
+
* Adds new subscribers for {@link EventSubscriber#supportsEventTopics | interested topics}.
|
|
26
|
+
*
|
|
27
|
+
* @param subscribers - interested in events of specified topics.
|
|
28
|
+
*/
|
|
29
|
+
subscribe(...subscribers: Array<EventSubscriber | Array<EventSubscriber>>): void;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* @public
|
|
34
|
+
*/
|
|
35
|
+
export declare interface EventParams {
|
|
36
|
+
/**
|
|
37
|
+
* Topic for which this event should be published.
|
|
38
|
+
*/
|
|
39
|
+
topic: string;
|
|
40
|
+
/**
|
|
41
|
+
* Event payload.
|
|
42
|
+
*/
|
|
43
|
+
eventPayload: unknown;
|
|
44
|
+
/**
|
|
45
|
+
* Metadata (e.g., HTTP headers and similar for events received from external).
|
|
46
|
+
*/
|
|
47
|
+
metadata?: Record<string, string | string[] | undefined>;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Publishes events to be consumed by subscribers for their topic.
|
|
52
|
+
* The events can come from different (external) sources
|
|
53
|
+
* like emitted themselves, received via HTTP endpoint (i.e. webhook)
|
|
54
|
+
* or from event brokers, queues, etc.
|
|
55
|
+
*
|
|
56
|
+
* @public
|
|
57
|
+
*/
|
|
58
|
+
export declare interface EventPublisher {
|
|
59
|
+
setEventBroker(eventBroker: EventBroker): Promise<void>;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Subscribes to a topic and - depending on a set of conditions -
|
|
64
|
+
* republishes the event to another topic.
|
|
65
|
+
*
|
|
66
|
+
* @see {@link https://www.enterpriseintegrationpatterns.com/MessageRouter.html | Message Router pattern}.
|
|
67
|
+
* @public
|
|
68
|
+
*/
|
|
69
|
+
export declare abstract class EventRouter implements EventPublisher, EventSubscriber {
|
|
70
|
+
private eventBroker?;
|
|
71
|
+
protected abstract determineDestinationTopic(params: EventParams): string | undefined;
|
|
72
|
+
onEvent(params: EventParams): Promise<void>;
|
|
73
|
+
setEventBroker(eventBroker: EventBroker): Promise<void>;
|
|
74
|
+
abstract supportsEventTopics(): string[];
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/* Excluded from this release type: EventsExtensionPoint */
|
|
78
|
+
|
|
79
|
+
/* Excluded from this release type: eventsExtensionPoint */
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* Handles received events.
|
|
83
|
+
* This may include triggering refreshes of catalog entities
|
|
84
|
+
* or other actions to react on events.
|
|
85
|
+
*
|
|
86
|
+
* @public
|
|
87
|
+
*/
|
|
88
|
+
export declare interface EventSubscriber {
|
|
89
|
+
/**
|
|
90
|
+
* Supported event topics like "github", "bitbucketCloud", etc.
|
|
91
|
+
*/
|
|
92
|
+
supportsEventTopics(): string[];
|
|
93
|
+
/**
|
|
94
|
+
* React on a received event.
|
|
95
|
+
*
|
|
96
|
+
* @param params - parameters for the to be received event.
|
|
97
|
+
*/
|
|
98
|
+
onEvent(params: EventParams): Promise<void>;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* @public
|
|
103
|
+
*/
|
|
104
|
+
export declare interface HttpPostIngressOptions {
|
|
105
|
+
topic: string;
|
|
106
|
+
validator?: RequestValidator;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* Details for how to respond to the rejection
|
|
111
|
+
* of the received HTTP request transmitting an event payload.
|
|
112
|
+
*
|
|
113
|
+
* @public
|
|
114
|
+
*/
|
|
115
|
+
export declare interface RequestRejectionDetails {
|
|
116
|
+
status: number;
|
|
117
|
+
payload: unknown;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* Passed context for the validation
|
|
122
|
+
* at which rejections can be expressed.
|
|
123
|
+
*
|
|
124
|
+
* @public
|
|
125
|
+
*/
|
|
126
|
+
export declare interface RequestValidationContext {
|
|
127
|
+
/**
|
|
128
|
+
* Rejects the validated request
|
|
129
|
+
*
|
|
130
|
+
* @param details - Optional details about the rejection which will be provided to the sender.
|
|
131
|
+
*/
|
|
132
|
+
reject(details?: Partial<RequestRejectionDetails>): void;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* Validator used to check the received HTTP request
|
|
137
|
+
* transmitting an event payload.
|
|
138
|
+
*
|
|
139
|
+
* E.g., it can be used for signature verification like
|
|
140
|
+
* for GitHub webhook events
|
|
141
|
+
* (https://docs.github.com/en/developers/webhooks-and-events/webhooks/creating-webhooks#secret)
|
|
142
|
+
* or other kinds of checks.
|
|
143
|
+
*
|
|
144
|
+
* @public
|
|
145
|
+
*/
|
|
146
|
+
export declare type RequestValidator = (request: Request_2, context: RequestValidationContext) => Promise<void>;
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* Subscribes to the provided (generic) topic
|
|
150
|
+
* and publishes the events under the more concrete sub-topic
|
|
151
|
+
* depending on the implemented logic for determining it.
|
|
152
|
+
* Implementing classes might use information from `metadata`
|
|
153
|
+
* and/or properties within the payload.
|
|
154
|
+
*
|
|
155
|
+
* @public
|
|
156
|
+
*/
|
|
157
|
+
export declare abstract class SubTopicEventRouter extends EventRouter {
|
|
158
|
+
private readonly topic;
|
|
159
|
+
protected constructor(topic: string);
|
|
160
|
+
protected abstract determineSubTopic(params: EventParams): string | undefined;
|
|
161
|
+
protected determineDestinationTopic(params: EventParams): string | undefined;
|
|
162
|
+
supportsEventTopics(): string[];
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
export { }
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
Object.defineProperty(exports, '__esModule', { value: true });
|
|
4
|
+
|
|
5
|
+
var backendPluginApi = require('@backstage/backend-plugin-api');
|
|
6
|
+
|
|
7
|
+
class EventRouter {
|
|
8
|
+
async onEvent(params) {
|
|
9
|
+
var _a;
|
|
10
|
+
const topic = this.determineDestinationTopic(params);
|
|
11
|
+
if (!topic) {
|
|
12
|
+
return;
|
|
13
|
+
}
|
|
14
|
+
(_a = this.eventBroker) == null ? void 0 : _a.publish({
|
|
15
|
+
...params,
|
|
16
|
+
topic
|
|
17
|
+
});
|
|
18
|
+
}
|
|
19
|
+
async setEventBroker(eventBroker) {
|
|
20
|
+
this.eventBroker = eventBroker;
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
class SubTopicEventRouter extends EventRouter {
|
|
25
|
+
constructor(topic) {
|
|
26
|
+
super();
|
|
27
|
+
this.topic = topic;
|
|
28
|
+
}
|
|
29
|
+
determineDestinationTopic(params) {
|
|
30
|
+
const subTopic = this.determineSubTopic(params);
|
|
31
|
+
return subTopic ? `${params.topic}.${subTopic}` : void 0;
|
|
32
|
+
}
|
|
33
|
+
supportsEventTopics() {
|
|
34
|
+
return [this.topic];
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
const eventsExtensionPoint = backendPluginApi.createExtensionPoint({
|
|
39
|
+
id: "events"
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
exports.EventRouter = EventRouter;
|
|
43
|
+
exports.SubTopicEventRouter = SubTopicEventRouter;
|
|
44
|
+
exports.eventsExtensionPoint = eventsExtensionPoint;
|
|
45
|
+
//# sourceMappingURL=index.cjs.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.cjs.js","sources":["../src/api/EventRouter.ts","../src/api/SubTopicEventRouter.ts","../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 { 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","/*\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 './api';\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":";;;;;;AA4BO,MAAe,WAAuD,CAAA;AAAA,EAO3E,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,QAAW,GAAA,CAAA,EAAG,MAAO,CAAA,KAAA,CAAA,CAAA,EAAS,QAAa,CAAA,CAAA,GAAA,KAAA,CAAA,CAAA;AAAA,GACpD;AAAA,EAEA,mBAAgC,GAAA;AAC9B,IAAO,OAAA,CAAC,KAAK,KAAK,CAAA,CAAA;AAAA,GACpB;AACF;;ACCO,MAAM,uBAAuBA,qCAA2C,CAAA;AAAA,EAC7E,EAAI,EAAA,QAAA;AACN,CAAC;;;;;;"}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The events-node module for `@backstage/plugin-events-backend`.
|
|
3
|
+
*
|
|
4
|
+
* @packageDocumentation
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { ExtensionPoint } from '@backstage/backend-plugin-api';
|
|
8
|
+
import { Request as Request_2 } from 'express';
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* Allows a decoupled and asynchronous communication between components.
|
|
12
|
+
* Components can publish events for a given topic and
|
|
13
|
+
* others can subscribe for future events for topics they are interested in.
|
|
14
|
+
*
|
|
15
|
+
* @public
|
|
16
|
+
*/
|
|
17
|
+
export declare interface EventBroker {
|
|
18
|
+
/**
|
|
19
|
+
* Publishes an event for the topic.
|
|
20
|
+
*
|
|
21
|
+
* @param params - parameters for the to be published event.
|
|
22
|
+
*/
|
|
23
|
+
publish(params: EventParams): Promise<void>;
|
|
24
|
+
/**
|
|
25
|
+
* Adds new subscribers for {@link EventSubscriber#supportsEventTopics | interested topics}.
|
|
26
|
+
*
|
|
27
|
+
* @param subscribers - interested in events of specified topics.
|
|
28
|
+
*/
|
|
29
|
+
subscribe(...subscribers: Array<EventSubscriber | Array<EventSubscriber>>): void;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* @public
|
|
34
|
+
*/
|
|
35
|
+
export declare interface EventParams {
|
|
36
|
+
/**
|
|
37
|
+
* Topic for which this event should be published.
|
|
38
|
+
*/
|
|
39
|
+
topic: string;
|
|
40
|
+
/**
|
|
41
|
+
* Event payload.
|
|
42
|
+
*/
|
|
43
|
+
eventPayload: unknown;
|
|
44
|
+
/**
|
|
45
|
+
* Metadata (e.g., HTTP headers and similar for events received from external).
|
|
46
|
+
*/
|
|
47
|
+
metadata?: Record<string, string | string[] | undefined>;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Publishes events to be consumed by subscribers for their topic.
|
|
52
|
+
* The events can come from different (external) sources
|
|
53
|
+
* like emitted themselves, received via HTTP endpoint (i.e. webhook)
|
|
54
|
+
* or from event brokers, queues, etc.
|
|
55
|
+
*
|
|
56
|
+
* @public
|
|
57
|
+
*/
|
|
58
|
+
export declare interface EventPublisher {
|
|
59
|
+
setEventBroker(eventBroker: EventBroker): Promise<void>;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Subscribes to a topic and - depending on a set of conditions -
|
|
64
|
+
* republishes the event to another topic.
|
|
65
|
+
*
|
|
66
|
+
* @see {@link https://www.enterpriseintegrationpatterns.com/MessageRouter.html | Message Router pattern}.
|
|
67
|
+
* @public
|
|
68
|
+
*/
|
|
69
|
+
export declare abstract class EventRouter implements EventPublisher, EventSubscriber {
|
|
70
|
+
private eventBroker?;
|
|
71
|
+
protected abstract determineDestinationTopic(params: EventParams): string | undefined;
|
|
72
|
+
onEvent(params: EventParams): Promise<void>;
|
|
73
|
+
setEventBroker(eventBroker: EventBroker): Promise<void>;
|
|
74
|
+
abstract supportsEventTopics(): string[];
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/* Excluded from this release type: EventsExtensionPoint */
|
|
78
|
+
|
|
79
|
+
/* Excluded from this release type: eventsExtensionPoint */
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* Handles received events.
|
|
83
|
+
* This may include triggering refreshes of catalog entities
|
|
84
|
+
* or other actions to react on events.
|
|
85
|
+
*
|
|
86
|
+
* @public
|
|
87
|
+
*/
|
|
88
|
+
export declare interface EventSubscriber {
|
|
89
|
+
/**
|
|
90
|
+
* Supported event topics like "github", "bitbucketCloud", etc.
|
|
91
|
+
*/
|
|
92
|
+
supportsEventTopics(): string[];
|
|
93
|
+
/**
|
|
94
|
+
* React on a received event.
|
|
95
|
+
*
|
|
96
|
+
* @param params - parameters for the to be received event.
|
|
97
|
+
*/
|
|
98
|
+
onEvent(params: EventParams): Promise<void>;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* @public
|
|
103
|
+
*/
|
|
104
|
+
export declare interface HttpPostIngressOptions {
|
|
105
|
+
topic: string;
|
|
106
|
+
validator?: RequestValidator;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* Details for how to respond to the rejection
|
|
111
|
+
* of the received HTTP request transmitting an event payload.
|
|
112
|
+
*
|
|
113
|
+
* @public
|
|
114
|
+
*/
|
|
115
|
+
export declare interface RequestRejectionDetails {
|
|
116
|
+
status: number;
|
|
117
|
+
payload: unknown;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* Passed context for the validation
|
|
122
|
+
* at which rejections can be expressed.
|
|
123
|
+
*
|
|
124
|
+
* @public
|
|
125
|
+
*/
|
|
126
|
+
export declare interface RequestValidationContext {
|
|
127
|
+
/**
|
|
128
|
+
* Rejects the validated request
|
|
129
|
+
*
|
|
130
|
+
* @param details - Optional details about the rejection which will be provided to the sender.
|
|
131
|
+
*/
|
|
132
|
+
reject(details?: Partial<RequestRejectionDetails>): void;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* Validator used to check the received HTTP request
|
|
137
|
+
* transmitting an event payload.
|
|
138
|
+
*
|
|
139
|
+
* E.g., it can be used for signature verification like
|
|
140
|
+
* for GitHub webhook events
|
|
141
|
+
* (https://docs.github.com/en/developers/webhooks-and-events/webhooks/creating-webhooks#secret)
|
|
142
|
+
* or other kinds of checks.
|
|
143
|
+
*
|
|
144
|
+
* @public
|
|
145
|
+
*/
|
|
146
|
+
export declare type RequestValidator = (request: Request_2, context: RequestValidationContext) => Promise<void>;
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* Subscribes to the provided (generic) topic
|
|
150
|
+
* and publishes the events under the more concrete sub-topic
|
|
151
|
+
* depending on the implemented logic for determining it.
|
|
152
|
+
* Implementing classes might use information from `metadata`
|
|
153
|
+
* and/or properties within the payload.
|
|
154
|
+
*
|
|
155
|
+
* @public
|
|
156
|
+
*/
|
|
157
|
+
export declare abstract class SubTopicEventRouter extends EventRouter {
|
|
158
|
+
private readonly topic;
|
|
159
|
+
protected constructor(topic: string);
|
|
160
|
+
protected abstract determineSubTopic(params: EventParams): string | undefined;
|
|
161
|
+
protected determineDestinationTopic(params: EventParams): string | undefined;
|
|
162
|
+
supportsEventTopics(): string[];
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
export { }
|
package/package.json
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@backstage/plugin-events-node",
|
|
3
|
+
"description": "The plugin-events-node module for @backstage/plugin-events-backend",
|
|
4
|
+
"version": "0.0.0-nightly-20221115024001",
|
|
5
|
+
"main": "dist/index.cjs.js",
|
|
6
|
+
"types": "dist/index.d.ts",
|
|
7
|
+
"license": "Apache-2.0",
|
|
8
|
+
"publishConfig": {
|
|
9
|
+
"access": "public",
|
|
10
|
+
"alphaTypes": "dist/index.alpha.d.ts",
|
|
11
|
+
"main": "dist/index.cjs.js",
|
|
12
|
+
"types": "dist/index.d.ts"
|
|
13
|
+
},
|
|
14
|
+
"backstage": {
|
|
15
|
+
"role": "node-library"
|
|
16
|
+
},
|
|
17
|
+
"scripts": {
|
|
18
|
+
"start": "backstage-cli package start",
|
|
19
|
+
"build": "backstage-cli package build --experimental-type-build",
|
|
20
|
+
"lint": "backstage-cli package lint",
|
|
21
|
+
"test": "backstage-cli package test",
|
|
22
|
+
"clean": "backstage-cli package clean",
|
|
23
|
+
"prepack": "backstage-cli package prepack",
|
|
24
|
+
"postpack": "backstage-cli package postpack"
|
|
25
|
+
},
|
|
26
|
+
"dependencies": {
|
|
27
|
+
"@backstage/backend-plugin-api": "^0.0.0-nightly-20221115024001",
|
|
28
|
+
"@types/express": "^4.17.6",
|
|
29
|
+
"express": "^4.17.1"
|
|
30
|
+
},
|
|
31
|
+
"devDependencies": {
|
|
32
|
+
"@backstage/cli": "^0.0.0-nightly-20221115024001"
|
|
33
|
+
},
|
|
34
|
+
"files": [
|
|
35
|
+
"alpha",
|
|
36
|
+
"dist"
|
|
37
|
+
]
|
|
38
|
+
}
|