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

feat(backend): add extensionPointFactoryMiddleware to createBackend

Browse Source 
Allow the backend to reimplement extension point outputs at creation
time via a new extensionPointFactoryMiddleware option on createBackend().
Each middleware entry declaratively targets a specific extension point
by reference and the framework handles matching and pass-through
automatically.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: Jack Palmer <jackpalmer@spotify.com>
This commit is contained in:
Jack Palmer
2026-04-07 09:34:54 +01:00
parent 7d5a3a2567
commit 3595c974f6
12 changed files with 323 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/extension-point-middleware-backend-app-api.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/backend-app-api': minor
---
Added `ExtensionPointFactoryMiddleware` type and `createExtensionPointFactoryMiddleware` helper to reimplement extension point outputs at backend creation time.
.changeset/extension-point-middleware-backend-defaults.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/backend-defaults': patch
---
Added `extensionPointFactoryMiddleware` option to `createBackend()` to reimplement extension point outputs at backend initialization time. Also re-exports `ExtensionPointFactoryMiddleware` type and `createExtensionPointFactoryMiddleware` helper from `@backstage/backend-app-api`.
packages/backend-app-api/report.api.md
+17
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>(
extensionPoint: ExtensionPoint<T>,
middleware: (original: T) => T,
): ExtensionPointFactoryMiddleware;
// @public (undocumented)
export function createSpecializedBackend(
options: CreateSpecializedBackendOptions,
@@ -51,6 +58,16 @@ export function createSpecializedBackend(
export interface CreateSpecializedBackendOptions {
// (undocumented)
defaultServiceFactories: ServiceFactory[];
// (undocumented)
extensionPointFactoryMiddleware?: ExtensionPointFactoryMiddleware[];
}
// @public
export interface ExtensionPointFactoryMiddleware<T = unknown> {
// (undocumented)
extensionPoint: ExtensionPoint<T>;
// (undocumented)
middleware: (original: T) => T;
}
// @public
packages/backend-app-api/src/wiring/BackendInitializer.test.ts
+203
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,206 @@ 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, 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(extensionPointA, 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, original => ({
...original,
values: [...original.values, 'first'],
})),
createExtensionPointFactoryMiddleware(extensionPoint, 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(
unregisteredExtensionPoint,
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
+22 -14
View File
@@ -25,7 +25,10 @@ import {
createServiceFactory,
ExtensionPointFactoryContext,
} from '@backstage/backend-plugin-api';
import { ServiceOrExtensionPoint } from './types';
import {
ExtensionPointFactoryMiddleware,
ServiceOrExtensionPoint,
} from './types';
// Direct internal import to avoid duplication
// eslint-disable-next-line @backstage/no-relative-monorepo-imports
import type {
@@ -166,11 +169,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 +204,17 @@ 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) {
if (mw.extensionPoint.id === ref.id) {
epImpl = (mw.middleware as (original: unknown) => unknown)(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
@@ -21,6 +21,34 @@ import {
ServiceFactory,
} from '@backstage/backend-plugin-api';
/**
* 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<T = unknown> {
extensionPoint: ExtensionPoint<T>;
middleware: (original: T) => T;
}
/**
* 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>(
extensionPoint: ExtensionPoint<T>,
middleware: (original: T) => T,
): ExtensionPointFactoryMiddleware {
return {
extensionPoint: extensionPoint as ExtensionPoint<unknown>,
middleware: middleware as (original: unknown) => unknown,
};
}
/**
* @public
*/
@@ -35,6 +63,7 @@ export interface Backend {
*/
export interface CreateSpecializedBackendOptions {
defaultServiceFactories: ServiceFactory[];
extensionPointFactoryMiddleware?: ExtensionPointFactoryMiddleware[];
}
/**
packages/backend-defaults/report.api.md
+9 -1
View File
@@ -5,10 +5,18 @@
```ts
import { Backend } from '@backstage/backend-app-api';
import { BackendFeature } from '@backstage/backend-plugin-api';
import { createExtensionPointFactoryMiddleware } from '@backstage/backend-app-api';
import { ExtensionPointFactoryMiddleware } from '@backstage/backend-app-api';
// @public (undocumented)
export function createBackend(): Backend;
export function createBackend(options?: {
extensionPointFactoryMiddleware?: ExtensionPointFactoryMiddleware[];
}): Backend;
export { createExtensionPointFactoryMiddleware };
// @public
export const discoveryFeatureLoader: BackendFeature;
export { ExtensionPointFactoryMiddleware };
```
packages/backend-defaults/src/CreateBackend.ts
+12 -3
View File
@@ -14,7 +14,11 @@
* limitations under the License.
*/
import { Backend, createSpecializedBackend } from '@backstage/backend-app-api';
import {
Backend,
createSpecializedBackend,
ExtensionPointFactoryMiddleware,
} from '@backstage/backend-app-api';
import { auditorServiceFactory } from '@backstage/backend-defaults/auditor';
import { authServiceFactory } from '@backstage/backend-defaults/auth';
import { cacheServiceFactory } from '@backstage/backend-defaults/cache';
@@ -76,6 +80,11 @@ export const defaultServiceFactories = [
/**
* @public
*/
export function createBackend(): Backend {
return createSpecializedBackend({ defaultServiceFactories });
export function createBackend(options?: {
extensionPointFactoryMiddleware?: ExtensionPointFactoryMiddleware[];
}): Backend {
return createSpecializedBackend({
defaultServiceFactories,
extensionPointFactoryMiddleware: options?.extensionPointFactoryMiddleware,
});
}
packages/backend-defaults/src/index.ts
+2
View File
@@ -21,4 +21,6 @@
*/
export { createBackend } from './CreateBackend';
export type { ExtensionPointFactoryMiddleware } from '@backstage/backend-app-api';
export { createExtensionPointFactoryMiddleware } from '@backstage/backend-app-api';
export { discoveryFeatureLoader } from './discoveryFeatureLoader';