paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 41 Packages Projects Releases Wiki Activity

Merge pull request #33782 from UsainBloot/feat/extension-point-middleware

Browse Source 
feat(backend): add extensionPointFactoryMiddleware to createBackend
This commit is contained in:
Patrik Oldsberg
2026-04-15 01:00:53 +02:00
committed by GitHub
parent e4c62f263f 90b62c24ef
commit 3210dbd638
20 changed files with 432 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/backend-app-api/report.api.md
+15
View File
@@ -5,6 +5,7 @@
```ts
import { BackendFeature } from '@backstage/backend-plugin-api';
import { CustomErrorBase } from '@backstage/errors';
import { ExtensionPoint } from '@backstage/backend-plugin-api';
import { ServiceFactory } from '@backstage/backend-plugin-api';
// @public (undocumented)
@@ -42,6 +43,12 @@ export interface BackendStartupResult {
resultAt: Date;
}
// @public
export function createExtensionPointFactoryMiddleware<T>(options: {
extensionPoint: ExtensionPoint<T>;
middleware: (original: T) => Promise<T>;
}): ExtensionPointFactoryMiddleware;
// @public (undocumented)
export function createSpecializedBackend(
options: CreateSpecializedBackendOptions,
@@ -51,6 +58,14 @@ export function createSpecializedBackend(
export interface CreateSpecializedBackendOptions {
// (undocumented)
defaultServiceFactories: ServiceFactory[];
// (undocumented)
extensionPointFactoryMiddleware?: ExtensionPointFactoryMiddleware[];
}
// @public
export interface ExtensionPointFactoryMiddleware {
// (undocumented)
$$type: '@backstage/ExtensionPointFactoryMiddleware';
}
// @public
packages/backend-app-api/src/wiring/BackendInitializer.test.ts
+215
View File
@@ -28,6 +28,7 @@ import {
import { BackendInitializer } from './BackendInitializer';
import { mockServices } from '@backstage/backend-test-utils';
import { BackendStartupError } from './BackendStartupError';
import { createExtensionPointFactoryMiddleware } from './types';
const baseFactories = [
mockServices.rootLifecycle.factory(),
@@ -2111,4 +2112,218 @@ describe('BackendInitializer', () => {
);
});
});
describe('extensionPointFactoryMiddleware', () => {
it('should apply middleware to matching extension points', async () => {
expect.assertions(1);
const extensionPoint = createExtensionPoint<{ values: string[] }>({
id: 'test.ext',
});
const init = new BackendInitializer(baseFactories, [
createExtensionPointFactoryMiddleware({
extensionPoint,
middleware: async original => ({
...original,
values: [...original.values, 'from-middleware'],
}),
}),
]);
init.add(testPlugin);
init.add(
createBackendModule({
pluginId: 'test',
moduleId: 'provider',
register(reg) {
reg.registerExtensionPoint(extensionPoint, {
values: ['original'],
});
reg.registerInit({ deps: {}, async init() {} });
},
}),
);
init.add(
createBackendModule({
pluginId: 'test',
moduleId: 'consumer',
register(reg) {
reg.registerInit({
deps: { ext: extensionPoint },
async init({ ext }) {
expect(ext.values).toEqual(['original', 'from-middleware']);
},
});
},
}),
);
await init.start();
});
it('should not affect non-matching extension points', async () => {
expect.assertions(1);
const extensionPointA = createExtensionPoint<{ values: string[] }>({
id: 'test.a',
});
const extensionPointB = createExtensionPoint<{ values: string[] }>({
id: 'test.b',
});
const init = new BackendInitializer(baseFactories, [
createExtensionPointFactoryMiddleware({
extensionPoint: extensionPointA,
middleware: async original => ({
...original,
values: [...original.values, 'wrapped'],
}),
}),
]);
init.add(testPlugin);
init.add(
createBackendModule({
pluginId: 'test',
moduleId: 'provider',
register(reg) {
reg.registerExtensionPoint(extensionPointB, {
values: ['untouched'],
});
reg.registerInit({ deps: {}, async init() {} });
},
}),
);
init.add(
createBackendModule({
pluginId: 'test',
moduleId: 'consumer',
register(reg) {
reg.registerInit({
deps: { ext: extensionPointB },
async init({ ext }) {
expect(ext.values).toEqual(['untouched']);
},
});
},
}),
);
await init.start();
});
it('should chain multiple middlewares for the same extension point', async () => {
expect.assertions(1);
const extensionPoint = createExtensionPoint<{ values: string[] }>({
id: 'test.ext',
});
const init = new BackendInitializer(baseFactories, [
createExtensionPointFactoryMiddleware({
extensionPoint,
middleware: async original => ({
...original,
values: [...original.values, 'first'],
}),
}),
createExtensionPointFactoryMiddleware({
extensionPoint,
middleware: async original => ({
...original,
values: [...original.values, 'second'],
}),
}),
]);
init.add(testPlugin);
init.add(
createBackendModule({
pluginId: 'test',
moduleId: 'provider',
register(reg) {
reg.registerExtensionPoint(extensionPoint, { values: ['base'] });
reg.registerInit({ deps: {}, async init() {} });
},
}),
);
init.add(
createBackendModule({
pluginId: 'test',
moduleId: 'consumer',
register(reg) {
reg.registerInit({
deps: { ext: extensionPoint },
async init({ ext }) {
expect(ext.values).toEqual(['base', 'first', 'second']);
},
});
},
}),
);
await init.start();
});
it('should not fail when middleware targets an unregistered extension point', async () => {
const unregisteredExtensionPoint = createExtensionPoint<{
values: string[];
}>({
id: 'test.unregistered',
});
const init = new BackendInitializer(baseFactories, [
createExtensionPointFactoryMiddleware({
extensionPoint: unregisteredExtensionPoint,
middleware: async original => ({
...original,
values: [...original.values, 'never-applied'],
}),
}),
]);
init.add(testPlugin);
const { result } = await init.start();
expect(result.outcome).toBe('success');
});
it('should pass through when no middleware is provided', async () => {
expect.assertions(1);
const extensionPoint = createExtensionPoint<{ values: string[] }>({
id: 'test.ext',
});
const init = new BackendInitializer(baseFactories);
init.add(testPlugin);
init.add(
createBackendModule({
pluginId: 'test',
moduleId: 'provider',
register(reg) {
reg.registerExtensionPoint(extensionPoint, { values: ['orig'] });
reg.registerInit({ deps: {}, async init() {} });
},
}),
);
init.add(
createBackendModule({
pluginId: 'test',
moduleId: 'consumer',
register(reg) {
reg.registerInit({
deps: { ext: extensionPoint },
async init({ ext }) {
expect(ext.values).toEqual(['orig']);
},
});
},
}),
);
await init.start();
});
});
});
packages/backend-app-api/src/wiring/BackendInitializer.ts
+24 -14
View File
@@ -25,7 +25,11 @@ import {
createServiceFactory,
ExtensionPointFactoryContext,
} from '@backstage/backend-plugin-api';
import { ServiceOrExtensionPoint } from './types';
import {
ExtensionPointFactoryMiddleware,
ServiceOrExtensionPoint,
} from './types';
import { OpaqueExtensionPointFactoryMiddleware } from '@internal/backend';
// Direct internal import to avoid duplication
// eslint-disable-next-line @backstage/no-relative-monorepo-imports
import type {
@@ -166,11 +170,17 @@ export class BackendInitializer {
#serviceRegistry: ServiceRegistry;
#registeredFeatures = new Array<Promise<BackendFeature>>();
#registeredFeatureLoaders = new Array<InternalBackendFeatureLoader>();
#extensionPointFactoryMiddleware: ExtensionPointFactoryMiddleware[];
#unhandledRejectionHandler?: (reason: Error) => void;
#uncaughtExceptionHandler?: (error: Error) => void;
constructor(defaultApiFactories: ServiceFactory[]) {
constructor(
defaultApiFactories: ServiceFactory[],
extensionPointFactoryMiddleware?: ExtensionPointFactoryMiddleware[],
) {
this.#serviceRegistry = ServiceRegistry.create([...defaultApiFactories]);
this.#extensionPointFactoryMiddleware =
extensionPointFactoryMiddleware ?? [];
}
async #getInitDeps(
@@ -195,18 +205,18 @@ export class BackendInitializer {
`Rejected dependency on extension point ${ref.id} from outside of a module`,
);
}
result.set(
name,
ep.factory({
reportModuleStartupFailure: ({ error }) => {
resultCollector.amendPluginModuleResult(
pluginId,
moduleId,
error,
);
},
}),
);
let epImpl = ep.factory({
reportModuleStartupFailure: ({ error }) => {
resultCollector.amendPluginModuleResult(pluginId, moduleId, error);
},
});
for (const mw of this.#extensionPointFactoryMiddleware) {
const internal = OpaqueExtensionPointFactoryMiddleware.toInternal(mw);
if (internal.extensionPointId === ref.id) {
epImpl = await internal.middleware(epImpl);
}
}
result.set(name, epImpl);
} else {
const impl = await this.#serviceRegistry.get(
ref as ServiceRef<unknown>,
packages/backend-app-api/src/wiring/BackstageBackend.ts
+13 -3
View File
@@ -17,13 +17,23 @@
import { BackendFeature, ServiceFactory } from '@backstage/backend-plugin-api';
import { BackendInitializer } from './BackendInitializer';
import { unwrapFeature } from './helpers';
import { Backend, BackendStartupResult } from './types';
import {
Backend,
BackendStartupResult,
ExtensionPointFactoryMiddleware,
} from './types';
export class BackstageBackend implements Backend {
#initializer: BackendInitializer;
constructor(defaultServiceFactories: ServiceFactory[]) {
this.#initializer = new BackendInitializer(defaultServiceFactories);
constructor(
defaultServiceFactories: ServiceFactory[],
extensionPointFactoryMiddleware?: ExtensionPointFactoryMiddleware[],
) {
this.#initializer = new BackendInitializer(
defaultServiceFactories,
extensionPointFactoryMiddleware,
);
}
add(feature: BackendFeature | Promise<{ default: BackendFeature }>): void {
packages/backend-app-api/src/wiring/createSpecializedBackend.ts
+4 -1
View File
@@ -43,5 +43,8 @@ export function createSpecializedBackend(
);
}
return new BackstageBackend(options.defaultServiceFactories);
return new BackstageBackend(
options.defaultServiceFactories,
options.extensionPointFactoryMiddleware,
);
}
packages/backend-app-api/src/wiring/index.ts
+2
View File
@@ -17,9 +17,11 @@
export type {
Backend,
CreateSpecializedBackendOptions,
ExtensionPointFactoryMiddleware,
BackendStartupResult,
PluginStartupResult,
ModuleStartupResult,
} from './types';
export { createExtensionPointFactoryMiddleware } from './types';
export { createSpecializedBackend } from './createSpecializedBackend';
export { BackendStartupError } from './BackendStartupError';
packages/backend-app-api/src/wiring/types.ts
+29
View File
@@ -20,6 +20,34 @@ import {
ServiceRef,
ServiceFactory,
} from '@backstage/backend-plugin-api';
import { OpaqueExtensionPointFactoryMiddleware } from '@internal/backend';
/**
* A middleware entry that reimplements a specific extension point's output.
* The framework matches by extension point ID and passes through all
* non-matching extension points automatically.
*
* @public
*/
export interface ExtensionPointFactoryMiddleware {
$$type: '@backstage/ExtensionPointFactoryMiddleware';
}
/**
* Creates a typed middleware entry that reimplements a specific extension point.
* Use this helper to preserve type inference for the middleware callback.
*
* @public
*/
export function createExtensionPointFactoryMiddleware<T>(options: {
extensionPoint: ExtensionPoint<T>;
middleware: (original: T) => Promise<T>;
}): ExtensionPointFactoryMiddleware {
return OpaqueExtensionPointFactoryMiddleware.createInstance('v1', {
extensionPointId: options.extensionPoint.id,
middleware: options.middleware as (original: unknown) => Promise<unknown>,
});
}
/**
* @public
@@ -35,6 +63,7 @@ export interface Backend {
*/
export interface CreateSpecializedBackendOptions {
defaultServiceFactories: ServiceFactory[];
extensionPointFactoryMiddleware?: ExtensionPointFactoryMiddleware[];
}
/**