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

backend-plugin-api: internal refactor to split creators

Browse Source 
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
This commit is contained in:
Patrik Oldsberg
2024-08-04 17:37:38 +02:00
parent 67e76f2bb9
commit 8b45adcadd
8 changed files with 354 additions and 291 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/backend-plugin-api/src/wiring/factories.test.ts → packages/backend-plugin-api/src/wiring/createBackendModule.test.ts
+1 -52
View File
@@ -14,60 +14,9 @@
* limitations under the License.
*/
import {
createBackendModule,
createBackendPlugin,
createExtensionPoint,
} from './factories';
import { createBackendModule } from './createBackendModule';
import { InternalBackendFeature } from './types';
describe('createExtensionPoint', () => {
it('should create an ExtensionPoint', () => {
const extensionPoint = createExtensionPoint({ id: 'x' });
expect(extensionPoint).toBeDefined();
expect(extensionPoint.id).toBe('x');
expect(() => extensionPoint.T).not.toThrow();
expect(String(extensionPoint)).toBe('extensionPoint{x}');
});
});
describe('createBackendPlugin', () => {
it('should create a BackendPlugin', () => {
const result = createBackendPlugin({
pluginId: 'x',
register(r) {
r.registerInit({ deps: {}, async init() {} });
},
});
// legacy form
const legacy = result() as unknown as InternalBackendFeature;
expect(legacy.$$type).toEqual('@backstage/BackendFeature');
expect(legacy.version).toEqual('v1');
expect(legacy.getRegistrations).toEqual(expect.any(Function));
// new form
const plugin = result as unknown as InternalBackendFeature;
expect(plugin.$$type).toEqual('@backstage/BackendFeature');
expect(plugin.version).toEqual('v1');
expect(plugin.getRegistrations).toEqual(expect.any(Function));
expect(plugin.getRegistrations()).toEqual([
{
type: 'plugin',
pluginId: 'x',
extensionPoints: [],
init: {
deps: expect.any(Object),
func: expect.any(Function),
},
},
]);
// @ts-expect-error
expect(plugin({ a: 'a' })).toBeDefined();
});
});
describe('createBackendModule', () => {
it('should create a BackendModule', () => {
const result = createBackendModule({
packages/backend-plugin-api/src/wiring/createBackendModule.ts
+107
View File
@@ -0,0 +1,107 @@
/*
* 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 { BackendFeatureCompat } from '../types';
import {
BackendModuleRegistrationPoints,
InternalBackendModuleRegistration,
InternalBackendPluginRegistration,
} from './types';
/**
* The configuration options passed to {@link createBackendModule}.
*
* @public
* @see {@link https://backstage.io/docs/backend-system/architecture/modules | The architecture of modules}
* @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
*/
export interface CreateBackendModuleOptions {
/**
* Should exactly match the `id` of the plugin that the module extends.
*
* @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
*/
pluginId: string;
/**
* The ID of this module, used to identify the module and ensure that it is not installed twice.
*/
moduleId: string;
register(reg: BackendModuleRegistrationPoints): void;
}
/**
* Creates a new backend module for a given plugin.
*
* @public
* @see {@link https://backstage.io/docs/backend-system/architecture/modules | The architecture of modules}
* @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
*/
export function createBackendModule(
options: CreateBackendModuleOptions,
): BackendFeatureCompat {
function getRegistrations() {
const extensionPoints: InternalBackendPluginRegistration['extensionPoints'] =
[];
let init: InternalBackendModuleRegistration['init'] | undefined = undefined;
options.register({
registerExtensionPoint(ext, impl) {
if (init) {
throw new Error('registerExtensionPoint called after registerInit');
}
extensionPoints.push([ext, impl]);
},
registerInit(regInit) {
if (init) {
throw new Error('registerInit must only be called once');
}
init = {
deps: regInit.deps,
func: regInit.init,
};
},
});
if (!init) {
throw new Error(
`registerInit was not called by register in ${options.moduleId} module for ${options.pluginId}`,
);
}
return [
{
type: 'module',
pluginId: options.pluginId,
moduleId: options.moduleId,
extensionPoints,
init,
},
];
}
function backendFeatureCompatWrapper() {
return backendFeatureCompatWrapper;
}
Object.assign(backendFeatureCompatWrapper, {
$$type: '@backstage/BackendFeature' as const,
version: 'v1',
getRegistrations,
});
return backendFeatureCompatWrapper as BackendFeatureCompat;
}
packages/backend-plugin-api/src/wiring/createBackendPlugin.test.ts
+55
View File
@@ -0,0 +1,55 @@
/*
* 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 { createBackendPlugin } from './createBackendPlugin';
import { InternalBackendFeature } from './types';
describe('createBackendPlugin', () => {
it('should create a BackendPlugin', () => {
const result = createBackendPlugin({
pluginId: 'x',
register(r) {
r.registerInit({ deps: {}, async init() {} });
},
});
// legacy form
const legacy = result() as unknown as InternalBackendFeature;
expect(legacy.$$type).toEqual('@backstage/BackendFeature');
expect(legacy.version).toEqual('v1');
expect(legacy.getRegistrations).toEqual(expect.any(Function));
// new form
const plugin = result as unknown as InternalBackendFeature;
expect(plugin.$$type).toEqual('@backstage/BackendFeature');
expect(plugin.version).toEqual('v1');
expect(plugin.getRegistrations).toEqual(expect.any(Function));
expect(plugin.getRegistrations()).toEqual([
{
type: 'plugin',
pluginId: 'x',
extensionPoints: [],
init: {
deps: expect.any(Object),
func: expect.any(Function),
},
},
]);
// @ts-expect-error
expect(plugin({ a: 'a' })).toBeDefined();
});
});
packages/backend-plugin-api/src/wiring/createBackendPlugin.ts
+100
View File
@@ -0,0 +1,100 @@
/*
* 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 { BackendFeatureCompat } from '../types';
import {
BackendPluginRegistrationPoints,
InternalBackendPluginRegistration,
} from './types';
/**
* The configuration options passed to {@link createBackendPlugin}.
*
* @public
* @see {@link https://backstage.io/docs/backend-system/architecture/plugins | The architecture of plugins}
* @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
*/
export interface CreateBackendPluginOptions {
/**
* The ID of this plugin.
*
* @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
*/
pluginId: string;
register(reg: BackendPluginRegistrationPoints): void;
}
/**
* Creates a new backend plugin.
*
* @public
* @see {@link https://backstage.io/docs/backend-system/architecture/plugins | The architecture of plugins}
* @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
*/
export function createBackendPlugin(
options: CreateBackendPluginOptions,
): BackendFeatureCompat {
function getRegistrations() {
const extensionPoints: InternalBackendPluginRegistration['extensionPoints'] =
[];
let init: InternalBackendPluginRegistration['init'] | undefined = undefined;
options.register({
registerExtensionPoint(ext, impl) {
if (init) {
throw new Error('registerExtensionPoint called after registerInit');
}
extensionPoints.push([ext, impl]);
},
registerInit(regInit) {
if (init) {
throw new Error('registerInit must only be called once');
}
init = {
deps: regInit.deps,
func: regInit.init,
};
},
});
if (!init) {
throw new Error(
`registerInit was not called by register in ${options.pluginId}`,
);
}
return [
{
type: 'plugin',
pluginId: options.pluginId,
extensionPoints,
init,
},
];
}
function backendFeatureCompatWrapper() {
return backendFeatureCompatWrapper;
}
Object.assign(backendFeatureCompatWrapper, {
$$type: '@backstage/BackendFeature' as const,
version: 'v1',
getRegistrations,
});
return backendFeatureCompatWrapper as BackendFeatureCompat;
}
packages/backend-plugin-api/src/wiring/createExtensionPoint.test.ts
+27
View File
@@ -0,0 +1,27 @@
/*
* 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 { createExtensionPoint } from './createExtensionPoint';
describe('createExtensionPoint', () => {
it('should create an ExtensionPoint', () => {
const extensionPoint = createExtensionPoint({ id: 'x' });
expect(extensionPoint).toBeDefined();
expect(extensionPoint.id).toBe('x');
expect(() => extensionPoint.T).not.toThrow();
expect(String(extensionPoint)).toBe('extensionPoint{x}');
});
});
packages/backend-plugin-api/src/wiring/createExtensionPoint.ts
+58
View File
@@ -0,0 +1,58 @@
/*
* 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 { ExtensionPoint } from './types';
/**
* The configuration options passed to {@link createExtensionPoint}.
*
* @public
* @see {@link https://backstage.io/docs/backend-system/architecture/extension-points | The architecture of extension points}
* @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
*/
export interface CreateExtensionPointOptions {
/**
* The ID of this extension point.
*
* @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
*/
id: string;
}
/**
* Creates a new backend extension point.
*
* @public
* @see {@link https://backstage.io/docs/backend-system/architecture/extension-points | The architecture of extension points}
*/
export function createExtensionPoint<T>(
options: CreateExtensionPointOptions,
): ExtensionPoint<T> {
return {
id: options.id,
get T(): T {
if (process.env.NODE_ENV === 'test') {
// Avoid throwing errors so tests asserting extensions' properties cannot be easily broken
return null as T;
}
throw new Error(`tried to read ExtensionPoint.T of ${this}`);
},
toString() {
return `extensionPoint{${options.id}}`;
},
$$type: '@backstage/ExtensionPoint',
};
}
packages/backend-plugin-api/src/wiring/factories.ts
-229
View File
@@ -1,229 +0,0 @@
/*
* 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 { BackendFeatureCompat } from '../types';
import {
BackendModuleRegistrationPoints,
BackendPluginRegistrationPoints,
ExtensionPoint,
InternalBackendModuleRegistration,
InternalBackendPluginRegistration,
} from './types';
/**
* The configuration options passed to {@link createExtensionPoint}.
*
* @public
* @see {@link https://backstage.io/docs/backend-system/architecture/extension-points | The architecture of extension points}
* @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
*/
export interface CreateExtensionPointOptions {
/**
* The ID of this extension point.
*
* @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
*/
id: string;
}
/**
* Creates a new backend extension point.
*
* @public
* @see {@link https://backstage.io/docs/backend-system/architecture/extension-points | The architecture of extension points}
*/
export function createExtensionPoint<T>(
options: CreateExtensionPointOptions,
): ExtensionPoint<T> {
return {
id: options.id,
get T(): T {
if (process.env.NODE_ENV === 'test') {
// Avoid throwing errors so tests asserting extensions' properties cannot be easily broken
return null as T;
}
throw new Error(`tried to read ExtensionPoint.T of ${this}`);
},
toString() {
return `extensionPoint{${options.id}}`;
},
$$type: '@backstage/ExtensionPoint',
};
}
/**
* The configuration options passed to {@link createBackendPlugin}.
*
* @public
* @see {@link https://backstage.io/docs/backend-system/architecture/plugins | The architecture of plugins}
* @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
*/
export interface CreateBackendPluginOptions {
/**
* The ID of this plugin.
*
* @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
*/
pluginId: string;
register(reg: BackendPluginRegistrationPoints): void;
}
/**
* Creates a new backend plugin.
*
* @public
* @see {@link https://backstage.io/docs/backend-system/architecture/plugins | The architecture of plugins}
* @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
*/
export function createBackendPlugin(
options: CreateBackendPluginOptions,
): BackendFeatureCompat {
function getRegistrations() {
const extensionPoints: InternalBackendPluginRegistration['extensionPoints'] =
[];
let init: InternalBackendPluginRegistration['init'] | undefined = undefined;
options.register({
registerExtensionPoint(ext, impl) {
if (init) {
throw new Error('registerExtensionPoint called after registerInit');
}
extensionPoints.push([ext, impl]);
},
registerInit(regInit) {
if (init) {
throw new Error('registerInit must only be called once');
}
init = {
deps: regInit.deps,
func: regInit.init,
};
},
});
if (!init) {
throw new Error(
`registerInit was not called by register in ${options.pluginId}`,
);
}
return [
{
type: 'plugin',
pluginId: options.pluginId,
extensionPoints,
init,
},
];
}
function backendFeatureCompatWrapper() {
return backendFeatureCompatWrapper;
}
Object.assign(backendFeatureCompatWrapper, {
$$type: '@backstage/BackendFeature' as const,
version: 'v1',
getRegistrations,
});
return backendFeatureCompatWrapper as BackendFeatureCompat;
}
/**
* The configuration options passed to {@link createBackendModule}.
*
* @public
* @see {@link https://backstage.io/docs/backend-system/architecture/modules | The architecture of modules}
* @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
*/
export interface CreateBackendModuleOptions {
/**
* Should exactly match the `id` of the plugin that the module extends.
*
* @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
*/
pluginId: string;
/**
* The ID of this module, used to identify the module and ensure that it is not installed twice.
*/
moduleId: string;
register(reg: BackendModuleRegistrationPoints): void;
}
/**
* Creates a new backend module for a given plugin.
*
* @public
* @see {@link https://backstage.io/docs/backend-system/architecture/modules | The architecture of modules}
* @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
*/
export function createBackendModule(
options: CreateBackendModuleOptions,
): BackendFeatureCompat {
function getRegistrations() {
const extensionPoints: InternalBackendPluginRegistration['extensionPoints'] =
[];
let init: InternalBackendModuleRegistration['init'] | undefined = undefined;
options.register({
registerExtensionPoint(ext, impl) {
if (init) {
throw new Error('registerExtensionPoint called after registerInit');
}
extensionPoints.push([ext, impl]);
},
registerInit(regInit) {
if (init) {
throw new Error('registerInit must only be called once');
}
init = {
deps: regInit.deps,
func: regInit.init,
};
},
});
if (!init) {
throw new Error(
`registerInit was not called by register in ${options.moduleId} module for ${options.pluginId}`,
);
}
return [
{
type: 'module',
pluginId: options.pluginId,
moduleId: options.moduleId,
extensionPoints,
init,
},
];
}
function backendFeatureCompatWrapper() {
return backendFeatureCompatWrapper;
}
Object.assign(backendFeatureCompatWrapper, {
$$type: '@backstage/BackendFeature' as const,
version: 'v1',
getRegistrations,
});
return backendFeatureCompatWrapper as BackendFeatureCompat;
}
packages/backend-plugin-api/src/wiring/index.ts
+6 -10
View File
@@ -14,17 +14,13 @@
* limitations under the License.
*/
import type {
CreateBackendPluginOptions,
CreateBackendModuleOptions,
CreateExtensionPointOptions,
} from './factories';
import { type CreateBackendModuleOptions } from './createBackendModule';
import { type CreateBackendPluginOptions } from './createBackendPlugin';
import { type CreateExtensionPointOptions } from './createExtensionPoint';
export {
createBackendModule,
createBackendPlugin,
createExtensionPoint,
} from './factories';
export { createBackendModule } from './createBackendModule';
export { createBackendPlugin } from './createBackendPlugin';
export { createExtensionPoint } from './createExtensionPoint';
export type {
BackendModuleRegistrationPoints,