@@ -136,7 +181,6 @@ const ExternalPage = PageBlueprint.make({
loader: async () => {
const Component = () => {
const indexLink = useRouteRef(indexRouteRef);
- // const pageXLink = useRouteRef(pageXRouteRef);
return (
@@ -150,15 +194,272 @@ const ExternalPage = PageBlueprint.make({
},
});
+// Example: Page enabled only when a single feature flag is active.
+//
+// The `if` predicate is evaluated once at app startup (before the router
+// tree is built), so this page simply won't exist in the app until the flag is
+// toggled and the page is refreshed.
+//
+// To test: enable the 'experimental-features' flag in Settings, then refresh.
+const FeatureFlagPage = PageBlueprint.make({
+ name: 'featureFlagExample',
+ params: {
+ path: '/feature-flag-example',
+ loader: async () => {
+ const Component = () => {
+ const indexLink = useRouteRef(indexRouteRef);
+ return (
+
+
Feature Flag Enabled Page
+
+ This page is only present in the app when the{' '}
+ experimental-features feature flag is active.
+
+
+ It uses a simple{' '}
+
+ {'{ featureFlags: { $contains: "experimental-features" } }'}
+ {' '}
+ predicate.
+
+ {indexLink &&
Go back}
+
+ );
+ };
+ return
;
+ },
+ },
+ if: { featureFlags: { $contains: 'experimental-features' } },
+});
+
+// Example: Page enabled only when ALL of several feature flags are active.
+//
+// The $all operator requires every nested predicate to be satisfied. This page
+// won't appear unless both 'experimental-features' and 'advanced-features' are
+// enabled at the same time.
+//
+// To test: enable BOTH flags in Settings, then refresh.
+const AllFlagsPage = PageBlueprint.make({
+ name: 'allFlagsExample',
+ params: {
+ path: '/all-flags-example',
+ loader: async () => {
+ const Component = () => {
+ const indexLink = useRouteRef(indexRouteRef);
+ return (
+
+
All Flags Required Page
+
+ This page requires both {' '}
+ experimental-features and{' '}
+ advanced-features to be active simultaneously.
+
+
+ It uses a $all predicate to AND the two conditions
+ together.
+
+ {indexLink &&
Go back}
+
+ );
+ };
+ return
;
+ },
+ },
+ if: {
+ $all: [
+ { featureFlags: { $contains: 'experimental-features' } },
+ { featureFlags: { $contains: 'advanced-features' } },
+ ],
+ },
+});
+
+// Example: Page enabled when ANY one of several feature flags is active.
+//
+// The $any operator is satisfied as soon as at least one nested predicate
+// matches. Enabling either 'experimental-features' or 'beta-access' will make
+// this page appear.
+//
+// To test: enable at least one of the two flags in Settings, then refresh.
+const AnyFlagPage = PageBlueprint.make({
+ name: 'anyFlagExample',
+ params: {
+ path: '/any-flag-example',
+ loader: async () => {
+ const Component = () => {
+ const indexLink = useRouteRef(indexRouteRef);
+ return (
+
+
Any Flag Sufficient Page
+
+ This page appears when either {' '}
+ experimental-features or beta-access is
+ active.
+
+
+ It uses a $any predicate to OR the two conditions
+ together.
+
+ {indexLink &&
Go back}
+
+ );
+ };
+ return
;
+ },
+ },
+ if: {
+ $any: [
+ { featureFlags: { $contains: 'experimental-features' } },
+ { featureFlags: { $contains: 'beta-access' } },
+ ],
+ },
+});
+
+// Blueprint for cards that attach to the PermissionCardPage below.
+//
+// Each card receives a title and description and renders a simple bordered card.
+// Individual card instances can be selectively enabled via the `if`
+// predicate, so only the cards the user is allowed to see will be instantiated.
+const PermissionExampleCardBlueprint = createExtensionBlueprint({
+ kind: 'permission-example-card',
+ attachTo: { id: 'page:pages/permissionCardExample', input: 'cards' },
+ output: [coreExtensionData.reactElement],
+ *factory(params: { title: string; description: string }) {
+ yield coreExtensionData.reactElement(
+
+
{params.title}
+
{params.description}
+
,
+ );
+ },
+});
+
+// Example: Page with cards that are individually toggled by permissions.
+//
+// The page itself is always present. What changes is which cards are
+// instantiated inside it — each card declares its own `enabled` predicate
+// and is only wired into the page if that predicate is satisfied at startup.
+//
+// To test: make sure you do NOT have the catalog.entity.create permission and
+// refresh the page — the "Restricted Card" below should disappear.
+const PermissionCardPage = PageBlueprint.makeWithOverrides({
+ name: 'permissionCardExample',
+ inputs: {
+ cards: createExtensionInput([coreExtensionData.reactElement]),
+ },
+ factory(originalFactory, { inputs }) {
+ return originalFactory({
+ path: '/permission-card-example',
+ loader: async () => {
+ const Component = () => {
+ const indexLink = useRouteRef(indexRouteRef);
+ const cards = inputs.cards.map(card =>
+ card.get(coreExtensionData.reactElement),
+ );
+ return (
+
+
Permission-Gated Card Example
+
+ This page is always visible. The cards below are individually
+ gated — each one declares its own{' '}
+ {'if: { permissions: { $contains: "..." } }'}{' '}
+ predicate. Cards whose predicate fails are never instantiated,
+ so they simply won't appear here.
+
+
+ {cards.length > 0 ? (
+ cards
+ ) : (
+
+ No cards are visible — you may lack the required
+ permissions.
+
+ )}
+
+ {indexLink &&
Go back}
+
+ );
+ };
+ return
;
+ },
+ });
+ },
+});
+
+// Always-visible card — no predicate, every user sees this.
+const PublicCard = PermissionExampleCardBlueprint.make({
+ name: 'public',
+ params: {
+ title: 'Public Card',
+ description: 'This card is visible to everyone regardless of permissions.',
+ },
+});
+
+// Permission-gated card — only instantiated when the user has
+// the catalog.entity.create permission.
+const RestrictedCard = PermissionExampleCardBlueprint.make({
+ name: 'restricted',
+ params: {
+ title: 'Restricted Card',
+ description:
+ 'This card is only visible to users who have the catalog.entity.create permission.',
+ },
+ if: { permissions: { $contains: 'catalog.entity.create' } },
+});
+
+// Feature flag-gated card — only instantiated when the user has
+// the experimental-card FF enabled.
+const FeatureFlagCard = PermissionExampleCardBlueprint.make({
+ name: 'feature-flag',
+ params: {
+ title: 'Feature Flagged Card',
+ description: 'Visible only with the experimental-card FF active.',
+ },
+ if: { featureFlags: { $contains: 'experimental-card' } },
+});
+
+// Example: Page enabled only when the user is allowed to create catalog entities.
+//
+// The `if` predicate is evaluated once at app startup (after sign-in),
+// so this page simply won't exist in the router tree if the user lacks the
+// required permission.
+const PermissionGatedPage = PageBlueprint.make({
+ name: 'permissionGatedExample',
+ params: {
+ path: '/permission-gated-example',
+ loader: async () => {
+ const Component = () => {
+ const indexLink = useRouteRef(indexRouteRef);
+ return (
+
+
Permission Gated Page
+
+ This page is only present when the user has the{' '}
+ catalog.entity.create permission.
+
+ {indexLink &&
Go back}
+
+ );
+ };
+ return
;
+ },
+ },
+ if: { permissions: { $contains: 'catalog.entity.create' } },
+});
+
export const pagesPlugin = createFrontendPlugin({
pluginId: 'pages',
- // routes: {
- // index: indexRouteRef,
- // // reference in config:
- // // 'plugin.pages.routes.index'
- // // OR
- // // 'page1'
- // },
info: {
packageJson: () => import('../../package.json'),
manifest: () => import('../../catalog-info.yaml'),
@@ -170,5 +471,23 @@ export const pagesPlugin = createFrontendPlugin({
externalRoutes: {
pageX: externalPageXRouteRef,
},
- extensions: [IndexPage, Page1, ExternalPage],
+ featureFlags: [
+ { name: 'experimental-features' },
+ { name: 'advanced-features' },
+ { name: 'beta-access' },
+ { name: 'experimental-card' },
+ ],
+ extensions: [
+ IndexPage,
+ Page1,
+ ExternalPage,
+ FeatureFlagPage,
+ AllFlagsPage,
+ AnyFlagPage,
+ PermissionCardPage,
+ PublicCard,
+ RestrictedCard,
+ PermissionGatedPage,
+ FeatureFlagCard,
+ ],
});
diff --git a/packages/app/src/modules/appModuleNav.tsx b/packages/app/src/modules/appModuleNav.tsx
index a507679c73..044cd96e23 100644
--- a/packages/app/src/modules/appModuleNav.tsx
+++ b/packages/app/src/modules/appModuleNav.tsx
@@ -27,15 +27,11 @@ import {
} from '@backstage/core-components';
import SearchIcon from '@material-ui/icons/Search';
import MenuIcon from '@material-ui/icons/Menu';
-import BuildIcon from '@material-ui/icons/Build';
import { createFrontendModule } from '@backstage/frontend-plugin-api';
import { NavContentBlueprint } from '@backstage/plugin-app-react';
import { SidebarSearchModal } from '@backstage/plugin-search';
import { NotificationsSidebarItem } from '@backstage/plugin-notifications';
-import {
- Settings,
- UserSettingsSignInAvatar,
-} from '@backstage/plugin-user-settings';
+import { UserSettingsSignInAvatar } from '@backstage/plugin-user-settings';
import { makeStyles } from '@material-ui/core/styles';
const useSidebarLogoStyles = makeStyles({
@@ -111,7 +107,9 @@ export const appModuleNav = createFrontendModule({
text={item.title}
/>
));
- nav.take('page:home'); // Skip home
+ // Consume without rendering — these are handled by dedicated sidebar groups
+ nav.take('page:home');
+ nav.take('page:search');
return (
);
diff --git a/packages/backend-app-api/CHANGELOG.md b/packages/backend-app-api/CHANGELOG.md
index f1d26a7f4a..f46cfe28bb 100644
--- a/packages/backend-app-api/CHANGELOG.md
+++ b/packages/backend-app-api/CHANGELOG.md
@@ -1,5 +1,52 @@
# @backstage/backend-app-api
+## 1.6.1-next.1
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.9.0-next.1
+
+## 1.6.1-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.1-next.0
+ - @backstage/config@1.3.6
+ - @backstage/errors@1.2.7
+
+## 1.6.0
+
+### Minor Changes
+
+- 545557a: Registration errors should be forwarded as BackendStartupResult
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0
+
+## 1.6.0-next.1
+
+### Minor Changes
+
+- 545557a: Registration errors should be forwarded as BackendStartupResult
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0-next.1
+
+## 1.5.1-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.7.1-next.0
+ - @backstage/config@1.3.6
+ - @backstage/errors@1.2.7
+
## 1.5.0
### Minor Changes
diff --git a/packages/backend-app-api/package.json b/packages/backend-app-api/package.json
index 97e5964e39..2ebcc05941 100644
--- a/packages/backend-app-api/package.json
+++ b/packages/backend-app-api/package.json
@@ -1,6 +1,6 @@
{
"name": "@backstage/backend-app-api",
- "version": "1.5.0",
+ "version": "1.6.1-next.1",
"description": "Core API used by Backstage backend apps",
"backstage": {
"role": "node-library"
diff --git a/packages/backend-app-api/src/wiring/BackendInitializer.test.ts b/packages/backend-app-api/src/wiring/BackendInitializer.test.ts
index 0491faa96f..f782295e71 100644
--- a/packages/backend-app-api/src/wiring/BackendInitializer.test.ts
+++ b/packages/backend-app-api/src/wiring/BackendInitializer.test.ts
@@ -899,7 +899,7 @@ describe('BackendInitializer', () => {
});
it('should reject duplicate plugins', async () => {
- const init = new BackendInitializer([]);
+ const init = new BackendInitializer(baseFactories);
init.add(
createBackendPlugin({
pluginId: 'test',
@@ -922,13 +922,24 @@ describe('BackendInitializer', () => {
},
}),
);
- await expect(init.start()).rejects.toThrow(
+
+ const err = await init.start().then(
+ () => {
+ throw new Error('Expected BackendStartupError to be thrown');
+ },
+ (e: BackendStartupError) => e,
+ );
+
+ expect(err).toBeInstanceOf(BackendStartupError);
+ const plugin = err?.result.plugins.find(p => p.pluginId === 'test');
+ expect(plugin?.failure?.error.message).toBe(
"Plugin 'test' is already registered",
);
+ expect(plugin?.failure?.allowed).toBe(false);
});
it('should reject duplicate modules', async () => {
- const init = new BackendInitializer([]);
+ const init = new BackendInitializer(baseFactories);
init.add(testPlugin);
init.add(
createBackendModule({
@@ -954,8 +965,202 @@ describe('BackendInitializer', () => {
},
}),
);
- await expect(init.start()).rejects.toThrow(
- "Module 'mod' for plugin 'test' is already registered",
+
+ const err = await init.start().then(
+ () => {
+ throw new Error('Expected BackendStartupError to be thrown');
+ },
+ (e: BackendStartupError) => e,
+ );
+
+ expect(err).toBeInstanceOf(BackendStartupError);
+ const plugin = err?.result.plugins.find(p => p.pluginId === 'test');
+ const modResult = plugin?.modules.find(
+ m =>
+ m.failure?.error.message ===
+ "Module 'mod' for plugin 'test' is already registered",
+ );
+ expect(modResult).toBeDefined();
+ expect(modResult?.failure?.allowed).toBe(false);
+ });
+
+ it('should allow other plugins to continue when one has a registration error', async () => {
+ const pluginAInit = jest.fn(async () => {});
+ const init = new BackendInitializer(baseFactories);
+ init.add(
+ createBackendPlugin({
+ pluginId: 'plugin-a',
+ register(reg) {
+ reg.registerInit({
+ deps: {},
+ init: pluginAInit,
+ });
+ },
+ }),
+ );
+ init.add(
+ createBackendPlugin({
+ pluginId: 'plugin-b',
+ register(reg) {
+ reg.registerInit({
+ deps: {},
+ async init() {},
+ });
+ },
+ }),
+ );
+ init.add(
+ createBackendPlugin({
+ pluginId: 'plugin-b',
+ register(reg) {
+ reg.registerInit({
+ deps: {},
+ async init() {},
+ });
+ },
+ }),
+ );
+
+ const err = await init.start().then(
+ () => {
+ throw new Error('Expected BackendStartupError to be thrown');
+ },
+ (e: BackendStartupError) => e,
+ );
+
+ expect(err).toBeInstanceOf(BackendStartupError);
+ // plugin-a should have started successfully
+ expect(pluginAInit).toHaveBeenCalled();
+ const pluginA = err?.result.plugins.find(p => p.pluginId === 'plugin-a');
+ expect(pluginA?.failure).toBeUndefined();
+ // plugin-b should have a registration failure
+ const pluginB = err?.result.plugins.find(p => p.pluginId === 'plugin-b');
+ expect(pluginB?.failure?.error.message).toBe(
+ "Plugin 'plugin-b' is already registered",
+ );
+ });
+
+ it('should permit registration errors for plugins with onPluginBootFailure: continue', async () => {
+ const init = new BackendInitializer([
+ ...baseFactories,
+ mockServices.rootConfig.factory({
+ data: {
+ backend: {
+ startup: {
+ plugins: { test: { onPluginBootFailure: 'continue' } },
+ },
+ },
+ },
+ }),
+ ]);
+ init.add(
+ createBackendPlugin({
+ pluginId: 'test',
+ register(reg) {
+ reg.registerInit({
+ deps: {},
+ async init() {},
+ });
+ },
+ }),
+ );
+ init.add(
+ createBackendPlugin({
+ pluginId: 'test',
+ register(reg) {
+ reg.registerInit({
+ deps: {},
+ async init() {},
+ });
+ },
+ }),
+ );
+
+ const { result } = await init.start();
+ const plugin = result.plugins.find(p => p.pluginId === 'test');
+ expect(plugin?.failure?.error.message).toBe(
+ "Plugin 'test' is already registered",
+ );
+ expect(plugin?.failure?.allowed).toBe(true);
+ });
+
+ it('should attribute duplicate extension point errors to the correct plugin', async () => {
+ const extensionPoint = createExtensionPoint
({ id: 'shared-ext' });
+ const init = new BackendInitializer(baseFactories);
+ init.add(
+ createBackendPlugin({
+ pluginId: 'plugin-a',
+ register(reg) {
+ reg.registerExtensionPoint(extensionPoint, 'a');
+ reg.registerInit({
+ deps: {},
+ async init() {},
+ });
+ },
+ }),
+ );
+ init.add(
+ createBackendPlugin({
+ pluginId: 'plugin-b',
+ register(reg) {
+ reg.registerExtensionPoint(extensionPoint, 'b');
+ reg.registerInit({
+ deps: {},
+ async init() {},
+ });
+ },
+ }),
+ );
+
+ const err = await init.start().then(
+ () => {
+ throw new Error('Expected BackendStartupError to be thrown');
+ },
+ (e: BackendStartupError) => e,
+ );
+
+ expect(err).toBeInstanceOf(BackendStartupError);
+ // plugin-a should succeed (registered first)
+ const pluginA = err?.result.plugins.find(p => p.pluginId === 'plugin-a');
+ expect(pluginA?.failure).toBeUndefined();
+ // plugin-b should fail due to duplicate extension point
+ const pluginB = err?.result.plugins.find(p => p.pluginId === 'plugin-b');
+ expect(pluginB?.failure?.error.message).toBe(
+ "ExtensionPoint with ID 'shared-ext' is already registered",
+ );
+ });
+
+ it('should attribute invalid registration type errors to plugin when pluginId is available', async () => {
+ const init = new BackendInitializer(baseFactories);
+ // Create a fake registration with an invalid type but valid pluginId
+ const fakeFeature = {
+ $$type: '@backstage/BackendFeature' as const,
+ version: 'v1' as const,
+ featureType: 'registrations' as const,
+ getRegistrations: () => [
+ {
+ type: 'invalid-type',
+ pluginId: 'broken-plugin',
+ init: { deps: {}, func: async () => {} },
+ extensionPoints: [],
+ },
+ ],
+ };
+ init.add(fakeFeature as any);
+
+ const err = await init.start().then(
+ () => {
+ throw new Error('Expected BackendStartupError to be thrown');
+ },
+ (e: BackendStartupError) => e,
+ );
+
+ expect(err).toBeInstanceOf(BackendStartupError);
+ const plugin = err?.result.plugins.find(
+ p => p.pluginId === 'broken-plugin',
+ );
+ expect(plugin?.failure?.error.message).toBe(
+ "Invalid registration type 'invalid-type'",
);
});
diff --git a/packages/backend-app-api/src/wiring/BackendInitializer.ts b/packages/backend-app-api/src/wiring/BackendInitializer.ts
index d51befb644..8ebab723da 100644
--- a/packages/backend-app-api/src/wiring/BackendInitializer.ts
+++ b/packages/backend-app-api/src/wiring/BackendInitializer.ts
@@ -310,77 +310,6 @@ export class BackendInitializer {
// Initialize all root scoped services
await this.#serviceRegistry.initializeEagerServicesWithScope('root');
- const pluginInits = new Map();
- const moduleInits = new Map>();
-
- // Enumerate all registrations
- for (const feature of this.#registrations) {
- for (const r of feature.getRegistrations()) {
- const provides = new Set>();
-
- if (r.type === 'plugin' || r.type === 'module') {
- // Handle v1 format: Array, unknown]>
- for (const [extRef, extImpl] of r.extensionPoints) {
- if (this.#extensionPoints.has(extRef.id)) {
- throw new Error(
- `ExtensionPoint with ID '${extRef.id}' is already registered`,
- );
- }
- this.#extensionPoints.set(extRef.id, {
- pluginId: r.pluginId,
- factory: () => extImpl,
- });
- provides.add(extRef);
- }
- } else if (r.type === 'plugin-v1.1' || r.type === 'module-v1.1') {
- // Handle v1.1 format: Array
- for (const extReg of r.extensionPoints) {
- if (this.#extensionPoints.has(extReg.extensionPoint.id)) {
- throw new Error(
- `ExtensionPoint with ID '${extReg.extensionPoint.id}' is already registered`,
- );
- }
- this.#extensionPoints.set(extReg.extensionPoint.id, {
- pluginId: r.pluginId,
- factory: extReg.factory,
- });
- provides.add(extReg.extensionPoint);
- }
- }
-
- if (r.type === 'plugin' || r.type === 'plugin-v1.1') {
- if (pluginInits.has(r.pluginId)) {
- throw new Error(`Plugin '${r.pluginId}' is already registered`);
- }
- pluginInits.set(r.pluginId, {
- provides,
- consumes: new Set(Object.values(r.init.deps)),
- init: r.init,
- });
- } else if (r.type === 'module' || r.type === 'module-v1.1') {
- let modules = moduleInits.get(r.pluginId);
- if (!modules) {
- modules = new Map();
- moduleInits.set(r.pluginId, modules);
- }
- if (modules.has(r.moduleId)) {
- throw new Error(
- `Module '${r.moduleId}' for plugin '${r.pluginId}' is already registered`,
- );
- }
- modules.set(r.moduleId, {
- provides,
- consumes: new Set(Object.values(r.init.deps)),
- init: r.init,
- });
- } else {
- throw new Error(`Invalid registration type '${(r as any).type}'`);
- }
- }
- }
-
- const pluginIds = [...pluginInits.keys()];
-
const rootConfig = await this.#serviceRegistry.get(
coreServices.rootConfig,
'root',
@@ -390,15 +319,32 @@ export class BackendInitializer {
'root',
);
+ const allRegistrations = this.#registrations.flatMap(f =>
+ f.getRegistrations(),
+ );
+
+ const allPluginIds = [
+ ...new Set(
+ allRegistrations.flatMap(r =>
+ 'pluginId' in r && typeof r.pluginId === 'string' ? [r.pluginId] : [],
+ ),
+ ),
+ ];
+
const resultCollector = createInitializationResultCollector({
- pluginIds,
+ pluginIds: allPluginIds,
logger: rootLogger,
allowBootFailurePredicate: createAllowBootFailurePredicate(rootConfig),
});
+ const { pluginInits, moduleInits } = this.#enumerateRegistrations(
+ allRegistrations,
+ resultCollector,
+ );
+
// All plugins are initialized in parallel
await Promise.all(
- pluginIds.map(async pluginId => {
+ [...pluginInits.keys()].map(async pluginId => {
try {
// Initialize all eager services
await this.#serviceRegistry.initializeEagerServicesWithScope(
@@ -491,6 +437,104 @@ export class BackendInitializer {
return { result };
}
+ #enumerateRegistrations(
+ allRegistrations: ReturnType<
+ InternalBackendRegistrations['getRegistrations']
+ >,
+ resultCollector: ReturnType,
+ ): {
+ pluginInits: Map;
+ moduleInits: Map>;
+ } {
+ const pluginInits = new Map();
+ const moduleInits = new Map>();
+
+ for (const r of allRegistrations) {
+ const addedExtensionPointIds: string[] = [];
+ try {
+ const provides = new Set>();
+
+ if (r.type === 'plugin' || r.type === 'module') {
+ // Handle v1 format: Array, unknown]>
+ for (const [extRef, extImpl] of r.extensionPoints) {
+ if (this.#extensionPoints.has(extRef.id)) {
+ throw new Error(
+ `ExtensionPoint with ID '${extRef.id}' is already registered`,
+ );
+ }
+ this.#extensionPoints.set(extRef.id, {
+ pluginId: r.pluginId,
+ factory: () => extImpl,
+ });
+ addedExtensionPointIds.push(extRef.id);
+ provides.add(extRef);
+ }
+ } else if (r.type === 'plugin-v1.1' || r.type === 'module-v1.1') {
+ // Handle v1.1 format: Array
+ for (const extReg of r.extensionPoints) {
+ if (this.#extensionPoints.has(extReg.extensionPoint.id)) {
+ throw new Error(
+ `ExtensionPoint with ID '${extReg.extensionPoint.id}' is already registered`,
+ );
+ }
+ this.#extensionPoints.set(extReg.extensionPoint.id, {
+ pluginId: r.pluginId,
+ factory: extReg.factory,
+ });
+ addedExtensionPointIds.push(extReg.extensionPoint.id);
+ provides.add(extReg.extensionPoint);
+ }
+ }
+
+ if (r.type === 'plugin' || r.type === 'plugin-v1.1') {
+ if (pluginInits.has(r.pluginId)) {
+ throw new Error(`Plugin '${r.pluginId}' is already registered`);
+ }
+ pluginInits.set(r.pluginId, {
+ provides,
+ consumes: new Set(Object.values(r.init.deps)),
+ init: r.init,
+ });
+ } else if (r.type === 'module' || r.type === 'module-v1.1') {
+ let modules = moduleInits.get(r.pluginId);
+ if (!modules) {
+ modules = new Map();
+ moduleInits.set(r.pluginId, modules);
+ }
+ if (modules.has(r.moduleId)) {
+ throw new Error(
+ `Module '${r.moduleId}' for plugin '${r.pluginId}' is already registered`,
+ );
+ }
+ modules.set(r.moduleId, {
+ provides,
+ consumes: new Set(Object.values(r.init.deps)),
+ init: r.init,
+ });
+ } else {
+ throw new Error(`Invalid registration type '${(r as any).type}'`);
+ }
+ } catch (error: unknown) {
+ assertError(error);
+ // Clean up partially registered extension points
+ for (const id of addedExtensionPointIds) {
+ this.#extensionPoints.delete(id);
+ }
+ if ('pluginId' in r && 'moduleId' in r) {
+ resultCollector.onPluginModuleResult(r.pluginId, r.moduleId, error);
+ } else if ('pluginId' in r) {
+ pluginInits.delete(r.pluginId);
+ moduleInits.delete(r.pluginId);
+ resultCollector.onPluginResult(r.pluginId, error);
+ } else {
+ throw error;
+ }
+ }
+ }
+
+ return { pluginInits, moduleInits };
+ }
+
// It's fine to call .stop() multiple times, which for example can happen with manual stop + process exit
async stop(): Promise {
instanceRegistry.unregister(this);
diff --git a/packages/backend-defaults/CHANGELOG.md b/packages/backend-defaults/CHANGELOG.md
index da970f1f45..f635723677 100644
--- a/packages/backend-defaults/CHANGELOG.md
+++ b/packages/backend-defaults/CHANGELOG.md
@@ -1,5 +1,138 @@
# @backstage/backend-defaults
+## 0.16.1-next.1
+
+### Patch Changes
+
+- 4559806: Added support for typed `examples` on actions registered via the actions registry. Action authors can now provide examples with compile-time-checked `input` and `output` values that match their schema definitions.
+- 5cd814f: Refactored auditor severity log level mappings to use `zod/v4` with schema-driven defaults and type inference.
+- 6e2aaab: Fixed `AwsS3UrlReader` failing to read files from S3 buckets configured with custom endpoint hosts. When an integration was configured with a specific endpoint like `https://bucket-1.s3.eu-central-1.amazonaws.com`, the URL parser incorrectly fell through to the non-AWS code path, always defaulting the region to `us-east-1` instead of extracting it from the hostname.
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.9.0-next.1
+ - @backstage/plugin-auth-node@0.7.0-next.1
+ - @backstage/backend-app-api@1.6.1-next.1
+ - @backstage/plugin-events-node@0.4.21-next.1
+ - @backstage/plugin-permission-node@0.10.12-next.1
+
+## 0.16.1-next.0
+
+### Patch Changes
+
+- 79453c0: Updated dependency `wait-for-expect` to `^4.0.0`.
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.1-next.0
+ - @backstage/cli-node@0.3.1-next.0
+ - @backstage/config-loader@1.10.10-next.0
+ - @backstage/backend-app-api@1.6.1-next.0
+ - @backstage/plugin-auth-node@0.6.15-next.0
+ - @backstage/plugin-permission-node@0.10.12-next.0
+ - @backstage/plugin-events-node@0.4.21-next.0
+ - @backstage/backend-dev-utils@0.1.7
+ - @backstage/config@1.3.6
+ - @backstage/errors@1.2.7
+ - @backstage/integration@2.0.0
+ - @backstage/integration-aws-node@0.1.20
+ - @backstage/types@1.2.2
+ - @backstage/plugin-permission-common@0.9.7
+
+## 0.16.0
+
+### Minor Changes
+
+- 42960f1: The actions registry invoke endpoint now accepts direct user credentials in addition to service principals, enabling CLI and other direct user clients to invoke actions.
+- 0e7d8f9: The scheduler service now uses the metrics service to create metrics, providing plugin-scoped attribution.
+- 527cf88: **BREAKING** Removed deprecated `BitbucketUrlReader`. Use the `BitbucketCloudUrlReader` or the `BitbucketServerUrlReader` instead.
+
+### Patch Changes
+
+- cc8348e: Added permissions integration to the actions registry. Actions registered with a `visibilityPermission` field are now checked against the permissions framework when listing and invoking. Denied actions are filtered from list results, and invoking a denied action returns a `404 Not Found` as if the action does not exist. Permissions are automatically registered with the `PermissionsRegistryService` so they appear in the permission policy system.
+- dee4283: Added `pluginId` field to `ActionsServiceAction` type, populated from the registering plugin's metadata.
+- 015668c: Added `cancelTask` method to the `SchedulerService` interface and implementation, allowing cancellation of currently running scheduled tasks. For global tasks, the database lock is released and a periodic liveness check aborts the running task function. For local tasks, the task's abort signal is triggered directly. A new `POST /.backstage/scheduler/v1/tasks/:id/cancel` endpoint is also available.
+- 638e6c7: chore(deps): bump `yauzl` from 3.2.0 to 3.2.1
+- 6738cf0: build(deps): bump `minimatch` from 9.0.5 to 10.2.1
+- 62f0a53: Fixed error forwarding in the actions registry so that known errors like `InputError` and `NotFoundError` thrown by actions preserve their original status codes and messages instead of being wrapped in `ForwardedError` and coerced to 500.
+- d933f62: Add configurable throttling and retry mechanism for GitLab integration.
+- b99158a: Fixed `yarn backstage-cli config:check --strict --config app-config.yaml` config validation error by adding
+ an optional `default` type discriminator to PostgreSQL connection configuration,
+ allowing `config:check` to properly validate `default` connection configurations.
+- 1ee5b28: Adds an alpha `MetricsService` to provide a unified interface for metrics instrumentation across Backstage plugins.
+- 5fcbef2: Updated dependency `express-rate-limit` to `^8.0.0`.
+- a49a40d: Updated dependency `zod` to `^3.25.76 || ^4.0.0` & migrated to `/v3` or `/v4` imports.
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0
+ - @backstage/cli-node@0.3.0
+ - @backstage/integration@2.0.0
+ - @backstage/config-loader@1.10.9
+ - @backstage/plugin-permission-common@0.9.7
+ - @backstage/plugin-permission-node@0.10.11
+ - @backstage/plugin-auth-node@0.6.14
+ - @backstage/backend-app-api@1.6.0
+ - @backstage/plugin-events-node@0.4.20
+
+## 0.16.0-next.2
+
+### Patch Changes
+
+- 015668c: Added `cancelTask` method to the `SchedulerService` interface and implementation, allowing cancellation of currently running scheduled tasks. For global tasks, the database lock is released and a periodic liveness check aborts the running task function. For local tasks, the task's abort signal is triggered directly. A new `POST /.backstage/scheduler/v1/tasks/:id/cancel` endpoint is also available.
+- 5fcbef2: Updated dependency `express-rate-limit` to `^8.0.0`.
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0-next.1
+ - @backstage/integration@2.0.0-next.2
+ - @backstage/backend-app-api@1.6.0-next.1
+ - @backstage/plugin-auth-node@0.6.14-next.2
+ - @backstage/plugin-events-node@0.4.20-next.1
+ - @backstage/plugin-permission-node@0.10.11-next.1
+
+## 0.16.0-next.1
+
+### Minor Changes
+
+- 0e7d8f9: The scheduler service now uses the metrics service to create metrics, providing plugin-scoped attribution.
+- 527cf88: **BREAKING** Removed deprecated `BitbucketUrlReader`. Use the `BitbucketCloudUrlReader` or the `BitbucketServerUrlReader` instead.
+
+### Patch Changes
+
+- 62f0a53: Fixed error forwarding in the actions registry so that known errors like `InputError` and `NotFoundError` thrown by actions preserve their original status codes and messages instead of being wrapped in `ForwardedError` and coerced to 500.
+- Updated dependencies
+ - @backstage/cli-node@0.2.19-next.1
+ - @backstage/integration@2.0.0-next.1
+ - @backstage/plugin-auth-node@0.6.14-next.1
+ - @backstage/backend-app-api@1.5.1-next.0
+ - @backstage/backend-dev-utils@0.1.7
+ - @backstage/backend-plugin-api@1.7.1-next.0
+ - @backstage/config@1.3.6
+ - @backstage/config-loader@1.10.9-next.0
+ - @backstage/errors@1.2.7
+ - @backstage/integration-aws-node@0.1.20
+ - @backstage/types@1.2.2
+ - @backstage/plugin-events-node@0.4.20-next.0
+ - @backstage/plugin-permission-node@0.10.11-next.0
+
+## 0.15.3-next.0
+
+### Patch Changes
+
+- 6738cf0: build(deps): bump `minimatch` from 9.0.5 to 10.2.1
+- d933f62: Add configurable throttling and retry mechanism for GitLab integration.
+- b99158a: Fixed `yarn backstage-cli config:check --strict --config app-config.yaml` config validation error by adding
+ an optional `default` type discriminator to PostgreSQL connection configuration,
+ allowing `config:check` to properly validate `default` connection configurations.
+- 1ee5b28: Adds an alpha `MetricsService` to provide a unified interface for metrics instrumentation across Backstage plugins.
+- Updated dependencies
+ - @backstage/cli-node@0.2.19-next.0
+ - @backstage/integration@1.21.0-next.0
+ - @backstage/config-loader@1.10.9-next.0
+ - @backstage/backend-plugin-api@1.7.1-next.0
+ - @backstage/backend-app-api@1.5.1-next.0
+ - @backstage/backend-dev-utils@0.1.7
+ - @backstage/config@1.3.6
+ - @backstage/errors@1.2.7
+ - @backstage/integration-aws-node@0.1.20
+ - @backstage/types@1.2.2
+ - @backstage/plugin-auth-node@0.6.14-next.0
+ - @backstage/plugin-events-node@0.4.20-next.0
+ - @backstage/plugin-permission-node@0.10.11-next.0
+
## 0.15.2
### Patch Changes
diff --git a/packages/backend-defaults/package.json b/packages/backend-defaults/package.json
index 6f705de7ba..33a262aadd 100644
--- a/packages/backend-defaults/package.json
+++ b/packages/backend-defaults/package.json
@@ -1,6 +1,6 @@
{
"name": "@backstage/backend-defaults",
- "version": "0.15.2",
+ "version": "0.16.1-next.1",
"description": "Backend defaults used by Backstage backend apps",
"backstage": {
"role": "node-library"
@@ -144,6 +144,7 @@
"@backstage/integration-aws-node": "workspace:^",
"@backstage/plugin-auth-node": "workspace:^",
"@backstage/plugin-events-node": "workspace:^",
+ "@backstage/plugin-permission-common": "workspace:^",
"@backstage/plugin-permission-node": "workspace:^",
"@backstage/types": "workspace:^",
"@google-cloud/storage": "^7.0.0",
@@ -164,7 +165,7 @@
"cron": "^3.0.0",
"express": "^4.22.0",
"express-promise-router": "^4.1.0",
- "express-rate-limit": "^7.5.0",
+ "express-rate-limit": "^8.2.2",
"fs-extra": "^11.2.0",
"git-url-parse": "^15.0.0",
"helmet": "^6.0.0",
@@ -193,9 +194,9 @@
"uuid": "^11.0.0",
"winston": "^3.2.1",
"winston-transport": "^4.5.0",
- "yauzl": "^3.0.0",
+ "yauzl": "^3.2.1",
"yn": "^4.0.0",
- "zod": "^3.25.76",
+ "zod": "^3.25.76 || ^4.0.0",
"zod-to-json-schema": "^3.25.1"
},
"devDependencies": {
@@ -220,7 +221,7 @@
"msw": "^1.0.0",
"node-mocks-http": "^1.0.0",
"supertest": "^7.0.0",
- "wait-for-expect": "^3.0.2"
+ "wait-for-expect": "^4.0.0"
},
"peerDependencies": {
"@google-cloud/cloud-sql-connector": "^1.4.0",
diff --git a/packages/backend-defaults/report-scheduler.api.md b/packages/backend-defaults/report-scheduler.api.md
index e0a85710a5..44a503d18c 100644
--- a/packages/backend-defaults/report-scheduler.api.md
+++ b/packages/backend-defaults/report-scheduler.api.md
@@ -6,6 +6,7 @@
import { DatabaseService } from '@backstage/backend-plugin-api';
import { HttpRouterService } from '@backstage/backend-plugin-api';
import { LoggerService } from '@backstage/backend-plugin-api';
+import { MetricsService } from '@backstage/backend-plugin-api/alpha';
import { PluginMetadataService } from '@backstage/backend-plugin-api';
import { RootLifecycleService } from '@backstage/backend-plugin-api';
import { SchedulerService } from '@backstage/backend-plugin-api';
@@ -17,6 +18,7 @@ export class DefaultSchedulerService {
static create(options: {
database: DatabaseService;
logger: LoggerService;
+ metrics: MetricsService;
rootLifecycle: RootLifecycleService;
httpRouter: HttpRouterService;
pluginMetadata: PluginMetadataService;
diff --git a/packages/backend-defaults/report-urlReader.api.md b/packages/backend-defaults/report-urlReader.api.md
index 78a35911b8..c32a63231b 100644
--- a/packages/backend-defaults/report-urlReader.api.md
+++ b/packages/backend-defaults/report-urlReader.api.md
@@ -10,7 +10,6 @@ import { AzureCredentialsManager } from '@backstage/integration';
import { AzureDevOpsCredentialsProvider } from '@backstage/integration';
import { AzureIntegration } from '@backstage/integration';
import { BitbucketCloudIntegration } from '@backstage/integration';
-import { BitbucketIntegration } from '@backstage/integration';
import { BitbucketServerIntegration } from '@backstage/integration';
import { Config } from '@backstage/config';
import { GerritIntegration } from '@backstage/integration';
@@ -190,38 +189,6 @@ export class BitbucketServerUrlReader implements UrlReaderService {
toString(): string;
}
-// @public @deprecated
-export class BitbucketUrlReader implements UrlReaderService {
- constructor(
- integration: BitbucketIntegration,
- logger: LoggerService,
- deps: {
- treeResponseFactory: ReadTreeResponseFactory;
- },
- );
- // (undocumented)
- static factory: ReaderFactory;
- // (undocumented)
- read(url: string): Promise;
- // (undocumented)
- readTree(
- url: string,
- options?: UrlReaderServiceReadTreeOptions,
- ): Promise;
- // (undocumented)
- readUrl(
- url: string,
- options?: UrlReaderServiceReadUrlOptions,
- ): Promise;
- // (undocumented)
- search(
- url: string,
- options?: UrlReaderServiceSearchOptions,
- ): Promise;
- // (undocumented)
- toString(): string;
-}
-
// @public
export class FetchUrlReader implements UrlReaderService {
static factory: ReaderFactory;
diff --git a/packages/backend-defaults/src/alpha/entrypoints/actions/actionsServiceFactory.test.ts b/packages/backend-defaults/src/alpha/entrypoints/actions/actionsServiceFactory.test.ts
index dbce47bea4..3f600dcbbc 100644
--- a/packages/backend-defaults/src/alpha/entrypoints/actions/actionsServiceFactory.test.ts
+++ b/packages/backend-defaults/src/alpha/entrypoints/actions/actionsServiceFactory.test.ts
@@ -66,6 +66,7 @@ describe('actionsServiceFactory', () => {
const mockActionsDefinition: ActionsServiceAction = {
description: 'my mock description',
id: 'my-plugin:test',
+ pluginId: 'my-plugin',
name: 'testy',
title: 'Test',
schema: {
@@ -755,6 +756,7 @@ describe('actionsServiceFactory', () => {
{
description: 'Test',
id: 'plugin-with-action:with-validation',
+ pluginId: 'plugin-with-action',
name: 'with-validation',
schema: {
input: {
diff --git a/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/DefaultActionsRegistryService.ts b/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/DefaultActionsRegistryService.ts
index 7348e0a185..1f6f108589 100644
--- a/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/DefaultActionsRegistryService.ts
+++ b/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/DefaultActionsRegistryService.ts
@@ -16,24 +16,25 @@
import {
AuthService,
+ BackstageCredentials,
HttpAuthService,
LoggerService,
+ PermissionsRegistryService,
+ PermissionsService,
PluginMetadataService,
} from '@backstage/backend-plugin-api';
import PromiseRouter from 'express-promise-router';
import { Router, json } from 'express';
-import { z, AnyZodObject } from 'zod';
+import { z, AnyZodObject } from 'zod/v3';
import zodToJsonSchema from 'zod-to-json-schema';
import {
ActionsRegistryActionOptions,
ActionsRegistryService,
} from '@backstage/backend-plugin-api/alpha';
-import {
- ForwardedError,
- InputError,
- NotAllowedError,
- NotFoundError,
-} from '@backstage/errors';
+import { InputError, NotAllowedError, NotFoundError } from '@backstage/errors';
+import { AuthorizeResult } from '@backstage/plugin-permission-common';
+
+type ActionEntry = [string, ActionsRegistryActionOptions];
export class DefaultActionsRegistryService implements ActionsRegistryService {
private actions: Map> =
@@ -43,17 +44,23 @@ export class DefaultActionsRegistryService implements ActionsRegistryService {
private readonly httpAuth: HttpAuthService;
private readonly auth: AuthService;
private readonly metadata: PluginMetadataService;
+ private readonly permissions: PermissionsService;
+ private readonly permissionsRegistry: PermissionsRegistryService;
private constructor(
logger: LoggerService,
httpAuth: HttpAuthService,
auth: AuthService,
metadata: PluginMetadataService,
+ permissions: PermissionsService,
+ permissionsRegistry: PermissionsRegistryService,
) {
this.logger = logger;
this.httpAuth = httpAuth;
this.auth = auth;
this.metadata = metadata;
+ this.permissions = permissions;
+ this.permissionsRegistry = permissionsRegistry;
}
static create({
@@ -61,24 +68,46 @@ export class DefaultActionsRegistryService implements ActionsRegistryService {
logger,
auth,
metadata,
+ permissions,
+ permissionsRegistry,
}: {
httpAuth: HttpAuthService;
logger: LoggerService;
auth: AuthService;
metadata: PluginMetadataService;
+ permissions: PermissionsService;
+ permissionsRegistry: PermissionsRegistryService;
}): DefaultActionsRegistryService {
- return new DefaultActionsRegistryService(logger, httpAuth, auth, metadata);
+ return new DefaultActionsRegistryService(
+ logger,
+ httpAuth,
+ auth,
+ metadata,
+ permissions,
+ permissionsRegistry,
+ );
}
createRouter(): Router {
const router = PromiseRouter();
router.use(json());
- router.get('/.backstage/actions/v1/actions', (_, res) => {
+ router.get('/.backstage/actions/v1/actions', async (req, res) => {
+ const credentials = await this.httpAuth.credentials(req);
+ const entries = Array.from(this.actions.entries());
+
+ const allowedActions = await this.filterByPermissions(
+ entries,
+ credentials,
+ );
+
return res.json({
- actions: Array.from(this.actions.entries()).map(([id, action]) => ({
+ actions: allowedActions.map(([id, action]) => ({
id,
- ...action,
+ name: action.name,
+ title: action.title,
+ description: action.description,
+ pluginId: this.metadata.getId(),
attributes: {
// Inspired by the @modelcontextprotocol/sdk defaults for the hints.
// https://github.com/modelcontextprotocol/typescript-sdk/blob/dd69efa1de8646bb6b195ff8d5f52e13739f4550/src/types.ts#L777-L812
@@ -86,6 +115,7 @@ export class DefaultActionsRegistryService implements ActionsRegistryService {
idempotent: action.attributes?.idempotent ?? false,
readOnly: action.attributes?.readOnly ?? false,
},
+ examples: action.examples,
schema: {
input: action.schema?.input
? zodToJsonSchema(action.schema.input(z))
@@ -102,15 +132,9 @@ export class DefaultActionsRegistryService implements ActionsRegistryService {
'/.backstage/actions/v1/actions/:actionId/invoke',
async (req, res) => {
const credentials = await this.httpAuth.credentials(req);
- if (this.auth.isPrincipal(credentials, 'user')) {
- if (!credentials.principal.actor) {
- throw new NotAllowedError(
- `Actions must be invoked by a service, not a user`,
- );
- }
- } else if (this.auth.isPrincipal(credentials, 'none')) {
+ if (this.auth.isPrincipal(credentials, 'none')) {
throw new NotAllowedError(
- `Actions must be invoked by a service, not an anonymous request`,
+ `Actions must be invoked by an authenticated principal, not an anonymous request`,
);
}
@@ -120,6 +144,18 @@ export class DefaultActionsRegistryService implements ActionsRegistryService {
throw new NotFoundError(`Action "${req.params.actionId}" not found`);
}
+ if (action.visibilityPermission) {
+ const [decision] = await this.permissions.authorize(
+ [{ permission: action.visibilityPermission }],
+ { credentials },
+ );
+ if (decision.result !== AuthorizeResult.ALLOW) {
+ throw new NotFoundError(
+ `Action "${req.params.actionId}" not found`,
+ );
+ }
+ }
+
const input = action.schema?.input
? action.schema.input(z).safeParse(req.body)
: ({ success: true, data: undefined } as const);
@@ -131,31 +167,24 @@ export class DefaultActionsRegistryService implements ActionsRegistryService {
);
}
- try {
- const result = await action.action({
- input: input.data,
- credentials,
- logger: this.logger,
- });
+ const result = await action.action({
+ input: input.data,
+ credentials,
+ logger: this.logger,
+ });
- const output = action.schema?.output
- ? action.schema.output(z).safeParse(result?.output)
- : ({ success: true, data: result?.output } as const);
+ const output = action.schema?.output
+ ? action.schema.output(z).safeParse(result?.output)
+ : ({ success: true, data: result?.output } as const);
- if (!output.success) {
- throw new InputError(
- `Invalid output from action "${req.params.actionId}"`,
- output.error,
- );
- }
-
- res.json({ output: output.data });
- } catch (error) {
- throw new ForwardedError(
- `Failed execution of action "${req.params.actionId}"`,
- error,
+ if (!output.success) {
+ throw new InputError(
+ `Invalid output from action "${req.params.actionId}"`,
+ output.error,
);
}
+
+ res.json({ output: output.data });
},
);
return router;
@@ -171,6 +200,38 @@ export class DefaultActionsRegistryService implements ActionsRegistryService {
throw new Error(`Action with id "${id}" is already registered`);
}
+ if (options.visibilityPermission) {
+ this.permissionsRegistry.addPermissions([options.visibilityPermission]);
+ }
+
this.actions.set(id, options);
}
+
+ private async filterByPermissions(
+ entries: ActionEntry[],
+ credentials: BackstageCredentials,
+ ): Promise {
+ const permissionedEntries = entries.filter(
+ ([_, action]) => action.visibilityPermission,
+ );
+
+ if (permissionedEntries.length === 0) {
+ return entries;
+ }
+
+ const decisions = await this.permissions.authorize(
+ permissionedEntries.map(([_, action]) => ({
+ permission: action.visibilityPermission!,
+ })),
+ { credentials },
+ );
+
+ const deniedIds = new Set(
+ permissionedEntries
+ .filter((_, index) => decisions[index].result !== AuthorizeResult.ALLOW)
+ .map(([id]) => id),
+ );
+
+ return entries.filter(([id]) => !deniedIds.has(id));
+ }
}
diff --git a/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/actionsRegistryServiceFactory.test.ts b/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/actionsRegistryServiceFactory.test.ts
index 79c103c284..39392c101c 100644
--- a/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/actionsRegistryServiceFactory.test.ts
+++ b/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/actionsRegistryServiceFactory.test.ts
@@ -22,8 +22,12 @@ import {
import { httpRouterServiceFactory } from '../../../entrypoints/httpRouter';
import request from 'supertest';
import { actionsRegistryServiceFactory } from './actionsRegistryServiceFactory';
-import { InputError } from '@backstage/errors';
+import { InputError, NotFoundError } from '@backstage/errors';
import { actionsRegistryServiceRef } from '@backstage/backend-plugin-api/alpha';
+import {
+ AuthorizeResult,
+ createPermission,
+} from '@backstage/plugin-permission-common';
describe('actionsRegistryServiceFactory', () => {
const defaultServices = [
@@ -107,6 +111,57 @@ describe('actionsRegistryServiceFactory', () => {
expect(true).toBe(true);
});
+
+ it('should enforce types on example input and output', () => {
+ createBackendPlugin({
+ pluginId: 'my-plugin',
+ register(reg) {
+ reg.registerInit({
+ deps: {
+ actionsRegistry: actionsRegistryServiceRef,
+ },
+ async init({ actionsRegistry }) {
+ actionsRegistry.register({
+ name: 'test',
+ title: 'Test',
+ description: 'Test',
+ schema: {
+ input: z =>
+ z.object({
+ name: z.string(),
+ }),
+ output: z =>
+ z.object({
+ ok: z.boolean(),
+ }),
+ },
+ examples: [
+ {
+ title: 'Valid example',
+ input: { name: 'test' },
+ output: { ok: true },
+ },
+ {
+ title: 'Bad input',
+ // @ts-expect-error - name must be a string
+ input: { name: 123 },
+ },
+ {
+ title: 'Bad output',
+ input: { name: 'test' },
+ // @ts-expect-error - ok must be a boolean
+ output: { ok: 'yes' },
+ },
+ ],
+ action: async () => ({ output: { ok: true } }),
+ });
+ },
+ });
+ },
+ });
+
+ expect(true).toBe(true);
+ });
});
describe('/.backstage/actions/v1/actions', () => {
@@ -282,6 +337,79 @@ describe('actionsRegistryServiceFactory', () => {
});
});
+ it('should return examples in the action list', async () => {
+ const pluginSubject = createBackendPlugin({
+ pluginId: 'my-plugin',
+ register(reg) {
+ reg.registerInit({
+ deps: {
+ actionsRegistry: actionsRegistryServiceRef,
+ },
+ async init({ actionsRegistry }) {
+ actionsRegistry.register({
+ name: 'test',
+ title: 'Test',
+ description: 'Test',
+ schema: {
+ input: z =>
+ z.object({
+ name: z.string(),
+ }),
+ output: z =>
+ z.object({
+ ok: z.boolean(),
+ }),
+ },
+ examples: [
+ {
+ title: 'Basic usage',
+ description: 'A simple example',
+ input: { name: 'world' },
+ output: { ok: true },
+ },
+ {
+ title: 'Without output',
+ input: { name: 'test' },
+ },
+ ],
+ action: async () => ({ output: { ok: true } }),
+ });
+ },
+ });
+ },
+ });
+
+ const { server } = await startTestBackend({
+ features: [pluginSubject, ...defaultServices],
+ });
+
+ const { body, status } = await request(server).get(
+ '/api/my-plugin/.backstage/actions/v1/actions',
+ );
+
+ expect(status).toBe(200);
+
+ expect(body).toMatchObject({
+ actions: [
+ {
+ name: 'test',
+ examples: [
+ {
+ title: 'Basic usage',
+ description: 'A simple example',
+ input: { name: 'world' },
+ output: { ok: true },
+ },
+ {
+ title: 'Without output',
+ input: { name: 'test' },
+ },
+ ],
+ },
+ ],
+ });
+ });
+
it('should forces registration of input and output schema as objects', async () => {
const pluginSubject = createBackendPlugin({
pluginId: 'my-plugin',
@@ -439,7 +567,7 @@ describe('actionsRegistryServiceFactory', () => {
});
});
- it('should throw an error if the action is invoked by a user', async () => {
+ it('should allow actions to be invoked by a user', async () => {
const testServices = [
actionsRegistryServiceFactory,
httpRouterServiceFactory,
@@ -460,12 +588,8 @@ describe('actionsRegistryServiceFactory', () => {
name: 'test',
});
- expect(status).toBe(403);
- expect(body).toMatchObject({
- error: {
- message: 'Actions must be invoked by a service, not a user',
- },
- });
+ expect(status).toBe(200);
+ expect(body).toMatchObject({ output: { ok: true } });
});
it('should validate the output of the action if provided', async () => {
@@ -510,7 +634,7 @@ describe('actionsRegistryServiceFactory', () => {
expect(body).toMatchObject({ output: { ok: true } });
});
- it('should return the error from the action if it throws', async () => {
+ it('should forward the original error when the action throws a known error', async () => {
const { server } = await startTestBackend({
features: [pluginSubject, ...defaultServices],
});
@@ -528,11 +652,341 @@ describe('actionsRegistryServiceFactory', () => {
expect(status).toBe(400);
expect(body).toMatchObject({
error: {
- message: expect.stringContaining(
- 'Failed execution of action "my-plugin:test"',
- ),
+ name: 'InputError',
+ message: 'test',
+ },
+ });
+ });
+
+ it('should forward a NotFoundError from the action with 404 status', async () => {
+ const { server } = await startTestBackend({
+ features: [pluginSubject, ...defaultServices],
+ });
+
+ mockAction.mockRejectedValue(new NotFoundError('entity not found'));
+
+ const { body, status } = await request(server)
+ .post(
+ '/api/my-plugin/.backstage/actions/v1/actions/my-plugin:test/invoke',
+ )
+ .send({
+ name: 'test',
+ });
+
+ expect(status).toBe(404);
+ expect(body).toMatchObject({
+ error: {
+ name: 'NotFoundError',
+ message: 'entity not found',
},
});
});
});
+
+ describe('permissions', () => {
+ const testPermission = createPermission({
+ name: 'test.action.use',
+ attributes: {},
+ });
+
+ it('should filter out actions with denied permissions when listing', async () => {
+ const pluginSubject = createBackendPlugin({
+ pluginId: 'my-plugin',
+ register(reg) {
+ reg.registerInit({
+ deps: {
+ actionsRegistry: actionsRegistryServiceRef,
+ },
+ async init({ actionsRegistry }) {
+ actionsRegistry.register({
+ name: 'public-action',
+ title: 'Public Action',
+ description: 'No permission required',
+ schema: {
+ input: z => z.object({}),
+ output: z => z.object({}),
+ },
+ action: async () => ({ output: {} }),
+ });
+ actionsRegistry.register({
+ name: 'protected-action',
+ title: 'Protected Action',
+ description: 'Permission required',
+ visibilityPermission: testPermission,
+ schema: {
+ input: z => z.object({}),
+ output: z => z.object({}),
+ },
+ action: async () => ({ output: {} }),
+ });
+ },
+ });
+ },
+ });
+
+ const { server } = await startTestBackend({
+ features: [
+ pluginSubject,
+ actionsRegistryServiceFactory,
+ httpRouterServiceFactory,
+ mockServices.httpAuth.factory({
+ defaultCredentials: mockCredentials.service('user:default/mock'),
+ }),
+ mockServices.permissions.factory({
+ result: AuthorizeResult.DENY,
+ }),
+ ],
+ });
+
+ const { body, status } = await request(server).get(
+ '/api/my-plugin/.backstage/actions/v1/actions',
+ );
+
+ expect(status).toBe(200);
+ expect(body.actions).toHaveLength(1);
+ expect(body.actions[0].name).toBe('public-action');
+ });
+
+ it('should include actions with allowed permissions when listing', async () => {
+ const pluginSubject = createBackendPlugin({
+ pluginId: 'my-plugin',
+ register(reg) {
+ reg.registerInit({
+ deps: {
+ actionsRegistry: actionsRegistryServiceRef,
+ },
+ async init({ actionsRegistry }) {
+ actionsRegistry.register({
+ name: 'protected-action',
+ title: 'Protected Action',
+ description: 'Permission required',
+ visibilityPermission: testPermission,
+ schema: {
+ input: z => z.object({}),
+ output: z => z.object({}),
+ },
+ action: async () => ({ output: {} }),
+ });
+ },
+ });
+ },
+ });
+
+ const { server } = await startTestBackend({
+ features: [
+ pluginSubject,
+ actionsRegistryServiceFactory,
+ httpRouterServiceFactory,
+ mockServices.httpAuth.factory({
+ defaultCredentials: mockCredentials.service('user:default/mock'),
+ }),
+ mockServices.permissions.factory({
+ result: AuthorizeResult.ALLOW,
+ }),
+ ],
+ });
+
+ const { body, status } = await request(server).get(
+ '/api/my-plugin/.backstage/actions/v1/actions',
+ );
+
+ expect(status).toBe(200);
+ expect(body.actions).toHaveLength(1);
+ expect(body.actions[0].name).toBe('protected-action');
+ });
+
+ it('should return 404 when invoking an action with denied permission', async () => {
+ const pluginSubject = createBackendPlugin({
+ pluginId: 'my-plugin',
+ register(reg) {
+ reg.registerInit({
+ deps: {
+ actionsRegistry: actionsRegistryServiceRef,
+ },
+ async init({ actionsRegistry }) {
+ actionsRegistry.register({
+ name: 'protected-action',
+ title: 'Protected Action',
+ description: 'Permission required',
+ visibilityPermission: testPermission,
+ schema: {
+ input: z => z.object({}),
+ output: z => z.object({}),
+ },
+ action: async () => ({ output: {} }),
+ });
+ },
+ });
+ },
+ });
+
+ const { server } = await startTestBackend({
+ features: [
+ pluginSubject,
+ actionsRegistryServiceFactory,
+ httpRouterServiceFactory,
+ mockServices.httpAuth.factory({
+ defaultCredentials: mockCredentials.service('user:default/mock'),
+ }),
+ mockServices.permissions.factory({
+ result: AuthorizeResult.DENY,
+ }),
+ ],
+ });
+
+ const { body, status } = await request(server).post(
+ '/api/my-plugin/.backstage/actions/v1/actions/my-plugin:protected-action/invoke',
+ );
+
+ expect(status).toBe(404);
+ expect(body).toMatchObject({
+ error: {
+ message: 'Action "my-plugin:protected-action" not found',
+ },
+ });
+ });
+
+ it('should allow invoking an action when permission is granted', async () => {
+ const mockAction = jest.fn().mockResolvedValue({ output: { ok: true } });
+
+ const pluginSubject = createBackendPlugin({
+ pluginId: 'my-plugin',
+ register(reg) {
+ reg.registerInit({
+ deps: {
+ actionsRegistry: actionsRegistryServiceRef,
+ },
+ async init({ actionsRegistry }) {
+ actionsRegistry.register({
+ name: 'protected-action',
+ title: 'Protected Action',
+ description: 'Permission required',
+ visibilityPermission: testPermission,
+ schema: {
+ input: z => z.object({}),
+ output: z => z.object({ ok: z.boolean() }),
+ },
+ action: mockAction,
+ });
+ },
+ });
+ },
+ });
+
+ const { server } = await startTestBackend({
+ features: [
+ pluginSubject,
+ actionsRegistryServiceFactory,
+ httpRouterServiceFactory,
+ mockServices.httpAuth.factory({
+ defaultCredentials: mockCredentials.service('user:default/mock'),
+ }),
+ mockServices.permissions.factory({
+ result: AuthorizeResult.ALLOW,
+ }),
+ ],
+ });
+
+ const { body, status } = await request(server).post(
+ '/api/my-plugin/.backstage/actions/v1/actions/my-plugin:protected-action/invoke',
+ );
+
+ expect(status).toBe(200);
+ expect(body).toMatchObject({ output: { ok: true } });
+ expect(mockAction).toHaveBeenCalled();
+ });
+
+ it('should pass the correct permission to the authorize call', async () => {
+ const permissionsMock = mockServices.permissions.mock({
+ authorize: async () => [{ result: AuthorizeResult.ALLOW }],
+ });
+
+ const pluginSubject = createBackendPlugin({
+ pluginId: 'my-plugin',
+ register(reg) {
+ reg.registerInit({
+ deps: {
+ actionsRegistry: actionsRegistryServiceRef,
+ },
+ async init({ actionsRegistry }) {
+ actionsRegistry.register({
+ name: 'protected-action',
+ title: 'Protected Action',
+ description: 'Permission required',
+ visibilityPermission: testPermission,
+ schema: {
+ input: z => z.object({}),
+ output: z => z.object({}),
+ },
+ action: async () => ({ output: {} }),
+ });
+ },
+ });
+ },
+ });
+
+ const { server } = await startTestBackend({
+ features: [
+ pluginSubject,
+ actionsRegistryServiceFactory,
+ httpRouterServiceFactory,
+ mockServices.httpAuth.factory({
+ defaultCredentials: mockCredentials.service('user:default/mock'),
+ }),
+ permissionsMock.factory,
+ ],
+ });
+
+ await request(server).get('/api/my-plugin/.backstage/actions/v1/actions');
+
+ expect(permissionsMock.authorize).toHaveBeenCalledWith(
+ [{ permission: testPermission }],
+ expect.objectContaining({ credentials: expect.anything() }),
+ );
+ });
+
+ it('should register the permission with the permissions registry', async () => {
+ const permissionsRegistryMock = mockServices.permissionsRegistry.mock();
+
+ const pluginSubject = createBackendPlugin({
+ pluginId: 'my-plugin',
+ register(reg) {
+ reg.registerInit({
+ deps: {
+ actionsRegistry: actionsRegistryServiceRef,
+ },
+ async init({ actionsRegistry }) {
+ actionsRegistry.register({
+ name: 'protected-action',
+ title: 'Protected Action',
+ description: 'Permission required',
+ visibilityPermission: testPermission,
+ schema: {
+ input: z => z.object({}),
+ output: z => z.object({}),
+ },
+ action: async () => ({ output: {} }),
+ });
+ },
+ });
+ },
+ });
+
+ await startTestBackend({
+ features: [
+ pluginSubject,
+ actionsRegistryServiceFactory,
+ httpRouterServiceFactory,
+ mockServices.httpAuth.factory({
+ defaultCredentials: mockCredentials.service('user:default/mock'),
+ }),
+ permissionsRegistryMock.factory,
+ ],
+ });
+
+ expect(permissionsRegistryMock.addPermissions).toHaveBeenCalledWith([
+ testPermission,
+ ]);
+ });
+ });
});
diff --git a/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/actionsRegistryServiceFactory.ts b/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/actionsRegistryServiceFactory.ts
index 8c19b8148c..4ac6b2c782 100644
--- a/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/actionsRegistryServiceFactory.ts
+++ b/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/actionsRegistryServiceFactory.ts
@@ -32,13 +32,25 @@ export const actionsRegistryServiceFactory = createServiceFactory({
httpAuth: coreServices.httpAuth,
logger: coreServices.logger,
auth: coreServices.auth,
+ permissions: coreServices.permissions,
+ permissionsRegistry: coreServices.permissionsRegistry,
},
- factory: ({ metadata, httpRouter, httpAuth, logger, auth }) => {
+ factory: ({
+ metadata,
+ httpRouter,
+ httpAuth,
+ logger,
+ auth,
+ permissions,
+ permissionsRegistry,
+ }) => {
const actionsRegistryService = DefaultActionsRegistryService.create({
httpAuth,
logger,
auth,
metadata,
+ permissions,
+ permissionsRegistry,
});
httpRouter.use(actionsRegistryService.createRouter());
diff --git a/packages/backend-defaults/src/entrypoints/auditor/utils.ts b/packages/backend-defaults/src/entrypoints/auditor/utils.ts
index 719a227bf9..0513aa84b2 100644
--- a/packages/backend-defaults/src/entrypoints/auditor/utils.ts
+++ b/packages/backend-defaults/src/entrypoints/auditor/utils.ts
@@ -16,8 +16,20 @@
import type { Config } from '@backstage/config';
import { InputError } from '@backstage/errors';
-import { z } from 'zod';
-import { CONFIG_ROOT_KEY, severityLogLevelMappingsSchema } from './types';
+import { z } from 'zod/v4';
+
+const CONFIG_ROOT_KEY = 'backend.auditor';
+
+const logLevel = z.enum(['debug', 'info', 'warn', 'error']);
+
+const severityLogLevelMappingsSchema = z.object({
+ low: logLevel.default('debug'),
+ medium: logLevel.default('info'),
+ high: logLevel.default('info'),
+ critical: logLevel.default('info'),
+});
+
+type SeverityLogLevelMappings = z.infer;
/**
* Gets the `backend.auditor.severityLogLevelMappings` configuration.
@@ -26,41 +38,32 @@ import { CONFIG_ROOT_KEY, severityLogLevelMappingsSchema } from './types';
* @returns The validated severity-to-log-level mappings.
* @throws error - {@link @backstage/errors#InputError} if the mapping configuration is invalid.
*/
-export function getSeverityLogLevelMappings(config: Config) {
+export function getSeverityLogLevelMappings(
+ config: Config,
+): SeverityLogLevelMappings {
const auditorConfig = config.getOptionalConfig(CONFIG_ROOT_KEY);
- const severityLogLevelMappings = {
- low:
- auditorConfig?.getOptionalString('severityLogLevelMappings.low') ??
- 'debug',
- medium:
- auditorConfig?.getOptionalString('severityLogLevelMappings.medium') ??
- 'info',
- high:
- auditorConfig?.getOptionalString('severityLogLevelMappings.high') ??
- 'info',
- critical:
- auditorConfig?.getOptionalString('severityLogLevelMappings.critical') ??
- 'info',
- } as Required>;
+ const input = {
+ low: auditorConfig?.getOptionalString('severityLogLevelMappings.low'),
+ medium: auditorConfig?.getOptionalString('severityLogLevelMappings.medium'),
+ high: auditorConfig?.getOptionalString('severityLogLevelMappings.high'),
+ critical: auditorConfig?.getOptionalString(
+ 'severityLogLevelMappings.critical',
+ ),
+ };
- const res = severityLogLevelMappingsSchema.safeParse(
- severityLogLevelMappings,
- );
- if (!res.success) {
- const key = res.error.issues.at(0)?.path.at(0) as string;
- const value = (
- res.error.issues.at(0) as unknown as Record
- ).received as string;
- const validKeys = (
- res.error.issues.at(0) as unknown as Record
- ).options as string[];
+ const parsed = severityLogLevelMappingsSchema.safeParse(input);
+
+ if (!parsed.success) {
+ const issue = parsed.error.issues[0];
+ const key = issue.path[0] as keyof typeof input;
+ const receivedValue = input[key];
throw new InputError(
- `The configuration value for 'backend.auditor.severityLogLevelMappings.${key}' was given an invalid value: '${value}'. Expected one of the following valid values: '${validKeys.join(
+ `The configuration value for '${CONFIG_ROOT_KEY}.severityLogLevelMappings.${key}' was given an invalid value: '${receivedValue}'. Expected one of the following valid values: '${logLevel.options.join(
', ',
)}'.`,
);
}
- return severityLogLevelMappings;
+ return parsed.data;
}
diff --git a/packages/backend-defaults/src/entrypoints/scheduler/lib/DefaultSchedulerService.test.ts b/packages/backend-defaults/src/entrypoints/scheduler/lib/DefaultSchedulerService.test.ts
index 61f9bd0639..3de69ba566 100644
--- a/packages/backend-defaults/src/entrypoints/scheduler/lib/DefaultSchedulerService.test.ts
+++ b/packages/backend-defaults/src/entrypoints/scheduler/lib/DefaultSchedulerService.test.ts
@@ -20,6 +20,7 @@ import waitForExpect from 'wait-for-expect';
import { DefaultSchedulerService } from './DefaultSchedulerService';
import { createTestScopedSignal } from './__testUtils__/createTestScopedSignal';
import { PluginMetadataService } from '@backstage/backend-plugin-api';
+import { metricsServiceMock } from '@backstage/backend-test-utils/alpha';
jest.setTimeout(60_000);
@@ -32,6 +33,7 @@ describe('TaskScheduler', () => {
getId: () => 'test',
} satisfies PluginMetadataService;
const testScopedSignal = createTestScopedSignal();
+ const metrics = metricsServiceMock.mock();
it.each(databases.eachSupportedId())(
'can return a working v1 plugin impl, %p',
@@ -42,6 +44,7 @@ describe('TaskScheduler', () => {
const manager = DefaultSchedulerService.create({
database,
logger,
+ metrics,
rootLifecycle,
httpRouter,
pluginMetadata,
@@ -71,6 +74,7 @@ describe('TaskScheduler', () => {
const manager = DefaultSchedulerService.create({
database,
logger,
+ metrics,
rootLifecycle,
httpRouter,
pluginMetadata,
diff --git a/packages/backend-defaults/src/entrypoints/scheduler/lib/DefaultSchedulerService.ts b/packages/backend-defaults/src/entrypoints/scheduler/lib/DefaultSchedulerService.ts
index 0a7b9fbb87..07531cffc8 100644
--- a/packages/backend-defaults/src/entrypoints/scheduler/lib/DefaultSchedulerService.ts
+++ b/packages/backend-defaults/src/entrypoints/scheduler/lib/DefaultSchedulerService.ts
@@ -27,6 +27,7 @@ import { Duration } from 'luxon';
import { migrateBackendTasks } from '../database/migrateBackendTasks';
import { PluginTaskSchedulerImpl } from './PluginTaskSchedulerImpl';
import { PluginTaskSchedulerJanitor } from './PluginTaskSchedulerJanitor';
+import { MetricsService } from '@backstage/backend-plugin-api/alpha';
/**
* Default implementation of the task scheduler service.
@@ -37,6 +38,7 @@ export class DefaultSchedulerService {
static create(options: {
database: DatabaseService;
logger: LoggerService;
+ metrics: MetricsService;
rootLifecycle: RootLifecycleService;
httpRouter: HttpRouterService;
pluginMetadata: PluginMetadataService;
@@ -67,6 +69,7 @@ export class DefaultSchedulerService {
options.pluginMetadata.getId(),
databaseFactory,
options.logger,
+ options.metrics,
options.rootLifecycle,
);
diff --git a/packages/backend-defaults/src/entrypoints/scheduler/lib/LocalTaskWorker.test.ts b/packages/backend-defaults/src/entrypoints/scheduler/lib/LocalTaskWorker.test.ts
index 14fedfb3c0..04c2b17ad3 100644
--- a/packages/backend-defaults/src/entrypoints/scheduler/lib/LocalTaskWorker.test.ts
+++ b/packages/backend-defaults/src/entrypoints/scheduler/lib/LocalTaskWorker.test.ts
@@ -16,6 +16,7 @@
import { LocalTaskWorker } from './LocalTaskWorker';
import { mockServices } from '@backstage/backend-test-utils';
+import { ConflictError } from '@backstage/errors';
import waitFor from 'wait-for-expect';
jest.setTimeout(10_000);
@@ -110,6 +111,54 @@ describe('LocalTaskWorker', () => {
controller.abort();
});
+ it('can cancel a running task', async () => {
+ let receivedSignal: AbortSignal | undefined;
+ const fn = jest.fn(async (signal: AbortSignal) => {
+ receivedSignal = signal;
+ await new Promise(r => setTimeout(r, 5000));
+ });
+ const controller = new AbortController();
+
+ const worker = new LocalTaskWorker('a', fn, logger);
+ worker.start(
+ {
+ version: 2,
+ cadence: 'PT10S',
+ timeoutAfterDuration: 'PT10S',
+ },
+ { signal: controller.signal },
+ );
+
+ await waitFor(() => {
+ expect(fn).toHaveBeenCalledTimes(1);
+ });
+
+ expect(receivedSignal?.aborted).toBe(false);
+ worker.cancel();
+ expect(receivedSignal?.aborted).toBe(true);
+
+ controller.abort();
+ });
+
+ it('cannot cancel a task that is not running', async () => {
+ const fn = jest.fn();
+ const controller = new AbortController();
+
+ const worker = new LocalTaskWorker('a', fn, logger);
+ worker.start(
+ {
+ version: 2,
+ initialDelayDuration: 'PT1000S',
+ cadence: 'PT10S',
+ timeoutAfterDuration: 'PT10S',
+ },
+ { signal: controller.signal },
+ );
+
+ expect(() => worker.cancel()).toThrow(ConflictError);
+ controller.abort();
+ });
+
it('goes through the expected states', async () => {
const fn = jest
.fn()
diff --git a/packages/backend-defaults/src/entrypoints/scheduler/lib/LocalTaskWorker.ts b/packages/backend-defaults/src/entrypoints/scheduler/lib/LocalTaskWorker.ts
index efecb1c0ed..168649436c 100644
--- a/packages/backend-defaults/src/entrypoints/scheduler/lib/LocalTaskWorker.ts
+++ b/packages/backend-defaults/src/entrypoints/scheduler/lib/LocalTaskWorker.ts
@@ -29,6 +29,7 @@ import { delegateAbortController, serializeError, sleep } from './util';
*/
export class LocalTaskWorker {
private abortWait: AbortController | undefined;
+ private taskAbortController: AbortController | undefined;
#taskState: Exclude = {
status: 'idle',
};
@@ -93,6 +94,13 @@ export class LocalTaskWorker {
this.abortWait.abort();
}
+ cancel(): void {
+ if (!this.taskAbortController) {
+ throw new ConflictError(`Task ${this.taskId} is not running`);
+ }
+ this.taskAbortController.abort();
+ }
+
taskState(): TaskApiTasksResponse['taskState'] {
return this.#taskState;
}
@@ -134,10 +142,10 @@ export class LocalTaskWorker {
): Promise {
// Abort the task execution either if the worker is stopped, or if the
// task timeout is hit
- const taskAbortController = delegateAbortController(signal);
+ this.taskAbortController = delegateAbortController(signal);
const timeoutDuration = Duration.fromISO(settings.timeoutAfterDuration);
const timeoutHandle = setTimeout(() => {
- taskAbortController.abort();
+ this.taskAbortController?.abort();
}, timeoutDuration.as('milliseconds'));
this.#taskState = {
@@ -152,7 +160,7 @@ export class LocalTaskWorker {
};
try {
- await this.fn(taskAbortController.signal);
+ await this.fn(this.taskAbortController.signal);
this.#taskState.lastRunEndedAt = DateTime.utc().toISO()!;
this.#taskState.lastRunError = undefined;
} catch (e) {
@@ -162,7 +170,8 @@ export class LocalTaskWorker {
// release resources
clearTimeout(timeoutHandle);
- taskAbortController.abort();
+ this.taskAbortController.abort();
+ this.taskAbortController = undefined;
}
/**
diff --git a/packages/backend-defaults/src/entrypoints/scheduler/lib/PluginTaskSchedulerImpl.test.ts b/packages/backend-defaults/src/entrypoints/scheduler/lib/PluginTaskSchedulerImpl.test.ts
index 5872ae793e..cc8aac5f51 100644
--- a/packages/backend-defaults/src/entrypoints/scheduler/lib/PluginTaskSchedulerImpl.test.ts
+++ b/packages/backend-defaults/src/entrypoints/scheduler/lib/PluginTaskSchedulerImpl.test.ts
@@ -27,6 +27,7 @@ import {
parseDuration,
} from './PluginTaskSchedulerImpl';
import { createDeferred } from '@backstage/types';
+import { metricsServiceMock } from '@backstage/backend-test-utils/alpha';
jest.setTimeout(60_000);
@@ -56,6 +57,7 @@ describe('PluginTaskManagerImpl', () => {
'myplugin',
async () => knex,
mockServices.logger.mock(),
+ metricsServiceMock.mock(),
{
addShutdownHook,
addBeforeShutdownHook: jest.fn(),
@@ -397,6 +399,100 @@ describe('PluginTaskManagerImpl', () => {
);
});
+ describe('cancelTask with local scope', () => {
+ it('can cancel a running task', async () => {
+ const { manager } = await init('SQLITE_3');
+
+ const promise = createDeferred();
+
+ await manager.scheduleTask({
+ id: 'task1',
+ timeout: Duration.fromMillis(5000),
+ frequency: Duration.fromObject({ years: 1 }),
+ fn: async () => {
+ promise.resolve();
+ await new Promise(r => setTimeout(r, 20000));
+ },
+ scope: 'local',
+ });
+
+ await promise;
+ await expect(manager.cancelTask('task1')).resolves.toBeUndefined();
+ }, 60_000);
+
+ it('cannot cancel a task that is not running', async () => {
+ const { manager } = await init('SQLITE_3');
+
+ const fn = jest.fn();
+ await manager.scheduleTask({
+ id: 'task1',
+ timeout: Duration.fromMillis(5000),
+ frequency: Duration.fromObject({ years: 1 }),
+ initialDelay: Duration.fromObject({ years: 1 }),
+ fn,
+ scope: 'local',
+ });
+
+ await expect(manager.cancelTask('task1')).rejects.toThrow(ConflictError);
+ }, 60_000);
+ });
+
+ describe('cancelTask with global scope', () => {
+ it.each(databases.eachSupportedId())(
+ 'can cancel a running task, %p',
+ async databaseId => {
+ const { manager } = await init(databaseId);
+
+ const promise = createDeferred();
+
+ await manager.scheduleTask({
+ id: 'task1',
+ timeout: Duration.fromMillis(5000),
+ frequency: Duration.fromObject({ years: 1 }),
+ fn: async () => {
+ promise.resolve();
+ await new Promise(r => setTimeout(r, 20000));
+ },
+ scope: 'global',
+ });
+
+ await promise;
+ await expect(manager.cancelTask('task1')).resolves.toBeUndefined();
+ },
+ );
+
+ it.each(databases.eachSupportedId())(
+ 'cannot cancel a non-existent task, %p',
+ async databaseId => {
+ const { manager } = await init(databaseId);
+
+ await expect(manager.cancelTask('nonexistent')).rejects.toThrow(
+ NotFoundError,
+ );
+ },
+ );
+
+ it.each(databases.eachSupportedId())(
+ 'cannot cancel a task that is not running, %p',
+ async databaseId => {
+ const { manager } = await init(databaseId);
+
+ await manager.scheduleTask({
+ id: 'task1',
+ timeout: Duration.fromMillis(5000),
+ frequency: Duration.fromObject({ years: 1 }),
+ initialDelay: Duration.fromObject({ years: 1 }),
+ fn: jest.fn(),
+ scope: 'global',
+ });
+
+ await expect(manager.cancelTask('task1')).rejects.toThrow(
+ ConflictError,
+ );
+ },
+ );
+ });
+
describe('parseDuration', () => {
it('should parse durations', () => {
expect(parseDuration({ milliseconds: 5000 })).toEqual('PT5S');
diff --git a/packages/backend-defaults/src/entrypoints/scheduler/lib/PluginTaskSchedulerImpl.ts b/packages/backend-defaults/src/entrypoints/scheduler/lib/PluginTaskSchedulerImpl.ts
index 90f5d08e4a..2aad8647fe 100644
--- a/packages/backend-defaults/src/entrypoints/scheduler/lib/PluginTaskSchedulerImpl.ts
+++ b/packages/backend-defaults/src/entrypoints/scheduler/lib/PluginTaskSchedulerImpl.ts
@@ -24,7 +24,13 @@ import {
SchedulerServiceTaskRunner,
SchedulerServiceTaskScheduleDefinition,
} from '@backstage/backend-plugin-api';
-import { Counter, Histogram, Gauge, metrics, trace } from '@opentelemetry/api';
+import { trace } from '@opentelemetry/api';
+import {
+ MetricsService,
+ MetricsServiceCounter,
+ MetricsServiceGauge,
+ MetricsServiceHistogram,
+} from '@backstage/backend-plugin-api/alpha';
import { Knex } from 'knex';
import { Duration } from 'luxon';
import express from 'express';
@@ -45,10 +51,10 @@ export class PluginTaskSchedulerImpl implements SchedulerService {
private readonly allScheduledTasks: SchedulerServiceTaskDescriptor[] = [];
private readonly shutdownInitiated: Promise;
- private readonly counter: Counter;
- private readonly duration: Histogram;
- private readonly lastStarted: Gauge;
- private readonly lastCompleted: Gauge;
+ private readonly counter: MetricsServiceCounter;
+ private readonly duration: MetricsServiceHistogram;
+ private readonly lastStarted: MetricsServiceGauge;
+ private readonly lastCompleted: MetricsServiceGauge;
private readonly pluginId: string;
private readonly databaseFactory: () => Promise;
@@ -58,24 +64,27 @@ export class PluginTaskSchedulerImpl implements SchedulerService {
pluginId: string,
databaseFactory: () => Promise,
logger: LoggerService,
+ metrics: MetricsService,
rootLifecycle: RootLifecycleService,
) {
this.pluginId = pluginId;
this.databaseFactory = databaseFactory;
this.logger = logger;
- const meter = metrics.getMeter('default');
- this.counter = meter.createCounter('backend_tasks.task.runs.count', {
+ this.counter = metrics.createCounter('backend_tasks.task.runs.count', {
description: 'Total number of times a task has been run',
});
- this.duration = meter.createHistogram('backend_tasks.task.runs.duration', {
- description: 'Histogram of task run durations',
- unit: 'seconds',
- });
- this.lastStarted = meter.createGauge('backend_tasks.task.runs.started', {
+ this.duration = metrics.createHistogram(
+ 'backend_tasks.task.runs.duration',
+ {
+ description: 'Histogram of task run durations',
+ unit: 'seconds',
+ },
+ );
+ this.lastStarted = metrics.createGauge('backend_tasks.task.runs.started', {
description: 'Epoch timestamp seconds when the task was last started',
unit: 'seconds',
});
- this.lastCompleted = meter.createGauge(
+ this.lastCompleted = metrics.createGauge(
'backend_tasks.task.runs.completed',
{
description: 'Epoch timestamp seconds when the task was last completed',
@@ -98,6 +107,17 @@ export class PluginTaskSchedulerImpl implements SchedulerService {
await TaskWorker.trigger(knex, id);
}
+ async cancelTask(id: string): Promise {
+ const localTask = this.localWorkersById.get(id);
+ if (localTask) {
+ localTask.cancel();
+ return;
+ }
+
+ const knex = await this.databaseFactory();
+ await TaskWorker.cancel(knex, id);
+ }
+
async scheduleTask(
task: SchedulerServiceTaskScheduleDefinition &
SchedulerServiceTaskInvocationDefinition,
@@ -197,6 +217,15 @@ export class PluginTaskSchedulerImpl implements SchedulerService {
},
);
+ router.post(
+ '/.backstage/scheduler/v1/tasks/:id/cancel',
+ async (req, res) => {
+ const { id } = req.params;
+ await this.cancelTask(id);
+ res.status(200).end();
+ },
+ );
+
return router;
}
diff --git a/packages/backend-defaults/src/entrypoints/scheduler/lib/TaskWorker.test.ts b/packages/backend-defaults/src/entrypoints/scheduler/lib/TaskWorker.test.ts
index 5bd3fb38cb..2f690ef499 100644
--- a/packages/backend-defaults/src/entrypoints/scheduler/lib/TaskWorker.test.ts
+++ b/packages/backend-defaults/src/entrypoints/scheduler/lib/TaskWorker.test.ts
@@ -15,6 +15,7 @@
*/
import { TestDatabases, mockServices } from '@backstage/backend-test-utils';
+import { ConflictError, NotFoundError } from '@backstage/errors';
import { DateTime, Duration } from 'luxon';
import waitForExpect from 'wait-for-expect';
import { migrateBackendTasks } from '../database/migrateBackendTasks';
@@ -25,123 +26,154 @@ import { TaskSettingsV2 } from './types';
jest.setTimeout(60_000);
-describe('TaskWorker', () => {
+const databases = TestDatabases.create();
+
+describe.each(databases.eachSupportedId())('TaskWorker, %s', databaseId => {
const logger = mockServices.logger.mock();
- const databases = TestDatabases.create();
const testScopedSignal = createTestScopedSignal();
- beforeEach(() => {
+ let knex: Awaited>;
+
+ beforeEach(async () => {
+ knex = await databases.init(databaseId);
+ await migrateBackendTasks(knex);
jest.resetAllMocks();
});
- it.each(databases.eachSupportedId())(
- 'goes through the expected states, %p',
- async databaseId => {
- const knex = await databases.init(databaseId);
- await migrateBackendTasks(knex);
+ afterEach(async () => {
+ await knex?.destroy();
+ });
- const fn = jest.fn(
- async () => new Promise(resolve => setTimeout(resolve, 50)),
- );
- const settings: TaskSettingsV2 = {
- version: 2,
- cadence: '*/2 * * * * *',
- initialDelayDuration: Duration.fromObject({ seconds: 3 }).toISO()!, // over 1 second, to cover for 1-second granularity in some database timestamps
- timeoutAfterDuration: Duration.fromObject({ minutes: 1 }).toISO()!,
- };
+ it('goes through the expected states', async () => {
+ const fn = jest.fn(
+ async () => new Promise(resolve => setTimeout(resolve, 50)),
+ );
+ const settings: TaskSettingsV2 = {
+ version: 2,
+ cadence: '*/2 * * * * *',
+ initialDelayDuration: Duration.fromObject({ seconds: 3 }).toISO()!, // over 1 second, to cover for 1-second granularity in some database timestamps
+ timeoutAfterDuration: Duration.fromObject({ minutes: 1 }).toISO()!,
+ };
- const worker = new TaskWorker('task1', fn, knex, logger);
- await worker.persistTask(settings);
+ const worker = new TaskWorker('task1', fn, knex, logger);
+ await worker.persistTask(settings);
- let row = (await knex(DB_TASKS_TABLE))[0];
- expect(row).toEqual(
- expect.objectContaining({
- id: 'task1',
- current_run_ticket: null,
- current_run_started_at: null,
- current_run_expires_at: null,
- }),
- );
- expect(JSON.parse(row.settings_json)).toEqual({
- version: 2,
- cadence: '*/2 * * * * *',
- initialDelayDuration: 'PT3S',
- timeoutAfterDuration: 'PT1M',
- });
- await expect(TaskWorker.taskStates(knex)).resolves.toEqual(
- new Map([
- [
- 'task1',
- {
- status: 'idle',
- startsAt: expect.anything(),
- },
- ],
- ]),
- );
+ let row = (await knex(DB_TASKS_TABLE))[0];
+ expect(row).toEqual(
+ expect.objectContaining({
+ id: 'task1',
+ current_run_ticket: null,
+ current_run_started_at: null,
+ current_run_expires_at: null,
+ }),
+ );
+ expect(JSON.parse(row.settings_json)).toEqual({
+ version: 2,
+ cadence: '*/2 * * * * *',
+ initialDelayDuration: 'PT3S',
+ timeoutAfterDuration: 'PT1M',
+ });
+ await expect(TaskWorker.taskStates(knex)).resolves.toEqual(
+ new Map([
+ [
+ 'task1',
+ {
+ status: 'idle',
+ startsAt: expect.anything(),
+ },
+ ],
+ ]),
+ );
- // Note that this is timing sensitive - if things take too long between
- // persistTask and findReadyTask, this test will fail. We set some margin
- // of initialDelayDuration to cover for this, but if this turns out to be
- // flaky, we may have to revisit how this test is written.
+ // Note that this is timing sensitive - if things take too long between
+ // persistTask and findReadyTask, this test will fail. We set some margin
+ // of initialDelayDuration to cover for this, but if this turns out to be
+ // flaky, we may have to revisit how this test is written.
+ await expect(worker.findReadyTask()).resolves.toEqual({
+ result: 'not-ready-yet',
+ });
+
+ await waitForExpect(async () => {
await expect(worker.findReadyTask()).resolves.toEqual({
- result: 'not-ready-yet',
+ result: 'ready',
+ settings,
});
+ });
- await waitForExpect(async () => {
- await expect(worker.findReadyTask()).resolves.toEqual({
- result: 'ready',
- settings,
- });
- });
+ row = (await knex(DB_TASKS_TABLE))[0];
+ expect(row).toEqual(
+ expect.objectContaining({
+ id: 'task1',
+ current_run_ticket: null,
+ current_run_started_at: null,
+ current_run_expires_at: null,
+ }),
+ );
- row = (await knex(DB_TASKS_TABLE))[0];
- expect(row).toEqual(
- expect.objectContaining({
- id: 'task1',
- current_run_ticket: null,
- current_run_started_at: null,
- current_run_expires_at: null,
- }),
- );
+ await expect(worker.tryClaimTask('ticket', settings)).resolves.toBe(true);
- await expect(worker.tryClaimTask('ticket', settings)).resolves.toBe(true);
+ row = (await knex(DB_TASKS_TABLE))[0];
+ expect(row).toEqual(
+ expect.objectContaining({
+ id: 'task1',
+ current_run_ticket: 'ticket',
+ current_run_started_at: expect.anything(),
+ current_run_expires_at: expect.anything(),
+ }),
+ );
+ await expect(TaskWorker.taskStates(knex)).resolves.toEqual(
+ new Map([
+ [
+ 'task1',
+ {
+ status: 'running',
+ startedAt: expect.anything(),
+ timesOutAt: expect.anything(),
+ },
+ ],
+ ]),
+ );
- row = (await knex(DB_TASKS_TABLE))[0];
- expect(row).toEqual(
- expect.objectContaining({
- id: 'task1',
- current_run_ticket: 'ticket',
- current_run_started_at: expect.anything(),
- current_run_expires_at: expect.anything(),
- }),
- );
- await expect(TaskWorker.taskStates(knex)).resolves.toEqual(
- new Map([
- [
- 'task1',
- {
- status: 'running',
- startedAt: expect.anything(),
- timesOutAt: expect.anything(),
- },
- ],
- ]),
- );
+ await expect(worker.tryReleaseTask('ticket', settings)).resolves.toBe(true);
- await expect(worker.tryReleaseTask('ticket', settings)).resolves.toBe(
- true,
- );
+ row = (await knex(DB_TASKS_TABLE))[0];
+ expect(row).toEqual(
+ expect.objectContaining({
+ id: 'task1',
+ current_run_ticket: null,
+ current_run_started_at: null,
+ current_run_expires_at: null,
+ }),
+ );
+ await expect(TaskWorker.taskStates(knex)).resolves.toEqual(
+ new Map([
+ [
+ 'task1',
+ {
+ status: 'idle',
+ startsAt: expect.anything(),
+ lastRunEndedAt: expect.anything(),
+ },
+ ],
+ ]),
+ );
+ });
- row = (await knex(DB_TASKS_TABLE))[0];
- expect(row).toEqual(
- expect.objectContaining({
- id: 'task1',
- current_run_ticket: null,
- current_run_started_at: null,
- current_run_expires_at: null,
- }),
- );
+ it('logs error when the task throws', async () => {
+ jest.spyOn(logger, 'error');
+ const fn = jest.fn().mockRejectedValue(new Error('failed'));
+ const settings: TaskSettingsV2 = {
+ version: 2,
+ initialDelayDuration: undefined,
+ cadence: '* * * * * *',
+ timeoutAfterDuration: Duration.fromMillis(60000).toISO()!,
+ };
+ const checkFrequency = Duration.fromObject({ milliseconds: 100 });
+ const worker = new TaskWorker('task1', fn, knex, logger, checkFrequency);
+ worker.start(settings, { signal: testScopedSignal() });
+
+ await waitForExpect(async () => {
+ expect(logger.error).toHaveBeenCalled();
await expect(TaskWorker.taskStates(knex)).resolves.toEqual(
new Map([
[
@@ -150,438 +182,386 @@ describe('TaskWorker', () => {
status: 'idle',
startsAt: expect.anything(),
lastRunEndedAt: expect.anything(),
+ lastRunError: expect.stringContaining('failed'),
},
],
]),
);
- },
- );
+ });
+ });
- it.each(databases.eachSupportedId())(
- 'logs error when the task throws, %p',
- async databaseId => {
- const knex = await databases.init(databaseId);
- await migrateBackendTasks(knex);
+ it('runs tasks more than once even when the task throws', async () => {
+ const fn = jest.fn().mockRejectedValue(new Error('failed'));
+ const settings: TaskSettingsV2 = {
+ version: 2,
+ initialDelayDuration: undefined,
+ cadence: '* * * * * *',
+ timeoutAfterDuration: Duration.fromMillis(60000).toISO()!,
+ };
+ const checkFrequency = Duration.fromObject({ milliseconds: 100 });
+ const worker = new TaskWorker('task1', fn, knex, logger, checkFrequency);
+ worker.start(settings, { signal: testScopedSignal() });
- jest.spyOn(logger, 'error');
- const fn = jest.fn().mockRejectedValue(new Error('failed'));
- const settings: TaskSettingsV2 = {
- version: 2,
- initialDelayDuration: undefined,
- cadence: '* * * * * *',
- timeoutAfterDuration: Duration.fromMillis(60000).toISO()!,
- };
- const checkFrequency = Duration.fromObject({ milliseconds: 100 });
- const worker = new TaskWorker('task1', fn, knex, logger, checkFrequency);
- worker.start(settings, { signal: testScopedSignal() });
+ await waitForExpect(() => {
+ expect(fn).toHaveBeenCalledTimes(3);
+ });
+ });
- await waitForExpect(async () => {
- expect(logger.error).toHaveBeenCalled();
- await expect(TaskWorker.taskStates(knex)).resolves.toEqual(
- new Map([
- [
- 'task1',
- {
- status: 'idle',
- startsAt: expect.anything(),
- lastRunEndedAt: expect.anything(),
- lastRunError: expect.stringContaining('failed'),
- },
- ],
- ]),
- );
+ it('does not clobber ticket lock when stolen', async () => {
+ const fn = jest.fn(
+ async () => new Promise(resolve => setTimeout(resolve, 50)),
+ );
+ const settings: TaskSettingsV2 = {
+ version: 2,
+ initialDelayDuration: undefined,
+ cadence: '* * * * * *',
+ timeoutAfterDuration: Duration.fromMillis(60000).toISO()!,
+ };
+
+ const worker = new TaskWorker('task1', fn, knex, logger);
+ await worker.persistTask(settings);
+
+ await waitForExpect(async () => {
+ await expect(worker.findReadyTask()).resolves.toEqual({
+ result: 'ready',
+ settings,
});
- },
- );
+ });
- it.each(databases.eachSupportedId())(
- 'runs tasks more than once even when the task throws, %p',
- async databaseId => {
- const knex = await databases.init(databaseId);
- await migrateBackendTasks(knex);
+ await expect(worker.tryClaimTask('ticket', settings)).resolves.toBe(true);
- const fn = jest.fn().mockRejectedValue(new Error('failed'));
- const settings: TaskSettingsV2 = {
- version: 2,
- initialDelayDuration: undefined,
- cadence: '* * * * * *',
- timeoutAfterDuration: Duration.fromMillis(60000).toISO()!,
- };
- const checkFrequency = Duration.fromObject({ milliseconds: 100 });
- const worker = new TaskWorker('task1', fn, knex, logger, checkFrequency);
- worker.start(settings, { signal: testScopedSignal() });
+ let row = (await knex(DB_TASKS_TABLE))[0];
+ expect(row).toEqual(
+ expect.objectContaining({
+ id: 'task1',
+ current_run_ticket: 'ticket',
+ current_run_started_at: expect.anything(),
+ current_run_expires_at: expect.anything(),
+ }),
+ );
- await waitForExpect(() => {
- expect(fn).toHaveBeenCalledTimes(3);
+ await knex(DB_TASKS_TABLE)
+ .where('id', '=', 'task1')
+ .update({ current_run_ticket: 'stolen' });
+
+ await expect(worker.tryReleaseTask('ticket', settings)).resolves.toBe(
+ false,
+ );
+
+ row = (await knex(DB_TASKS_TABLE))[0];
+ expect(row).toEqual(
+ expect.objectContaining({
+ id: 'task1',
+ current_run_ticket: 'stolen',
+ current_run_started_at: expect.anything(),
+ current_run_expires_at: expect.anything(),
+ }),
+ );
+ });
+
+ it('gracefully handles a disappeared task row', async () => {
+ const fn = jest.fn(async () => {});
+ const settings: TaskSettingsV2 = {
+ version: 2,
+ initialDelayDuration: undefined,
+ cadence: '* * * * * *',
+ timeoutAfterDuration: Duration.fromMillis(60000).toISO()!,
+ };
+
+ const worker1 = new TaskWorker('task1', fn, knex, logger);
+ await worker1.persistTask(settings);
+ await knex(DB_TASKS_TABLE).where('id', '=', 'task1').delete();
+ await expect(worker1.findReadyTask()).resolves.toEqual({
+ result: 'abort',
+ });
+
+ const worker2 = new TaskWorker('task2', fn, knex, logger);
+ await worker2.persistTask(settings);
+
+ await waitForExpect(async () => {
+ await expect(worker2.findReadyTask()).resolves.toEqual({
+ result: 'ready',
+ settings,
});
- },
- );
+ });
- it.each(databases.eachSupportedId())(
- 'does not clobber ticket lock when stolen, %p',
- async databaseId => {
- const knex = await databases.init(databaseId);
- await migrateBackendTasks(knex);
+ await knex(DB_TASKS_TABLE).where('id', '=', 'task2').delete();
+ await expect(worker2.tryClaimTask('ticket', settings)).resolves.toBe(false);
- const fn = jest.fn(
- async () => new Promise(resolve => setTimeout(resolve, 50)),
- );
- const settings: TaskSettingsV2 = {
- version: 2,
- initialDelayDuration: undefined,
- cadence: '* * * * * *',
- timeoutAfterDuration: Duration.fromMillis(60000).toISO()!,
- };
+ const worker3 = new TaskWorker('task3', fn, knex, logger);
+ await worker3.persistTask(settings);
- const worker = new TaskWorker('task1', fn, knex, logger);
- await worker.persistTask(settings);
-
- await waitForExpect(async () => {
- await expect(worker.findReadyTask()).resolves.toEqual({
- result: 'ready',
- settings,
- });
+ await waitForExpect(async () => {
+ await expect(worker3.findReadyTask()).resolves.toEqual({
+ result: 'ready',
+ settings,
});
+ });
- await expect(worker.tryClaimTask('ticket', settings)).resolves.toBe(true);
+ await expect(worker3.tryClaimTask('ticket', settings)).resolves.toBe(true);
+ await knex(DB_TASKS_TABLE).where('id', '=', 'task3').delete();
+ await expect(worker3.tryReleaseTask('ticket', settings)).resolves.toBe(
+ false,
+ );
+ });
- let row = (await knex(DB_TASKS_TABLE))[0];
- expect(row).toEqual(
- expect.objectContaining({
- id: 'task1',
- current_run_ticket: 'ticket',
- current_run_started_at: expect.anything(),
- current_run_expires_at: expect.anything(),
- }),
- );
+ it('respects initialDelayDuration per worker', async () => {
+ const abortFirst = new AbortController();
+ const settings: TaskSettingsV2 = {
+ version: 2,
+ initialDelayDuration: 'PT0.3S',
+ cadence: 'PT0.1S',
+ timeoutAfterDuration: 'PT10S',
+ };
- await knex(DB_TASKS_TABLE)
- .where('id', '=', 'task1')
- .update({ current_run_ticket: 'stolen' });
+ // Start a single worker and make sure it waits and then goes to work
+ const fn1 = jest.fn(async () => {});
+ const worker1 = new TaskWorker(
+ 'task1',
+ fn1,
+ knex,
+ logger,
+ Duration.fromMillis(10),
+ );
+ await worker1.start(settings, { signal: abortFirst.signal });
- await expect(worker.tryReleaseTask('ticket', settings)).resolves.toBe(
- false,
- );
+ expect(fn1).toHaveBeenCalledTimes(0);
+ await new Promise(resolve => setTimeout(resolve, 250));
+ expect(fn1).toHaveBeenCalledTimes(0);
+ await new Promise(resolve => setTimeout(resolve, 100));
+ expect(fn1.mock.calls.length).toBeGreaterThan(0);
- row = (await knex(DB_TASKS_TABLE))[0];
- expect(row).toEqual(
- expect.objectContaining({
- id: 'task1',
- current_run_ticket: 'stolen',
- current_run_started_at: expect.anything(),
- current_run_expires_at: expect.anything(),
- }),
- );
- },
- );
+ // Start a second worker and make sure it waits but the first worker still works along
+ const fn2 = jest.fn();
+ const promise2 = new Promise(resolve => fn2.mockImplementation(resolve));
+ const worker2 = new TaskWorker(
+ 'task1',
+ fn2,
+ knex,
+ logger,
+ Duration.fromMillis(10),
+ );
+ await worker2.start(settings, { signal: testScopedSignal() });
- it.each(databases.eachSupportedId())(
- 'gracefully handles a disappeared task row, %p',
- async databaseId => {
- const knex = await databases.init(databaseId);
- await migrateBackendTasks(knex);
+ // We eventually abort the first worker just to make sure that the second
+ // one for sure will get a go at running the task
+ setTimeout(() => abortFirst.abort(), 1000);
- const fn = jest.fn(async () => {});
- const settings: TaskSettingsV2 = {
- version: 2,
- initialDelayDuration: undefined,
- cadence: '* * * * * *',
- timeoutAfterDuration: Duration.fromMillis(60000).toISO()!,
- };
+ const before = fn1.mock.calls.length;
+ await promise2;
+ expect(fn1.mock.calls.length).toBeGreaterThan(before);
+ });
- const worker1 = new TaskWorker('task1', fn, knex, logger);
- await worker1.persistTask(settings);
- await knex(DB_TASKS_TABLE).where('id', '=', 'task1').delete();
- await expect(worker1.findReadyTask()).resolves.toEqual({
- result: 'abort',
- });
+ it('next_run_start_at is always the min between schedule changes from cron frequency', async () => {
+ const fn = jest.fn(
+ async () => new Promise(resolve => setTimeout(resolve, 50)),
+ );
+ const settings: TaskSettingsV2 = {
+ version: 2,
+ cadence: '*/15 * * * *',
+ initialDelayDuration: 'PT2M',
+ timeoutAfterDuration: 'PT1M',
+ };
- const worker2 = new TaskWorker('task2', fn, knex, logger);
- await worker2.persistTask(settings);
+ const worker = new TaskWorker('task99', fn, knex, logger);
+ await worker.persistTask(settings);
+ const row1 = (await knex(DB_TASKS_TABLE))[0];
- await waitForExpect(async () => {
- await expect(worker2.findReadyTask()).resolves.toEqual({
- result: 'ready',
- settings,
- });
- });
+ const settings2 = {
+ ...settings,
+ cadence: '*/2 * * * *',
+ initialDelayDuration: 'PT1M',
+ };
+ await worker.persistTask(settings2);
+ const row2 = (await knex(DB_TASKS_TABLE))[0];
- await knex(DB_TASKS_TABLE).where('id', '=', 'task2').delete();
- await expect(worker2.tryClaimTask('ticket', settings)).resolves.toBe(
- false,
- );
+ expect(row2.next_run_start_at).not.toStrictEqual(row1.next_run_start_at);
- const worker3 = new TaskWorker('task3', fn, knex, logger);
- await worker3.persistTask(settings);
+ const settings3 = { ...settings };
+ await worker.persistTask(settings3);
+ const row3 = (await knex(DB_TASKS_TABLE))[0];
- await waitForExpect(async () => {
- await expect(worker3.findReadyTask()).resolves.toEqual({
- result: 'ready',
- settings,
- });
- });
+ // The new timestamp can basically be 0 or a minute depending on how the
+ // initialDelayDuration falls right on a cron boundary. This kinda
+ // contrived check removes a test flakiness based on wall clock time.
+ expect(
+ Math.abs(
+ +new Date(row3.next_run_start_at!) - +new Date(row2.next_run_start_at!),
+ ),
+ ).toBeLessThanOrEqual(60_000);
+ });
- await expect(worker3.tryClaimTask('ticket', settings)).resolves.toBe(
- true,
- );
- await knex(DB_TASKS_TABLE).where('id', '=', 'task3').delete();
- await expect(worker3.tryReleaseTask('ticket', settings)).resolves.toBe(
- false,
- );
- },
- );
+ it('next_run_start_at is always the min between schedule changes when using human duration frequency', async () => {
+ const fn = jest.fn(
+ async () => new Promise(resolve => setTimeout(resolve, 50)),
+ );
- it.each(databases.eachSupportedId())(
- 'respects initialDelayDuration per worker, %p',
- async databaseId => {
- const knex = await databases.init(databaseId);
- await migrateBackendTasks(knex);
+ const initialSettings: TaskSettingsV2 = {
+ version: 2,
+ cadence: 'PT120M',
+ timeoutAfterDuration: 'PT1M',
+ };
- const abortFirst = new AbortController();
- const settings: TaskSettingsV2 = {
- version: 2,
- initialDelayDuration: 'PT0.3S',
- cadence: 'PT0.1S',
- timeoutAfterDuration: 'PT10S',
- };
+ const worker = new TaskWorker('task99', fn, knex, logger);
+ await worker.persistTask(initialSettings);
+ // replicate task running, sets next_run_start_at based on cadence
+ await worker.tryClaimTask('ticket', initialSettings);
+ await worker.tryReleaseTask('ticket', initialSettings);
- // Start a single worker and make sure it waits and then goes to work
- const fn1 = jest.fn(async () => {});
- const worker1 = new TaskWorker(
- 'task1',
- fn1,
- knex,
- logger,
- Duration.fromMillis(10),
- );
- await worker1.start(settings, { signal: abortFirst.signal });
+ // grab initial row for comparisons later
+ const rowAfterClaimAndRelease = (await knex(DB_TASKS_TABLE))[0];
- expect(fn1).toHaveBeenCalledTimes(0);
- await new Promise(resolve => setTimeout(resolve, 250));
- expect(fn1).toHaveBeenCalledTimes(0);
- await new Promise(resolve => setTimeout(resolve, 100));
- expect(fn1.mock.calls.length).toBeGreaterThan(0);
+ const settings: TaskSettingsV2 = {
+ ...initialSettings,
+ cadence: 'PT60M',
+ };
+ await worker.persistTask(settings);
+ const row1 = (await knex(DB_TASKS_TABLE))[0];
- // Start a second worker and make sure it waits but the first worker still works along
- const fn2 = jest.fn();
- const promise2 = new Promise(resolve => fn2.mockImplementation(resolve));
- const worker2 = new TaskWorker(
- 'task1',
- fn2,
- knex,
- logger,
- Duration.fromMillis(10),
- );
- await worker2.start(settings, { signal: testScopedSignal() });
+ const rowAfterClaimAndReleaseNextStartAt = DateTime.fromJSDate(
+ new Date(rowAfterClaimAndRelease.next_run_start_at!),
+ );
+ const row1NextStartAt = DateTime.fromJSDate(
+ new Date(row1.next_run_start_at!),
+ );
+ const now = DateTime.now();
+ expect(
+ rowAfterClaimAndReleaseNextStartAt.diff(row1NextStartAt).as('minutes'),
+ ).toBeCloseTo(60, 1); // ensure that next start at is sooner than initial by one hour
+ expect(row1NextStartAt.diff(now).as('minutes')).toBeCloseTo(60, 1); // ensure that next start at is later than now by one hour
+ expect(
+ rowAfterClaimAndReleaseNextStartAt.diff(now).as('minutes'),
+ ).toBeCloseTo(120, 1);
- // We eventually abort the first worker just to make sure that the second
- // one for sure will get a go at running the task
- setTimeout(() => abortFirst.abort(), 1000);
+ const settings2 = {
+ ...settings,
+ };
+ await worker.persistTask(settings2);
+ const row2 = (await knex(DB_TASKS_TABLE))[0];
- const before = fn1.mock.calls.length;
- await promise2;
- expect(fn1.mock.calls.length).toBeGreaterThan(before);
+ expect(row2.next_run_start_at).toStrictEqual(row1.next_run_start_at);
+ });
- await knex.destroy();
- },
- );
+ it('next_run_start_at is always the min between schedule changes when using human duration frequency with initial start delay', async () => {
+ const fn = jest.fn(
+ async () => new Promise(resolve => setTimeout(resolve, 50)),
+ );
- it.each(databases.eachSupportedId())(
- 'next_run_start_at is always the min between schedule changes from cron frequency, %p',
- async databaseId => {
- const knex = await databases.init(databaseId);
- await migrateBackendTasks(knex);
+ const initialSettings: TaskSettingsV2 = {
+ version: 2,
+ cadence: 'PT120M',
+ initialDelayDuration: 'PT2M',
+ timeoutAfterDuration: 'PT1M',
+ };
- const fn = jest.fn(
- async () => new Promise(resolve => setTimeout(resolve, 50)),
- );
- const settings: TaskSettingsV2 = {
- version: 2,
- cadence: '*/15 * * * *',
- initialDelayDuration: 'PT2M',
- timeoutAfterDuration: 'PT1M',
- };
+ const worker = new TaskWorker('task99', fn, knex, logger);
+ await worker.persistTask(initialSettings);
+ // replicate task running, sets next_run_start_at based on cadence
+ await worker.tryClaimTask('ticket', initialSettings);
+ await worker.tryReleaseTask('ticket', initialSettings);
- const worker = new TaskWorker('task99', fn, knex, logger);
- await worker.persistTask(settings);
- const row1 = (await knex(DB_TASKS_TABLE))[0];
+ // grab initial row for comparisons later
+ const rowAfterClaimAndRelease = (await knex(DB_TASKS_TABLE))[0];
- const settings2 = {
- ...settings,
- cadence: '*/2 * * * *',
- initialDelayDuration: 'PT1M',
- };
- await worker.persistTask(settings2);
- const row2 = (await knex(DB_TASKS_TABLE))[0];
+ const settings: TaskSettingsV2 = {
+ ...initialSettings,
+ cadence: 'PT60M',
+ };
+ await worker.persistTask(settings);
+ const row1 = (await knex(DB_TASKS_TABLE))[0];
- expect(row2.next_run_start_at).not.toStrictEqual(row1.next_run_start_at);
+ const rowAfterClaimAndReleaseNextStartAt = DateTime.fromJSDate(
+ new Date(rowAfterClaimAndRelease.next_run_start_at!),
+ );
+ const row1NextStartAt = DateTime.fromJSDate(
+ new Date(row1.next_run_start_at!),
+ );
+ const now = DateTime.now();
+ expect(
+ rowAfterClaimAndReleaseNextStartAt.diff(row1NextStartAt).as('minutes'),
+ ).toBeCloseTo(62, 1); // ensure that next start at is sooner than initial by one hour, plus the 2 minute delay (set my tryReleaseTask)
+ expect(row1NextStartAt.diff(now).as('minutes')).toBeCloseTo(60, 1); // ensure that next start at is later than now by one hour (2 minute delay doesn't take effect here)
+ expect(
+ rowAfterClaimAndReleaseNextStartAt.diff(now).as('minutes'),
+ ).toBeCloseTo(122, 1); // includes 2 minute start delay (which is persisted from tryReleaseTask)
- const settings3 = { ...settings };
- await worker.persistTask(settings3);
- const row3 = (await knex(DB_TASKS_TABLE))[0];
+ const settings2 = {
+ ...settings,
+ };
+ await worker.persistTask(settings2);
+ const row2 = (await knex(DB_TASKS_TABLE))[0];
- // The new timestamp can basically be 0 or a minute depending on how the
- // initialDelayDuration falls right on a cron boundary. This kinda
- // contrived check removes a test flakiness based on wall clock time.
- expect(
- Math.abs(
- +new Date(row3.next_run_start_at!) -
- +new Date(row2.next_run_start_at!),
- ),
- ).toBeLessThanOrEqual(60_000);
+ expect(row2.next_run_start_at).toStrictEqual(row1.next_run_start_at);
+ });
- await knex.destroy();
- },
- );
+ it('next_run_start_at is not set for manually-triggered tasks', async () => {
+ const fn = jest.fn(
+ async () => new Promise(resolve => setTimeout(resolve, 50)),
+ );
- it.each(databases.eachSupportedId())(
- 'next_run_start_at is always the min between schedule changes when using human duration frequency, %p',
- async databaseId => {
- const knex = await databases.init(databaseId);
- await migrateBackendTasks(knex);
+ const initialSettings: TaskSettingsV2 = {
+ version: 2,
+ cadence: 'manual',
+ timeoutAfterDuration: 'PT1M',
+ };
- const fn = jest.fn(
- async () => new Promise(resolve => setTimeout(resolve, 50)),
- );
+ const worker = new TaskWorker('task99', fn, knex, logger);
+ await worker.persistTask(initialSettings);
+ await worker.tryClaimTask('ticket', initialSettings);
+ await worker.tryReleaseTask('ticket', initialSettings);
- const initialSettings: TaskSettingsV2 = {
- version: 2,
- cadence: 'PT120M',
- timeoutAfterDuration: 'PT1M',
- };
+ const row = (await knex(DB_TASKS_TABLE))[0];
+ expect(row.next_run_start_at).toBeNull();
+ });
- const worker = new TaskWorker('task99', fn, knex, logger);
- await worker.persistTask(initialSettings);
- // replicate task running, sets next_run_start_at based on cadence
- await worker.tryClaimTask('ticket', initialSettings);
- await worker.tryReleaseTask('ticket', initialSettings);
+ it('can cancel a running task', async () => {
+ const fn = jest.fn(async () => {});
+ const settings: TaskSettingsV2 = {
+ version: 2,
+ cadence: '* * * * * *',
+ initialDelayDuration: undefined,
+ timeoutAfterDuration: Duration.fromObject({ minutes: 1 }).toISO()!,
+ };
- // grab initial row for comparisons later
- const rowAfterClaimAndRelease = (
- await knex(DB_TASKS_TABLE)
- )[0];
+ const worker = new TaskWorker('task1', fn, knex, logger);
+ await worker.persistTask(settings);
+ await worker.tryClaimTask('ticket', settings);
- const settings: TaskSettingsV2 = {
- ...initialSettings,
- cadence: 'PT60M',
- };
- await worker.persistTask(settings);
- const row1 = (await knex(DB_TASKS_TABLE))[0];
+ // Verify the task is running
+ let row = (await knex(DB_TASKS_TABLE))[0];
+ expect(row.current_run_ticket).toBe('ticket');
- const rowAfterClaimAndReleaseNextStartAt = DateTime.fromJSDate(
- new Date(rowAfterClaimAndRelease.next_run_start_at!),
- );
- const row1NextStartAt = DateTime.fromJSDate(
- new Date(row1.next_run_start_at!),
- );
- const now = DateTime.now();
- expect(
- rowAfterClaimAndReleaseNextStartAt.diff(row1NextStartAt).as('minutes'),
- ).toBeCloseTo(60, 1); // ensure that next start at is sooner than initial by one hour
- expect(row1NextStartAt.diff(now).as('minutes')).toBeCloseTo(60, 1); // ensure that next start at is later than now by one hour
- expect(
- rowAfterClaimAndReleaseNextStartAt.diff(now).as('minutes'),
- ).toBeCloseTo(120, 1);
+ await TaskWorker.cancel(knex, 'task1');
- const settings2 = {
- ...settings,
- };
- await worker.persistTask(settings2);
- const row2 = (await knex(DB_TASKS_TABLE))[0];
+ // Verify the task is now idle with a cancellation error recorded
+ row = (await knex(DB_TASKS_TABLE))[0];
+ expect(row.current_run_ticket).toBeNull();
+ expect(row.current_run_started_at).toBeNull();
+ expect(row.current_run_expires_at).toBeNull();
+ expect(row.last_run_ended_at).not.toBeNull();
+ expect(row.last_run_error_json).toContain('Task was cancelled');
+ });
- expect(row2.next_run_start_at).toStrictEqual(row1.next_run_start_at);
+ it('cannot cancel a non-existent task', async () => {
+ await expect(TaskWorker.cancel(knex, 'nonexistent')).rejects.toThrow(
+ NotFoundError,
+ );
+ });
- await knex.destroy();
- },
- );
+ it('cannot cancel a task that is not running', async () => {
+ const fn = jest.fn(async () => {});
+ const settings: TaskSettingsV2 = {
+ version: 2,
+ cadence: '* * * * * *',
+ initialDelayDuration: undefined,
+ timeoutAfterDuration: Duration.fromObject({ minutes: 1 }).toISO()!,
+ };
- it.each(databases.eachSupportedId())(
- 'next_run_start_at is always the min between schedule changes when using human duration frequency with initial start delay, %p',
- async databaseId => {
- const knex = await databases.init(databaseId);
- await migrateBackendTasks(knex);
+ const worker = new TaskWorker('task1', fn, knex, logger);
+ await worker.persistTask(settings);
- const fn = jest.fn(
- async () => new Promise(resolve => setTimeout(resolve, 50)),
- );
-
- const initialSettings: TaskSettingsV2 = {
- version: 2,
- cadence: 'PT120M',
- initialDelayDuration: 'PT2M',
- timeoutAfterDuration: 'PT1M',
- };
-
- const worker = new TaskWorker('task99', fn, knex, logger);
- await worker.persistTask(initialSettings);
- // replicate task running, sets next_run_start_at based on cadence
- await worker.tryClaimTask('ticket', initialSettings);
- await worker.tryReleaseTask('ticket', initialSettings);
-
- // grab initial row for comparisons later
- const rowAfterClaimAndRelease = (
- await knex(DB_TASKS_TABLE)
- )[0];
-
- const settings: TaskSettingsV2 = {
- ...initialSettings,
- cadence: 'PT60M',
- };
- await worker.persistTask(settings);
- const row1 = (await knex(DB_TASKS_TABLE))[0];
-
- const rowAfterClaimAndReleaseNextStartAt = DateTime.fromJSDate(
- new Date(rowAfterClaimAndRelease.next_run_start_at!),
- );
- const row1NextStartAt = DateTime.fromJSDate(
- new Date(row1.next_run_start_at!),
- );
- const now = DateTime.now();
- expect(
- rowAfterClaimAndReleaseNextStartAt.diff(row1NextStartAt).as('minutes'),
- ).toBeCloseTo(62, 1); // ensure that next start at is sooner than initial by one hour, plus the 2 minute delay (set my tryReleaseTask)
- expect(row1NextStartAt.diff(now).as('minutes')).toBeCloseTo(60, 1); // ensure that next start at is later than now by one hour (2 minute delay doesn't take effect here)
- expect(
- rowAfterClaimAndReleaseNextStartAt.diff(now).as('minutes'),
- ).toBeCloseTo(122, 1); // includes 2 minute start delay (which is persisted from tryReleaseTask)
-
- const settings2 = {
- ...settings,
- };
- await worker.persistTask(settings2);
- const row2 = (await knex(DB_TASKS_TABLE))[0];
-
- expect(row2.next_run_start_at).toStrictEqual(row1.next_run_start_at);
-
- await knex.destroy();
- },
- );
-
- it.each(databases.eachSupportedId())(
- 'next_run_start_at is not set for manually-triggered tasks, %p',
- async databaseId => {
- const knex = await databases.init(databaseId);
- await migrateBackendTasks(knex);
-
- const fn = jest.fn(
- async () => new Promise(resolve => setTimeout(resolve, 50)),
- );
-
- const initialSettings: TaskSettingsV2 = {
- version: 2,
- cadence: 'manual',
- timeoutAfterDuration: 'PT1M',
- };
-
- const worker = new TaskWorker('task99', fn, knex, logger);
- await worker.persistTask(initialSettings);
- await worker.tryClaimTask('ticket', initialSettings);
- await worker.tryReleaseTask('ticket', initialSettings);
-
- const row = (await knex(DB_TASKS_TABLE))[0];
- expect(row.next_run_start_at).toBeNull();
-
- await knex.destroy();
- },
- );
+ await expect(TaskWorker.cancel(knex, 'task1')).rejects.toThrow(
+ ConflictError,
+ );
+ });
});
diff --git a/packages/backend-defaults/src/entrypoints/scheduler/lib/TaskWorker.ts b/packages/backend-defaults/src/entrypoints/scheduler/lib/TaskWorker.ts
index e47967de90..4f32dc6863 100644
--- a/packages/backend-defaults/src/entrypoints/scheduler/lib/TaskWorker.ts
+++ b/packages/backend-defaults/src/entrypoints/scheduler/lib/TaskWorker.ts
@@ -152,6 +152,36 @@ export class TaskWorker {
}
}
+ static async cancel(knex: Knex, taskId: string): Promise {
+ const [row] = await knex(DB_TASKS_TABLE)
+ .where('id', '=', taskId)
+ .select('settings_json', 'current_run_ticket');
+ if (!row) {
+ throw new NotFoundError(`Task ${taskId} does not exist`);
+ }
+ if (!row.current_run_ticket) {
+ throw new ConflictError(`Task ${taskId} is not running`);
+ }
+
+ const settings = taskSettingsV2Schema.parse(JSON.parse(row.settings_json));
+ const nextRun = TaskWorker.computeNextRunStartAt(knex, settings);
+
+ const updatedRows = await knex(DB_TASKS_TABLE)
+ .where('id', '=', taskId)
+ .where('current_run_ticket', '=', row.current_run_ticket)
+ .update({
+ next_run_start_at: nextRun,
+ current_run_ticket: knex.raw('null'),
+ current_run_started_at: knex.raw('null'),
+ current_run_expires_at: knex.raw('null'),
+ last_run_ended_at: knex.fn.now(),
+ last_run_error_json: serializeError(new Error('Task was cancelled')),
+ });
+ if (updatedRows < 1) {
+ throw new ConflictError(`Task ${taskId} is not running`);
+ }
+ }
+
static async taskStates(
knex: Knex,
): Promise> {
@@ -227,11 +257,22 @@ export class TaskWorker {
}
// Abort the task execution either if the worker is stopped, or if the
- // task timeout is hit
+ // task timeout is hit, or if the task ticket was lost (e.g. due to
+ // cancellation from another host)
const taskAbortController = delegateAbortController(signal);
const timeoutHandle = setTimeout(() => {
taskAbortController.abort();
}, Duration.fromISO(taskSettings.timeoutAfterDuration).as('milliseconds'));
+ let livenessHandle: ReturnType | undefined;
+ const scheduleLivenessCheck = () => {
+ livenessHandle = setTimeout(async () => {
+ await this.checkLiveness(ticket, taskAbortController);
+ if (!taskAbortController.signal.aborted) {
+ scheduleLivenessCheck();
+ }
+ }, this.workCheckFrequency.as('milliseconds'));
+ };
+ scheduleLivenessCheck();
try {
this.#workerState = {
@@ -248,6 +289,7 @@ export class TaskWorker {
status: 'idle',
};
clearTimeout(timeoutHandle);
+ clearTimeout(livenessHandle);
}
await this.tryReleaseTask(ticket, taskSettings);
@@ -283,7 +325,7 @@ export class TaskWorker {
// We make a conversion here to make typescript happy, because the luxon versions of the cron library and here may not be the same
const timeConverted = DateTime.fromJSDate(time.toJSDate());
- nextStartAt = this.nextRunAtRaw(timeConverted);
+ nextStartAt = TaskWorker.nextRunAtRaw(this.knex, timeConverted);
startAt ||= nextStartAt;
} else if (isManual) {
nextStartAt = this.knex.raw('null');
@@ -334,6 +376,33 @@ export class TaskWorker {
);
}
+ /**
+ * Checks whether the current task ticket is still valid in the database.
+ * If the ticket has been cleared (e.g. by cancellation or janitor cleanup),
+ * aborts the task execution.
+ */
+ private async checkLiveness(
+ ticket: string,
+ taskAbortController: AbortController,
+ ): Promise {
+ try {
+ const [row] = await this.knex(DB_TASKS_TABLE)
+ .where('id', '=', this.taskId)
+ .select('current_run_ticket');
+
+ if (!row || row.current_run_ticket !== ticket) {
+ this.logger.info(
+ `Task ticket for "${this.taskId}" is no longer valid; aborting execution`,
+ );
+ taskAbortController.abort();
+ }
+ } catch (e) {
+ this.logger.warn(
+ `Failed to check liveness for task "${this.taskId}", ${e}`,
+ );
+ }
+ }
+
/**
* Check if the task is ready to run
*/
@@ -407,48 +476,49 @@ export class TaskWorker {
return rows === 1;
}
+ private static computeNextRunStartAt(
+ knex: Knex,
+ settings: TaskSettingsV2,
+ ): Knex.Raw {
+ const isManual = settings?.cadence === 'manual';
+ const isDuration = settings?.cadence.startsWith('P');
+ const isCron = !isManual && !isDuration;
+
+ if (isCron) {
+ const time = new CronTime(settings.cadence).sendAt().toUTC();
+ const timeConverted = DateTime.fromJSDate(time.toJSDate());
+ return TaskWorker.nextRunAtRaw(knex, timeConverted);
+ }
+
+ if (isManual) {
+ return knex.raw('null');
+ }
+
+ const dt = Duration.fromISO(settings.cadence).as('seconds');
+
+ if (knex.client.config.client.includes('sqlite3')) {
+ return knex.raw(`max(datetime(next_run_start_at, ?), datetime('now'))`, [
+ `+${dt} seconds`,
+ ]);
+ }
+
+ if (knex.client.config.client.includes('mysql')) {
+ return knex.raw(
+ `greatest(next_run_start_at + interval ${dt} second, now())`,
+ );
+ }
+
+ return knex.raw(
+ `greatest(next_run_start_at + interval '${dt} seconds', now())`,
+ );
+ }
+
async tryReleaseTask(
ticket: string,
settings: TaskSettingsV2,
error?: Error,
): Promise {
- const isManual = settings?.cadence === 'manual';
- const isDuration = settings?.cadence.startsWith('P');
- const isCron = !isManual && !isDuration;
-
- let nextRun: Knex.Raw;
- if (isCron) {
- const time = new CronTime(settings.cadence).sendAt().toUTC();
- this.logger.debug(`task: ${this.taskId} will next occur around ${time}`);
- // We make a conversion here to make typescript happy, because the luxon versions of the cron library and here may not be the same
- const timeConverted = DateTime.fromJSDate(time.toJSDate());
-
- nextRun = this.nextRunAtRaw(timeConverted);
- } else if (isManual) {
- nextRun = this.knex.raw('null');
- } else {
- const dt = Duration.fromISO(settings.cadence).as('seconds');
- this.logger.debug(
- `task: ${this.taskId} will next occur around ${DateTime.now().plus({
- seconds: dt,
- })}`,
- );
-
- if (this.knex.client.config.client.includes('sqlite3')) {
- nextRun = this.knex.raw(
- `max(datetime(next_run_start_at, ?), datetime('now'))`,
- [`+${dt} seconds`],
- );
- } else if (this.knex.client.config.client.includes('mysql')) {
- nextRun = this.knex.raw(
- `greatest(next_run_start_at + interval ${dt} second, now())`,
- );
- } else {
- nextRun = this.knex.raw(
- `greatest(next_run_start_at + interval '${dt} seconds', now())`,
- );
- }
- }
+ const nextRun = TaskWorker.computeNextRunStartAt(this.knex, settings);
const rows = await this.knex(DB_TASKS_TABLE)
.where('id', '=', this.taskId)
@@ -467,12 +537,13 @@ export class TaskWorker {
return rows === 1;
}
- private nextRunAtRaw(time: DateTime): Knex.Raw {
- if (this.knex.client.config.client.includes('sqlite3')) {
- return this.knex.raw('datetime(?)', [time.toISO()]);
- } else if (this.knex.client.config.client.includes('mysql')) {
- return this.knex.raw(`?`, [time.toSQL({ includeOffset: false })]);
+ private static nextRunAtRaw(knex: Knex, time: DateTime): Knex.Raw {
+ if (knex.client.config.client.includes('sqlite3')) {
+ return knex.raw('datetime(?)', [time.toISO()]);
}
- return this.knex.raw(`?`, [time.toISO()]);
+ if (knex.client.config.client.includes('mysql')) {
+ return knex.raw(`?`, [time.toSQL({ includeOffset: false })]);
+ }
+ return knex.raw(`?`, [time.toISO()]);
}
}
diff --git a/packages/backend-defaults/src/entrypoints/scheduler/lib/types.ts b/packages/backend-defaults/src/entrypoints/scheduler/lib/types.ts
index f691ef78a0..64f7d00899 100644
--- a/packages/backend-defaults/src/entrypoints/scheduler/lib/types.ts
+++ b/packages/backend-defaults/src/entrypoints/scheduler/lib/types.ts
@@ -17,7 +17,7 @@
import { JsonObject } from '@backstage/types';
import { CronTime } from 'cron';
import { Duration } from 'luxon';
-import { z } from 'zod';
+import { z } from 'zod/v4';
function isValidOptionalDurationString(d: string | undefined): boolean {
try {
diff --git a/packages/backend-defaults/src/entrypoints/scheduler/schedulerServiceFactory.ts b/packages/backend-defaults/src/entrypoints/scheduler/schedulerServiceFactory.ts
index 186e5f6940..8aacdc0005 100644
--- a/packages/backend-defaults/src/entrypoints/scheduler/schedulerServiceFactory.ts
+++ b/packages/backend-defaults/src/entrypoints/scheduler/schedulerServiceFactory.ts
@@ -18,6 +18,7 @@ import {
coreServices,
createServiceFactory,
} from '@backstage/backend-plugin-api';
+import { metricsServiceRef } from '@backstage/backend-plugin-api/alpha';
import { DefaultSchedulerService } from './lib/DefaultSchedulerService';
/**
@@ -37,6 +38,7 @@ export const schedulerServiceFactory = createServiceFactory({
rootLifecycle: coreServices.rootLifecycle,
httpRouter: coreServices.httpRouter,
pluginMetadata: coreServices.pluginMetadata,
+ metrics: metricsServiceRef,
},
async factory({
database,
@@ -44,6 +46,7 @@ export const schedulerServiceFactory = createServiceFactory({
rootLifecycle,
httpRouter,
pluginMetadata,
+ metrics,
}) {
return DefaultSchedulerService.create({
database,
@@ -51,6 +54,7 @@ export const schedulerServiceFactory = createServiceFactory({
rootLifecycle,
httpRouter,
pluginMetadata,
+ metrics,
});
},
});
diff --git a/packages/backend-defaults/src/entrypoints/urlReader/lib/AwsS3UrlReader.test.ts b/packages/backend-defaults/src/entrypoints/urlReader/lib/AwsS3UrlReader.test.ts
index dc3d1e5b8e..3592b3d72b 100644
--- a/packages/backend-defaults/src/entrypoints/urlReader/lib/AwsS3UrlReader.test.ts
+++ b/packages/backend-defaults/src/entrypoints/urlReader/lib/AwsS3UrlReader.test.ts
@@ -128,6 +128,55 @@ describe('parseUrl', () => {
});
});
+ it('supports aws formats with custom endpoint hosts', () => {
+ expect(
+ parseUrl(
+ 'https://bucket-1.s3.eu-central-1.amazonaws.com/path/to/file.yaml',
+ {
+ host: 'bucket-1.s3.eu-central-1.amazonaws.com',
+ },
+ ),
+ ).toEqual({
+ path: 'path/to/file.yaml',
+ bucket: 'bucket-1',
+ region: 'eu-central-1',
+ });
+ expect(
+ parseUrl('https://my-bucket.s3.cn-north-1.amazonaws.com.cn/data.json', {
+ host: 'my-bucket.s3.cn-north-1.amazonaws.com.cn',
+ }),
+ ).toEqual({
+ path: 'data.json',
+ bucket: 'my-bucket',
+ region: 'cn-north-1',
+ });
+ expect(
+ parseUrl(
+ 'https://s3.eu-central-1.amazonaws.com/my-bucket/path/to/file.yaml',
+ {
+ host: 's3.eu-central-1.amazonaws.com',
+ },
+ ),
+ ).toEqual({
+ path: 'path/to/file.yaml',
+ bucket: 'my-bucket',
+ region: 'eu-central-1',
+ });
+ expect(
+ parseUrl(
+ 'https://s3.eu-central-1.amazonaws.com/my-bucket/path/to/file.yaml',
+ {
+ host: 's3.eu-central-1.amazonaws.com',
+ s3ForcePathStyle: true,
+ },
+ ),
+ ).toEqual({
+ path: 'path/to/file.yaml',
+ bucket: 'my-bucket',
+ region: 'eu-central-1',
+ });
+ });
+
it('supports all non-aws formats', () => {
expect(
parseUrl('https://my-host.com/my.bucket-3/a/puppy.jpg', {
diff --git a/packages/backend-defaults/src/entrypoints/urlReader/lib/AwsS3UrlReader.ts b/packages/backend-defaults/src/entrypoints/urlReader/lib/AwsS3UrlReader.ts
index cb776fc977..0b17ffe326 100644
--- a/packages/backend-defaults/src/entrypoints/urlReader/lib/AwsS3UrlReader.ts
+++ b/packages/backend-defaults/src/entrypoints/urlReader/lib/AwsS3UrlReader.ts
@@ -74,7 +74,12 @@ export function parseUrl(
const host = parsedUrl.host;
// Treat Amazon hosted separately because it has special region logic
- if (config.host === 'amazonaws.com' || config.host === 'amazonaws.com.cn') {
+ if (
+ config.host === 'amazonaws.com' ||
+ config.host === 'amazonaws.com.cn' ||
+ config.host.endsWith('.amazonaws.com') ||
+ config.host.endsWith('.amazonaws.com.cn')
+ ) {
const match = host.match(
/^(?:([a-z0-9.-]+)\.)?s3(?:[.-]([a-z0-9-]+))?\.amazonaws\.com(\.cn)?$/,
);
diff --git a/packages/backend-defaults/src/entrypoints/urlReader/lib/BitbucketUrlReader.test.ts b/packages/backend-defaults/src/entrypoints/urlReader/lib/BitbucketUrlReader.test.ts
deleted file mode 100644
index 1a72d2af73..0000000000
--- a/packages/backend-defaults/src/entrypoints/urlReader/lib/BitbucketUrlReader.test.ts
+++ /dev/null
@@ -1,656 +0,0 @@
-/*
- * Copyright 2020 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 { ConfigReader } from '@backstage/config';
-import {
- BitbucketIntegration,
- readBitbucketIntegrationConfig,
-} from '@backstage/integration';
-import {
- createMockDirectory,
- mockServices,
- registerMswTestHooks,
-} from '@backstage/backend-test-utils';
-import fs from 'fs-extra';
-import { rest } from 'msw';
-import { setupServer } from 'msw/node';
-import path from 'node:path';
-import { NotModifiedError } from '@backstage/errors';
-import { BitbucketUrlReader } from './BitbucketUrlReader';
-import { DefaultReadTreeResponseFactory } from './tree';
-import getRawBody from 'raw-body';
-import { UrlReaderServiceReadUrlResponse } from '@backstage/backend-plugin-api';
-
-const logger = mockServices.logger.mock();
-
-describe('BitbucketUrlReader.factory', () => {
- it('only apply integration configs not inherited from bitbucketCloud or bitbucketServer', () => {
- const config = new ConfigReader({
- integrations: {
- bitbucket: [],
- bitbucketCloud: [
- {
- username: 'username',
- appPassword: 'password',
- },
- ],
- bitbucketServer: [
- {
- host: 'bitbucket-server.local',
- token: 'test-token',
- },
- ],
- },
- });
- const treeResponseFactory = DefaultReadTreeResponseFactory.create({
- config: config,
- });
-
- const tuples = BitbucketUrlReader.factory({
- config,
- logger,
- treeResponseFactory,
- });
-
- expect(tuples).toHaveLength(0);
- });
-});
-
-describe('BitbucketUrlReader', () => {
- const mockDir = createMockDirectory({ mockOsTmpDir: true });
-
- beforeEach(mockDir.clear);
-
- const treeResponseFactory = DefaultReadTreeResponseFactory.create({
- config: new ConfigReader({}),
- });
-
- const bitbucketProcessor = new BitbucketUrlReader(
- new BitbucketIntegration(
- readBitbucketIntegrationConfig(
- new ConfigReader({
- host: 'bitbucket.org',
- apiBaseUrl: 'https://api.bitbucket.org/2.0',
- }),
- ),
- ),
- logger,
- { treeResponseFactory },
- );
-
- const hostedBitbucketProcessor = new BitbucketUrlReader(
- new BitbucketIntegration(
- readBitbucketIntegrationConfig(
- new ConfigReader({
- host: 'bitbucket.mycompany.net',
- apiBaseUrl: 'https://api.bitbucket.mycompany.net/rest/api/1.0',
- }),
- ),
- ),
- logger,
- { treeResponseFactory },
- );
-
- const worker = setupServer();
- registerMswTestHooks(worker);
-
- describe('readUrl', () => {
- it('should be able to readUrl via buffer without ETag', async () => {
- worker.use(
- rest.get(
- 'https://api.bitbucket.org/2.0/repositories/backstage-verification/test-template/src/master/template.yaml',
- (req, res, ctx) => {
- expect(req.headers.get('If-None-Match')).toBeNull();
- return res(
- ctx.status(200),
- ctx.body('foo'),
- ctx.set('ETag', 'etag-value'),
- );
- },
- ),
- );
-
- const result = await bitbucketProcessor.readUrl(
- 'https://bitbucket.org/backstage-verification/test-template/src/master/template.yaml',
- );
- const buffer = await result.buffer();
- expect(buffer.toString()).toBe('foo');
- });
-
- it('should be able to readUrl using provided token', async () => {
- worker.use(
- rest.get(
- 'https://api.bitbucket.org/2.0/repositories/backstage-verification/test-template/src/master/template.yaml',
- (req, res, ctx) => {
- expect(req.headers.get('authorization')).toBe(
- 'Bearer manual-token',
- );
- return res(ctx.status(200), ctx.body('foo'));
- },
- ),
- );
-
- const result = await bitbucketProcessor.readUrl(
- 'https://bitbucket.org/backstage-verification/test-template/src/master/template.yaml',
- { token: 'manual-token' },
- );
- const buffer = await result.buffer();
- expect(buffer.toString()).toBe('foo');
- });
-
- it('should be able to readUrl via stream without ETag', async () => {
- worker.use(
- rest.get(
- 'https://api.bitbucket.org/2.0/repositories/backstage-verification/test-template/src/master/template.yaml',
- (req, res, ctx) => {
- expect(req.headers.get('If-None-Match')).toBeNull();
- return res(
- ctx.status(200),
- ctx.body('foo'),
- ctx.set('ETag', 'etag-value'),
- );
- },
- ),
- );
-
- const result = await bitbucketProcessor.readUrl(
- 'https://bitbucket.org/backstage-verification/test-template/src/master/template.yaml',
- );
- const fromStream = await getRawBody(result.stream!());
- expect(fromStream.toString()).toBe('foo');
- });
-
- it('should be able to readUrl with matching ETag', async () => {
- worker.use(
- rest.get(
- 'https://api.bitbucket.org/2.0/repositories/backstage-verification/test-template/src/master/template.yaml',
- (req, res, ctx) => {
- expect(req.headers.get('If-None-Match')).toBe(
- 'matching-etag-value',
- );
- return res(ctx.status(304));
- },
- ),
- );
-
- await expect(
- bitbucketProcessor.readUrl(
- 'https://bitbucket.org/backstage-verification/test-template/src/master/template.yaml',
- { etag: 'matching-etag-value' },
- ),
- ).rejects.toThrow(NotModifiedError);
- });
-
- it('should be able to readUrl without matching ETag', async () => {
- worker.use(
- rest.get(
- 'https://api.bitbucket.org/2.0/repositories/backstage-verification/test-template/src/master/template.yaml',
- (req, res, ctx) => {
- expect(req.headers.get('If-None-Match')).toBe(
- 'previous-etag-value',
- );
- return res(
- ctx.status(200),
- ctx.body('foo'),
- ctx.set('ETag', 'new-etag-value'),
- );
- },
- ),
- );
-
- const result = await bitbucketProcessor.readUrl(
- 'https://bitbucket.org/backstage-verification/test-template/src/master/template.yaml',
- { etag: 'previous-etag-value' },
- );
- const buffer = await result.buffer();
- expect(buffer.toString()).toBe('foo');
- expect(result.etag).toBe('new-etag-value');
- });
-
- it('should be able to readUrl via buffer without If-Modified-Since', async () => {
- worker.use(
- rest.get(
- 'https://api.bitbucket.org/2.0/repositories/backstage-verification/test-template/src/master/template.yaml',
- (req, res, ctx) => {
- expect(req.headers.get('If-None-Match')).toBeNull();
- return res(
- ctx.status(200),
- ctx.body('foo'),
- ctx.set('ETag', 'etag-value'),
- ctx.set(
- 'Last-Modified',
- new Date('2020-01-01T00:00:00Z').toUTCString(),
- ),
- );
- },
- ),
- );
-
- const result = await bitbucketProcessor.readUrl(
- 'https://bitbucket.org/backstage-verification/test-template/src/master/template.yaml',
- );
- const buffer = await result.buffer();
- expect(result.lastModifiedAt).toEqual(new Date('2020-01-01T00:00:00Z'));
- expect(buffer.toString()).toBe('foo');
- });
-
- it('should be throw not modified when If-Modified-Since returns a 304', async () => {
- worker.use(
- rest.get(
- 'https://api.bitbucket.org/2.0/repositories/backstage-verification/test-template/src/master/template.yaml',
- (req, res, ctx) => {
- expect(req.headers.get('If-Modified-Since')).toBe(
- new Date('1999 12 31 23:59:59 GMT').toUTCString(),
- );
- return res(ctx.status(304));
- },
- ),
- );
-
- await expect(
- bitbucketProcessor.readUrl(
- 'https://bitbucket.org/backstage-verification/test-template/src/master/template.yaml',
- { lastModifiedAfter: new Date('1999 12 31 23:59:59 GMT') },
- ),
- ).rejects.toThrow(NotModifiedError);
- });
-
- it('should be able to readUrl when If-Modified-Since is before Last-Modified', async () => {
- worker.use(
- rest.get(
- 'https://api.bitbucket.org/2.0/repositories/backstage-verification/test-template/src/master/template.yaml',
- (req, res, ctx) => {
- expect(req.headers.get('If-Modified-Since')).toBe(
- new Date('1999 12 31 23:59:59 GMT').toUTCString(),
- );
- return res(
- ctx.status(200),
- ctx.set(
- 'Last-Modified',
- new Date('2020-01-01T00:00:00Z').toUTCString(),
- ),
- ctx.body('foo'),
- );
- },
- ),
- );
-
- const result = await bitbucketProcessor.readUrl(
- 'https://bitbucket.org/backstage-verification/test-template/src/master/template.yaml',
- { lastModifiedAfter: new Date('1999 12 31 23:59:59 GMT') },
- );
- const buffer = await result.buffer();
- expect(buffer.toString()).toBe('foo');
- expect(result.lastModifiedAt).toEqual(new Date('2020-01-01T00:00:00Z'));
- });
- });
-
- describe('read', () => {
- it('rejects unknown targets', async () => {
- await expect(
- bitbucketProcessor.read('https://not.bitbucket.com/apa'),
- ).rejects.toThrow(
- 'Incorrect URL: https://not.bitbucket.com/apa, Error: Invalid Bitbucket URL or file path',
- );
- });
- });
-
- describe('readTree', () => {
- const repoBuffer = fs.readFileSync(
- path.resolve(
- __dirname,
- '__fixtures__/bitbucket-repo-with-commit-hash.tar.gz',
- ),
- );
-
- const privateBitbucketRepoBuffer = fs.readFileSync(
- path.resolve(__dirname, '__fixtures__/bitbucket-server-repo.tar.gz'),
- );
-
- beforeEach(() => {
- worker.use(
- rest.get(
- 'https://api.bitbucket.org/2.0/repositories/backstage/mock',
- (_, res, ctx) =>
- res(
- ctx.status(200),
- ctx.json({
- mainbranch: {
- type: 'branch',
- name: 'master',
- },
- }),
- ),
- ),
- rest.get(
- 'https://bitbucket.org/backstage/mock/get/master.tar.gz',
- (_, res, ctx) =>
- res(
- ctx.status(200),
- ctx.set('Content-Type', 'application/zip'),
- ctx.set(
- 'content-disposition',
- 'attachment; filename=backstage-mock-12ab34cd56ef.tar.gz',
- ),
- ctx.body(new Uint8Array(repoBuffer)),
- ),
- ),
- rest.get(
- 'https://api.bitbucket.org/2.0/repositories/backstage/mock/commits/master',
- (_, res, ctx) =>
- res(
- ctx.status(200),
- ctx.json({
- values: [{ hash: '12ab34cd56ef78gh90ij12kl34mn56op78qr90st' }],
- }),
- ),
- ),
- rest.get(
- 'https://api.bitbucket.mycompany.net/rest/api/1.0/projects/backstage/repos/mock/archive',
- (_, res, ctx) =>
- res(
- ctx.status(200),
- ctx.set('Content-Type', 'application/zip'),
- ctx.set(
- 'content-disposition',
- 'attachment; filename=backstage-mock.tgz',
- ),
- ctx.body(new Uint8Array(privateBitbucketRepoBuffer)),
- ),
- ),
- rest.get(
- 'https://api.bitbucket.mycompany.net/rest/api/1.0/projects/backstage/repos/mock/commits',
- (_, res, ctx) =>
- res(
- ctx.status(200),
- ctx.json({
- values: [{ id: '12ab34cd56ef78gh90ij12kl34mn56op78qr90st' }],
- }),
- ),
- ),
- );
- });
-
- it('returns the wanted files from an archive', async () => {
- const response = await bitbucketProcessor.readTree(
- 'https://bitbucket.org/backstage/mock/src/master',
- );
-
- expect(response.etag).toBe('12ab34cd56ef');
-
- const files = await response.files();
-
- expect(files.length).toBe(2);
- const mkDocsFile = await files[0].content();
- const indexMarkdownFile = await files[1].content();
-
- expect(indexMarkdownFile.toString()).toBe('# Test\n');
- expect(mkDocsFile.toString()).toBe('site_name: Test\n');
- });
-
- it('creates a directory with the wanted files', async () => {
- const response = await bitbucketProcessor.readTree(
- 'https://bitbucket.org/backstage/mock',
- );
-
- const dir = await response.dir({ targetDir: mockDir.path });
-
- await expect(
- fs.readFile(path.join(dir, 'mkdocs.yml'), 'utf8'),
- ).resolves.toBe('site_name: Test\n');
- await expect(
- fs.readFile(path.join(dir, 'docs', 'index.md'), 'utf8'),
- ).resolves.toBe('# Test\n');
- });
-
- it('uses private bitbucket host', async () => {
- const response = await hostedBitbucketProcessor.readTree(
- 'https://bitbucket.mycompany.net/projects/backstage/repos/mock/browse/docs?at=some-branch',
- );
-
- expect(response.etag).toBe('12ab34cd56ef');
-
- const files = await response.files();
-
- expect(files.length).toBe(1);
- const indexMarkdownFile = await files[0].content();
-
- expect(indexMarkdownFile.toString()).toBe('# Test\n');
- });
-
- it('returns the wanted files from an archive with a subpath', async () => {
- const response = await bitbucketProcessor.readTree(
- 'https://bitbucket.org/backstage/mock/src/master/docs',
- );
-
- expect(response.etag).toBe('12ab34cd56ef');
-
- const files = await response.files();
-
- expect(files.length).toBe(1);
- const indexMarkdownFile = await files[0].content();
-
- expect(indexMarkdownFile.toString()).toBe('# Test\n');
- });
-
- it('creates a directory with the wanted files with a subpath', async () => {
- const response = await bitbucketProcessor.readTree(
- 'https://bitbucket.org/backstage/mock/src/master/docs',
- );
-
- const dir = await response.dir({ targetDir: mockDir.path });
-
- await expect(
- fs.readFile(path.join(dir, 'index.md'), 'utf8'),
- ).resolves.toBe('# Test\n');
- });
-
- it('throws a NotModifiedError when given a etag in options', async () => {
- const fnBitbucket = async () => {
- await bitbucketProcessor.readTree(
- 'https://bitbucket.org/backstage/mock',
- { etag: '12ab34cd56ef' },
- );
- };
-
- await expect(fnBitbucket).rejects.toThrow(NotModifiedError);
- });
-
- it('should not throw a NotModifiedError when given an outdated etag in options', async () => {
- const response = await bitbucketProcessor.readTree(
- 'https://bitbucket.org/backstage/mock',
- { etag: 'outdatedetag123abc' },
- );
-
- expect(response.etag).toBe('12ab34cd56ef');
- });
- });
-
- describe('search hosted', () => {
- const repoBuffer = fs.readFileSync(
- path.resolve(
- __dirname,
- '__fixtures__/bitbucket-repo-with-commit-hash.tar.gz',
- ),
- );
-
- beforeEach(() => {
- worker.use(
- rest.get(
- 'https://api.bitbucket.org/2.0/repositories/backstage/mock',
- (_, res, ctx) =>
- res(
- ctx.status(200),
- ctx.json({
- mainbranch: {
- type: 'branch',
- name: 'master',
- },
- }),
- ),
- ),
- rest.get(
- 'https://bitbucket.org/backstage/mock/get/master.tar.gz',
- (_, res, ctx) =>
- res(
- ctx.status(200),
- ctx.set('Content-Type', 'application/zip'),
- ctx.set(
- 'content-disposition',
- 'attachment; filename=backstage-mock-12ab34cd56ef.tar.gz',
- ),
- ctx.body(new Uint8Array(repoBuffer)),
- ),
- ),
- rest.get(
- 'https://api.bitbucket.org/2.0/repositories/backstage/mock/commits/master',
- (_, res, ctx) =>
- res(
- ctx.status(200),
- ctx.json({
- values: [{ hash: '12ab34cd56ef78gh90ij12kl34mn56op78qr90st' }],
- }),
- ),
- ),
- );
- });
-
- it('works for the naive case', async () => {
- const result = await bitbucketProcessor.search(
- 'https://bitbucket.org/backstage/mock/src/master/**/index.*',
- );
- expect(result.etag).toBe('12ab34cd56ef');
- expect(result.files.length).toBe(1);
- expect(result.files[0].url).toBe(
- 'https://bitbucket.org/backstage/mock/src/master/docs/index.md',
- );
- await expect(result.files[0].content()).resolves.toEqual(
- Buffer.from('# Test\n'),
- );
- });
-
- it('works in nested folders', async () => {
- const result = await bitbucketProcessor.search(
- 'https://bitbucket.org/backstage/mock/src/master/docs/index.*',
- );
- expect(result.etag).toBe('12ab34cd56ef');
- expect(result.files.length).toBe(1);
- expect(result.files[0].url).toBe(
- 'https://bitbucket.org/backstage/mock/src/master/docs/index.md',
- );
- await expect(result.files[0].content()).resolves.toEqual(
- Buffer.from('# Test\n'),
- );
- });
-
- it('throws NotModifiedError when same etag', async () => {
- await expect(
- bitbucketProcessor.search(
- 'https://bitbucket.org/backstage/mock/src/master/**/index.*',
- { etag: '12ab34cd56ef' },
- ),
- ).rejects.toThrow(NotModifiedError);
- });
- });
-
- describe('search private', () => {
- const privateBitbucketRepoBuffer = fs.readFileSync(
- path.resolve(__dirname, '__fixtures__/bitbucket-server-repo.tar.gz'),
- );
-
- beforeEach(() => {
- worker.use(
- rest.get(
- 'https://api.bitbucket.mycompany.net/rest/api/1.0/projects/backstage/repos/mock/archive',
- (_, res, ctx) =>
- res(
- ctx.status(200),
- ctx.set('Content-Type', 'application/zip'),
- ctx.set(
- 'content-disposition',
- 'attachment; filename=backstage-mock.tgz',
- ),
- ctx.body(new Uint8Array(privateBitbucketRepoBuffer)),
- ),
- ),
- rest.get(
- 'https://api.bitbucket.mycompany.net/rest/api/1.0/projects/backstage/repos/mock/commits',
- (_, res, ctx) =>
- res(
- ctx.status(200),
- ctx.json({
- values: [{ id: '12ab34cd56ef78gh90ij12kl34mn56op78qr90st' }],
- }),
- ),
- ),
- );
- });
-
- it('works for the naive case', async () => {
- const result = await hostedBitbucketProcessor.search(
- 'https://bitbucket.mycompany.net/projects/backstage/repos/mock/browse/**/index.*?at=master',
- );
- expect(result.etag).toBe('12ab34cd56ef');
- expect(result.files.length).toBe(1);
- expect(result.files[0].url).toBe(
- 'https://bitbucket.mycompany.net/projects/backstage/repos/mock/browse/docs/index.md?at=master',
- );
- await expect(result.files[0].content()).resolves.toEqual(
- Buffer.from('# Test\n'),
- );
- });
-
- it('works in nested folders', async () => {
- const result = await hostedBitbucketProcessor.search(
- 'https://bitbucket.mycompany.net/projects/backstage/repos/mock/browse/docs/index.*?at=master',
- );
- expect(result.etag).toBe('12ab34cd56ef');
- expect(result.files.length).toBe(1);
- expect(result.files[0].url).toBe(
- 'https://bitbucket.mycompany.net/projects/backstage/repos/mock/browse/docs/index.md?at=master',
- );
- await expect(result.files[0].content()).resolves.toEqual(
- Buffer.from('# Test\n'),
- );
- });
-
- it('throws NotModifiedError when same etag', async () => {
- await expect(
- hostedBitbucketProcessor.search(
- 'https://bitbucket.mycompany.net/projects/backstage/repos/mock/browse/**/index.*?at=master',
- { etag: '12ab34cd56ef' },
- ),
- ).rejects.toThrow(NotModifiedError);
- });
-
- it('should work for exact URLs', async () => {
- hostedBitbucketProcessor.readUrl = jest.fn().mockResolvedValue({
- buffer: async () => Buffer.from('content'),
- etag: 'etag',
- } as UrlReaderServiceReadUrlResponse);
-
- const result = await hostedBitbucketProcessor.search(
- 'https://bitbucket.mycompany.net/projects/backstage/repos/mock/browse/docs/index.md?at=master',
- );
- expect(result.etag).toBe('etag');
- expect(result.files.length).toBe(1);
- expect(result.files[0].url).toBe(
- 'https://bitbucket.mycompany.net/projects/backstage/repos/mock/browse/docs/index.md?at=master',
- );
- expect((await result.files[0].content()).toString()).toEqual('content');
- });
- });
-});
diff --git a/packages/backend-defaults/src/entrypoints/urlReader/lib/BitbucketUrlReader.ts b/packages/backend-defaults/src/entrypoints/urlReader/lib/BitbucketUrlReader.ts
deleted file mode 100644
index 8c8843d7e9..0000000000
--- a/packages/backend-defaults/src/entrypoints/urlReader/lib/BitbucketUrlReader.ts
+++ /dev/null
@@ -1,313 +0,0 @@
-/*
- * Copyright 2020 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 {
- UrlReaderService,
- UrlReaderServiceReadTreeOptions,
- UrlReaderServiceReadTreeResponse,
- UrlReaderServiceReadUrlOptions,
- UrlReaderServiceReadUrlResponse,
- UrlReaderServiceSearchOptions,
- UrlReaderServiceSearchResponse,
-} from '@backstage/backend-plugin-api';
-import {
- assertError,
- NotFoundError,
- NotModifiedError,
-} from '@backstage/errors';
-import {
- BitbucketIntegration,
- getBitbucketDefaultBranch,
- getBitbucketDownloadUrl,
- getBitbucketFileFetchUrl,
- getBitbucketRequestOptions,
- ScmIntegrations,
-} from '@backstage/integration';
-import parseGitUrl from 'git-url-parse';
-import { trimEnd } from 'lodash';
-import { Minimatch } from 'minimatch';
-import { LoggerService } from '@backstage/backend-plugin-api';
-import { ReaderFactory, ReadTreeResponseFactory } from './types';
-import { ReadUrlResponseFactory } from './ReadUrlResponseFactory';
-
-/**
- * Implements a {@link @backstage/backend-plugin-api#UrlReaderService} for files from Bitbucket v1 and v2 APIs, such
- * as the one exposed by Bitbucket Cloud itself.
- *
- * @public
- * @deprecated in favor of BitbucketCloudUrlReader and BitbucketServerUrlReader
- */
-export class BitbucketUrlReader implements UrlReaderService {
- static factory: ReaderFactory = ({ config, logger, treeResponseFactory }) => {
- const integrations = ScmIntegrations.fromConfig(config);
- return integrations.bitbucket
- .list()
- .filter(
- item =>
- !integrations.bitbucketCloud.byHost(item.config.host) &&
- !integrations.bitbucketServer.byHost(item.config.host),
- )
- .map(integration => {
- const reader = new BitbucketUrlReader(integration, logger, {
- treeResponseFactory,
- });
- const predicate = (url: URL) => url.host === integration.config.host;
- return { reader, predicate };
- });
- };
-
- private readonly integration: BitbucketIntegration;
- private readonly deps: { treeResponseFactory: ReadTreeResponseFactory };
-
- constructor(
- integration: BitbucketIntegration,
- logger: LoggerService,
- deps: { treeResponseFactory: ReadTreeResponseFactory },
- ) {
- this.integration = integration;
- this.deps = deps;
- const { host, token, username, appPassword } = integration.config;
- const replacement =
- host === 'bitbucket.org' ? 'bitbucketCloud' : 'bitbucketServer';
- logger.warn(
- `[Deprecated] Please migrate from "integrations.bitbucket" to "integrations.${replacement}".`,
- );
-
- if (!token && username && !appPassword) {
- throw new Error(
- `Bitbucket integration for '${host}' has configured a username but is missing a required appPassword.`,
- );
- }
- }
-
- async read(url: string): Promise {
- const response = await this.readUrl(url);
- return response.buffer();
- }
-
- private getCredentials = async (options?: {
- token?: string;
- }): Promise<{ headers: Record }> => {
- if (options?.token) {
- return {
- headers: {
- Authorization: `Bearer ${options.token}`,
- },
- };
- }
-
- return await getBitbucketRequestOptions(this.integration.config);
- };
-
- async readUrl(
- url: string,
- options?: UrlReaderServiceReadUrlOptions,
- ): Promise {
- const { etag, lastModifiedAfter, signal } = options ?? {};
- const bitbucketUrl = getBitbucketFileFetchUrl(url, this.integration.config);
- const requestOptions = await this.getCredentials(options);
-
- let response: Response;
- try {
- response = await fetch(bitbucketUrl.toString(), {
- headers: {
- ...requestOptions.headers,
- ...(etag && { 'If-None-Match': etag }),
- ...(lastModifiedAfter && {
- 'If-Modified-Since': lastModifiedAfter.toUTCString(),
- }),
- },
- // TODO(freben): The signal cast is there because pre-3.x versions of
- // node-fetch have a very slightly deviating AbortSignal type signature.
- // The difference does not affect us in practice however. The cast can be
- // removed after we support ESM for CLI dependencies and migrate to
- // version 3 of node-fetch.
- // https://github.com/backstage/backstage/issues/8242
- ...(signal && { signal: signal as any }),
- });
- } catch (e) {
- throw new Error(`Unable to read ${url}, ${e}`);
- }
-
- if (response.status === 304) {
- throw new NotModifiedError();
- }
-
- if (response.ok) {
- return ReadUrlResponseFactory.fromResponse(response);
- }
-
- const message = `${url} could not be read as ${bitbucketUrl}, ${response.status} ${response.statusText}`;
- if (response.status === 404) {
- throw new NotFoundError(message);
- }
- throw new Error(message);
- }
-
- async readTree(
- url: string,
- options?: UrlReaderServiceReadTreeOptions,
- ): Promise {
- const { filepath } = parseGitUrl(url);
-
- const lastCommitShortHash = await this.getLastCommitShortHash(url);
- if (options?.etag && options.etag === lastCommitShortHash) {
- throw new NotModifiedError();
- }
-
- const downloadUrl = await getBitbucketDownloadUrl(
- url,
- this.integration.config,
- );
- const archiveBitbucketResponse = await fetch(
- downloadUrl,
- getBitbucketRequestOptions(this.integration.config),
- );
- if (!archiveBitbucketResponse.ok) {
- const message = `Failed to read tree from ${url}, ${archiveBitbucketResponse.status} ${archiveBitbucketResponse.statusText}`;
- if (archiveBitbucketResponse.status === 404) {
- throw new NotFoundError(message);
- }
- throw new Error(message);
- }
-
- return await this.deps.treeResponseFactory.fromTarArchive({
- response: archiveBitbucketResponse,
- subpath: filepath,
- etag: lastCommitShortHash,
- filter: options?.filter,
- });
- }
-
- async search(
- url: string,
- options?: UrlReaderServiceSearchOptions,
- ): Promise {
- const { filepath } = parseGitUrl(url);
-
- // If it's a direct URL we use readUrl instead
- if (!filepath?.match(/[*?]/)) {
- try {
- const data = await this.readUrl(url, options);
-
- return {
- files: [
- {
- url: url,
- content: data.buffer,
- lastModifiedAt: data.lastModifiedAt,
- },
- ],
- etag: data.etag ?? '',
- };
- } catch (error) {
- assertError(error);
- if (error.name === 'NotFoundError') {
- return {
- files: [],
- etag: '',
- };
- }
- throw error;
- }
- }
-
- const matcher = new Minimatch(filepath);
-
- // TODO(freben): For now, read the entire repo and filter through that. In
- // a future improvement, we could be smart and try to deduce that non-glob
- // prefixes (like for filepaths such as some-prefix/**/a.yaml) can be used
- // to get just that part of the repo.
- const treeUrl = trimEnd(url.replace(filepath, ''), '/');
-
- const tree = await this.readTree(treeUrl, {
- etag: options?.etag,
- filter: path => matcher.match(path),
- });
- const files = await tree.files();
-
- return {
- etag: tree.etag,
- files: files.map(file => ({
- url: this.integration.resolveUrl({
- url: `/${file.path}`,
- base: url,
- }),
- content: file.content,
- lastModifiedAt: file.lastModifiedAt,
- })),
- };
- }
-
- toString() {
- const { host, token, username, appPassword } = this.integration.config;
- let authed = Boolean(token);
- if (!authed) {
- authed = Boolean(username && appPassword);
- }
- return `bitbucket{host=${host},authed=${authed}}`;
- }
-
- private async getLastCommitShortHash(url: string): Promise {
- const { resource, name: repoName, owner: project, ref } = parseGitUrl(url);
-
- let branch = ref;
- if (!branch) {
- branch = await getBitbucketDefaultBranch(url, this.integration.config);
- }
-
- const isHosted = resource === 'bitbucket.org';
- // Bitbucket Server https://docs.atlassian.com/bitbucket-server/rest/7.9.0/bitbucket-rest.html#idp222
- const commitsApiUrl = isHosted
- ? `${this.integration.config.apiBaseUrl}/repositories/${project}/${repoName}/commits/${branch}`
- : `${this.integration.config.apiBaseUrl}/projects/${project}/repos/${repoName}/commits`;
-
- const commitsResponse = await fetch(
- commitsApiUrl,
- getBitbucketRequestOptions(this.integration.config),
- );
- if (!commitsResponse.ok) {
- const message = `Failed to retrieve commits from ${commitsApiUrl}, ${commitsResponse.status} ${commitsResponse.statusText}`;
- if (commitsResponse.status === 404) {
- throw new NotFoundError(message);
- }
- throw new Error(message);
- }
-
- const commits = await commitsResponse.json();
- if (isHosted) {
- if (
- commits &&
- commits.values &&
- commits.values.length > 0 &&
- commits.values[0].hash
- ) {
- return commits.values[0].hash.substring(0, 12);
- }
- } else {
- if (
- commits &&
- commits.values &&
- commits.values.length > 0 &&
- commits.values[0].id
- ) {
- return commits.values[0].id.substring(0, 12);
- }
- }
-
- throw new Error(`Failed to read response from ${commitsApiUrl}`);
- }
-}
diff --git a/packages/backend-defaults/src/entrypoints/urlReader/lib/UrlReaders.ts b/packages/backend-defaults/src/entrypoints/urlReader/lib/UrlReaders.ts
index 229bdd4903..f04a668b0a 100644
--- a/packages/backend-defaults/src/entrypoints/urlReader/lib/UrlReaders.ts
+++ b/packages/backend-defaults/src/entrypoints/urlReader/lib/UrlReaders.ts
@@ -24,7 +24,6 @@ import { UrlReaderPredicateMux } from './UrlReaderPredicateMux';
import { AzureUrlReader } from './AzureUrlReader';
import { BitbucketCloudUrlReader } from './BitbucketCloudUrlReader';
import { BitbucketServerUrlReader } from './BitbucketServerUrlReader';
-import { BitbucketUrlReader } from './BitbucketUrlReader';
import { GerritUrlReader } from './GerritUrlReader';
import { GithubUrlReader } from './GithubUrlReader';
import { GitlabUrlReader } from './GitlabUrlReader';
@@ -92,7 +91,6 @@ export class UrlReaders {
AzureUrlReader.factory,
BitbucketCloudUrlReader.factory,
BitbucketServerUrlReader.factory,
- BitbucketUrlReader.factory,
GerritUrlReader.factory,
GithubUrlReader.factory,
GiteaUrlReader.factory,
diff --git a/packages/backend-defaults/src/entrypoints/urlReader/lib/index.ts b/packages/backend-defaults/src/entrypoints/urlReader/lib/index.ts
index fc33efbc3a..3f5d7a7ea5 100644
--- a/packages/backend-defaults/src/entrypoints/urlReader/lib/index.ts
+++ b/packages/backend-defaults/src/entrypoints/urlReader/lib/index.ts
@@ -16,7 +16,6 @@
export { AzureUrlReader } from './AzureUrlReader';
export { BitbucketCloudUrlReader } from './BitbucketCloudUrlReader';
-export { BitbucketUrlReader } from './BitbucketUrlReader';
export { BitbucketServerUrlReader } from './BitbucketServerUrlReader';
export { GerritUrlReader } from './GerritUrlReader';
export { GithubUrlReader } from './GithubUrlReader';
diff --git a/packages/backend-dynamic-feature-service/CHANGELOG.md b/packages/backend-dynamic-feature-service/CHANGELOG.md
index a9be5cd0ba..3ea462e952 100644
--- a/packages/backend-dynamic-feature-service/CHANGELOG.md
+++ b/packages/backend-dynamic-feature-service/CHANGELOG.md
@@ -1,5 +1,148 @@
# @backstage/backend-dynamic-feature-service
+## 0.8.1-next.1
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.9.0-next.1
+ - @backstage/backend-defaults@0.16.1-next.1
+ - @backstage/plugin-catalog-backend@3.5.1-next.1
+ - @backstage/plugin-auth-node@0.7.0-next.1
+ - @backstage/backend-openapi-utils@0.6.8-next.1
+ - @backstage/plugin-app-node@0.1.44-next.1
+ - @backstage/plugin-events-backend@0.6.1-next.1
+ - @backstage/plugin-events-node@0.4.21-next.1
+ - @backstage/plugin-permission-node@0.10.12-next.1
+ - @backstage/plugin-scaffolder-node@0.13.1-next.1
+ - @backstage/plugin-search-backend-node@1.4.3-next.1
+
+## 0.8.1-next.0
+
+### Patch Changes
+
+- 79453c0: Updated dependency `wait-for-expect` to `^4.0.0`.
+- Updated dependencies
+ - @backstage/cli-common@0.2.1-next.0
+ - @backstage/plugin-catalog-backend@3.5.1-next.0
+ - @backstage/backend-defaults@0.16.1-next.0
+ - @backstage/backend-plugin-api@1.8.1-next.0
+ - @backstage/cli-node@0.3.1-next.0
+ - @backstage/config-loader@1.10.10-next.0
+ - @backstage/plugin-auth-node@0.6.15-next.0
+ - @backstage/plugin-events-backend@0.6.1-next.0
+ - @backstage/plugin-permission-node@0.10.12-next.0
+ - @backstage/plugin-search-backend-node@1.4.3-next.0
+ - @backstage/backend-openapi-utils@0.6.8-next.0
+ - @backstage/plugin-app-node@0.1.44-next.0
+ - @backstage/plugin-events-node@0.4.21-next.0
+ - @backstage/plugin-scaffolder-node@0.13.1-next.0
+ - @backstage/config@1.3.6
+ - @backstage/errors@1.2.7
+ - @backstage/types@1.2.2
+ - @backstage/plugin-permission-common@0.9.7
+ - @backstage/plugin-search-common@1.2.22
+
+## 0.8.0
+
+### Minor Changes
+
+- 0fbcf23: Migrated OpenAPI schemas to 3.1.
+
+### Patch Changes
+
+- 4074a22: Fixed `resolvePackagePath` resolution for bundled dynamic plugins. When a plugin bundles its own copy of `@backstage/backend-plugin-api` inside `node_modules`, the `CommonJSModuleLoader` fallback now correctly resolves the plugin's `package.json` by name. Previously the fallback only applied when the resolution originated from the host application; it now also applies when originating from a bundled dependency, which is the case for plugins produced by the `backstage-cli package bundle` command.
+- 70fc178: Migrated from deprecated `findPaths` to `targetPaths` and `findOwnPaths` from `@backstage/cli-common`.
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0
+ - @backstage/backend-defaults@0.16.0
+ - @backstage/cli-node@0.3.0
+ - @backstage/plugin-catalog-backend@3.5.0
+ - @backstage/cli-common@0.2.0
+ - @backstage/plugin-scaffolder-node@0.13.0
+ - @backstage/plugin-events-backend@0.6.0
+ - @backstage/config-loader@1.10.9
+ - @backstage/plugin-permission-common@0.9.7
+ - @backstage/plugin-permission-node@0.10.11
+ - @backstage/plugin-auth-node@0.6.14
+ - @backstage/backend-openapi-utils@0.6.7
+ - @backstage/plugin-app-node@0.1.43
+ - @backstage/plugin-events-node@0.4.20
+ - @backstage/plugin-search-backend-node@1.4.2
+
+## 0.8.0-next.2
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0-next.1
+ - @backstage/backend-defaults@0.16.0-next.2
+ - @backstage/cli-common@0.2.0-next.2
+ - @backstage/plugin-catalog-backend@3.5.0-next.2
+ - @backstage/backend-openapi-utils@0.6.7-next.1
+ - @backstage/plugin-app-node@0.1.43-next.1
+ - @backstage/plugin-auth-node@0.6.14-next.2
+ - @backstage/plugin-events-backend@0.6.0-next.2
+ - @backstage/plugin-events-node@0.4.20-next.1
+ - @backstage/plugin-permission-node@0.10.11-next.1
+ - @backstage/plugin-scaffolder-node@0.13.0-next.2
+ - @backstage/plugin-search-backend-node@1.4.2-next.1
+
+## 0.8.0-next.1
+
+### Minor Changes
+
+- 0fbcf23: Migrated OpenAPI schemas to 3.1.
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/plugin-catalog-backend@3.5.0-next.1
+ - @backstage/cli-common@0.2.0-next.1
+ - @backstage/cli-node@0.2.19-next.1
+ - @backstage/backend-defaults@0.16.0-next.1
+ - @backstage/plugin-events-backend@0.6.0-next.1
+ - @backstage/plugin-scaffolder-node@0.13.0-next.1
+ - @backstage/plugin-auth-node@0.6.14-next.1
+ - @backstage/backend-openapi-utils@0.6.7-next.0
+ - @backstage/backend-plugin-api@1.7.1-next.0
+ - @backstage/config@1.3.6
+ - @backstage/config-loader@1.10.9-next.0
+ - @backstage/errors@1.2.7
+ - @backstage/types@1.2.2
+ - @backstage/plugin-app-node@0.1.43-next.0
+ - @backstage/plugin-events-node@0.4.20-next.0
+ - @backstage/plugin-permission-common@0.9.6
+ - @backstage/plugin-permission-node@0.10.11-next.0
+ - @backstage/plugin-search-backend-node@1.4.2-next.0
+ - @backstage/plugin-search-common@1.2.22
+
+## 0.7.10-next.0
+
+### Patch Changes
+
+- 70fc178: Migrated from deprecated `findPaths` to `targetPaths` and `findOwnPaths` from `@backstage/cli-common`.
+- Updated dependencies
+ - @backstage/cli-common@0.2.0-next.0
+ - @backstage/cli-node@0.2.19-next.0
+ - @backstage/backend-defaults@0.15.3-next.0
+ - @backstage/plugin-catalog-backend@3.5.0-next.0
+ - @backstage/config-loader@1.10.9-next.0
+ - @backstage/backend-plugin-api@1.7.1-next.0
+ - @backstage/backend-openapi-utils@0.6.7-next.0
+ - @backstage/config@1.3.6
+ - @backstage/errors@1.2.7
+ - @backstage/types@1.2.2
+ - @backstage/plugin-app-node@0.1.43-next.0
+ - @backstage/plugin-auth-node@0.6.14-next.0
+ - @backstage/plugin-events-backend@0.5.12-next.0
+ - @backstage/plugin-events-node@0.4.20-next.0
+ - @backstage/plugin-permission-common@0.9.6
+ - @backstage/plugin-permission-node@0.10.11-next.0
+ - @backstage/plugin-scaffolder-node@0.12.6-next.0
+ - @backstage/plugin-search-backend-node@1.4.2-next.0
+ - @backstage/plugin-search-common@1.2.22
+
## 0.7.9
### Patch Changes
diff --git a/packages/backend-dynamic-feature-service/README.md b/packages/backend-dynamic-feature-service/README.md
index 8122810f96..914df15f65 100644
--- a/packages/backend-dynamic-feature-service/README.md
+++ b/packages/backend-dynamic-feature-service/README.md
@@ -97,7 +97,7 @@ Since this service only handles loading, you would choose a packaging approach b
**When to use:** Plugin only uses dependencies that are already provided by the main Backstage application.
-**How to apply:**
+**How to use:**
```bash
cd my-backstage-plugin
@@ -117,7 +117,7 @@ tar -xzf package.tgz -C /path/to/dynamic-plugins-root/my-backstage-plugin --stri
**When to use:** Plugin has private dependencies not available in the main Backstage application.
-**How to apply:**
+**How to use:**
```bash
# Package the plugin
@@ -136,35 +136,47 @@ yarn install # Installs all the plugin's dependencies
**Example scenario:** Plugin needs `axios@1.4.0` which isn't available in the main application.
-### 3. Custom packaging CLI tool
+### 3. Dedicated bundling CLI command
-**When to use:** When you want to produce self-contained dynamic plugin packages that can be directly extracted without any post-action, and systematically use the core `@backstage` dependencies provided by the Backstage application.
+**When to use:**
-**What a packaging CLI needs to do:**
+- When you want to produce self-contained dynamic plugin packages that can be directly extracted and loaded without any post-action,
+- especially when your plugin depends on other packages in the same monorepo.
-1. **Analyze plugin dependencies** - Identify which are Backstage core vs private dependencies
-2. **Create distribution package** - Generate a new directory with modified structure:
- - Move `@backstage/*` packages from `dependencies` to `peerDependencies` in package.json
- - Keep only private dependencies in the `dependencies` section
- - Keep the built JavaScript code unchanged
- - Include only the filtered private dependencies in `node_modules`
-3. **Result** - A self-contained package that uses the main app's `@backstage/*` packages but includes its own private dependencies
+**How to use:**
-**Benefits:**
-
-- Systematic use of main application's `@backstage/*` packages (no version conflicts), enabling the future implementation of `@backstage` dependency version checking at start time
-- Self-contained packages with only necessary private dependencies
-- No post-installation steps required (extract and run)
-- Consistent dependency structure across all dynamic plugins
-- Production-ready distribution format
-
-**Example implementation:** The [`@red-hat-developer-hub/cli`](https://github.com/redhat-developer/rhdh-cli) tool implements this approach:
+The [`backstage-cli package bundle`](../cli/cli-report.md) command automates the required steps. Run it from within a plugin directory:
```bash
cd my-backstage-plugin
-npx @red-hat-developer-hub/cli@latest plugin export
-# Creates a self-contained package with embedded dependencies in the `/dist-dynamic` sub-folder
-
-# Deploy the generated package
-cp -r dist-dynamic /path/to/dynamic-plugins-root/my-backstage-plugin
+yarn backstage-cli package bundle --output-destination /path/to/dynamic-plugins-root
+# Creates a self-contained bundle in the /path/to/dynamic-plugins-root/my-backstage-plugin/ sub-folder
```
+
+**Batch bundling:** When bundling many plugins from the same monorepo, use `--pre-packed-dir` to avoid redundant work:
+
+```bash
+# First, build a shared dist workspace
+backstage-cli build-workspace dist-workspace --alwaysPack ...plugin-packages
+
+# Then bundle each plugin using the pre-packed output
+cd plugins/my-backstage-plugin
+backstage-cli package bundle --pre-packed-dir ../../dist-workspace
+```
+
+See the full list of options in the [CLI reference](../cli/cli-report.md).
+
+**What the command does:**
+
+1. **Builds the plugin** — Produces CJS output for the backend plugin and its transitively-required monorepo packages (`*-node` or `*-common`)
+2. **Packs local packages** — Resolves `workspace:^` and `backstage:^` dependencies on both the main plugin package and its transitively-required monorepo packages (`*-node` or `*-common`)
+3. **Installs private dependencies** — Seeds a lockfile from the plugin source monorepo and prunes it, then installs a private `node_modules` containing all required dependencies
+4. **Collects configuration schemas** — Gathers plugin config schemas and writes them to `dist/.config-schema.json` so they are available for validation at load time
+
+**Benefits:**
+
+- Self-contained packages with all necessary dependencies
+- No post-installation steps required (extract and run)
+- Consistent dependency structure across all dynamic plugins
+- Automatic configuration schema collection
+- Production-ready distribution format
diff --git a/packages/backend-dynamic-feature-service/package.json b/packages/backend-dynamic-feature-service/package.json
index c197ad041c..fb1e5dd803 100644
--- a/packages/backend-dynamic-feature-service/package.json
+++ b/packages/backend-dynamic-feature-service/package.json
@@ -1,6 +1,6 @@
{
"name": "@backstage/backend-dynamic-feature-service",
- "version": "0.7.9",
+ "version": "0.8.1-next.1",
"description": "Backstage dynamic feature service",
"backstage": {
"role": "node-library"
@@ -84,7 +84,7 @@
"@backstage/repo-tools": "workspace:^",
"@types/express": "^4.17.6",
"triple-beam": "^1.4.1",
- "wait-for-expect": "^3.0.2"
+ "wait-for-expect": "^4.0.0"
},
"configSchema": "config.d.ts"
}
diff --git a/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/dist/index.cjs.js b/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/dist/index.cjs.js
new file mode 100644
index 0000000000..f3671bc0a7
--- /dev/null
+++ b/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/dist/index.cjs.js
@@ -0,0 +1,28 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+// This require resolves to the bundled proxy copy inside this plugin's
+// own node_modules/@backstage/backend-plugin-api, NOT the host's copy.
+var backendPluginApi = require('@backstage/backend-plugin-api');
+
+// Triggers the _resolveFilename fallback: require.resolve runs from
+// the bundled @backstage/backend-plugin-api whose mod.path is inside
+// this plugin's node_modules.
+var pkgDir = backendPluginApi.resolvePackagePath('plugin-test-backend-bundled');
+
+const testBundledPlugin = backendPluginApi.createBackendPlugin({
+ pluginId: "test-bundled",
+ register(env) {
+ env.registerInit({
+ deps: {
+ logger: backendPluginApi.coreServices.rootLogger,
+ },
+ async init({ logger }) {
+ logger.info("Bundled backend plugin loaded successfully");
+ }
+ });
+ }
+});
+
+exports.default = testBundledPlugin;
diff --git a/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/node_modules/@backstage/backend-plugin-api/index.js b/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/node_modules/@backstage/backend-plugin-api/index.js
new file mode 100644
index 0000000000..70e57950be
--- /dev/null
+++ b/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/node_modules/@backstage/backend-plugin-api/index.js
@@ -0,0 +1,22 @@
+'use strict';
+
+// Proxy that simulates a bundled copy of @backstage/backend-plugin-api.
+// Re-exports everything from the real workspace package, but provides a
+// local resolvePackagePath so that require.resolve() runs from THIS
+// file's context (mod.path inside node_modules/@backstage/backend-plugin-api).
+
+const nodePath = require('node:path');
+const real = require('../../../../../../../../../backend-plugin-api/src');
+
+function resolvePackagePath(name) {
+ const args = Array.prototype.slice.call(arguments, 1);
+ const pkgJson = require.resolve(name + '/package.json');
+ return nodePath.resolve.apply(
+ nodePath,
+ [nodePath.dirname(pkgJson)].concat(args),
+ );
+}
+
+module.exports = Object.assign({}, real, {
+ resolvePackagePath: resolvePackagePath,
+});
diff --git a/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/node_modules/@backstage/backend-plugin-api/package.json b/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/node_modules/@backstage/backend-plugin-api/package.json
new file mode 100644
index 0000000000..f487169afe
--- /dev/null
+++ b/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/node_modules/@backstage/backend-plugin-api/package.json
@@ -0,0 +1,6 @@
+{
+ "name": "@backstage/backend-plugin-api",
+ "version": "0.0.0",
+ "description": "Proxy that re-exports the real @backstage/backend-plugin-api with a local resolvePackagePath, simulating a bundled copy.",
+ "main": "index.js"
+}
diff --git a/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/package.json b/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/package.json
new file mode 100644
index 0000000000..bb2dbf15a6
--- /dev/null
+++ b/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/package.json
@@ -0,0 +1,31 @@
+{
+ "name": "plugin-test-backend-bundled-dynamic",
+ "version": "0.0.0",
+ "description": "A test dynamic backend plugin that bundles its own @backstage/backend-plugin-api.",
+ "backstage": {
+ "role": "backend-plugin",
+ "pluginId": "test-bundled",
+ "pluginPackages": [
+ "plugin-test-backend-bundled"
+ ]
+ },
+ "keywords": [
+ "backstage",
+ "dynamic"
+ ],
+ "exports": {
+ ".": {
+ "require": "./dist/index.cjs.js",
+ "default": "./dist/index.cjs.js"
+ },
+ "./package.json": "./package.json"
+ },
+ "main": "./dist/index.cjs.js",
+ "files": [
+ "dist"
+ ],
+ "dependencies": {
+ "@backstage/backend-plugin-api": "0.0.0"
+ },
+ "bundleDependencies": true
+}
diff --git a/packages/backend-dynamic-feature-service/src/features/features.test.ts b/packages/backend-dynamic-feature-service/src/features/features.test.ts
index ce15964c77..ac6c6ea510 100644
--- a/packages/backend-dynamic-feature-service/src/features/features.test.ts
+++ b/packages/backend-dynamic-feature-service/src/features/features.test.ts
@@ -465,6 +465,45 @@ Require stack:
});
});
+ it('should load a backend plugin that bundles its own @backstage/backend-plugin-api', async () => {
+ const dynamicPluginsLister = new DynamicPluginLister();
+ const dynamicPluginsRootForBundled = resolvePath(
+ __dirname,
+ '__fixtures__/dynamic-plugins-root-for-bundled',
+ );
+ await startTestBackend({
+ features: [
+ mockServices.rootConfig.factory({
+ data: {
+ dynamicPlugins: {
+ rootDirectory: dynamicPluginsRootForBundled,
+ },
+ backend: {
+ baseUrl: `http://localhost:0`,
+ },
+ },
+ }),
+ dynamicPluginsFeatureLoader({
+ moduleLoader: logger =>
+ jestFreeTypescriptAwareModuleLoader({ logger }),
+ }),
+ dynamicPluginsLister.feature(),
+ ],
+ });
+
+ expect(dynamicPluginsLister.loadedPlugins).toMatchObject([
+ {
+ installer: {
+ kind: 'new',
+ },
+ name: 'plugin-test-backend-bundled-dynamic',
+ platform: 'node',
+ role: 'backend-plugin',
+ version: '0.0.0',
+ },
+ ]);
+ });
+
describe('module federation support', () => {
const createRemoteProviderPlugin = (
provider: FrontendRemoteResolverProvider,
diff --git a/packages/backend-dynamic-feature-service/src/loader/CommonJSModuleLoader.ts b/packages/backend-dynamic-feature-service/src/loader/CommonJSModuleLoader.ts
index 3cc640086f..8902decdfa 100644
--- a/packages/backend-dynamic-feature-service/src/loader/CommonJSModuleLoader.ts
+++ b/packages/backend-dynamic-feature-service/src/loader/CommonJSModuleLoader.ts
@@ -99,15 +99,21 @@ export class CommonJSModuleLoader implements ModuleLoader {
);
}
- // Are we trying to resolve a `package.json` from an originating module of the core backstage application
- // (this is mostly done by calling `@backstage/backend-plugin-api/resolvePackagePath`).
- const resolvingPackageJsonFromBackstageApplication =
+ // Is this a `resolvePackagePath` call from `@backstage/backend-plugin-api`?
+ // This covers both the host application's copy and a bundled copy living
+ // inside a dynamic plugin's own node_modules.
+ // The regex matches mod.path against the various ways the package can be resolved on disk
+ // (with optional subdirectory such as /src or /dist after the package name):
+ // - .../node_modules/@backstage/backend-plugin-api[/...] (npm-installed)
+ // - ...//node_modules/@backstage/backend-plugin-api[/...] (bundled)
+ // - .../packages/backend-plugin-api[/...] (symlinked workspace in monorepo)
+ const resolvingPackageJsonViaResolvePackagePath =
request?.endsWith('/package.json') &&
- mod?.path &&
- !dynamicPluginsPaths.some(p => mod.path.startsWith(p));
+ /[/\\](?:@backstage|packages)[/\\]backend-plugin-api(?:[/\\]|$)/.test(
+ mod?.path ?? '',
+ );
- // If not, we don't need the dedicated specific case below.
- if (!resolvingPackageJsonFromBackstageApplication) {
+ if (!resolvingPackageJsonViaResolvePackagePath) {
throw errorToThrow;
}
diff --git a/packages/backend-dynamic-feature-service/src/schema/openapi.yaml b/packages/backend-dynamic-feature-service/src/schema/openapi.yaml
index 9b1871c366..987b59f4b5 100644
--- a/packages/backend-dynamic-feature-service/src/schema/openapi.yaml
+++ b/packages/backend-dynamic-feature-service/src/schema/openapi.yaml
@@ -1,4 +1,4 @@
-openapi: 3.0.3
+openapi: 3.1.0
info:
title: .backstage/dynamic-features
version: '1'
diff --git a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/apis/Api.server.ts b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/apis/Api.server.ts
index 285345d44c..7d241760dc 100644
--- a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/apis/Api.server.ts
+++ b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/apis/Api.server.ts
@@ -1,5 +1,5 @@
/*
- * Copyright 2025 The Backstage Authors
+ * Copyright 2026 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.
diff --git a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/apis/index.ts b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/apis/index.ts
index 8d81cbaf39..9a0ffed740 100644
--- a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/apis/index.ts
+++ b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/apis/index.ts
@@ -1,5 +1,5 @@
/*
- * Copyright 2025 The Backstage Authors
+ * Copyright 2026 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.
diff --git a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/index.ts b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/index.ts
index dec4b8804e..58fc52487a 100644
--- a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/index.ts
+++ b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/index.ts
@@ -1,5 +1,5 @@
/*
- * Copyright 2025 The Backstage Authors
+ * Copyright 2026 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.
diff --git a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/ErrorError.model.ts b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/ErrorError.model.ts
index e0265e95d7..853f88cc14 100644
--- a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/ErrorError.model.ts
+++ b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/ErrorError.model.ts
@@ -1,5 +1,5 @@
/*
- * Copyright 2025 The Backstage Authors
+ * Copyright 2026 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.
diff --git a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/ErrorRequest.model.ts b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/ErrorRequest.model.ts
index 3eb5e15740..1591911bc9 100644
--- a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/ErrorRequest.model.ts
+++ b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/ErrorRequest.model.ts
@@ -1,5 +1,5 @@
/*
- * Copyright 2025 The Backstage Authors
+ * Copyright 2026 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.
diff --git a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/ErrorResponse.model.ts b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/ErrorResponse.model.ts
index edbcc32df7..1eff0557ed 100644
--- a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/ErrorResponse.model.ts
+++ b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/ErrorResponse.model.ts
@@ -1,5 +1,5 @@
/*
- * Copyright 2025 The Backstage Authors
+ * Copyright 2026 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.
diff --git a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/ModelError.model.ts b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/ModelError.model.ts
index 958fde7d0b..9d5c36325e 100644
--- a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/ModelError.model.ts
+++ b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/ModelError.model.ts
@@ -1,5 +1,5 @@
/*
- * Copyright 2025 The Backstage Authors
+ * Copyright 2026 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.
@@ -26,7 +26,6 @@ import { ErrorResponse } from '../models/ErrorResponse.model';
*/
export interface ModelError {
[key: string]: any;
-
error: ErrorError;
request?: ErrorRequest;
response: ErrorResponse;
diff --git a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/Remote.model.ts b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/Remote.model.ts
index 7440110ad8..ff5cae705f 100644
--- a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/Remote.model.ts
+++ b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/Remote.model.ts
@@ -1,5 +1,5 @@
/*
- * Copyright 2025 The Backstage Authors
+ * Copyright 2026 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.
diff --git a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/RemoteInfo.model.ts b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/RemoteInfo.model.ts
index 72edba90d4..6e8bdeff0a 100644
--- a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/RemoteInfo.model.ts
+++ b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/RemoteInfo.model.ts
@@ -1,5 +1,5 @@
/*
- * Copyright 2025 The Backstage Authors
+ * Copyright 2026 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.
diff --git a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/index.ts b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/index.ts
index 0c54a6585b..4cf296a0b9 100644
--- a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/index.ts
+++ b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/models/index.ts
@@ -1,5 +1,5 @@
/*
- * Copyright 2025 The Backstage Authors
+ * Copyright 2026 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.
diff --git a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/router.ts b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/router.ts
index cf48bcfc95..b228198c3c 100644
--- a/packages/backend-dynamic-feature-service/src/schema/openapi/generated/router.ts
+++ b/packages/backend-dynamic-feature-service/src/schema/openapi/generated/router.ts
@@ -1,5 +1,5 @@
/*
- * Copyright 2025 The Backstage Authors
+ * Copyright 2026 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.
@@ -21,7 +21,7 @@ import { createValidatedOpenApiRouterFromGeneratedEndpointMap } from '@backstage
import { EndpointMap } from './apis';
export const spec = {
- openapi: '3.0.3',
+ openapi: '3.1.0',
info: {
title: '.backstage/dynamic-features',
version: '1',
diff --git a/packages/backend-dynamic-feature-service/src/schema/openapi/index.ts b/packages/backend-dynamic-feature-service/src/schema/openapi/index.ts
index 196aad553a..fb49a2b9c0 100644
--- a/packages/backend-dynamic-feature-service/src/schema/openapi/index.ts
+++ b/packages/backend-dynamic-feature-service/src/schema/openapi/index.ts
@@ -1,5 +1,5 @@
/*
- * Copyright 2025 The Backstage Authors
+ * Copyright 2026 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.
diff --git a/packages/backend-openapi-utils/CHANGELOG.md b/packages/backend-openapi-utils/CHANGELOG.md
index 58436b3235..8b382a3f84 100644
--- a/packages/backend-openapi-utils/CHANGELOG.md
+++ b/packages/backend-openapi-utils/CHANGELOG.md
@@ -1,5 +1,44 @@
# @backstage/backend-openapi-utils
+## 0.6.8-next.1
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.9.0-next.1
+
+## 0.6.8-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.1-next.0
+ - @backstage/errors@1.2.7
+ - @backstage/types@1.2.2
+
+## 0.6.7
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0
+
+## 0.6.7-next.1
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0-next.1
+
+## 0.6.7-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.7.1-next.0
+ - @backstage/errors@1.2.7
+ - @backstage/types@1.2.2
+
## 0.6.6
### Patch Changes
diff --git a/packages/backend-openapi-utils/README.md b/packages/backend-openapi-utils/README.md
index 33f2200f81..bb420f49fa 100644
--- a/packages/backend-openapi-utils/README.md
+++ b/packages/backend-openapi-utils/README.md
@@ -4,6 +4,8 @@
This package is meant to provide a typed Express router for an OpenAPI spec. Based on the [`oatx`](https://github.com/varanauskas/oatx) library and adapted to override Express values.
+Only supports OpenAPI 3.1 specifications.
+
## Getting Started
### Configuration
diff --git a/packages/backend-openapi-utils/package.json b/packages/backend-openapi-utils/package.json
index 5c6a9c5773..135af02922 100644
--- a/packages/backend-openapi-utils/package.json
+++ b/packages/backend-openapi-utils/package.json
@@ -1,6 +1,6 @@
{
"name": "@backstage/backend-openapi-utils",
- "version": "0.6.6",
+ "version": "0.6.8-next.1",
"description": "OpenAPI typescript support.",
"backstage": {
"role": "node-library"
diff --git a/packages/backend-openapi-utils/src/stub.ts b/packages/backend-openapi-utils/src/stub.ts
index 717e2ae19b..b595f357bc 100644
--- a/packages/backend-openapi-utils/src/stub.ts
+++ b/packages/backend-openapi-utils/src/stub.ts
@@ -54,6 +54,7 @@ export function getOpenApiSpecRoute(baseUrl: string) {
/**
* Create a router with validation middleware. This is used by typing methods to create an
* "OpenAPI router" with all of the expected validation + metadata.
+ * Only supports OpenAPI 3.1 specifications.
* @param spec - Your OpenAPI spec imported as a JSON object.
* @param validatorOptions - `openapi-express-validator` options to override the defaults.
* @returns A new express router with validation middleware.
@@ -115,6 +116,7 @@ function createRouterWithValidation(
/**
* Create a new OpenAPI router with some default middleware.
+ * Only supports OpenAPI 3.1 specifications.
* @param spec - Your OpenAPI spec imported as a JSON object.
* @param validatorOptions - `openapi-express-validator` options to override the defaults.
* @returns A new express router with validation middleware.
@@ -132,6 +134,7 @@ export function createValidatedOpenApiRouter(
/**
* Create a new OpenAPI router with some default middleware.
+ * Only supports OpenAPI 3.1 specifications.
* @param spec - Your OpenAPI spec imported as a JSON object.
* @param validatorOptions - `openapi-express-validator` options to override the defaults.
* @returns A new express router with validation middleware.
diff --git a/packages/backend-plugin-api/CHANGELOG.md b/packages/backend-plugin-api/CHANGELOG.md
index 94768add54..bbcf28b17f 100644
--- a/packages/backend-plugin-api/CHANGELOG.md
+++ b/packages/backend-plugin-api/CHANGELOG.md
@@ -1,5 +1,101 @@
# @backstage/backend-plugin-api
+## 1.9.0-next.1
+
+### Minor Changes
+
+- 4559806: Added support for typed `examples` on actions registered via the actions registry. Action authors can now provide examples with compile-time-checked `input` and `output` values that match their schema definitions.
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/plugin-auth-node@0.7.0-next.1
+ - @backstage/plugin-permission-node@0.10.12-next.1
+
+## 1.8.1-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/cli-common@0.2.1-next.0
+ - @backstage/plugin-auth-node@0.6.15-next.0
+ - @backstage/plugin-permission-node@0.10.12-next.0
+ - @backstage/config@1.3.6
+ - @backstage/errors@1.2.7
+ - @backstage/types@1.2.2
+ - @backstage/plugin-permission-common@0.9.7
+
+## 1.8.0
+
+### Minor Changes
+
+- cc8348e: Added optional `visibilityPermission` field to `ActionsRegistryActionOptions`, allowing actions to declare a `BasicPermission` that controls visibility and access.
+
+ ```typescript
+ import { createPermission } from '@backstage/plugin-permission-common';
+
+ const myPermission = createPermission({
+ name: 'myPlugin.myAction.use',
+ attributes: {},
+ });
+
+ actionsRegistry.register({
+ name: 'my-action',
+ title: 'My Action',
+ description: 'An action that requires permission',
+ visibilityPermission: myPermission,
+ schema: {
+ input: z => z.object({ name: z.string() }),
+ output: z => z.object({ ok: z.boolean() }),
+ },
+ action: async ({ input }) => {
+ return { output: { ok: true } };
+ },
+ });
+ ```
+
+ Actions without a `visibilityPermission` field continue to work as before.
+
+- 015668c: Added `cancelTask` method to the `SchedulerService` interface and implementation, allowing cancellation of currently running scheduled tasks. For global tasks, the database lock is released and a periodic liveness check aborts the running task function. For local tasks, the task's abort signal is triggered directly. A new `POST /.backstage/scheduler/v1/tasks/:id/cancel` endpoint is also available.
+
+### Patch Changes
+
+- dee4283: Added `pluginId` field to `ActionsServiceAction` type, populated from the registering plugin's metadata.
+- 1ee5b28: Adds an alpha `MetricsService` to provide a unified interface for metrics instrumentation across Backstage plugins.
+- a49a40d: Updated dependency `zod` to `^3.25.76 || ^4.0.0` & migrated to `/v3` or `/v4` imports.
+- Updated dependencies
+ - @backstage/cli-common@0.2.0
+ - @backstage/plugin-permission-common@0.9.7
+ - @backstage/plugin-permission-node@0.10.11
+ - @backstage/plugin-auth-node@0.6.14
+
+## 1.8.0-next.1
+
+### Minor Changes
+
+- 015668c: Added `cancelTask` method to the `SchedulerService` interface and implementation, allowing cancellation of currently running scheduled tasks. For global tasks, the database lock is released and a periodic liveness check aborts the running task function. For local tasks, the task's abort signal is triggered directly. A new `POST /.backstage/scheduler/v1/tasks/:id/cancel` endpoint is also available.
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/cli-common@0.2.0-next.2
+ - @backstage/plugin-auth-node@0.6.14-next.2
+ - @backstage/plugin-permission-node@0.10.11-next.1
+
+## 1.7.1-next.0
+
+### Patch Changes
+
+- 1ee5b28: Adds an alpha `MetricsService` to provide a unified interface for metrics instrumentation across Backstage plugins.
+- Updated dependencies
+ - @backstage/cli-common@0.2.0-next.0
+ - @backstage/config@1.3.6
+ - @backstage/errors@1.2.7
+ - @backstage/types@1.2.2
+ - @backstage/plugin-auth-node@0.6.14-next.0
+ - @backstage/plugin-permission-common@0.9.6
+ - @backstage/plugin-permission-node@0.10.11-next.0
+
## 1.7.0
### Minor Changes
diff --git a/packages/backend-plugin-api/package.json b/packages/backend-plugin-api/package.json
index 131f24bafb..5f836592c0 100644
--- a/packages/backend-plugin-api/package.json
+++ b/packages/backend-plugin-api/package.json
@@ -1,6 +1,6 @@
{
"name": "@backstage/backend-plugin-api",
- "version": "1.7.0",
+ "version": "1.9.0-next.1",
"description": "Core API used by Backstage backend plugins",
"backstage": {
"role": "node-library"
@@ -66,7 +66,7 @@
"json-schema": "^0.4.0",
"knex": "^3.0.0",
"luxon": "^3.0.0",
- "zod": "^3.25.76"
+ "zod": "^3.25.76 || ^4.0.0"
},
"devDependencies": {
"@backstage/backend-test-utils": "workspace:^",
diff --git a/packages/backend-plugin-api/report-alpha.api.md b/packages/backend-plugin-api/report-alpha.api.md
index 7d6786b97e..d1db9c7eeb 100644
--- a/packages/backend-plugin-api/report-alpha.api.md
+++ b/packages/backend-plugin-api/report-alpha.api.md
@@ -3,14 +3,15 @@
> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
```ts
-import { AnyZodObject } from 'zod';
+import { AnyZodObject } from 'zod/v3';
import { BackstageCredentials } from '@backstage/backend-plugin-api';
+import { BasicPermission } from '@backstage/plugin-permission-common';
import { JsonObject } from '@backstage/types';
import { JSONSchema7 } from 'json-schema';
import { JsonValue } from '@backstage/types';
import { LoggerService } from '@backstage/backend-plugin-api';
import { ServiceRef } from '@backstage/backend-plugin-api';
-import { z } from 'zod';
+import { z } from 'zod/v3';
// @alpha (undocumented)
export type ActionsRegistryActionContext = {
@@ -19,6 +20,17 @@ export type ActionsRegistryActionContext = {
credentials: BackstageCredentials;
};
+// @alpha
+export type ActionsRegistryActionExample<
+ TInputSchema extends AnyZodObject,
+ TOutputSchema extends AnyZodObject,
+> = {
+ title: string;
+ description?: string;
+ input: z.infer;
+ output?: z.infer;
+};
+
// @alpha (undocumented)
export type ActionsRegistryActionOptions<
TInputSchema extends AnyZodObject,
@@ -31,6 +43,8 @@ export type ActionsRegistryActionOptions<
input: (zod: typeof z) => TInputSchema;
output: (zod: typeof z) => TOutputSchema;
};
+ examples?: Array>;
+ visibilityPermission?: BasicPermission;
attributes?: {
destructive?: boolean;
idempotent?: boolean;
@@ -82,6 +96,7 @@ export interface ActionsService {
// @alpha (undocumented)
export type ActionsServiceAction = {
id: string;
+ pluginId: string;
name: string;
title: string;
description: string;
@@ -89,6 +104,12 @@ export type ActionsServiceAction = {
input: JSONSchema7;
output: JSONSchema7;
};
+ examples?: Array<{
+ title: string;
+ description?: string;
+ input: JsonObject;
+ output?: JsonObject;
+ }>;
attributes: {
readOnly: boolean;
destructive: boolean;
diff --git a/packages/backend-plugin-api/report.api.md b/packages/backend-plugin-api/report.api.md
index 504be97ec6..96d1a02c0a 100644
--- a/packages/backend-plugin-api/report.api.md
+++ b/packages/backend-plugin-api/report.api.md
@@ -643,6 +643,7 @@ export interface RootServiceFactoryOptions<
// @public
export interface SchedulerService {
+ cancelTask(id: string): Promise;
createScheduledTaskRunner(
schedule: SchedulerServiceTaskScheduleDefinition,
): SchedulerServiceTaskRunner;
diff --git a/packages/backend-plugin-api/src/alpha/ActionsRegistryService.ts b/packages/backend-plugin-api/src/alpha/ActionsRegistryService.ts
index 9a7820e354..65f44be051 100644
--- a/packages/backend-plugin-api/src/alpha/ActionsRegistryService.ts
+++ b/packages/backend-plugin-api/src/alpha/ActionsRegistryService.ts
@@ -13,7 +13,8 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-import { z, AnyZodObject } from 'zod';
+import { z, AnyZodObject } from 'zod/v3';
+import { BasicPermission } from '@backstage/plugin-permission-common';
import {
LoggerService,
BackstageCredentials,
@@ -28,6 +29,21 @@ export type ActionsRegistryActionContext = {
credentials: BackstageCredentials;
};
+/**
+ * An example of how to use an action registered in the actions registry.
+ *
+ * @alpha
+ */
+export type ActionsRegistryActionExample<
+ TInputSchema extends AnyZodObject,
+ TOutputSchema extends AnyZodObject,
+> = {
+ title: string;
+ description?: string;
+ input: z.infer;
+ output?: z.infer;
+};
+
/**
* @alpha
*/
@@ -42,6 +58,8 @@ export type ActionsRegistryActionOptions<
input: (zod: typeof z) => TInputSchema;
output: (zod: typeof z) => TOutputSchema;
};
+ examples?: Array>;
+ visibilityPermission?: BasicPermission;
attributes?: {
destructive?: boolean;
idempotent?: boolean;
diff --git a/packages/backend-plugin-api/src/alpha/ActionsService.ts b/packages/backend-plugin-api/src/alpha/ActionsService.ts
index 528b6cea67..7062de9c77 100644
--- a/packages/backend-plugin-api/src/alpha/ActionsService.ts
+++ b/packages/backend-plugin-api/src/alpha/ActionsService.ts
@@ -22,6 +22,7 @@ import { BackstageCredentials } from '@backstage/backend-plugin-api';
*/
export type ActionsServiceAction = {
id: string;
+ pluginId: string;
name: string;
title: string;
description: string;
@@ -29,6 +30,12 @@ export type ActionsServiceAction = {
input: JSONSchema7;
output: JSONSchema7;
};
+ examples?: Array<{
+ title: string;
+ description?: string;
+ input: JsonObject;
+ output?: JsonObject;
+ }>;
attributes: {
readOnly: boolean;
destructive: boolean;
diff --git a/packages/backend-plugin-api/src/alpha/index.ts b/packages/backend-plugin-api/src/alpha/index.ts
index c487686338..9ec7ca5b09 100644
--- a/packages/backend-plugin-api/src/alpha/index.ts
+++ b/packages/backend-plugin-api/src/alpha/index.ts
@@ -23,6 +23,7 @@ export type {
ActionsRegistryService,
ActionsRegistryActionOptions,
ActionsRegistryActionContext,
+ ActionsRegistryActionExample,
} from './ActionsRegistryService';
export type { ActionsService, ActionsServiceAction } from './ActionsService';
diff --git a/packages/backend-plugin-api/src/services/definitions/ActionsRegistryService.ts b/packages/backend-plugin-api/src/services/definitions/ActionsRegistryService.ts
index 6c0936f85c..39c62ce731 100644
--- a/packages/backend-plugin-api/src/services/definitions/ActionsRegistryService.ts
+++ b/packages/backend-plugin-api/src/services/definitions/ActionsRegistryService.ts
@@ -13,7 +13,8 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-import { z, AnyZodObject } from 'zod';
+import { z, AnyZodObject } from 'zod/v3';
+import { BasicPermission } from '@backstage/plugin-permission-common';
import { LoggerService } from './LoggerService';
import { BackstageCredentials } from './AuthService';
@@ -26,6 +27,21 @@ export type ActionsRegistryActionContext = {
credentials: BackstageCredentials;
};
+/**
+ * An example of how to use an action registered in the actions registry.
+ *
+ * @public
+ */
+export type ActionsRegistryActionExample<
+ TInputSchema extends AnyZodObject,
+ TOutputSchema extends AnyZodObject,
+> = {
+ title: string;
+ description?: string;
+ input: z.infer;
+ output?: z.infer;
+};
+
/**
* @public
*/
@@ -40,6 +56,8 @@ export type ActionsRegistryActionOptions<
input: (zod: typeof z) => TInputSchema;
output: (zod: typeof z) => TOutputSchema;
};
+ examples?: Array>;
+ visibilityPermission?: BasicPermission;
attributes?: {
destructive?: boolean;
idempotent?: boolean;
diff --git a/packages/backend-plugin-api/src/services/definitions/ActionsService.ts b/packages/backend-plugin-api/src/services/definitions/ActionsService.ts
index d595008a42..3afa131915 100644
--- a/packages/backend-plugin-api/src/services/definitions/ActionsService.ts
+++ b/packages/backend-plugin-api/src/services/definitions/ActionsService.ts
@@ -29,6 +29,12 @@ export type ActionsServiceAction = {
input: JSONSchema7;
output: JSONSchema7;
};
+ examples?: Array<{
+ title: string;
+ description?: string;
+ input: JsonObject;
+ output?: JsonObject;
+ }>;
attributes: {
readOnly: boolean;
destructive: boolean;
diff --git a/packages/backend-plugin-api/src/services/definitions/SchedulerService.ts b/packages/backend-plugin-api/src/services/definitions/SchedulerService.ts
index b1a0e17df8..2748b8fac7 100644
--- a/packages/backend-plugin-api/src/services/definitions/SchedulerService.ts
+++ b/packages/backend-plugin-api/src/services/definitions/SchedulerService.ts
@@ -304,6 +304,16 @@ export interface SchedulerService {
*/
triggerTask(id: string): Promise;
+ /**
+ * Cancels a currently running task by ID, marking it as idle.
+ *
+ * If the task doesn't exist, a NotFoundError is thrown. If the task is
+ * not currently running, a ConflictError is thrown.
+ *
+ * @param id - The task ID
+ */
+ cancelTask(id: string): Promise;
+
/**
* Schedules a task function for recurring runs.
*
diff --git a/packages/backend-test-utils/CHANGELOG.md b/packages/backend-test-utils/CHANGELOG.md
index 0b144df1da..5f783d9029 100644
--- a/packages/backend-test-utils/CHANGELOG.md
+++ b/packages/backend-test-utils/CHANGELOG.md
@@ -1,5 +1,93 @@
# @backstage/backend-test-utils
+## 1.11.2-next.1
+
+### Patch Changes
+
+- 4559806: Added support for typed `examples` on actions registered via the actions registry. Action authors can now provide examples with compile-time-checked `input` and `output` values that match their schema definitions.
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.9.0-next.1
+ - @backstage/backend-defaults@0.16.1-next.1
+ - @backstage/plugin-auth-node@0.7.0-next.1
+ - @backstage/backend-app-api@1.6.1-next.1
+ - @backstage/plugin-events-node@0.4.21-next.1
+
+## 1.11.2-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-defaults@0.16.1-next.0
+ - @backstage/backend-plugin-api@1.8.1-next.0
+ - @backstage/backend-app-api@1.6.1-next.0
+ - @backstage/plugin-auth-node@0.6.15-next.0
+ - @backstage/plugin-events-node@0.4.21-next.0
+ - @backstage/config@1.3.6
+ - @backstage/errors@1.2.7
+ - @backstage/types@1.2.2
+ - @backstage/plugin-permission-common@0.9.7
+
+## 1.11.1
+
+### Patch Changes
+
+- dee4283: Added `pluginId` field to `ActionsServiceAction` type, populated from the registering plugin's metadata.
+- 164711a: Added `cancelTask` to `MockSchedulerService` and mock scheduler service factory.
+- 62f0a53: Fixed error forwarding in the actions registry so that known errors like `InputError` and `NotFoundError` thrown by actions preserve their original status codes and messages instead of being wrapped in `ForwardedError` and coerced to 500.
+- a49a40d: Updated dependency `zod` to `^3.25.76 || ^4.0.0` & migrated to `/v3` or `/v4` imports.
+- 1ee5b28: Adds a new metrics service mock to be leveraged in tests
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0
+ - @backstage/backend-defaults@0.16.0
+ - @backstage/plugin-permission-common@0.9.7
+ - @backstage/plugin-auth-node@0.6.14
+ - @backstage/backend-app-api@1.6.0
+ - @backstage/plugin-events-node@0.4.20
+
+## 1.11.1-next.2
+
+### Patch Changes
+
+- 164711a: Added `cancelTask` to `MockSchedulerService` and mock scheduler service factory.
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0-next.1
+ - @backstage/backend-defaults@0.16.0-next.2
+ - @backstage/backend-app-api@1.6.0-next.1
+ - @backstage/plugin-auth-node@0.6.14-next.2
+ - @backstage/plugin-events-node@0.4.20-next.1
+
+## 1.11.1-next.1
+
+### Patch Changes
+
+- 62f0a53: Fixed error forwarding in the actions registry so that known errors like `InputError` and `NotFoundError` thrown by actions preserve their original status codes and messages instead of being wrapped in `ForwardedError` and coerced to 500.
+- Updated dependencies
+ - @backstage/backend-defaults@0.16.0-next.1
+ - @backstage/plugin-auth-node@0.6.14-next.1
+ - @backstage/backend-app-api@1.5.1-next.0
+ - @backstage/backend-plugin-api@1.7.1-next.0
+ - @backstage/config@1.3.6
+ - @backstage/errors@1.2.7
+ - @backstage/types@1.2.2
+ - @backstage/plugin-events-node@0.4.20-next.0
+ - @backstage/plugin-permission-common@0.9.6
+
+## 1.11.1-next.0
+
+### Patch Changes
+
+- 1ee5b28: Adds a new metrics service mock to be leveraged in tests
+- Updated dependencies
+ - @backstage/backend-defaults@0.15.3-next.0
+ - @backstage/backend-plugin-api@1.7.1-next.0
+ - @backstage/backend-app-api@1.5.1-next.0
+ - @backstage/config@1.3.6
+ - @backstage/errors@1.2.7
+ - @backstage/types@1.2.2
+ - @backstage/plugin-auth-node@0.6.14-next.0
+ - @backstage/plugin-events-node@0.4.20-next.0
+ - @backstage/plugin-permission-common@0.9.6
+
## 1.11.0
### Minor Changes
diff --git a/packages/backend-test-utils/package.json b/packages/backend-test-utils/package.json
index ee65ddbc78..4e5bcb2074 100644
--- a/packages/backend-test-utils/package.json
+++ b/packages/backend-test-utils/package.json
@@ -1,6 +1,6 @@
{
"name": "@backstage/backend-test-utils",
- "version": "1.11.0",
+ "version": "1.11.2-next.1",
"description": "Test helpers library for Backstage backends",
"backstage": {
"role": "node-library"
@@ -79,7 +79,7 @@
"text-extensions": "^2.4.0",
"uuid": "^11.0.0",
"yn": "^4.0.0",
- "zod": "^3.25.76",
+ "zod": "^3.25.76 || ^4.0.0",
"zod-to-json-schema": "^3.25.1"
},
"devDependencies": {
diff --git a/packages/backend-test-utils/report-alpha.api.md b/packages/backend-test-utils/report-alpha.api.md
index b6bf9e883d..4813f49c35 100644
--- a/packages/backend-test-utils/report-alpha.api.md
+++ b/packages/backend-test-utils/report-alpha.api.md
@@ -7,7 +7,7 @@ import { ActionsRegistryActionOptions } from '@backstage/backend-plugin-api/alph
import { ActionsRegistryService } from '@backstage/backend-plugin-api/alpha';
import { ActionsService } from '@backstage/backend-plugin-api/alpha';
import { ActionsServiceAction } from '@backstage/backend-plugin-api/alpha';
-import { AnyZodObject } from 'zod';
+import { AnyZodObject } from 'zod/v3';
import { BackstageCredentials } from '@backstage/backend-plugin-api';
import { JsonObject } from '@backstage/types';
import { JsonValue } from '@backstage/types';
diff --git a/packages/backend-test-utils/src/alpha/services/MockActionsRegistry.ts b/packages/backend-test-utils/src/alpha/services/MockActionsRegistry.ts
index 94e5987afd..d3d94d8d9c 100644
--- a/packages/backend-test-utils/src/alpha/services/MockActionsRegistry.ts
+++ b/packages/backend-test-utils/src/alpha/services/MockActionsRegistry.ts
@@ -17,9 +17,9 @@ import {
BackstageCredentials,
LoggerService,
} from '@backstage/backend-plugin-api';
-import { ForwardedError, InputError, NotFoundError } from '@backstage/errors';
+import { InputError, NotFoundError } from '@backstage/errors';
import { JsonObject, JsonValue } from '@backstage/types';
-import { z, AnyZodObject } from 'zod';
+import { z, AnyZodObject } from 'zod/v3';
import zodToJsonSchema from 'zod-to-json-schema';
import { mockCredentials } from '../../services';
import {
@@ -82,6 +82,7 @@ export class MockActionsRegistry
return {
actions: Array.from(this.actions.entries()).map(([id, action]) => ({
id,
+ pluginId: 'test',
name: action.name,
title: action.title,
description: action.description,
@@ -90,6 +91,7 @@ export class MockActionsRegistry
idempotent: action.attributes?.idempotent ?? false,
readOnly: action.attributes?.readOnly ?? false,
},
+ examples: action.examples,
schema: {
input: action.schema?.input
? zodToJsonSchema(action.schema.input(z))
@@ -126,31 +128,24 @@ export class MockActionsRegistry
throw new InputError(`Invalid input to action "${opts.id}"`, input.error);
}
- try {
- const result = await action.action({
- input: input.data,
- credentials: opts.credentials ?? mockCredentials.none(),
- logger: this.logger,
- });
+ const result = await action.action({
+ input: input.data,
+ credentials: opts.credentials ?? mockCredentials.none(),
+ logger: this.logger,
+ });
- const output = action.schema?.output
- ? action.schema.output(z).safeParse(result?.output)
- : ({ success: true, data: result?.output } as const);
+ const output = action.schema?.output
+ ? action.schema.output(z).safeParse(result?.output)
+ : ({ success: true, data: result?.output } as const);
- if (!output.success) {
- throw new InputError(
- `Invalid output from action "${opts.id}"`,
- output.error,
- );
- }
-
- return { output: output.data };
- } catch (error) {
- throw new ForwardedError(
- `Failed execution of action "${opts.id}"`,
- error,
+ if (!output.success) {
+ throw new InputError(
+ `Invalid output from action "${opts.id}"`,
+ output.error,
);
}
+
+ return { output: output.data };
}
register<
diff --git a/packages/backend-test-utils/src/services/MockSchedulerService.test.ts b/packages/backend-test-utils/src/services/MockSchedulerService.test.ts
index faf4e3e26d..2668fa7205 100644
--- a/packages/backend-test-utils/src/services/MockSchedulerService.test.ts
+++ b/packages/backend-test-utils/src/services/MockSchedulerService.test.ts
@@ -206,6 +206,68 @@ describe('MockSchedulerService', () => {
await expect(isDone()).resolves.toBe(true);
});
+ it('should cancel a running task and allow re-triggering with a fresh signal', async () => {
+ const scheduler = new MockSchedulerService();
+ const signals: AbortSignal[] = [];
+
+ scheduler.scheduleTask({
+ ...baseOpts,
+ id: 'test',
+ fn: async signal => {
+ signals.push(signal);
+ // Simulate long-running work that respects cancellation
+ await new Promise((resolve, reject) => {
+ if (signal.aborted) {
+ reject(new Error('aborted'));
+ return;
+ }
+ signal.addEventListener('abort', () => reject(new Error('aborted')));
+ setTimeout(1).then(resolve);
+ });
+ },
+ });
+
+ // First run completes normally
+ await scheduler.triggerTask('test');
+ expect(signals).toHaveLength(1);
+ expect(signals[0].aborted).toBe(false);
+
+ // Start a task that will block until cancelled
+ const blockingScheduler = new MockSchedulerService();
+ let resolveBlock: (() => void) | undefined;
+ blockingScheduler.scheduleTask({
+ ...baseOpts,
+ id: 'blocking',
+ fn: async signal => {
+ signals.push(signal);
+ await new Promise((resolve, reject) => {
+ signal.addEventListener('abort', () => reject(new Error('aborted')));
+ resolveBlock = resolve;
+ });
+ },
+ });
+
+ const triggerPromise = blockingScheduler.triggerTask('blocking');
+ // Give the task fn time to start
+ await setTimeout(1);
+
+ await blockingScheduler.cancelTask('blocking');
+ await triggerPromise.catch(() => {});
+
+ expect(signals).toHaveLength(2);
+ expect(signals[1].aborted).toBe(true);
+
+ // Re-trigger should get a fresh non-aborted signal
+ resolveBlock = undefined;
+ const triggerPromise2 = blockingScheduler.triggerTask('blocking');
+ await setTimeout(1);
+ resolveBlock!();
+ await triggerPromise2;
+
+ expect(signals).toHaveLength(3);
+ expect(signals[2].aborted).toBe(false);
+ });
+
it('should abort tasks when shutting down', async () => {
let taskSignal: AbortSignal | undefined;
diff --git a/packages/backend-test-utils/src/services/MockSchedulerService.ts b/packages/backend-test-utils/src/services/MockSchedulerService.ts
index aafd6d98ec..3309ebc954 100644
--- a/packages/backend-test-utils/src/services/MockSchedulerService.ts
+++ b/packages/backend-test-utils/src/services/MockSchedulerService.ts
@@ -23,6 +23,7 @@ import {
SchedulerServiceTaskRunner,
SchedulerServiceTaskScheduleDefinition,
} from '@backstage/backend-plugin-api';
+import { ConflictError, NotFoundError } from '@backstage/errors';
import { createDeferred, DeferredPromise } from '@backstage/types';
export class MockSchedulerService implements SchedulerService {
@@ -95,10 +96,22 @@ export class MockSchedulerService implements SchedulerService {
});
}
+ async cancelTask(id: string): Promise {
+ const task = this.#tasks.get(id);
+ if (!task) {
+ throw new NotFoundError(`Task ${id} not found`);
+ }
+ if (!this.#runningTasks.has(id)) {
+ throw new ConflictError(`Task ${id} is not running`);
+ }
+ task.abortControllers.abort();
+ task.abortControllers = new AbortController();
+ }
+
async triggerTask(id: string): Promise {
const task = this.#tasks.get(id);
if (!task) {
- throw new Error(`Task ${id} not found`);
+ throw new NotFoundError(`Task ${id} not found`);
}
if (this.#runningTasks.has(id)) {
return;
diff --git a/packages/backend-test-utils/src/services/mockServices.ts b/packages/backend-test-utils/src/services/mockServices.ts
index 84783f04d7..4d54269b98 100644
--- a/packages/backend-test-utils/src/services/mockServices.ts
+++ b/packages/backend-test-utils/src/services/mockServices.ts
@@ -526,6 +526,7 @@ export namespace mockServices {
getScheduledTasks: jest.fn(),
scheduleTask: jest.fn(),
triggerTask: jest.fn(),
+ cancelTask: jest.fn(),
}));
}
diff --git a/packages/backend/CHANGELOG.md b/packages/backend/CHANGELOG.md
index 27ef95a0f3..9e3353c8be 100644
--- a/packages/backend/CHANGELOG.md
+++ b/packages/backend/CHANGELOG.md
@@ -1,5 +1,255 @@
# example-backend
+## 0.0.49-next.1
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.9.0-next.1
+ - @backstage/backend-defaults@0.16.1-next.1
+ - @backstage/plugin-catalog-backend@3.5.1-next.1
+ - @backstage/plugin-scaffolder-backend@3.3.0-next.1
+ - @backstage/plugin-auth-node@0.7.0-next.1
+ - @backstage/plugin-app-backend@0.5.13-next.1
+ - @backstage/plugin-auth-backend@0.28.0-next.1
+ - @backstage/plugin-auth-backend-module-github-provider@0.5.2-next.1
+ - @backstage/plugin-auth-backend-module-guest-provider@0.2.18-next.1
+ - @backstage/plugin-auth-backend-module-openshift-provider@0.1.6-next.1
+ - @backstage/plugin-catalog-backend-module-backstage-openapi@0.5.13-next.1
+ - @backstage/plugin-catalog-backend-module-logs@0.1.21-next.1
+ - @backstage/plugin-catalog-backend-module-openapi@0.2.21-next.1
+ - @backstage/plugin-catalog-backend-module-scaffolder-entity-model@0.2.19-next.1
+ - @backstage/plugin-catalog-backend-module-unprocessed@0.6.10-next.1
+ - @backstage/plugin-devtools-backend@0.5.16-next.1
+ - @backstage/plugin-events-backend@0.6.1-next.1
+ - @backstage/plugin-events-backend-module-google-pubsub@0.2.2-next.1
+ - @backstage/plugin-kubernetes-backend@0.21.3-next.1
+ - @backstage/plugin-mcp-actions-backend@0.1.11-next.1
+ - @backstage/plugin-notifications-backend@0.6.4-next.1
+ - @backstage/plugin-permission-backend@0.7.11-next.1
+ - @backstage/plugin-permission-backend-module-allow-all-policy@0.2.18-next.1
+ - @backstage/plugin-permission-node@0.10.12-next.1
+ - @backstage/plugin-proxy-backend@0.6.12-next.1
+ - @backstage/plugin-scaffolder-backend-module-github@0.9.8-next.1
+ - @backstage/plugin-scaffolder-backend-module-notifications@0.1.21-next.1
+ - @backstage/plugin-search-backend@2.1.1-next.1
+ - @backstage/plugin-search-backend-module-catalog@0.3.14-next.1
+ - @backstage/plugin-search-backend-module-elasticsearch@1.8.2-next.1
+ - @backstage/plugin-search-backend-module-explore@0.3.13-next.1
+ - @backstage/plugin-search-backend-module-techdocs@0.4.13-next.1
+ - @backstage/plugin-search-backend-node@1.4.3-next.1
+ - @backstage/plugin-signals-backend@0.3.14-next.1
+ - @backstage/plugin-techdocs-backend@2.1.7-next.1
+
+## 0.0.49-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/plugin-catalog-backend@3.5.1-next.0
+ - @backstage/plugin-auth-backend@0.28.0-next.0
+ - @backstage/backend-defaults@0.16.1-next.0
+ - @backstage/plugin-events-backend-module-google-pubsub@0.2.2-next.0
+ - @backstage/plugin-scaffolder-backend@3.2.1-next.0
+ - @backstage/backend-plugin-api@1.8.1-next.0
+ - @backstage/plugin-devtools-backend@0.5.16-next.0
+ - @backstage/plugin-catalog-backend-module-logs@0.1.21-next.0
+ - @backstage/plugin-auth-backend-module-github-provider@0.5.2-next.0
+ - @backstage/plugin-auth-backend-module-openshift-provider@0.1.6-next.0
+ - @backstage/plugin-notifications-backend@0.6.4-next.0
+ - @backstage/plugin-signals-backend@0.3.14-next.0
+ - @backstage/plugin-app-backend@0.5.13-next.0
+ - @backstage/plugin-auth-node@0.6.15-next.0
+ - @backstage/plugin-events-backend@0.6.1-next.0
+ - @backstage/plugin-kubernetes-backend@0.21.3-next.0
+ - @backstage/plugin-mcp-actions-backend@0.1.11-next.0
+ - @backstage/plugin-permission-backend@0.7.11-next.0
+ - @backstage/plugin-permission-node@0.10.12-next.0
+ - @backstage/plugin-proxy-backend@0.6.12-next.0
+ - @backstage/plugin-search-backend@2.1.1-next.0
+ - @backstage/plugin-search-backend-node@1.4.3-next.0
+ - @backstage/plugin-techdocs-backend@2.1.7-next.0
+ - @backstage/plugin-auth-backend-module-guest-provider@0.2.18-next.0
+ - @backstage/plugin-catalog-backend-module-backstage-openapi@0.5.13-next.0
+ - @backstage/plugin-catalog-backend-module-openapi@0.2.21-next.0
+ - @backstage/plugin-catalog-backend-module-scaffolder-entity-model@0.2.19-next.0
+ - @backstage/plugin-catalog-backend-module-unprocessed@0.6.10-next.0
+ - @backstage/plugin-permission-backend-module-allow-all-policy@0.2.18-next.0
+ - @backstage/plugin-scaffolder-backend-module-github@0.9.8-next.0
+ - @backstage/plugin-scaffolder-backend-module-notifications@0.1.21-next.0
+ - @backstage/plugin-search-backend-module-catalog@0.3.14-next.0
+ - @backstage/plugin-search-backend-module-elasticsearch@1.8.2-next.0
+ - @backstage/plugin-search-backend-module-explore@0.3.13-next.0
+ - @backstage/plugin-search-backend-module-techdocs@0.4.13-next.0
+ - @backstage/catalog-model@1.7.7
+ - @backstage/plugin-permission-common@0.9.7
+
+## 0.0.48
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0
+ - @backstage/backend-defaults@0.16.0
+ - @backstage/plugin-catalog-backend@3.5.0
+ - @backstage/plugin-auth-backend@0.27.2
+ - @backstage/plugin-techdocs-backend@2.1.6
+ - @backstage/plugin-scaffolder-backend-module-github@0.9.7
+ - @backstage/plugin-scaffolder-backend@3.2.0
+ - @backstage/plugin-mcp-actions-backend@0.1.10
+ - @backstage/plugin-kubernetes-backend@0.21.2
+ - @backstage/plugin-events-backend@0.6.0
+ - @backstage/plugin-search-backend@2.1.0
+ - @backstage/plugin-auth-backend-module-openshift-provider@0.1.5
+ - @backstage/plugin-auth-backend-module-github-provider@0.5.1
+ - @backstage/plugin-permission-backend@0.7.10
+ - @backstage/plugin-permission-common@0.9.7
+ - @backstage/plugin-permission-node@0.10.11
+ - @backstage/catalog-model@1.7.7
+ - @backstage/plugin-auth-node@0.6.14
+ - @backstage/plugin-app-backend@0.5.12
+ - @backstage/plugin-auth-backend-module-guest-provider@0.2.17
+ - @backstage/plugin-catalog-backend-module-backstage-openapi@0.5.12
+ - @backstage/plugin-catalog-backend-module-openapi@0.2.20
+ - @backstage/plugin-catalog-backend-module-scaffolder-entity-model@0.2.18
+ - @backstage/plugin-catalog-backend-module-unprocessed@0.6.9
+ - @backstage/plugin-devtools-backend@0.5.15
+ - @backstage/plugin-events-backend-module-google-pubsub@0.2.1
+ - @backstage/plugin-notifications-backend@0.6.3
+ - @backstage/plugin-permission-backend-module-allow-all-policy@0.2.17
+ - @backstage/plugin-proxy-backend@0.6.11
+ - @backstage/plugin-scaffolder-backend-module-notifications@0.1.20
+ - @backstage/plugin-search-backend-module-catalog@0.3.13
+ - @backstage/plugin-search-backend-module-elasticsearch@1.8.1
+ - @backstage/plugin-search-backend-module-explore@0.3.12
+ - @backstage/plugin-search-backend-module-techdocs@0.4.12
+ - @backstage/plugin-search-backend-node@1.4.2
+ - @backstage/plugin-signals-backend@0.3.13
+
+## 0.0.48-next.2
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0-next.1
+ - @backstage/backend-defaults@0.16.0-next.2
+ - @backstage/plugin-auth-backend@0.27.1-next.2
+ - @backstage/plugin-catalog-backend@3.5.0-next.2
+ - @backstage/plugin-scaffolder-backend@3.2.0-next.2
+ - @backstage/plugin-mcp-actions-backend@0.1.10-next.2
+ - @backstage/plugin-scaffolder-backend-module-github@0.9.7-next.2
+ - @backstage/plugin-app-backend@0.5.12-next.1
+ - @backstage/plugin-auth-backend-module-github-provider@0.5.1-next.1
+ - @backstage/plugin-auth-backend-module-guest-provider@0.2.17-next.1
+ - @backstage/plugin-auth-backend-module-openshift-provider@0.1.5-next.1
+ - @backstage/plugin-auth-node@0.6.14-next.2
+ - @backstage/plugin-catalog-backend-module-backstage-openapi@0.5.12-next.1
+ - @backstage/plugin-catalog-backend-module-openapi@0.2.20-next.2
+ - @backstage/plugin-catalog-backend-module-scaffolder-entity-model@0.2.18-next.2
+ - @backstage/plugin-catalog-backend-module-unprocessed@0.6.9-next.1
+ - @backstage/plugin-devtools-backend@0.5.15-next.1
+ - @backstage/plugin-events-backend@0.6.0-next.2
+ - @backstage/plugin-events-backend-module-google-pubsub@0.2.1-next.1
+ - @backstage/plugin-kubernetes-backend@0.21.2-next.2
+ - @backstage/plugin-notifications-backend@0.6.3-next.1
+ - @backstage/plugin-permission-backend@0.7.10-next.1
+ - @backstage/plugin-permission-backend-module-allow-all-policy@0.2.17-next.1
+ - @backstage/plugin-permission-node@0.10.11-next.1
+ - @backstage/plugin-proxy-backend@0.6.11-next.1
+ - @backstage/plugin-scaffolder-backend-module-notifications@0.1.20-next.2
+ - @backstage/plugin-search-backend@2.1.0-next.2
+ - @backstage/plugin-search-backend-module-catalog@0.3.13-next.2
+ - @backstage/plugin-search-backend-module-elasticsearch@1.8.1-next.1
+ - @backstage/plugin-search-backend-module-explore@0.3.12-next.1
+ - @backstage/plugin-search-backend-module-techdocs@0.4.12-next.2
+ - @backstage/plugin-search-backend-node@1.4.2-next.1
+ - @backstage/plugin-signals-backend@0.3.13-next.1
+ - @backstage/plugin-techdocs-backend@2.1.6-next.2
+
+## 0.0.48-next.1
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/plugin-catalog-backend@3.5.0-next.1
+ - @backstage/plugin-auth-backend@0.27.1-next.1
+ - @backstage/plugin-techdocs-backend@2.1.6-next.1
+ - @backstage/backend-defaults@0.16.0-next.1
+ - @backstage/plugin-scaffolder-backend@3.2.0-next.1
+ - @backstage/plugin-mcp-actions-backend@0.1.10-next.1
+ - @backstage/plugin-events-backend@0.6.0-next.1
+ - @backstage/plugin-search-backend@2.1.0-next.1
+ - @backstage/plugin-auth-node@0.6.14-next.1
+ - @backstage/plugin-kubernetes-backend@0.21.2-next.1
+ - @backstage/plugin-search-backend-module-catalog@0.3.13-next.1
+ - @backstage/plugin-search-backend-module-techdocs@0.4.12-next.1
+ - @backstage/backend-plugin-api@1.7.1-next.0
+ - @backstage/catalog-model@1.7.6
+ - @backstage/plugin-app-backend@0.5.12-next.0
+ - @backstage/plugin-auth-backend-module-github-provider@0.5.1-next.0
+ - @backstage/plugin-auth-backend-module-guest-provider@0.2.17-next.0
+ - @backstage/plugin-auth-backend-module-openshift-provider@0.1.5-next.0
+ - @backstage/plugin-catalog-backend-module-backstage-openapi@0.5.12-next.0
+ - @backstage/plugin-catalog-backend-module-openapi@0.2.20-next.1
+ - @backstage/plugin-catalog-backend-module-scaffolder-entity-model@0.2.18-next.1
+ - @backstage/plugin-catalog-backend-module-unprocessed@0.6.9-next.0
+ - @backstage/plugin-devtools-backend@0.5.15-next.0
+ - @backstage/plugin-events-backend-module-google-pubsub@0.2.1-next.0
+ - @backstage/plugin-notifications-backend@0.6.3-next.0
+ - @backstage/plugin-permission-backend@0.7.10-next.0
+ - @backstage/plugin-permission-backend-module-allow-all-policy@0.2.17-next.0
+ - @backstage/plugin-permission-common@0.9.6
+ - @backstage/plugin-permission-node@0.10.11-next.0
+ - @backstage/plugin-proxy-backend@0.6.11-next.0
+ - @backstage/plugin-scaffolder-backend-module-github@0.9.7-next.1
+ - @backstage/plugin-scaffolder-backend-module-notifications@0.1.20-next.1
+ - @backstage/plugin-search-backend-module-elasticsearch@1.8.1-next.0
+ - @backstage/plugin-search-backend-module-explore@0.3.12-next.0
+ - @backstage/plugin-search-backend-node@1.4.2-next.0
+ - @backstage/plugin-signals-backend@0.3.13-next.0
+
+## 0.0.48-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-defaults@0.15.3-next.0
+ - @backstage/plugin-auth-backend@0.27.1-next.0
+ - @backstage/plugin-catalog-backend@3.5.0-next.0
+ - @backstage/plugin-scaffolder-backend@3.1.4-next.0
+ - @backstage/backend-plugin-api@1.7.1-next.0
+ - @backstage/plugin-mcp-actions-backend@0.1.10-next.0
+ - @backstage/catalog-model@1.7.6
+ - @backstage/plugin-app-backend@0.5.12-next.0
+ - @backstage/plugin-auth-backend-module-github-provider@0.5.1-next.0
+ - @backstage/plugin-auth-backend-module-guest-provider@0.2.17-next.0
+ - @backstage/plugin-auth-backend-module-openshift-provider@0.1.5-next.0
+ - @backstage/plugin-auth-node@0.6.14-next.0
+ - @backstage/plugin-catalog-backend-module-backstage-openapi@0.5.12-next.0
+ - @backstage/plugin-catalog-backend-module-openapi@0.2.20-next.0
+ - @backstage/plugin-catalog-backend-module-scaffolder-entity-model@0.2.18-next.0
+ - @backstage/plugin-catalog-backend-module-unprocessed@0.6.9-next.0
+ - @backstage/plugin-devtools-backend@0.5.15-next.0
+ - @backstage/plugin-events-backend@0.5.12-next.0
+ - @backstage/plugin-events-backend-module-google-pubsub@0.2.1-next.0
+ - @backstage/plugin-kubernetes-backend@0.21.2-next.0
+ - @backstage/plugin-notifications-backend@0.6.3-next.0
+ - @backstage/plugin-permission-backend@0.7.10-next.0
+ - @backstage/plugin-permission-backend-module-allow-all-policy@0.2.17-next.0
+ - @backstage/plugin-permission-common@0.9.6
+ - @backstage/plugin-permission-node@0.10.11-next.0
+ - @backstage/plugin-proxy-backend@0.6.11-next.0
+ - @backstage/plugin-scaffolder-backend-module-github@0.9.7-next.0
+ - @backstage/plugin-scaffolder-backend-module-notifications@0.1.20-next.0
+ - @backstage/plugin-search-backend@2.0.13-next.0
+ - @backstage/plugin-search-backend-module-catalog@0.3.13-next.0
+ - @backstage/plugin-search-backend-module-elasticsearch@1.8.1-next.0
+ - @backstage/plugin-search-backend-module-explore@0.3.12-next.0
+ - @backstage/plugin-search-backend-module-techdocs@0.4.12-next.0
+ - @backstage/plugin-search-backend-node@1.4.2-next.0
+ - @backstage/plugin-signals-backend@0.3.13-next.0
+ - @backstage/plugin-techdocs-backend@2.1.6-next.0
+
## 0.0.47
### Patch Changes
diff --git a/packages/backend/package.json b/packages/backend/package.json
index b6b97f214e..fd2c166773 100644
--- a/packages/backend/package.json
+++ b/packages/backend/package.json
@@ -1,6 +1,6 @@
{
"name": "example-backend",
- "version": "0.0.47",
+ "version": "0.0.49-next.1",
"backstage": {
"role": "backend"
},
@@ -41,6 +41,7 @@
"@backstage/plugin-auth-node": "workspace:^",
"@backstage/plugin-catalog-backend": "workspace:^",
"@backstage/plugin-catalog-backend-module-backstage-openapi": "workspace:^",
+ "@backstage/plugin-catalog-backend-module-logs": "workspace:^",
"@backstage/plugin-catalog-backend-module-openapi": "workspace:^",
"@backstage/plugin-catalog-backend-module-scaffolder-entity-model": "workspace:^",
"@backstage/plugin-catalog-backend-module-unprocessed": "workspace:^",
@@ -66,9 +67,9 @@
"@backstage/plugin-search-backend-node": "workspace:^",
"@backstage/plugin-signals-backend": "workspace:^",
"@backstage/plugin-techdocs-backend": "workspace:^",
- "@opentelemetry/auto-instrumentations-node": "^0.67.0",
- "@opentelemetry/exporter-prometheus": "^0.211.0",
- "@opentelemetry/sdk-node": "^0.211.0",
+ "@opentelemetry/auto-instrumentations-node": "^0.71.0",
+ "@opentelemetry/exporter-prometheus": "^0.213.0",
+ "@opentelemetry/sdk-node": "^0.213.0",
"example-app": "link:../app"
},
"devDependencies": {
diff --git a/packages/backend/src/index.ts b/packages/backend/src/index.ts
index 14eb36a3a6..e77c83baac 100644
--- a/packages/backend/src/index.ts
+++ b/packages/backend/src/index.ts
@@ -50,6 +50,7 @@ backend.add(
import('@backstage/plugin-catalog-backend-module-scaffolder-entity-model'),
);
backend.add(import('@backstage/plugin-catalog-backend'));
+backend.add(import('@backstage/plugin-catalog-backend-module-logs'));
backend.add(import('@backstage/plugin-events-backend'));
backend.add(import('@backstage/plugin-devtools-backend'));
backend.add(import('@backstage/plugin-kubernetes-backend'));
diff --git a/packages/catalog-client/CHANGELOG.md b/packages/catalog-client/CHANGELOG.md
index 563a0ef828..874212077b 100644
--- a/packages/catalog-client/CHANGELOG.md
+++ b/packages/catalog-client/CHANGELOG.md
@@ -1,5 +1,62 @@
# @backstage/catalog-client
+## 1.14.0
+
+### Minor Changes
+
+- 972f686: Added support for the `query` field in `getEntitiesByRefs` requests, enabling predicate-based filtering with `$all`, `$any`, `$not`, `$exists`, `$in`, `$contains`, and `$hasPrefix` operators.
+- 5d95e8e: Add an `onConflict` option to location creation that can refresh an existing location instead of throwing a conflict error.
+- 56c908e: Added support for the `query` field in `getEntityFacets` requests, enabling predicate-based filtering with `$all`, `$any`, `$not`, `$exists`, `$in`, `$contains`, and `$hasPrefix` operators.
+- 0fbcf23: Migrated OpenAPI schemas to 3.1.
+- 51e23eb: Added predicate-based entity filtering via POST /entities/by-query endpoint.
+
+ Supports `$all`, `$any`, `$not`, `$exists`, `$in`, `$hasPrefix`, and (partially) `$contains` operators for expressive entity queries. Integrated into the existing `queryEntities` flow with full cursor-based pagination, permission enforcement, and `totalItems` support.
+
+ The catalog client's `queryEntities()` method automatically routes to the POST endpoint when a `query` predicate is provided.
+
+### Patch Changes
+
+- d2494d6: Minor update to catalog client docs
+- Updated dependencies
+ - @backstage/filter-predicates@0.1.1
+ - @backstage/catalog-model@1.7.7
+
+## 1.14.0-next.2
+
+### Minor Changes
+
+- 5d95e8e: Add an `onConflict` option to location creation that can refresh an existing location instead of throwing a conflict error.
+
+## 1.14.0-next.1
+
+### Minor Changes
+
+- 972f686: Added support for the `query` field in `getEntitiesByRefs` requests, enabling predicate-based filtering with `$all`, `$any`, `$not`, `$exists`, `$in`, `$contains`, and `$hasPrefix` operators.
+- 56c908e: Added support for the `query` field in `getEntityFacets` requests, enabling predicate-based filtering with `$all`, `$any`, `$not`, `$exists`, `$in`, `$contains`, and `$hasPrefix` operators.
+- 0fbcf23: Migrated OpenAPI schemas to 3.1.
+- 51e23eb: Added predicate-based entity filtering via POST /entities/by-query endpoint.
+
+ Supports `$all`, `$any`, `$not`, `$exists`, `$in`, `$hasPrefix`, and (partially) `$contains` operators for expressive entity queries. Integrated into the existing `queryEntities` flow with full cursor-based pagination, permission enforcement, and `totalItems` support.
+
+ The catalog client's `queryEntities()` method automatically routes to the POST endpoint when a `query` predicate is provided.
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/catalog-model@1.7.6
+ - @backstage/errors@1.2.7
+ - @backstage/filter-predicates@0.1.0
+
+## 1.13.1-next.0
+
+### Patch Changes
+
+- d2494d6: Minor update to catalog client docs
+- Updated dependencies
+ - @backstage/catalog-model@1.7.6
+ - @backstage/errors@1.2.7
+ - @backstage/filter-predicates@0.1.0
+
## 1.13.0
### Minor Changes
diff --git a/packages/catalog-client/package.json b/packages/catalog-client/package.json
index 1a299182e8..1235f4d5ca 100644
--- a/packages/catalog-client/package.json
+++ b/packages/catalog-client/package.json
@@ -1,6 +1,6 @@
{
"name": "@backstage/catalog-client",
- "version": "1.13.0",
+ "version": "1.14.0",
"description": "An isomorphic client for the catalog backend",
"backstage": {
"role": "common-library"
diff --git a/packages/catalog-client/report.api.md b/packages/catalog-client/report.api.md
index 58fc4bc8a1..73eb280d87 100644
--- a/packages/catalog-client/report.api.md
+++ b/packages/catalog-client/report.api.md
@@ -7,14 +7,15 @@ import type { AnalyzeLocationRequest } from '@backstage/plugin-catalog-common';
import type { AnalyzeLocationResponse } from '@backstage/plugin-catalog-common';
import { CompoundEntityRef } from '@backstage/catalog-model';
import { Entity } from '@backstage/catalog-model';
-import { FilterPredicate } from '@backstage/filter-predicates';
-import { SerializedError } from '@backstage/errors';
+import type { FilterPredicate } from '@backstage/filter-predicates';
+import type { SerializedError } from '@backstage/errors';
// @public
export type AddLocationRequest = {
type?: string;
target: string;
dryRun?: boolean;
+ onConflict?: 'refresh' | 'reject';
};
// @public
@@ -236,6 +237,7 @@ export interface GetEntitiesByRefsRequest {
entityRefs: string[];
fields?: EntityFieldsQuery | undefined;
filter?: EntityFilterQuery;
+ query?: FilterPredicate;
}
// @public
@@ -280,6 +282,7 @@ export interface GetEntityAncestorsResponse {
export interface GetEntityFacetsRequest {
facets: string[];
filter?: EntityFilterQuery;
+ query?: FilterPredicate;
}
// @public
@@ -320,6 +323,7 @@ export type QueryEntitiesInitialRequest = {
limit?: number;
offset?: number;
filter?: EntityFilterQuery;
+ query?: FilterPredicate;
orderFields?: EntityOrderQuery;
fullTextFilter?: {
term: string;
diff --git a/packages/catalog-client/src/CatalogClient.test.ts b/packages/catalog-client/src/CatalogClient.test.ts
index d62323852e..70265bd6cb 100644
--- a/packages/catalog-client/src/CatalogClient.test.ts
+++ b/packages/catalog-client/src/CatalogClient.test.ts
@@ -302,6 +302,103 @@ describe('CatalogClient', () => {
expect(response).toEqual({ items: [entity, undefined] });
});
+
+ it('sends only query predicate in the body when query is provided without filter', async () => {
+ expect.assertions(3);
+ const entity = {
+ apiVersion: '1',
+ kind: 'Component',
+ metadata: {
+ name: 'Test2',
+ namespace: 'test1',
+ },
+ };
+ server.use(
+ rest.post(`${mockBaseUrl}/entities/by-refs`, async (req, res, ctx) => {
+ expect(req.url.search).toBe('');
+ await expect(req.json()).resolves.toEqual({
+ entityRefs: ['k:n/a'],
+ query: { kind: 'Component' },
+ });
+ return res(ctx.json({ items: [entity] }));
+ }),
+ );
+
+ const response = await client.getEntitiesByRefs(
+ {
+ entityRefs: ['k:n/a'],
+ query: { kind: 'Component' },
+ },
+ { token },
+ );
+
+ expect(response).toEqual({ items: [entity] });
+ });
+
+ it('merges filter and query into $all predicate when both are provided', async () => {
+ expect.assertions(4);
+ const entity = {
+ apiVersion: '1',
+ kind: 'Component',
+ metadata: {
+ name: 'Test2',
+ namespace: 'test1',
+ },
+ };
+ server.use(
+ rest.post(`${mockBaseUrl}/entities/by-refs`, async (req, res, ctx) => {
+ expect(req.url.search).toBe('');
+ const body = await req.json();
+ expect(body.entityRefs).toEqual(['k:n/a']);
+ expect(body.query).toEqual({
+ $all: [{ kind: 'Component' }, { kind: 'API' }],
+ });
+ return res(ctx.json({ items: [entity] }));
+ }),
+ );
+
+ const response = await client.getEntitiesByRefs(
+ {
+ entityRefs: ['k:n/a'],
+ query: { kind: 'Component' },
+ filter: { kind: ['API'] },
+ },
+ { token },
+ );
+
+ expect(response).toEqual({ items: [entity] });
+ });
+
+ it('sends filter as query parameter when only filter is provided (backward compat)', async () => {
+ expect.assertions(4);
+ const entity = {
+ apiVersion: '1',
+ kind: 'Component',
+ metadata: {
+ name: 'Test2',
+ namespace: 'test1',
+ },
+ };
+ server.use(
+ rest.post(`${mockBaseUrl}/entities/by-refs`, async (req, res, ctx) => {
+ expect(req.url.search).toBe('?filter=kind%3DAPI');
+ const body = await req.json();
+ expect(body).toEqual({ entityRefs: ['k:n/a'] });
+ expect(body.query).toBeUndefined();
+ return res(ctx.json({ items: [entity] }));
+ }),
+ );
+
+ const response = await client.getEntitiesByRefs(
+ {
+ entityRefs: ['k:n/a'],
+ filter: { kind: ['API'] },
+ },
+ { token },
+ );
+
+ expect(response).toEqual({ items: [entity] });
+ });
});
describe('queryEntities', () => {
@@ -540,6 +637,350 @@ describe('CatalogClient', () => {
});
});
+ describe('queryEntities with predicate-based queries (POST endpoint)', () => {
+ const defaultResponse = {
+ items: [
+ {
+ apiVersion: '1',
+ kind: 'Component',
+ metadata: {
+ name: 'service-1',
+ namespace: 'default',
+ },
+ spec: {
+ type: 'service',
+ owner: 'team-a',
+ },
+ },
+ {
+ apiVersion: '1',
+ kind: 'Component',
+ metadata: {
+ name: 'service-2',
+ namespace: 'default',
+ },
+ spec: {
+ type: 'service',
+ owner: 'team-b',
+ },
+ },
+ ],
+ totalItems: 2,
+ pageInfo: {},
+ };
+
+ it('should use POST endpoint when query is provided', async () => {
+ const mockedEndpoint = jest.fn().mockImplementation((req, res, ctx) => {
+ expect(req.method).toBe('POST');
+ expect(req.body).toMatchObject({
+ query: { kind: 'component' },
+ limit: 20,
+ });
+ return res(ctx.json(defaultResponse));
+ });
+
+ server.use(rest.post(`${mockBaseUrl}/entities/by-query`, mockedEndpoint));
+
+ const response = await client.queryEntities({
+ query: { kind: 'component' },
+ limit: 20,
+ });
+
+ expect(mockedEndpoint).toHaveBeenCalledTimes(1);
+ expect(response.items).toEqual(defaultResponse.items);
+ expect(response.totalItems).toBe(2);
+ });
+
+ it('should support $all operator', async () => {
+ const mockedEndpoint = jest.fn().mockImplementation((req, res, ctx) => {
+ expect(req.body).toMatchObject({
+ query: {
+ $all: [{ kind: 'component' }, { 'spec.type': 'service' }],
+ },
+ });
+ return res(ctx.json(defaultResponse));
+ });
+
+ server.use(rest.post(`${mockBaseUrl}/entities/by-query`, mockedEndpoint));
+
+ await client.queryEntities({
+ query: {
+ $all: [{ kind: 'component' }, { 'spec.type': 'service' }],
+ },
+ });
+
+ expect(mockedEndpoint).toHaveBeenCalledTimes(1);
+ });
+
+ it('should support $any operator', async () => {
+ const mockedEndpoint = jest.fn().mockImplementation((req, res, ctx) => {
+ expect(req.body).toMatchObject({
+ query: {
+ $any: [{ 'spec.type': 'service' }, { 'spec.type': 'website' }],
+ },
+ });
+ return res(ctx.json(defaultResponse));
+ });
+
+ server.use(rest.post(`${mockBaseUrl}/entities/by-query`, mockedEndpoint));
+
+ await client.queryEntities({
+ query: {
+ $any: [{ 'spec.type': 'service' }, { 'spec.type': 'website' }],
+ },
+ });
+
+ expect(mockedEndpoint).toHaveBeenCalledTimes(1);
+ });
+
+ it('should support $not operator', async () => {
+ const mockedEndpoint = jest.fn().mockImplementation((req, res, ctx) => {
+ expect(req.body).toMatchObject({
+ query: {
+ $not: { 'spec.lifecycle': 'experimental' },
+ },
+ });
+ return res(ctx.json(defaultResponse));
+ });
+
+ server.use(rest.post(`${mockBaseUrl}/entities/by-query`, mockedEndpoint));
+
+ await client.queryEntities({
+ query: {
+ $not: { 'spec.lifecycle': 'experimental' },
+ },
+ });
+
+ expect(mockedEndpoint).toHaveBeenCalledTimes(1);
+ });
+
+ it('should support $exists operator', async () => {
+ const mockedEndpoint = jest.fn().mockImplementation((req, res, ctx) => {
+ expect(req.body).toMatchObject({
+ query: {
+ 'spec.owner': { $exists: true },
+ },
+ });
+ return res(ctx.json(defaultResponse));
+ });
+
+ server.use(rest.post(`${mockBaseUrl}/entities/by-query`, mockedEndpoint));
+
+ await client.queryEntities({
+ query: {
+ 'spec.owner': { $exists: true },
+ },
+ });
+
+ expect(mockedEndpoint).toHaveBeenCalledTimes(1);
+ });
+
+ it('should support $in operator', async () => {
+ const mockedEndpoint = jest.fn().mockImplementation((req, res, ctx) => {
+ expect(req.body).toMatchObject({
+ query: {
+ 'spec.owner': { $in: ['team-a', 'team-b', 'team-c'] },
+ },
+ });
+ return res(ctx.json(defaultResponse));
+ });
+
+ server.use(rest.post(`${mockBaseUrl}/entities/by-query`, mockedEndpoint));
+
+ await client.queryEntities({
+ query: {
+ 'spec.owner': { $in: ['team-a', 'team-b', 'team-c'] },
+ },
+ });
+
+ expect(mockedEndpoint).toHaveBeenCalledTimes(1);
+ });
+
+ it('should support complex nested predicates', async () => {
+ const mockedEndpoint = jest.fn().mockImplementation((req, res, ctx) => {
+ expect(req.body).toMatchObject({
+ query: {
+ $all: [
+ { kind: 'component' },
+ {
+ $any: [{ 'spec.type': 'service' }, { 'spec.type': 'website' }],
+ },
+ {
+ $not: {
+ 'spec.lifecycle': 'experimental',
+ },
+ },
+ ],
+ },
+ });
+ return res(ctx.json(defaultResponse));
+ });
+
+ server.use(rest.post(`${mockBaseUrl}/entities/by-query`, mockedEndpoint));
+
+ await client.queryEntities({
+ query: {
+ $all: [
+ { kind: 'component' },
+ {
+ $any: [{ 'spec.type': 'service' }, { 'spec.type': 'website' }],
+ },
+ {
+ $not: {
+ 'spec.lifecycle': 'experimental',
+ },
+ },
+ ],
+ },
+ });
+
+ expect(mockedEndpoint).toHaveBeenCalledTimes(1);
+ });
+
+ it('should send orderFields with correct format', async () => {
+ const mockedEndpoint = jest.fn().mockImplementation((req, res, ctx) => {
+ expect(req.body.orderBy).toEqual([
+ { field: 'metadata.name', order: 'asc' },
+ ]);
+ return res(ctx.json(defaultResponse));
+ });
+
+ server.use(rest.post(`${mockBaseUrl}/entities/by-query`, mockedEndpoint));
+
+ await client.queryEntities({
+ query: { kind: 'component' },
+ orderFields: { field: 'metadata.name', order: 'asc' },
+ });
+
+ expect(mockedEndpoint).toHaveBeenCalledTimes(1);
+ });
+
+ it('should send multiple orderFields with correct format', async () => {
+ const mockedEndpoint = jest.fn().mockImplementation((req, res, ctx) => {
+ expect(req.body.orderBy).toEqual([
+ { field: 'metadata.name', order: 'asc' },
+ { field: 'spec.type', order: 'desc' },
+ ]);
+ return res(ctx.json(defaultResponse));
+ });
+
+ server.use(rest.post(`${mockBaseUrl}/entities/by-query`, mockedEndpoint));
+
+ await client.queryEntities({
+ query: { kind: 'component' },
+ orderFields: [
+ { field: 'metadata.name', order: 'asc' },
+ { field: 'spec.type', order: 'desc' },
+ ],
+ });
+
+ expect(mockedEndpoint).toHaveBeenCalledTimes(1);
+ });
+
+ it('should send limit and offset parameters in the body', async () => {
+ const mockedEndpoint = jest.fn().mockImplementation((req, res, ctx) => {
+ expect(req.body.limit).toBe(50);
+ return res(ctx.json(defaultResponse));
+ });
+
+ server.use(rest.post(`${mockBaseUrl}/entities/by-query`, mockedEndpoint));
+
+ await client.queryEntities({
+ query: { kind: 'component' },
+ limit: 50,
+ });
+
+ expect(mockedEndpoint).toHaveBeenCalledTimes(1);
+ });
+
+ it('should paginate using POST when cursor contains a query', async () => {
+ // Simulate a cursor that contains a query predicate (as the server would encode it)
+ const cursorPayload = Buffer.from(
+ JSON.stringify({
+ orderFields: [],
+ orderFieldValues: [],
+ isPrevious: false,
+ query: { kind: 'component' },
+ totalItems: 100,
+ }),
+ ).toString('base64');
+
+ const page2Response = {
+ items: [
+ {
+ apiVersion: '1',
+ kind: 'Component',
+ metadata: { name: 'service-3', namespace: 'default' },
+ },
+ ],
+ totalItems: 100,
+ pageInfo: {},
+ };
+
+ const mockedEndpoint = jest.fn().mockImplementation((req, res, ctx) => {
+ expect(req.method).toBe('POST');
+ expect(req.body).toMatchObject({ cursor: cursorPayload });
+ return res(ctx.json(page2Response));
+ });
+
+ server.use(rest.post(`${mockBaseUrl}/entities/by-query`, mockedEndpoint));
+
+ const response = await client.queryEntities({
+ cursor: cursorPayload,
+ });
+
+ expect(mockedEndpoint).toHaveBeenCalledTimes(1);
+ expect(response.items).toEqual(page2Response.items);
+ expect(response.totalItems).toBe(100);
+ });
+
+ it('should use GET endpoint for cursor without query', async () => {
+ // A cursor that does NOT contain a query field should go to GET
+ const cursorPayload = Buffer.from(
+ JSON.stringify({
+ orderFields: [],
+ orderFieldValues: [],
+ isPrevious: false,
+ totalItems: 50,
+ }),
+ ).toString('base64');
+
+ const mockedGetEndpoint = jest.fn().mockImplementation((_req, res, ctx) =>
+ res(
+ ctx.json({
+ items: [],
+ totalItems: 50,
+ pageInfo: {},
+ }),
+ ),
+ );
+
+ const mockedPostEndpoint = jest.fn();
+
+ server.use(
+ rest.get(`${mockBaseUrl}/entities/by-query`, mockedGetEndpoint),
+ rest.post(`${mockBaseUrl}/entities/by-query`, mockedPostEndpoint),
+ );
+
+ await client.queryEntities({ cursor: cursorPayload });
+
+ expect(mockedGetEndpoint).toHaveBeenCalledTimes(1);
+ expect(mockedPostEndpoint).not.toHaveBeenCalled();
+ });
+
+ it('should handle errors from POST endpoint', async () => {
+ const mockedEndpoint = jest
+ .fn()
+ .mockImplementation((_req, res, ctx) => res(ctx.status(400)));
+
+ server.use(rest.post(`${mockBaseUrl}/entities/by-query`, mockedEndpoint));
+
+ await expect(() =>
+ client.queryEntities({ query: { kind: 'component' } }),
+ ).rejects.toThrow(/Request failed with 400/);
+ });
+ });
+
describe('streamEntities', () => {
const defaultResponse: QueryEntitiesResponse = {
items: [
diff --git a/packages/catalog-client/src/CatalogClient.ts b/packages/catalog-client/src/CatalogClient.ts
index b45bef8bbd..cf363e1823 100644
--- a/packages/catalog-client/src/CatalogClient.ts
+++ b/packages/catalog-client/src/CatalogClient.ts
@@ -20,7 +20,8 @@ import {
parseEntityRef,
stringifyLocationRef,
} from '@backstage/catalog-model';
-import { ResponseError } from '@backstage/errors';
+import { InputError, ResponseError } from '@backstage/errors';
+import { FilterPredicate } from '@backstage/filter-predicates';
import {
AddLocationRequest,
AddLocationResponse,
@@ -46,10 +47,17 @@ import {
StreamEntitiesRequest,
ValidateEntityResponse,
} from './types/api';
-import { isQueryEntitiesInitialRequest, splitRefsIntoChunks } from './utils';
+import {
+ convertFilterToPredicate,
+ isQueryEntitiesInitialRequest,
+ splitRefsIntoChunks,
+ cursorContainsQuery,
+} from './utils';
import {
DefaultApiClient,
+ GetEntitiesByQuery,
GetLocationsByQueryRequest,
+ QueryEntitiesByPredicateRequest,
TypedResponse,
} from './schema/openapi';
import type {
@@ -229,11 +237,36 @@ export class CatalogClient implements CatalogApi {
request: GetEntitiesByRefsRequest,
options?: CatalogRequestOptions,
): Promise {
+ const { filter, query } = request;
+
+ // Only convert and merge if both filter and query are provided, or if
+ // query alone is provided. When only filter is given, preserve the old
+ // query-parameter behavior for backward compatibility.
+ let filterPredicate: FilterPredicate | undefined;
+ if (query !== undefined) {
+ if (typeof query !== 'object' || query === null || Array.isArray(query)) {
+ throw new InputError('Query must be an object');
+ }
+ filterPredicate = query;
+ if (filter !== undefined) {
+ const converted = convertFilterToPredicate(filter);
+ filterPredicate = { $all: [filterPredicate, converted] };
+ }
+ }
+
const getOneChunk = async (refs: string[]) => {
const response = await this.apiClient.getEntitiesByRefs(
{
- body: { entityRefs: refs, fields: request.fields },
- query: { filter: this.getFilterValue(request.filter) },
+ body: {
+ entityRefs: refs,
+ fields: request.fields,
+ ...(filterPredicate && {
+ query: filterPredicate as unknown as { [key: string]: any },
+ }),
+ },
+ query: filterPredicate
+ ? {}
+ : { filter: this.getFilterValue(request.filter) },
},
options,
);
@@ -266,11 +299,26 @@ export class CatalogClient implements CatalogApi {
request: QueryEntitiesRequest = {},
options?: CatalogRequestOptions,
): Promise {
- const params: Partial<
- Parameters[0]['query']
- > = {};
+ const isInitialRequest = isQueryEntitiesInitialRequest(request);
- if (isQueryEntitiesInitialRequest(request)) {
+ // Route to POST endpoint if query predicate is provided (initial request)
+ if (isInitialRequest && request.query) {
+ return this.queryEntitiesByPredicate(request, options);
+ }
+
+ // Route to POST endpoint if cursor contains a query predicate (pagination)
+ // TODO(freben): It's costly and non-opaque to have to introspect the cursor
+ // like this. It should be refactored in the future to not need this.
+ // Suggestion: make the GET and POST endpoints understand the same cursor
+ // format, and pick which one to call ONLY based on whether the cursor size
+ // risks hitting url length limits
+ if (!isInitialRequest && cursorContainsQuery(request.cursor)) {
+ return this.queryEntitiesByPredicate(request, options);
+ }
+
+ const params: Partial = {};
+
+ if (isInitialRequest) {
const {
fields = [],
filter,
@@ -320,6 +368,84 @@ export class CatalogClient implements CatalogApi {
);
}
+ /**
+ * Query entities using predicate-based filters (POST endpoint).
+ * @internal
+ */
+ private async queryEntitiesByPredicate(
+ request: QueryEntitiesRequest,
+ options?: CatalogRequestOptions,
+ ): Promise {
+ const body: QueryEntitiesByPredicateRequest = {};
+
+ if (isQueryEntitiesInitialRequest(request)) {
+ const {
+ filter,
+ query,
+ limit,
+ offset,
+ orderFields,
+ fullTextFilter,
+ fields,
+ } = request;
+
+ let filterPredicate: FilterPredicate | undefined;
+ if (query !== undefined) {
+ if (
+ typeof query !== 'object' ||
+ query === null ||
+ Array.isArray(query)
+ ) {
+ throw new InputError('Query must be an object');
+ }
+ filterPredicate = query;
+ }
+ if (filter !== undefined) {
+ const converted = convertFilterToPredicate(filter);
+ filterPredicate = filterPredicate
+ ? { $all: [filterPredicate, converted] }
+ : converted;
+ }
+ if (filterPredicate !== undefined) {
+ body.query = filterPredicate as unknown as { [key: string]: any };
+ }
+
+ if (limit !== undefined) {
+ body.limit = limit;
+ }
+ if (offset !== undefined) {
+ body.offset = offset;
+ }
+ if (orderFields !== undefined) {
+ body.orderBy = [orderFields].flat();
+ }
+ if (fullTextFilter) {
+ body.fullTextFilter = fullTextFilter;
+ }
+ if (fields?.length) {
+ body.fields = fields;
+ }
+ } else {
+ body.cursor = request.cursor;
+ if (request.limit !== undefined) {
+ body.limit = request.limit;
+ }
+ if (request.fields?.length) {
+ body.fields = request.fields;
+ }
+ }
+
+ const res = await this.requestRequired(
+ await this.apiClient.queryEntitiesByPredicate({ body }, options),
+ );
+
+ return {
+ items: res.items,
+ totalItems: res.totalItems,
+ pageInfo: res.pageInfo,
+ };
+ }
+
/**
* {@inheritdoc CatalogApi.getEntityByRef}
*/
@@ -378,7 +504,13 @@ export class CatalogClient implements CatalogApi {
request: GetEntityFacetsRequest,
options?: CatalogRequestOptions,
): Promise {
- const { filter = [], facets } = request;
+ const { filter = [], query, facets } = request;
+
+ // Route to POST endpoint if query predicate is provided
+ if (query) {
+ return this.getEntityFacetsByPredicate(request, options);
+ }
+
return await this.requestOptional(
await this.apiClient.getEntityFacets(
{
@@ -389,6 +521,45 @@ export class CatalogClient implements CatalogApi {
);
}
+ /**
+ * Get entity facets using predicate-based filters (POST endpoint).
+ * @internal
+ */
+ private async getEntityFacetsByPredicate(
+ request: GetEntityFacetsRequest,
+ options?: CatalogRequestOptions,
+ ): Promise {
+ const { filter, query, facets } = request;
+
+ let filterPredicate: FilterPredicate | undefined;
+ if (query !== undefined) {
+ if (typeof query !== 'object' || query === null || Array.isArray(query)) {
+ throw new InputError('Query must be an object');
+ }
+ filterPredicate = query;
+ }
+ if (filter !== undefined) {
+ const converted = convertFilterToPredicate(filter);
+ filterPredicate = filterPredicate
+ ? { $all: [filterPredicate, converted] }
+ : converted;
+ }
+
+ return await this.requestOptional(
+ await this.apiClient.queryEntityFacetsByPredicate(
+ {
+ body: {
+ facets,
+ ...(filterPredicate && {
+ query: filterPredicate as unknown as { [key: string]: any },
+ }),
+ },
+ },
+ options,
+ ),
+ );
+ }
+
/**
* {@inheritdoc CatalogApi.addLocation}
*/
@@ -396,12 +567,15 @@ export class CatalogClient implements CatalogApi {
request: AddLocationRequest,
options?: CatalogRequestOptions,
): Promise {
- const { type = 'url', target, dryRun } = request;
+ const { type = 'url', target, dryRun, onConflict } = request;
const response = await this.apiClient.createLocation(
{
body: { type, target },
- query: { dryRun: dryRun ? 'true' : undefined },
+ query: {
+ dryRun: dryRun ? 'true' : undefined,
+ onConflict,
+ },
},
options,
);
diff --git a/packages/catalog-client/src/schema/openapi/generated/apis/Api.client.ts b/packages/catalog-client/src/schema/openapi/generated/apis/Api.client.ts
index 4530cd795c..4b3e088fe2 100644
--- a/packages/catalog-client/src/schema/openapi/generated/apis/Api.client.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/apis/Api.client.ts
@@ -29,6 +29,8 @@ import { Entity } from '../models/Entity.model';
import { EntityAncestryResponse } from '../models/EntityAncestryResponse.model';
import { EntityFacetsResponse } from '../models/EntityFacetsResponse.model';
import { GetEntitiesByRefsRequest } from '../models/GetEntitiesByRefsRequest.model';
+import { QueryEntitiesByPredicateRequest } from '../models/QueryEntitiesByPredicateRequest.model';
+import { QueryEntityFacetsByPredicateRequest } from '../models/QueryEntityFacetsByPredicateRequest.model';
import { RefreshEntityRequest } from '../models/RefreshEntityRequest.model';
import { ValidateEntityRequest } from '../models/ValidateEntityRequest.model';
import { AnalyzeLocationRequest } from '../models/AnalyzeLocationRequest.model';
@@ -139,6 +141,18 @@ export type GetEntityFacets = {
filter?: Array;
};
};
+/**
+ * @public
+ */
+export type QueryEntitiesByPredicate = {
+ body: QueryEntitiesByPredicateRequest;
+};
+/**
+ * @public
+ */
+export type QueryEntityFacetsByPredicate = {
+ body: QueryEntityFacetsByPredicateRequest;
+};
/**
* @public
*/
@@ -164,6 +178,7 @@ export type CreateLocation = {
body: CreateLocationRequest;
query: {
dryRun?: string;
+ onConflict?: 'refresh' | 'reject';
};
};
/**
@@ -246,9 +261,9 @@ export class DefaultApiClient {
/**
* Get all entities matching a given filter.
- * @param fields - By default the full entities are returned, but you can pass in a `fields` query parameter which selects what parts of the entity data to retain. This makes the response smaller and faster to transfer, and may allow the catalog to perform more efficient queries. The query parameter value is a comma separated list of simplified JSON paths like above. Each path corresponds to the key of either a value, or of a subtree root that you want to keep in the output. The rest is pruned away. For example, specifying `?fields=metadata.name,metadata.annotations,spec` retains only the `name` and `annotations` fields of the `metadata` of each entity (it'll be an object with at most two keys), keeps the entire `spec` unchanged, and cuts out all other roots such as `relations`. Some more real world usable examples: - Return only enough data to form the full ref of each entity: `/entities/by-query?fields=kind,metadata.namespace,metadata.name`
+ * @param fields - By default the full entities are returned, but you can pass in a `fields` query parameter which selects what parts of the entity data to retain. This makes the response smaller and faster to transfer, and may allow the catalog to perform more efficient queries. The query parameter value is a comma separated list of simplified JSON paths like above. Each path corresponds to the key of either a value, or of a subtree root that you want to keep in the output. The rest is pruned away. For example, specifying `?fields=metadata.name,metadata.annotations,spec` retains only the `name` and `annotations` fields of the `metadata` of each entity (it\'ll be an object with at most two keys), keeps the entire `spec` unchanged, and cuts out all other roots such as `relations`. Some more real world usable examples: - Return only enough data to form the full ref of each entity: `/entities/by-query?fields=kind,metadata.namespace,metadata.name`
* @param limit - Number of records to return in the response.
- * @param filter - You can pass in one or more filter sets that get matched against each entity. Each filter set is a number of conditions that all have to match for the condition to be true (conditions effectively have an AND between them). At least one filter set has to be true for the entity to be part of the result set (filter sets effectively have an OR between them). Example: ```text /entities/by-query?filter=kind=user,metadata.namespace=default&filter=kind=group,spec.type Return entities that match Filter set 1: Condition 1: kind = user AND Condition 2: metadata.namespace = default OR Filter set 2: Condition 1: kind = group AND Condition 2: spec.type exists ``` Each condition is either on the form `<key>`, or on the form `<key>=<value>`. The first form asserts on the existence of a certain key (with any value), and the second asserts that the key exists and has a certain value. All checks are always case _insensitive_. In all cases, the key is a simplified JSON path in a given piece of entity data. Each part of the path is a key of an object, and the traversal also descends through arrays. There are two special forms: - Array items that are simple value types (such as strings) match on a key-value pair where the key is the item as a string, and the value is the string `true` - Relations can be matched on a `relations.<type>=<targetRef>` form Let's look at a simplified example to illustrate the concept: ```json { \"a\": { \"b\": [\"c\", { \"d\": 1 }], \"e\": 7 } } ``` This would match any one of the following conditions: - `a` - `a.b` - `a.b.c` - `a.b.c=true` - `a.b.d` - `a.b.d=1` - `a.e` - `a.e=7` Some more real world usable examples: - Return all orphaned entities: `/entities/by-query?filter=metadata.annotations.backstage.io/orphan=true` - Return all users and groups: `/entities/by-query?filter=kind=user&filter=kind=group` - Return all service components: `/entities/by-query?filter=kind=component,spec.type=service` - Return all entities with the `java` tag: `/entities/by-query?filter=metadata.tags.java` - Return all users who are members of the `ops` group (note that the full [reference](references.md) of the group is used): `/entities/by-query?filter=kind=user,relations.memberof=group:default/ops`
+ * @param filter - You can pass in one or more filter sets that get matched against each entity. Each filter set is a number of conditions that all have to match for the condition to be true (conditions effectively have an AND between them). At least one filter set has to be true for the entity to be part of the result set (filter sets effectively have an OR between them). Example: ```text /entities/by-query?filter=kind=user,metadata.namespace=default&filter=kind=group,spec.type Return entities that match Filter set 1: Condition 1: kind = user AND Condition 2: metadata.namespace = default OR Filter set 2: Condition 1: kind = group AND Condition 2: spec.type exists ``` Each condition is either on the form `<key>`, or on the form `<key>=<value>`. The first form asserts on the existence of a certain key (with any value), and the second asserts that the key exists and has a certain value. All checks are always case _insensitive_. In all cases, the key is a simplified JSON path in a given piece of entity data. Each part of the path is a key of an object, and the traversal also descends through arrays. There are two special forms: - Array items that are simple value types (such as strings) match on a key-value pair where the key is the item as a string, and the value is the string `true` - Relations can be matched on a `relations.<type>=<targetRef>` form Let\'s look at a simplified example to illustrate the concept: ```json { \"a\": { \"b\": [\"c\", { \"d\": 1 }], \"e\": 7 } } ``` This would match any one of the following conditions: - `a` - `a.b` - `a.b.c` - `a.b.c=true` - `a.b.d` - `a.b.d=1` - `a.e` - `a.e=7` Some more real world usable examples: - Return all orphaned entities: `/entities/by-query?filter=metadata.annotations.backstage.io/orphan=true` - Return all users and groups: `/entities/by-query?filter=kind=user&filter=kind=group` - Return all service components: `/entities/by-query?filter=kind=component,spec.type=service` - Return all entities with the `java` tag: `/entities/by-query?filter=metadata.tags.java` - Return all users who are members of the `ops` group (note that the full [reference](references.md) of the group is used): `/entities/by-query?filter=kind=user,relations.memberof=group:default/ops`
* @param offset - Number of records to skip in the query page.
* @param after - Pointer to the previous page of results.
* @param order -
@@ -277,12 +292,12 @@ export class DefaultApiClient {
/**
* Search for entities by a given query.
- * @param fields - By default the full entities are returned, but you can pass in a `fields` query parameter which selects what parts of the entity data to retain. This makes the response smaller and faster to transfer, and may allow the catalog to perform more efficient queries. The query parameter value is a comma separated list of simplified JSON paths like above. Each path corresponds to the key of either a value, or of a subtree root that you want to keep in the output. The rest is pruned away. For example, specifying `?fields=metadata.name,metadata.annotations,spec` retains only the `name` and `annotations` fields of the `metadata` of each entity (it'll be an object with at most two keys), keeps the entire `spec` unchanged, and cuts out all other roots such as `relations`. Some more real world usable examples: - Return only enough data to form the full ref of each entity: `/entities/by-query?fields=kind,metadata.namespace,metadata.name`
+ * @param fields - By default the full entities are returned, but you can pass in a `fields` query parameter which selects what parts of the entity data to retain. This makes the response smaller and faster to transfer, and may allow the catalog to perform more efficient queries. The query parameter value is a comma separated list of simplified JSON paths like above. Each path corresponds to the key of either a value, or of a subtree root that you want to keep in the output. The rest is pruned away. For example, specifying `?fields=metadata.name,metadata.annotations,spec` retains only the `name` and `annotations` fields of the `metadata` of each entity (it\'ll be an object with at most two keys), keeps the entire `spec` unchanged, and cuts out all other roots such as `relations`. Some more real world usable examples: - Return only enough data to form the full ref of each entity: `/entities/by-query?fields=kind,metadata.namespace,metadata.name`
* @param limit - Number of records to return in the response.
* @param offset - Number of records to skip in the query page.
* @param orderField - By default the entities are returned ordered by their internal uid. You can customize the `orderField` query parameters to affect that ordering. For example, to return entities by their name: `/entities/by-query?orderField=metadata.name,asc` Each parameter can be followed by `asc` for ascending lexicographical order or `desc` for descending (reverse) lexicographical order.
- * @param cursor - You may pass the `cursor` query parameters to perform cursor based pagination through the set of entities. The value of `cursor` will be returned in the response, under the `pageInfo` property: ```json \"pageInfo\": { \"nextCursor\": \"a-cursor\", \"prevCursor\": \"another-cursor\" } ``` If `nextCursor` exists, it can be used to retrieve the next batch of entities. Following the same approach, if `prevCursor` exists, it can be used to retrieve the previous batch of entities. - [`filter`](#filtering), for selecting only a subset of all entities - [`fields`](#field-selection), for selecting only parts of the full data structure of each entity - `limit` for limiting the number of entities returned (20 is the default) - [`orderField`](#ordering), for deciding the order of the entities - `fullTextFilter` **NOTE**: [`filter`, `orderField`, `fullTextFilter`] and `cursor` are mutually exclusive. This means that, it isn't possible to change any of [`filter`, `orderField`, `fullTextFilter`] when passing `cursor` as query parameters, as changing any of these properties will affect pagination. If any of `filter`, `orderField`, `fullTextFilter` is specified together with `cursor`, only the latter is taken into consideration.
- * @param filter - You can pass in one or more filter sets that get matched against each entity. Each filter set is a number of conditions that all have to match for the condition to be true (conditions effectively have an AND between them). At least one filter set has to be true for the entity to be part of the result set (filter sets effectively have an OR between them). Example: ```text /entities/by-query?filter=kind=user,metadata.namespace=default&filter=kind=group,spec.type Return entities that match Filter set 1: Condition 1: kind = user AND Condition 2: metadata.namespace = default OR Filter set 2: Condition 1: kind = group AND Condition 2: spec.type exists ``` Each condition is either on the form `<key>`, or on the form `<key>=<value>`. The first form asserts on the existence of a certain key (with any value), and the second asserts that the key exists and has a certain value. All checks are always case _insensitive_. In all cases, the key is a simplified JSON path in a given piece of entity data. Each part of the path is a key of an object, and the traversal also descends through arrays. There are two special forms: - Array items that are simple value types (such as strings) match on a key-value pair where the key is the item as a string, and the value is the string `true` - Relations can be matched on a `relations.<type>=<targetRef>` form Let's look at a simplified example to illustrate the concept: ```json { \"a\": { \"b\": [\"c\", { \"d\": 1 }], \"e\": 7 } } ``` This would match any one of the following conditions: - `a` - `a.b` - `a.b.c` - `a.b.c=true` - `a.b.d` - `a.b.d=1` - `a.e` - `a.e=7` Some more real world usable examples: - Return all orphaned entities: `/entities/by-query?filter=metadata.annotations.backstage.io/orphan=true` - Return all users and groups: `/entities/by-query?filter=kind=user&filter=kind=group` - Return all service components: `/entities/by-query?filter=kind=component,spec.type=service` - Return all entities with the `java` tag: `/entities/by-query?filter=metadata.tags.java` - Return all users who are members of the `ops` group (note that the full [reference](references.md) of the group is used): `/entities/by-query?filter=kind=user,relations.memberof=group:default/ops`
+ * @param cursor - You may pass the `cursor` query parameters to perform cursor based pagination through the set of entities. The value of `cursor` will be returned in the response, under the `pageInfo` property: ```json \"pageInfo\": { \"nextCursor\": \"a-cursor\", \"prevCursor\": \"another-cursor\" } ``` If `nextCursor` exists, it can be used to retrieve the next batch of entities. Following the same approach, if `prevCursor` exists, it can be used to retrieve the previous batch of entities. - [`filter`](#filtering), for selecting only a subset of all entities - [`fields`](#field-selection), for selecting only parts of the full data structure of each entity - `limit` for limiting the number of entities returned (20 is the default) - [`orderField`](#ordering), for deciding the order of the entities - `fullTextFilter` **NOTE**: [`filter`, `orderField`, `fullTextFilter`] and `cursor` are mutually exclusive. This means that, it isn\'t possible to change any of [`filter`, `orderField`, `fullTextFilter`] when passing `cursor` as query parameters, as changing any of these properties will affect pagination. If any of `filter`, `orderField`, `fullTextFilter` is specified together with `cursor`, only the latter is taken into consideration.
+ * @param filter - You can pass in one or more filter sets that get matched against each entity. Each filter set is a number of conditions that all have to match for the condition to be true (conditions effectively have an AND between them). At least one filter set has to be true for the entity to be part of the result set (filter sets effectively have an OR between them). Example: ```text /entities/by-query?filter=kind=user,metadata.namespace=default&filter=kind=group,spec.type Return entities that match Filter set 1: Condition 1: kind = user AND Condition 2: metadata.namespace = default OR Filter set 2: Condition 1: kind = group AND Condition 2: spec.type exists ``` Each condition is either on the form `<key>`, or on the form `<key>=<value>`. The first form asserts on the existence of a certain key (with any value), and the second asserts that the key exists and has a certain value. All checks are always case _insensitive_. In all cases, the key is a simplified JSON path in a given piece of entity data. Each part of the path is a key of an object, and the traversal also descends through arrays. There are two special forms: - Array items that are simple value types (such as strings) match on a key-value pair where the key is the item as a string, and the value is the string `true` - Relations can be matched on a `relations.<type>=<targetRef>` form Let\'s look at a simplified example to illustrate the concept: ```json { \"a\": { \"b\": [\"c\", { \"d\": 1 }], \"e\": 7 } } ``` This would match any one of the following conditions: - `a` - `a.b` - `a.b.c` - `a.b.c=true` - `a.b.d` - `a.b.d=1` - `a.e` - `a.e=7` Some more real world usable examples: - Return all orphaned entities: `/entities/by-query?filter=metadata.annotations.backstage.io/orphan=true` - Return all users and groups: `/entities/by-query?filter=kind=user&filter=kind=group` - Return all service components: `/entities/by-query?filter=kind=component,spec.type=service` - Return all entities with the `java` tag: `/entities/by-query?filter=metadata.tags.java` - Return all users who are members of the `ops` group (note that the full [reference](references.md) of the group is used): `/entities/by-query?filter=kind=user,relations.memberof=group:default/ops`
* @param fullTextFilterTerm - Text search term.
* @param fullTextFilterFields - A comma separated list of fields to sort returned results by.
*/
@@ -310,7 +325,7 @@ export class DefaultApiClient {
/**
* Get a batch set of entities given an array of entityRefs.
- * @param filter - You can pass in one or more filter sets that get matched against each entity. Each filter set is a number of conditions that all have to match for the condition to be true (conditions effectively have an AND between them). At least one filter set has to be true for the entity to be part of the result set (filter sets effectively have an OR between them). Example: ```text /entities/by-query?filter=kind=user,metadata.namespace=default&filter=kind=group,spec.type Return entities that match Filter set 1: Condition 1: kind = user AND Condition 2: metadata.namespace = default OR Filter set 2: Condition 1: kind = group AND Condition 2: spec.type exists ``` Each condition is either on the form `<key>`, or on the form `<key>=<value>`. The first form asserts on the existence of a certain key (with any value), and the second asserts that the key exists and has a certain value. All checks are always case _insensitive_. In all cases, the key is a simplified JSON path in a given piece of entity data. Each part of the path is a key of an object, and the traversal also descends through arrays. There are two special forms: - Array items that are simple value types (such as strings) match on a key-value pair where the key is the item as a string, and the value is the string `true` - Relations can be matched on a `relations.<type>=<targetRef>` form Let's look at a simplified example to illustrate the concept: ```json { \"a\": { \"b\": [\"c\", { \"d\": 1 }], \"e\": 7 } } ``` This would match any one of the following conditions: - `a` - `a.b` - `a.b.c` - `a.b.c=true` - `a.b.d` - `a.b.d=1` - `a.e` - `a.e=7` Some more real world usable examples: - Return all orphaned entities: `/entities/by-query?filter=metadata.annotations.backstage.io/orphan=true` - Return all users and groups: `/entities/by-query?filter=kind=user&filter=kind=group` - Return all service components: `/entities/by-query?filter=kind=component,spec.type=service` - Return all entities with the `java` tag: `/entities/by-query?filter=metadata.tags.java` - Return all users who are members of the `ops` group (note that the full [reference](references.md) of the group is used): `/entities/by-query?filter=kind=user,relations.memberof=group:default/ops`
+ * @param filter - You can pass in one or more filter sets that get matched against each entity. Each filter set is a number of conditions that all have to match for the condition to be true (conditions effectively have an AND between them). At least one filter set has to be true for the entity to be part of the result set (filter sets effectively have an OR between them). Example: ```text /entities/by-query?filter=kind=user,metadata.namespace=default&filter=kind=group,spec.type Return entities that match Filter set 1: Condition 1: kind = user AND Condition 2: metadata.namespace = default OR Filter set 2: Condition 1: kind = group AND Condition 2: spec.type exists ``` Each condition is either on the form `<key>`, or on the form `<key>=<value>`. The first form asserts on the existence of a certain key (with any value), and the second asserts that the key exists and has a certain value. All checks are always case _insensitive_. In all cases, the key is a simplified JSON path in a given piece of entity data. Each part of the path is a key of an object, and the traversal also descends through arrays. There are two special forms: - Array items that are simple value types (such as strings) match on a key-value pair where the key is the item as a string, and the value is the string `true` - Relations can be matched on a `relations.<type>=<targetRef>` form Let\'s look at a simplified example to illustrate the concept: ```json { \"a\": { \"b\": [\"c\", { \"d\": 1 }], \"e\": 7 } } ``` This would match any one of the following conditions: - `a` - `a.b` - `a.b.c` - `a.b.c=true` - `a.b.d` - `a.b.d=1` - `a.e` - `a.e=7` Some more real world usable examples: - Return all orphaned entities: `/entities/by-query?filter=metadata.annotations.backstage.io/orphan=true` - Return all users and groups: `/entities/by-query?filter=kind=user&filter=kind=group` - Return all service components: `/entities/by-query?filter=kind=component,spec.type=service` - Return all entities with the `java` tag: `/entities/by-query?filter=metadata.tags.java` - Return all users who are members of the `ops` group (note that the full [reference](references.md) of the group is used): `/entities/by-query?filter=kind=user,relations.memberof=group:default/ops`
* @param getEntitiesByRefsRequest -
*/
public async getEntitiesByRefs(
@@ -337,7 +352,7 @@ export class DefaultApiClient {
}
/**
- * Get an entity's ancestry by entity ref.
+ * Get an entity\'s ancestry by entity ref.
* @param kind -
* @param namespace -
* @param name -
@@ -425,7 +440,7 @@ export class DefaultApiClient {
/**
* Get all entity facets that match the given filters.
* @param facet -
- * @param filter - You can pass in one or more filter sets that get matched against each entity. Each filter set is a number of conditions that all have to match for the condition to be true (conditions effectively have an AND between them). At least one filter set has to be true for the entity to be part of the result set (filter sets effectively have an OR between them). Example: ```text /entities/by-query?filter=kind=user,metadata.namespace=default&filter=kind=group,spec.type Return entities that match Filter set 1: Condition 1: kind = user AND Condition 2: metadata.namespace = default OR Filter set 2: Condition 1: kind = group AND Condition 2: spec.type exists ``` Each condition is either on the form `<key>`, or on the form `<key>=<value>`. The first form asserts on the existence of a certain key (with any value), and the second asserts that the key exists and has a certain value. All checks are always case _insensitive_. In all cases, the key is a simplified JSON path in a given piece of entity data. Each part of the path is a key of an object, and the traversal also descends through arrays. There are two special forms: - Array items that are simple value types (such as strings) match on a key-value pair where the key is the item as a string, and the value is the string `true` - Relations can be matched on a `relations.<type>=<targetRef>` form Let's look at a simplified example to illustrate the concept: ```json { \"a\": { \"b\": [\"c\", { \"d\": 1 }], \"e\": 7 } } ``` This would match any one of the following conditions: - `a` - `a.b` - `a.b.c` - `a.b.c=true` - `a.b.d` - `a.b.d=1` - `a.e` - `a.e=7` Some more real world usable examples: - Return all orphaned entities: `/entities/by-query?filter=metadata.annotations.backstage.io/orphan=true` - Return all users and groups: `/entities/by-query?filter=kind=user&filter=kind=group` - Return all service components: `/entities/by-query?filter=kind=component,spec.type=service` - Return all entities with the `java` tag: `/entities/by-query?filter=metadata.tags.java` - Return all users who are members of the `ops` group (note that the full [reference](references.md) of the group is used): `/entities/by-query?filter=kind=user,relations.memberof=group:default/ops`
+ * @param filter - You can pass in one or more filter sets that get matched against each entity. Each filter set is a number of conditions that all have to match for the condition to be true (conditions effectively have an AND between them). At least one filter set has to be true for the entity to be part of the result set (filter sets effectively have an OR between them). Example: ```text /entities/by-query?filter=kind=user,metadata.namespace=default&filter=kind=group,spec.type Return entities that match Filter set 1: Condition 1: kind = user AND Condition 2: metadata.namespace = default OR Filter set 2: Condition 1: kind = group AND Condition 2: spec.type exists ``` Each condition is either on the form `<key>`, or on the form `<key>=<value>`. The first form asserts on the existence of a certain key (with any value), and the second asserts that the key exists and has a certain value. All checks are always case _insensitive_. In all cases, the key is a simplified JSON path in a given piece of entity data. Each part of the path is a key of an object, and the traversal also descends through arrays. There are two special forms: - Array items that are simple value types (such as strings) match on a key-value pair where the key is the item as a string, and the value is the string `true` - Relations can be matched on a `relations.<type>=<targetRef>` form Let\'s look at a simplified example to illustrate the concept: ```json { \"a\": { \"b\": [\"c\", { \"d\": 1 }], \"e\": 7 } } ``` This would match any one of the following conditions: - `a` - `a.b` - `a.b.c` - `a.b.c=true` - `a.b.d` - `a.b.d=1` - `a.e` - `a.e=7` Some more real world usable examples: - Return all orphaned entities: `/entities/by-query?filter=metadata.annotations.backstage.io/orphan=true` - Return all users and groups: `/entities/by-query?filter=kind=user&filter=kind=group` - Return all service components: `/entities/by-query?filter=kind=component,spec.type=service` - Return all entities with the `java` tag: `/entities/by-query?filter=metadata.tags.java` - Return all users who are members of the `ops` group (note that the full [reference](references.md) of the group is used): `/entities/by-query?filter=kind=user,relations.memberof=group:default/ops`
*/
public async getEntityFacets(
// @ts-ignore
@@ -449,6 +464,56 @@ export class DefaultApiClient {
});
}
+ /**
+ * Query entities using predicate-based filters.
+ * @param queryEntitiesByPredicateRequest -
+ */
+ public async queryEntitiesByPredicate(
+ // @ts-ignore
+ request: QueryEntitiesByPredicate,
+ options?: RequestOptions,
+ ): Promise> {
+ const baseUrl = await this.discoveryApi.getBaseUrl(pluginId);
+
+ const uriTemplate = `/entities/by-query`;
+
+ const uri = parser.parse(uriTemplate).expand({});
+
+ return await this.fetchApi.fetch(`${baseUrl}${uri}`, {
+ headers: {
+ 'Content-Type': 'application/json',
+ ...(options?.token && { Authorization: `Bearer ${options?.token}` }),
+ },
+ method: 'POST',
+ body: JSON.stringify(request.body),
+ });
+ }
+
+ /**
+ * Get entity facets using predicate-based filters.
+ * @param queryEntityFacetsByPredicateRequest -
+ */
+ public async queryEntityFacetsByPredicate(
+ // @ts-ignore
+ request: QueryEntityFacetsByPredicate,
+ options?: RequestOptions,
+ ): Promise> {
+ const baseUrl = await this.discoveryApi.getBaseUrl(pluginId);
+
+ const uriTemplate = `/entity-facets`;
+
+ const uri = parser.parse(uriTemplate).expand({});
+
+ return await this.fetchApi.fetch(`${baseUrl}${uri}`, {
+ headers: {
+ 'Content-Type': 'application/json',
+ ...(options?.token && { Authorization: `Bearer ${options?.token}` }),
+ },
+ method: 'POST',
+ body: JSON.stringify(request.body),
+ });
+ }
+
/**
* Refresh the entity related to entityRef.
* @param refreshEntityRequest -
@@ -528,6 +593,7 @@ export class DefaultApiClient {
* Create a location for a given target.
* @param createLocationRequest -
* @param dryRun -
+ * @param onConflict - Behavior when the location already exists. \'reject\' (default) returns a 409 error, \'refresh\' triggers a refresh of the existing location entity and returns 201.
*/
public async createLocation(
// @ts-ignore
@@ -536,7 +602,7 @@ export class DefaultApiClient {
): Promise> {
const baseUrl = await this.discoveryApi.getBaseUrl(pluginId);
- const uriTemplate = `/locations{?dryRun}`;
+ const uriTemplate = `/locations{?dryRun,onConflict}`;
const uri = parser.parse(uriTemplate).expand({
...request.query,
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/AnalyzeLocationExistingEntity.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/AnalyzeLocationExistingEntity.model.ts
index ea3d097ec5..06998f5422 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/AnalyzeLocationExistingEntity.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/AnalyzeLocationExistingEntity.model.ts
@@ -17,12 +17,11 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-
import { Entity } from '../models/Entity.model';
import { LocationSpec } from '../models/LocationSpec.model';
/**
- * If the folder pointed to already contained catalog info yaml files, they are read and emitted like this so that the frontend can inform the user that it located them and can make sure to register them as well if they weren't already
+ * If the folder pointed to already contained catalog info yaml files, they are read and emitted like this so that the frontend can inform the user that it located them and can make sure to register them as well if they weren\'t already
* @public
*/
export interface AnalyzeLocationExistingEntity {
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/AnalyzeLocationGenerateEntity.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/AnalyzeLocationGenerateEntity.model.ts
index 2999da3ddf..7b2ba72114 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/AnalyzeLocationGenerateEntity.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/AnalyzeLocationGenerateEntity.model.ts
@@ -17,12 +17,11 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-
import { AnalyzeLocationEntityField } from '../models/AnalyzeLocationEntityField.model';
import { RecursivePartialEntity } from '../models/RecursivePartialEntity.model';
/**
- * This is some form of representation of what the analyzer could deduce. We should probably have a chat about how this can best be conveyed to the frontend. It'll probably contain a (possibly incomplete) entity, plus enough info for the frontend to know what form data to show to the user for overriding/completing the info.
+ * This is some form of representation of what the analyzer could deduce. We should probably have a chat about how this can best be conveyed to the frontend. It\'ll probably contain a (possibly incomplete) entity, plus enough info for the frontend to know what form data to show to the user for overriding/completing the info.
* @public
*/
export interface AnalyzeLocationGenerateEntity {
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/AnalyzeLocationRequest.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/AnalyzeLocationRequest.model.ts
index 5099a5c8aa..a0a5615f25 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/AnalyzeLocationRequest.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/AnalyzeLocationRequest.model.ts
@@ -17,7 +17,6 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-
import { LocationInput } from '../models/LocationInput.model';
/**
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/AnalyzeLocationResponse.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/AnalyzeLocationResponse.model.ts
index a5eac33f7c..d4d8a0fdd9 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/AnalyzeLocationResponse.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/AnalyzeLocationResponse.model.ts
@@ -17,7 +17,6 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-
import { AnalyzeLocationExistingEntity } from '../models/AnalyzeLocationExistingEntity.model';
import { AnalyzeLocationGenerateEntity } from '../models/AnalyzeLocationGenerateEntity.model';
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/CreateLocation201Response.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/CreateLocation201Response.model.ts
index 610e565b3e..e224386de4 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/CreateLocation201Response.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/CreateLocation201Response.model.ts
@@ -17,7 +17,6 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-
import { Entity } from '../models/Entity.model';
import { Location } from '../models/Location.model';
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/EntitiesBatchResponse.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/EntitiesBatchResponse.model.ts
index e8bf79a501..0434965888 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/EntitiesBatchResponse.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/EntitiesBatchResponse.model.ts
@@ -17,7 +17,6 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-
import { NullableEntity } from '../models/NullableEntity.model';
/**
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/EntitiesQueryResponse.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/EntitiesQueryResponse.model.ts
index d201466db6..5165faec58 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/EntitiesQueryResponse.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/EntitiesQueryResponse.model.ts
@@ -17,7 +17,6 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-
import { EntitiesQueryResponsePageInfo } from '../models/EntitiesQueryResponsePageInfo.model';
import { Entity } from '../models/Entity.model';
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/Entity.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/Entity.model.ts
index 108a7b15b8..00cc91e89b 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/Entity.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/Entity.model.ts
@@ -17,12 +17,11 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-
import { EntityMeta } from '../models/EntityMeta.model';
import { EntityRelation } from '../models/EntityRelation.model';
/**
- * The parts of the format that's common to all versions/kinds of entity.
+ * The parts of the format that\'s common to all versions/kinds of entity.
* @public
*/
export interface Entity {
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/EntityAncestryResponse.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/EntityAncestryResponse.model.ts
index f2c1116f35..9d1e4d9052 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/EntityAncestryResponse.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/EntityAncestryResponse.model.ts
@@ -17,7 +17,6 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-
import { EntityAncestryResponseItemsInner } from '../models/EntityAncestryResponseItemsInner.model';
/**
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/EntityAncestryResponseItemsInner.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/EntityAncestryResponseItemsInner.model.ts
index 9c816e5517..0936545ec7 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/EntityAncestryResponseItemsInner.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/EntityAncestryResponseItemsInner.model.ts
@@ -17,7 +17,6 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-
import { Entity } from '../models/Entity.model';
/**
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/EntityFacetsResponse.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/EntityFacetsResponse.model.ts
index 5cc67294e5..540650bcaf 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/EntityFacetsResponse.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/EntityFacetsResponse.model.ts
@@ -17,7 +17,6 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-
import { EntityFacet } from '../models/EntityFacet.model';
/**
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/EntityMeta.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/EntityMeta.model.ts
index c1e1471045..a35ee87b61 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/EntityMeta.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/EntityMeta.model.ts
@@ -17,7 +17,6 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-
import { EntityLink } from '../models/EntityLink.model';
/**
@@ -26,7 +25,6 @@ import { EntityLink } from '../models/EntityLink.model';
*/
export interface EntityMeta {
[key: string]: any;
-
/**
* A list of external hyperlinks related to the entity.
*/
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/GetEntitiesByRefsRequest.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/GetEntitiesByRefsRequest.model.ts
index 0e7255f9c6..607c992ace 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/GetEntitiesByRefsRequest.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/GetEntitiesByRefsRequest.model.ts
@@ -24,4 +24,8 @@
export interface GetEntitiesByRefsRequest {
entityRefs: Array;
fields?: Array;
+ /**
+ * A type representing all allowed JSON object values.
+ */
+ query?: { [key: string]: any };
}
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/GetLocations200ResponseInner.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/GetLocations200ResponseInner.model.ts
index b77b78971f..846b58ba97 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/GetLocations200ResponseInner.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/GetLocations200ResponseInner.model.ts
@@ -17,7 +17,6 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-
import { Location } from '../models/Location.model';
/**
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/LocationsQueryResponse.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/LocationsQueryResponse.model.ts
index c231fccc57..05259caf32 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/LocationsQueryResponse.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/LocationsQueryResponse.model.ts
@@ -17,7 +17,6 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-
import { Location } from '../models/Location.model';
import { LocationsQueryResponsePageInfo } from '../models/LocationsQueryResponsePageInfo.model';
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/ModelError.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/ModelError.model.ts
index 207f16f828..9d5c36325e 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/ModelError.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/ModelError.model.ts
@@ -17,7 +17,6 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-
import { ErrorError } from '../models/ErrorError.model';
import { ErrorRequest } from '../models/ErrorRequest.model';
import { ErrorResponse } from '../models/ErrorResponse.model';
@@ -27,7 +26,6 @@ import { ErrorResponse } from '../models/ErrorResponse.model';
*/
export interface ModelError {
[key: string]: any;
-
error: ErrorError;
request?: ErrorRequest;
response: ErrorResponse;
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/NullableEntity.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/NullableEntity.model.ts
index 5e59af3327..288b6febb6 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/NullableEntity.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/NullableEntity.model.ts
@@ -17,12 +17,11 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-
import { EntityMeta } from '../models/EntityMeta.model';
import { EntityRelation } from '../models/EntityRelation.model';
/**
- * The parts of the format that's common to all versions/kinds of entity.
+ * The parts of the format that\'s common to all versions/kinds of entity.
* @public
*/
export type NullableEntity = {
diff --git a/plugins/scaffolder-backend/src/schema/openapi/generated/models/DryRun200ResponseAllOf.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/QueryEntitiesByPredicateRequest.model.ts
similarity index 54%
rename from plugins/scaffolder-backend/src/schema/openapi/generated/models/DryRun200ResponseAllOf.model.ts
rename to packages/catalog-client/src/schema/openapi/generated/models/QueryEntitiesByPredicateRequest.model.ts
index 5b6c2ff9c7..7196156f55 100644
--- a/plugins/scaffolder-backend/src/schema/openapi/generated/models/DryRun200ResponseAllOf.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/QueryEntitiesByPredicateRequest.model.ts
@@ -1,5 +1,5 @@
/*
- * Copyright 2025 The Backstage Authors
+ * Copyright 2026 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.
@@ -17,13 +17,21 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-import { DryRun200ResponseAllOfDirectoryContentsInner } from '../models/DryRun200ResponseAllOfDirectoryContentsInner.model';
-import { DryRun200ResponseAllOfStepsInner } from '../models/DryRun200ResponseAllOfStepsInner.model';
+import { QueryEntitiesByPredicateRequestFullTextFilter } from '../models/QueryEntitiesByPredicateRequestFullTextFilter.model';
+import { QueryEntitiesByPredicateRequestOrderByInner } from '../models/QueryEntitiesByPredicateRequestOrderByInner.model';
/**
* @public
*/
-export interface DryRun200ResponseAllOf {
- steps: Array;
- directoryContents?: Array;
+export interface QueryEntitiesByPredicateRequest {
+ cursor?: string;
+ limit?: number;
+ offset?: number;
+ orderBy?: Array;
+ fullTextFilter?: QueryEntitiesByPredicateRequestFullTextFilter;
+ fields?: Array;
+ /**
+ * A type representing all allowed JSON object values.
+ */
+ query?: { [key: string]: any };
}
diff --git a/plugins/scaffolder-backend/src/schema/openapi/generated/models/TaskSecretsAllOf.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/QueryEntitiesByPredicateRequestFullTextFilter.model.ts
similarity index 84%
rename from plugins/scaffolder-backend/src/schema/openapi/generated/models/TaskSecretsAllOf.model.ts
rename to packages/catalog-client/src/schema/openapi/generated/models/QueryEntitiesByPredicateRequestFullTextFilter.model.ts
index 0b33852cc9..e7e971e1ea 100644
--- a/plugins/scaffolder-backend/src/schema/openapi/generated/models/TaskSecretsAllOf.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/QueryEntitiesByPredicateRequestFullTextFilter.model.ts
@@ -1,5 +1,5 @@
/*
- * Copyright 2025 The Backstage Authors
+ * Copyright 2026 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.
@@ -21,6 +21,7 @@
/**
* @public
*/
-export interface TaskSecretsAllOf {
- backstageToken?: string;
+export interface QueryEntitiesByPredicateRequestFullTextFilter {
+ term?: string;
+ fields?: Array;
}
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/QueryEntitiesByPredicateRequestOrderByInner.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/QueryEntitiesByPredicateRequestOrderByInner.model.ts
new file mode 100644
index 0000000000..373ca9715f
--- /dev/null
+++ b/packages/catalog-client/src/schema/openapi/generated/models/QueryEntitiesByPredicateRequestOrderByInner.model.ts
@@ -0,0 +1,34 @@
+/*
+ * Copyright 2026 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.
+ */
+
+// ******************************************************************
+// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
+// ******************************************************************
+
+/**
+ * @public
+ */
+export interface QueryEntitiesByPredicateRequestOrderByInner {
+ field: string;
+ order: QueryEntitiesByPredicateRequestOrderByInnerOrderEnum;
+}
+
+/**
+ * @public
+ */
+export type QueryEntitiesByPredicateRequestOrderByInnerOrderEnum =
+ | 'asc'
+ | 'desc';
diff --git a/plugins/scaffolder-common/src/schema/openapi/generated/models/DryRunResultLogInnerBodyAllOf.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/QueryEntityFacetsByPredicateRequest.model.ts
similarity index 78%
rename from plugins/scaffolder-common/src/schema/openapi/generated/models/DryRunResultLogInnerBodyAllOf.model.ts
rename to packages/catalog-client/src/schema/openapi/generated/models/QueryEntityFacetsByPredicateRequest.model.ts
index e67240ee54..14fd3a8bc0 100644
--- a/plugins/scaffolder-common/src/schema/openapi/generated/models/DryRunResultLogInnerBodyAllOf.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/QueryEntityFacetsByPredicateRequest.model.ts
@@ -1,5 +1,5 @@
/*
- * Copyright 2025 The Backstage Authors
+ * Copyright 2026 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.
@@ -17,13 +17,14 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-import { TaskStatus } from '../models/TaskStatus.model';
/**
* @public
*/
-export interface DryRunResultLogInnerBodyAllOf {
- message: string;
- status?: TaskStatus;
- stepId?: string;
+export interface QueryEntityFacetsByPredicateRequest {
+ facets: Array;
+ /**
+ * A type representing all allowed JSON object values.
+ */
+ query?: { [key: string]: any };
}
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/RecursivePartialEntity.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/RecursivePartialEntity.model.ts
index 3f09c69672..3a607dd878 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/RecursivePartialEntity.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/RecursivePartialEntity.model.ts
@@ -17,7 +17,6 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-
import { RecursivePartialEntityMeta } from '../models/RecursivePartialEntityMeta.model';
import { RecursivePartialEntityRelation } from '../models/RecursivePartialEntityRelation.model';
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/RecursivePartialEntityMeta.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/RecursivePartialEntityMeta.model.ts
index 2db84dd085..7c2d3bed48 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/RecursivePartialEntityMeta.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/RecursivePartialEntityMeta.model.ts
@@ -17,7 +17,6 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-
import { EntityLink } from '../models/EntityLink.model';
/**
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/RecursivePartialEntityMetaAllOf.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/RecursivePartialEntityMetaAllOf.model.ts
deleted file mode 100644
index caca69a622..0000000000
--- a/packages/catalog-client/src/schema/openapi/generated/models/RecursivePartialEntityMetaAllOf.model.ts
+++ /dev/null
@@ -1,68 +0,0 @@
-/*
- * Copyright 2026 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.
- */
-
-// ******************************************************************
-// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
-// ******************************************************************
-
-import { EntityLink } from '../models/EntityLink.model';
-
-/**
- * Metadata fields common to all versions/kinds of entity.
- * @public
- */
-export interface RecursivePartialEntityMetaAllOf {
- /**
- * A list of external hyperlinks related to the entity.
- */
- links?: Array;
- /**
- * A list of single-valued strings, to for example classify catalog entities in various ways.
- */
- tags?: Array;
- /**
- * Construct a type with a set of properties K of type T
- */
- annotations?: { [key: string]: string };
- /**
- * Construct a type with a set of properties K of type T
- */
- labels?: { [key: string]: string };
- /**
- * A short (typically relatively few words, on one line) description of the entity.
- */
- description?: string;
- /**
- * A display name of the entity, to be presented in user interfaces instead of the `name` property above, when available. This field is sometimes useful when the `name` is cumbersome or ends up being perceived as overly technical. The title generally does not have as stringent format requirements on it, so it may contain special characters and be more explanatory. Do keep it very short though, and avoid situations where a title can be confused with the name of another entity, or where two entities share a title. Note that this is only for display purposes, and may be ignored by some parts of the code. Entity references still always make use of the `name` property, not the title.
- */
- title?: string;
- /**
- * The namespace that the entity belongs to.
- */
- namespace?: string;
- /**
- * The name of the entity. Must be unique within the catalog at any given point in time, for any given namespace + kind pair. This value is part of the technical identifier of the entity, and as such it will appear in URLs, database tables, entity references, and similar. It is subject to restrictions regarding what characters are allowed. If you want to use a different, more human readable string with fewer restrictions on it in user interfaces, see the `title` field below.
- */
- name?: string;
- /**
- * An opaque string that changes for each update operation to any part of the entity, including metadata. This field can not be set by the user at creation time, and the server will reject an attempt to do so. The field will be populated in read operations. The field can (optionally) be specified when performing update or delete operations, and the server will then reject the operation if it does not match the current stored value.
- */
- etag?: string;
- /**
- * A globally unique ID for the entity. This field can not be set by the user at creation time, and the server will reject an attempt to do so. The field will be populated in read operations. The field can (optionally) be specified when performing update or delete operations, but the server is free to reject requests that do so in such a way that it breaks semantics.
- */
- uid?: string;
-}
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/ValidateEntity400Response.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/ValidateEntity400Response.model.ts
index aabf825a57..2a41f2df5c 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/ValidateEntity400Response.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/ValidateEntity400Response.model.ts
@@ -17,7 +17,6 @@
// ******************************************************************
// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. *
// ******************************************************************
-
import { ValidateEntity400ResponseErrorsInner } from '../models/ValidateEntity400ResponseErrorsInner.model';
/**
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/ValidateEntity400ResponseErrorsInner.model.ts b/packages/catalog-client/src/schema/openapi/generated/models/ValidateEntity400ResponseErrorsInner.model.ts
index 4582bf2046..f8a7ae4386 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/ValidateEntity400ResponseErrorsInner.model.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/ValidateEntity400ResponseErrorsInner.model.ts
@@ -23,7 +23,6 @@
*/
export interface ValidateEntity400ResponseErrorsInner {
[key: string]: any;
-
name: string;
message: string;
}
diff --git a/packages/catalog-client/src/schema/openapi/generated/models/index.ts b/packages/catalog-client/src/schema/openapi/generated/models/index.ts
index abdb58378c..aaafc8e60e 100644
--- a/packages/catalog-client/src/schema/openapi/generated/models/index.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/models/index.ts
@@ -45,9 +45,12 @@ export * from '../models/LocationsQueryResponse.model';
export * from '../models/LocationsQueryResponsePageInfo.model';
export * from '../models/ModelError.model';
export * from '../models/NullableEntity.model';
+export * from '../models/QueryEntitiesByPredicateRequest.model';
+export * from '../models/QueryEntitiesByPredicateRequestFullTextFilter.model';
+export * from '../models/QueryEntitiesByPredicateRequestOrderByInner.model';
+export * from '../models/QueryEntityFacetsByPredicateRequest.model';
export * from '../models/RecursivePartialEntity.model';
export * from '../models/RecursivePartialEntityMeta.model';
-export * from '../models/RecursivePartialEntityMetaAllOf.model';
export * from '../models/RecursivePartialEntityRelation.model';
export * from '../models/RefreshEntityRequest.model';
export * from '../models/ValidateEntity400Response.model';
diff --git a/packages/catalog-client/src/testUtils/InMemoryCatalogClient.test.ts b/packages/catalog-client/src/testUtils/InMemoryCatalogClient.test.ts
index d867ab1d28..98b5d5c034 100644
--- a/packages/catalog-client/src/testUtils/InMemoryCatalogClient.test.ts
+++ b/packages/catalog-client/src/testUtils/InMemoryCatalogClient.test.ts
@@ -370,6 +370,25 @@ describe('InMemoryCatalogClient', () => {
{ kind: 'CustomKind', metadata: { name: 'e1' } },
]);
});
+
+ it('supports query predicate filter', async () => {
+ const client = new InMemoryCatalogClient({ entities });
+ const result = await client.getEntitiesByRefs({
+ entityRefs: ['secondcustomkind:default/e2', 'customkind:default/e1'],
+ query: { kind: 'CustomKind' },
+ });
+ expect(result.items).toEqual([undefined, entity1]);
+ });
+
+ it('supports both filter and query predicate together', async () => {
+ const client = new InMemoryCatalogClient({ entities });
+ const result = await client.getEntitiesByRefs({
+ entityRefs: ['customkind:default/e1', 'customkind:other/e3'],
+ filter: { kind: 'CustomKind' },
+ query: { 'metadata.namespace': 'other' },
+ });
+ expect(result.items).toEqual([undefined, entity3]);
+ });
});
describe('queryEntities', () => {
@@ -683,6 +702,83 @@ describe('InMemoryCatalogClient', () => {
]);
});
+ it('filters by predicate query', async () => {
+ const client = new InMemoryCatalogClient({ entities });
+ const result = await client.queryEntities({
+ query: { kind: 'CustomKind' },
+ });
+ expect(result.items).toEqual([entity1, entity3]);
+ expect(result.totalItems).toBe(2);
+ });
+
+ it('filters by predicate query with $all', async () => {
+ const client = new InMemoryCatalogClient({ entities });
+ const result = await client.queryEntities({
+ query: {
+ $all: [{ kind: 'CustomKind' }, { 'spec.type': 'service' }],
+ },
+ });
+ expect(result.items).toEqual([entity1, entity3]);
+ });
+
+ it('filters by predicate query with $any', async () => {
+ const client = new InMemoryCatalogClient({ entities });
+ const result = await client.queryEntities({
+ query: {
+ $any: [{ 'spec.type': 'service' }, { 'spec.type': 'website' }],
+ },
+ });
+ expect(result.items).toEqual([entity1, entity3, entity4]);
+ });
+
+ it('filters by predicate query with $not', async () => {
+ const client = new InMemoryCatalogClient({ entities });
+ const result = await client.queryEntities({
+ query: {
+ $all: [
+ { kind: 'CustomKind' },
+ { $not: { 'spec.lifecycle': 'production' } },
+ ],
+ },
+ });
+ expect(result.items).toEqual([]);
+ });
+
+ it('filters by predicate query with $in', async () => {
+ const client = new InMemoryCatalogClient({ entities });
+ const result = await client.queryEntities({
+ query: { 'spec.type': { $in: ['service', 'library'] } },
+ });
+ expect(result.items).toEqual([entity1, entity2, entity3]);
+ });
+
+ it('filters by predicate query with $exists', async () => {
+ const client = new InMemoryCatalogClient({ entities });
+ const result = await client.queryEntities({
+ query: { 'spec.lifecycle': { $exists: false } },
+ });
+ expect(result.items).toEqual([entity4]);
+ });
+
+ it('preserves query predicate through cursor pagination', async () => {
+ const client = new InMemoryCatalogClient({ entities });
+ const page1 = await client.queryEntities({
+ query: { kind: 'CustomKind' },
+ orderFields: { field: 'metadata.name', order: 'asc' },
+ limit: 1,
+ });
+ expect(page1.items.map(e => e.metadata.name)).toEqual(['e1']);
+ expect(page1.totalItems).toBe(2);
+ expect(page1.pageInfo.nextCursor).toBeDefined();
+
+ const page2 = await client.queryEntities({
+ cursor: page1.pageInfo.nextCursor!,
+ limit: 1,
+ });
+ expect(page2.items.map(e => e.metadata.name)).toEqual(['e3']);
+ expect(page2.pageInfo.nextCursor).toBeUndefined();
+ });
+
it('throws InputError for invalid cursor', async () => {
const client = new InMemoryCatalogClient({ entities });
await expect(
@@ -898,6 +994,29 @@ describe('InMemoryCatalogClient', () => {
});
expect(result.facets['spec.nonexistent']).toEqual([]);
});
+
+ it('supports query predicate filter', async () => {
+ const client = new InMemoryCatalogClient({ entities });
+ const result = await client.getEntityFacets({
+ facets: ['spec.type'],
+ query: { kind: 'CustomKind' },
+ });
+ expect(result.facets['spec.type']).toEqual([
+ { value: 'service', count: 2 },
+ ]);
+ });
+
+ it('supports both filter and query predicate together', async () => {
+ const client = new InMemoryCatalogClient({ entities });
+ const result = await client.getEntityFacets({
+ facets: ['spec.type'],
+ filter: { kind: 'CustomKind' },
+ query: { 'metadata.namespace': 'default' },
+ });
+ expect(result.facets['spec.type']).toEqual([
+ { value: 'service', count: 1 },
+ ]);
+ });
});
describe('not implemented methods', () => {
diff --git a/packages/catalog-client/src/testUtils/InMemoryCatalogClient.ts b/packages/catalog-client/src/testUtils/InMemoryCatalogClient.ts
index e64706ff8d..dd7f269188 100644
--- a/packages/catalog-client/src/testUtils/InMemoryCatalogClient.ts
+++ b/packages/catalog-client/src/testUtils/InMemoryCatalogClient.ts
@@ -51,6 +51,10 @@ import {
NotFoundError,
NotImplementedError,
} from '@backstage/errors';
+import {
+ FilterPredicate,
+ filterPredicateToFilterFunction,
+} from '@backstage/filter-predicates';
import lodash from 'lodash';
// eslint-disable-next-line @backstage/no-relative-monorepo-imports
import { traverse } from '../../../../plugins/catalog-backend/src/database/operations/stitcher/buildEntitySearch';
@@ -357,10 +361,15 @@ export class InMemoryCatalogClient implements CatalogApi {
request: GetEntitiesByRefsRequest,
): Promise {
const filter = createFilter(request.filter);
+ const queryFilter = request.query
+ ? filterPredicateToFilterFunction(request.query)
+ : undefined;
const refMap = this.#createEntityRefMap();
const items = request.entityRefs
.map(ref => refMap.get(ref))
- .map(e => (e && filter(e) ? e : undefined));
+ .map(e =>
+ e && filter(e) && (!queryFilter || queryFilter(e)) ? e : undefined,
+ );
return {
items: request.fields
? items.map(e => (e ? applyFieldsFilter(e, request.fields) : undefined))
@@ -373,6 +382,7 @@ export class InMemoryCatalogClient implements CatalogApi {
): Promise {
// Decode query parameters from cursor or from the request directly
let filter: EntityFilterQuery | undefined;
+ let query: FilterPredicate | undefined;
let orderFields: EntityOrderQuery | undefined;
let fullTextFilter: { term: string; fields?: string[] } | undefined;
let offset: number;
@@ -386,12 +396,14 @@ export class InMemoryCatalogClient implements CatalogApi {
throw new InputError('Invalid cursor');
}
filter = deserializeFilter(c.filter as any[]);
+ query = c.query as FilterPredicate | undefined;
orderFields = c.orderFields as EntityOrderQuery | undefined;
fullTextFilter = c.fullTextFilter as typeof fullTextFilter;
offset = c.offset as number;
limit = request.limit;
} else {
filter = request?.filter;
+ query = request?.query;
orderFields = request?.orderFields;
fullTextFilter = request?.fullTextFilter;
offset = request?.offset ?? 0;
@@ -401,6 +413,11 @@ export class InMemoryCatalogClient implements CatalogApi {
// Apply filter
let items = this.#entities.filter(createFilter(filter));
+ // Apply predicate-based query filter
+ if (query) {
+ items = items.filter(filterPredicateToFilterFunction(query));
+ }
+
// Apply full-text filter, defaulting to the sort field or metadata.uid
if (fullTextFilter) {
const orderFieldsList = orderFields ? [orderFields].flat() : [];
@@ -432,6 +449,7 @@ export class InMemoryCatalogClient implements CatalogApi {
const cursorBase = {
filter: serializeFilter(filter),
+ query,
orderFields,
fullTextFilter,
totalItems,
@@ -493,7 +511,12 @@ export class InMemoryCatalogClient implements CatalogApi {
request: GetEntityFacetsRequest,
): Promise {
const filter = createFilter(request.filter);
- const filteredEntities = this.#entities.filter(filter);
+ let filteredEntities = this.#entities.filter(filter);
+ if (request.query) {
+ filteredEntities = filteredEntities.filter(
+ filterPredicateToFilterFunction(request.query),
+ );
+ }
const facets = Object.fromEntries(
request.facets.map(facet => {
const facetValues = new Map();
diff --git a/packages/catalog-client/src/types/api.ts b/packages/catalog-client/src/types/api.ts
index c766b094b8..d6d5392fcf 100644
--- a/packages/catalog-client/src/types/api.ts
+++ b/packages/catalog-client/src/types/api.ts
@@ -14,13 +14,13 @@
* limitations under the License.
*/
-import { CompoundEntityRef, Entity } from '@backstage/catalog-model';
-import { SerializedError } from '@backstage/errors';
+import type { CompoundEntityRef, Entity } from '@backstage/catalog-model';
+import type { SerializedError } from '@backstage/errors';
import type {
AnalyzeLocationRequest,
AnalyzeLocationResponse,
} from '@backstage/plugin-catalog-common';
-import { FilterPredicate } from '@backstage/filter-predicates';
+import type { FilterPredicate } from '@backstage/filter-predicates';
/**
* This symbol can be used in place of a value when passed to filters in e.g.
@@ -212,6 +212,16 @@ export interface GetEntitiesByRefsRequest {
* If given, return only entities that match the given filter.
*/
filter?: EntityFilterQuery;
+ /**
+ * If given, return only entities that match the given predicate query.
+ *
+ * @remarks
+ *
+ * Supports operators like `$all`, `$any`, `$not`, `$exists`, `$in`,
+ * `$contains`, and `$hasPrefix`. When both `filter` and `query` are
+ * provided, they are combined with `$all`.
+ */
+ query?: FilterPredicate;
}
/**
@@ -297,6 +307,16 @@ export interface GetEntityFacetsRequest {
* of that key, no matter what its value is.
*/
filter?: EntityFilterQuery;
+ /**
+ * If given, return only entities that match the given predicate query.
+ *
+ * @remarks
+ *
+ * Supports operators like `$all`, `$any`, `$not`, `$exists`, `$in`,
+ * `$contains`, and `$hasPrefix`. When both `filter` and `query` are
+ * provided, they are combined with `$all`.
+ */
+ query?: FilterPredicate;
/**
* Dot separated paths for the facets to extract from each entity.
*
@@ -376,6 +396,12 @@ export type AddLocationRequest = {
* contain the entities that match the given location.
*/
dryRun?: boolean;
+ /**
+ * Behavior when the location already exists. If set to `'reject'` (the
+ * default), a conflict error is returned. If set to `'refresh'`, the
+ * existing location entity is marked for refresh and a 201 is returned.
+ */
+ onConflict?: 'refresh' | 'reject';
};
/**
@@ -418,16 +444,43 @@ export type QueryEntitiesRequest =
* The method takes this type in an initial pagination request,
* when requesting the first batch of entities.
*
- * The properties filter, sortField, query and sortFieldOrder, are going
+ * The properties filter, query, sortField and sortFieldOrder, are going
* to be immutable for the entire lifecycle of the following requests.
*
+ * @remarks
+ *
+ * Either `filter` or `query` can be provided, or even both:
+ * - `filter`: Uses the traditional key-value filter syntax (GET endpoint)
+ * - `query`: Uses the predicate-based filter syntax with logical operators (POST endpoint)
+ *
* @public
*/
export type QueryEntitiesInitialRequest = {
fields?: string[];
limit?: number;
offset?: number;
+ /**
+ * Traditional key-value based filter.
+ */
filter?: EntityFilterQuery;
+ /**
+ * Predicate-based filter with operators for logical expressions (`$all`,
+ * `$any`, and `$not`) and matching (`$exists`, `$in`, `$hasPrefix`, and
+ * (partially) `$contains`).
+ *
+ * @example
+ * ```typescript
+ * {
+ * query: {
+ * $all: [
+ * { kind: 'component' },
+ * { 'spec.type': { $in: ['service', 'website'] } }
+ * ]
+ * }
+ * }
+ * ```
+ */
+ query?: FilterPredicate;
orderFields?: EntityOrderQuery;
fullTextFilter?: {
term: string;
@@ -567,6 +620,7 @@ export interface CatalogApi {
* const response = await catalogClient.queryEntities({
* filter: [{ kind: 'group' }],
* limit: 20,
+ * fields: ['metadata', 'kind'],
* fullTextFilter: {
* term: 'A',
* },
@@ -583,11 +637,15 @@ export interface CatalogApi {
*
* ```
* const secondBatchResponse = await catalogClient
- * .queryEntities({ cursor: response.nextCursor });
+ * .queryEntities({
+ * cursor: response.nextCursor,
+ * limit: 20,
+ * fields: ['metadata', 'kind'],
+ * });
* ```
*
- * secondBatchResponse will contain the next batch of (maximum) 20 entities,
- * together with a prevCursor property, useful to fetch the previous batch.
+ * `secondBatchResponse` will contain the next batch of (maximum) 20 entities,
+ * together with a `prevCursor` property, useful to fetch the previous batch.
*
* @public
*
diff --git a/packages/catalog-client/src/utils.test.ts b/packages/catalog-client/src/utils.test.ts
index 2f00859985..ce60cc3083 100644
--- a/packages/catalog-client/src/utils.test.ts
+++ b/packages/catalog-client/src/utils.test.ts
@@ -14,7 +14,87 @@
* limitations under the License.
*/
-import { splitRefsIntoChunks } from './utils';
+import { CATALOG_FILTER_EXISTS } from './types/api';
+import { convertFilterToPredicate, splitRefsIntoChunks } from './utils';
+
+describe('convertFilterToPredicate', () => {
+ it('converts a single string value', () => {
+ expect(convertFilterToPredicate({ kind: 'component' })).toEqual({
+ kind: 'component',
+ });
+ });
+
+ it('converts multiple keys into $all', () => {
+ expect(
+ convertFilterToPredicate({
+ kind: 'component',
+ 'spec.type': 'service',
+ }),
+ ).toEqual({
+ $all: [{ kind: 'component' }, { 'spec.type': 'service' }],
+ });
+ });
+
+ it('converts an array of string values into $in', () => {
+ expect(
+ convertFilterToPredicate({ 'spec.type': ['service', 'website'] }),
+ ).toEqual({
+ 'spec.type': { $in: ['service', 'website'] },
+ });
+ });
+
+ it('converts CATALOG_FILTER_EXISTS into $exists', () => {
+ expect(
+ convertFilterToPredicate({ 'spec.owner': CATALOG_FILTER_EXISTS }),
+ ).toEqual({
+ 'spec.owner': { $exists: true },
+ });
+ });
+
+ it('converts an array of records into $any (OR)', () => {
+ expect(
+ convertFilterToPredicate([{ kind: 'component' }, { kind: 'api' }]),
+ ).toEqual({
+ $any: [{ kind: 'component' }, { kind: 'api' }],
+ });
+ });
+
+ it('converts array of records with multiple keys each', () => {
+ expect(
+ convertFilterToPredicate([
+ { kind: 'component', 'spec.type': 'service' },
+ { kind: 'api' },
+ ]),
+ ).toEqual({
+ $any: [
+ { $all: [{ kind: 'component' }, { 'spec.type': 'service' }] },
+ { kind: 'api' },
+ ],
+ });
+ });
+
+ it('treats CATALOG_FILTER_EXISTS mixed with string values as just existence', () => {
+ expect(
+ convertFilterToPredicate({
+ 'spec.owner': [CATALOG_FILTER_EXISTS, 'team-a'],
+ }),
+ ).toEqual({
+ 'spec.owner': { $exists: true },
+ });
+ });
+
+ it('converts a single-element array filter without wrapping in $any', () => {
+ expect(convertFilterToPredicate([{ kind: 'component' }])).toEqual({
+ kind: 'component',
+ });
+ });
+
+ it('ignores entries with no valid values', () => {
+ expect(
+ convertFilterToPredicate({ kind: 'component', other: [] as string[] }),
+ ).toEqual({ kind: 'component' });
+ });
+});
describe('splitRefsIntoChunks', () => {
it('splits by count limit', () => {
diff --git a/packages/catalog-client/src/utils.ts b/packages/catalog-client/src/utils.ts
index a16cf53db1..231aa2409f 100644
--- a/packages/catalog-client/src/utils.ts
+++ b/packages/catalog-client/src/utils.ts
@@ -14,7 +14,13 @@
* limitations under the License.
*/
+import type {
+ FilterPredicate,
+ FilterPredicateExpression,
+} from '@backstage/filter-predicates';
import {
+ CATALOG_FILTER_EXISTS,
+ EntityFilterQuery,
QueryEntitiesCursorRequest,
QueryEntitiesInitialRequest,
QueryEntitiesRequest,
@@ -26,6 +32,58 @@ export function isQueryEntitiesInitialRequest(
return !(request as QueryEntitiesCursorRequest).cursor;
}
+/**
+ * Check if a cursor contains a predicate query by attempting to decode it.
+ * @internal
+ */
+export function cursorContainsQuery(cursor: string): boolean {
+ try {
+ const decoded = JSON.parse(atob(cursor));
+ return 'query' in decoded;
+ } catch {
+ return false;
+ }
+}
+
+/**
+ * Converts an {@link EntityFilterQuery} into a predicate query object.
+ * @internal
+ */
+export function convertFilterToPredicate(filter: EntityFilterQuery):
+ | FilterPredicateExpression
+ | {
+ $all: FilterPredicate[];
+ }
+ | {
+ $any: FilterPredicate[];
+ } {
+ const records = [filter].flat();
+
+ const clauses = records.map(record => {
+ const parts: FilterPredicateExpression[] = [];
+
+ for (const [key, value] of Object.entries(record)) {
+ const values = [value].flat();
+ const strings = values.filter((v): v is string => typeof v === 'string');
+ const hasExists = values.some(v => v === CATALOG_FILTER_EXISTS);
+
+ if (hasExists) {
+ // Ignore whether there ALSO were some strings - that would boil down to
+ // just existence anyway since there's effectively an OR between them
+ parts.push({ [key]: { $exists: true } } as FilterPredicateExpression);
+ } else if (strings.length === 1) {
+ parts.push({ [key]: strings[0] } as FilterPredicateExpression);
+ } else if (strings.length > 1) {
+ parts.push({ [key]: { $in: strings } } as FilterPredicateExpression);
+ }
+ }
+
+ return parts.length === 1 ? parts[0] : { $all: parts };
+ });
+
+ return clauses.length === 1 ? clauses[0] : { $any: clauses };
+}
+
/**
* Takes a set of entity refs, and splits them into chunks (groups) such that
* the total string length in each chunk does not exceed the default Express.js
diff --git a/packages/catalog-model/CHANGELOG.md b/packages/catalog-model/CHANGELOG.md
index 2fb24c4943..6d3927a404 100644
--- a/packages/catalog-model/CHANGELOG.md
+++ b/packages/catalog-model/CHANGELOG.md
@@ -1,5 +1,11 @@
# @backstage/catalog-model
+## 1.7.7
+
+### Patch Changes
+
+- a49a40d: Updated dependency `zod` to `^3.25.76 || ^4.0.0` & migrated to `/v3` or `/v4` imports.
+
## 1.7.6
### Patch Changes
diff --git a/packages/catalog-model/examples/apis/hello-world-trpc-api.yaml b/packages/catalog-model/examples/apis/hello-world-trpc-api.yaml
index f5807537b3..f1847154ce 100644
--- a/packages/catalog-model/examples/apis/hello-world-trpc-api.yaml
+++ b/packages/catalog-model/examples/apis/hello-world-trpc-api.yaml
@@ -8,7 +8,7 @@ spec:
lifecycle: experimental
owner: team-c
definition: |
- import { z } from 'zod';
+ import { z } from 'zod/v3';
import { publicProcedure, router } from '../trpc';
export const apiRouter = router({
diff --git a/packages/catalog-model/package.json b/packages/catalog-model/package.json
index 85c299e941..ddee09d18f 100644
--- a/packages/catalog-model/package.json
+++ b/packages/catalog-model/package.json
@@ -1,6 +1,6 @@
{
"name": "@backstage/catalog-model",
- "version": "1.7.6",
+ "version": "1.7.7",
"description": "Types and validators that help describe the model of a Backstage Catalog",
"backstage": {
"role": "common-library"
diff --git a/packages/cli-common/CHANGELOG.md b/packages/cli-common/CHANGELOG.md
index c36322d60f..cbff8fe79c 100644
--- a/packages/cli-common/CHANGELOG.md
+++ b/packages/cli-common/CHANGELOG.md
@@ -1,5 +1,95 @@
# @backstage/cli-common
+## 0.2.1-next.0
+
+### Patch Changes
+
+- e928e73: chore(deps): bump `undici` from 7.22.0 to 7.24.0
+- Updated dependencies
+ - @backstage/errors@1.2.7
+
+## 0.2.0
+
+### Minor Changes
+
+- 56bd494: Added `targetPaths` and `findOwnPaths` as replacements for `findPaths`, with a cleaner separation between target project paths and package-relative paths.
+
+ To migrate existing `findPaths` usage:
+
+ ```ts
+ // Before
+ import { findPaths } from '@backstage/cli-common';
+ const paths = findPaths(__dirname);
+
+ // After — for target project paths (cwd-based):
+ import { targetPaths } from '@backstage/cli-common';
+ // paths.targetDir → targetPaths.dir
+ // paths.targetRoot → targetPaths.rootDir
+ // paths.resolveTarget('src') → targetPaths.resolve('src')
+ // paths.resolveTargetRoot('yarn.lock') → targetPaths.resolveRoot('yarn.lock')
+
+ // After — for package-relative paths:
+ import { findOwnPaths } from '@backstage/cli-common';
+ const own = findOwnPaths(__dirname);
+ // paths.ownDir → own.dir
+ // paths.ownRoot → own.rootDir
+ // paths.resolveOwn('config/jest.js') → own.resolve('config/jest.js')
+ // paths.resolveOwnRoot('tsconfig.json') → own.resolveRoot('tsconfig.json')
+ ```
+
+### Patch Changes
+
+- e44b6a9: The `findOwnRootDir` utility now searches for the monorepo root by traversing up the directory tree looking for a `package.json` with `workspaces`, instead of assuming a fixed `../..` relative path. If no workspaces root is found during this traversal, `findOwnRootDir` now throws to enforce stricter validation of the repository layout.
+- 9361965: Fixed `runCheck` to ignore stdio of the spawned process, preventing unwanted output from leaking to the terminal.
+
+## 0.2.0-next.2
+
+### Patch Changes
+
+- 9361965: Fixed `runCheck` to ignore stdio of the spawned process, preventing unwanted output from leaking to the terminal.
+
+## 0.2.0-next.1
+
+### Patch Changes
+
+- e44b6a9: The `findOwnRootDir` utility now searches for the monorepo root by traversing up the directory tree looking for a `package.json` with `workspaces`, instead of assuming a fixed `../..` relative path. If no workspaces root is found during this traversal, `findOwnRootDir` now throws to enforce stricter validation of the repository layout.
+- Updated dependencies
+ - @backstage/errors@1.2.7
+
+## 0.2.0-next.0
+
+### Minor Changes
+
+- 56bd494: Added `targetPaths` and `findOwnPaths` as replacements for `findPaths`, with a cleaner separation between target project paths and package-relative paths.
+
+ To migrate existing `findPaths` usage:
+
+ ```ts
+ // Before
+ import { findPaths } from '@backstage/cli-common';
+ const paths = findPaths(__dirname);
+
+ // After — for target project paths (cwd-based):
+ import { targetPaths } from '@backstage/cli-common';
+ // paths.targetDir → targetPaths.dir
+ // paths.targetRoot → targetPaths.rootDir
+ // paths.resolveTarget('src') → targetPaths.resolve('src')
+ // paths.resolveTargetRoot('yarn.lock') → targetPaths.resolveRoot('yarn.lock')
+
+ // After — for package-relative paths:
+ import { findOwnPaths } from '@backstage/cli-common';
+ const own = findOwnPaths(__dirname);
+ // paths.ownDir → own.dir
+ // paths.ownRoot → own.rootDir
+ // paths.resolveOwn('config/jest.js') → own.resolve('config/jest.js')
+ // paths.resolveOwnRoot('tsconfig.json') → own.resolveRoot('tsconfig.json')
+ ```
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/errors@1.2.7
+
## 0.1.18
### Patch Changes
diff --git a/packages/cli-common/package.json b/packages/cli-common/package.json
index 4eae1d96a4..b393335552 100644
--- a/packages/cli-common/package.json
+++ b/packages/cli-common/package.json
@@ -1,6 +1,6 @@
{
"name": "@backstage/cli-common",
- "version": "0.1.18",
+ "version": "0.2.1-next.0",
"description": "Common functionality used by cli, backend, and create-app",
"backstage": {
"role": "node-library"
@@ -51,7 +51,7 @@
"@backstage/errors": "workspace:^",
"cross-spawn": "^7.0.3",
"global-agent": "^3.0.0",
- "undici": "^7.2.3"
+ "undici": "^7.24.5"
},
"devDependencies": {
"@backstage/cli": "workspace:^",
diff --git a/packages/cli-common/src/paths.test.ts b/packages/cli-common/src/paths.test.ts
index 6ade904e12..df0e7c2044 100644
--- a/packages/cli-common/src/paths.test.ts
+++ b/packages/cli-common/src/paths.test.ts
@@ -16,18 +16,18 @@
/* eslint-disable no-restricted-syntax */
import { resolve as resolvePath } from 'node:path';
-import { findPaths, findRootPath, findOwnDir, findOwnRootDir } from './paths';
+import { findPaths, findRootPath, findOwnRootDir, findOwnPaths } from './paths';
describe('paths', () => {
afterEach(() => {
jest.restoreAllMocks();
});
- it('findOwnDir and findOwnRootDir should find owns paths', () => {
- const dir = findOwnDir(__dirname);
- const root = findOwnRootDir(dir);
+ it('findOwnPaths and findOwnRootDir should find own paths', () => {
+ const own = findOwnPaths(__dirname);
+ const root = findOwnRootDir(own.dir);
- expect(dir).toBe(resolvePath(__dirname, '..'));
+ expect(own.dir).toBe(resolvePath(__dirname, '..'));
expect(root).toBe(resolvePath(__dirname, '../../..'));
});
@@ -98,7 +98,9 @@ describe('paths', () => {
});
it('findPaths should find workspace root with object', () => {
- jest.spyOn(JSON, 'parse').mockReturnValue({ workspaces: { packages: [] } });
+ jest
+ .spyOn(JSON, 'parse')
+ .mockReturnValue({ workspaces: { packages: ['packages/*'] } });
jest.spyOn(process, 'cwd').mockReturnValue(__dirname);
const paths = findPaths(__dirname);
@@ -110,7 +112,7 @@ describe('paths', () => {
});
it('findPaths should find workspace root with array', () => {
- jest.spyOn(JSON, 'parse').mockReturnValue({ workspaces: [] });
+ jest.spyOn(JSON, 'parse').mockReturnValue({ workspaces: ['packages/*'] });
jest.spyOn(process, 'cwd').mockReturnValue(__dirname);
const paths = findPaths(__dirname);
diff --git a/packages/cli-common/src/paths.ts b/packages/cli-common/src/paths.ts
index 1cd84d4f5b..c6bedc77e4 100644
--- a/packages/cli-common/src/paths.ts
+++ b/packages/cli-common/src/paths.ts
@@ -119,7 +119,23 @@ export function findOwnRootDir(ownDir: string) {
);
}
- return resolvePath(ownDir, '../..');
+ const rootDir = findRootPath(ownDir, pkgJsonPath => {
+ try {
+ const content = fs.readFileSync(pkgJsonPath, 'utf8');
+ const data = JSON.parse(content);
+ return Boolean(data.workspaces);
+ } catch (error) {
+ throw new Error(
+ `Failed to read package.json at '${pkgJsonPath}', ${error}`,
+ );
+ }
+ });
+
+ if (!rootDir) {
+ throw new Error(`No monorepo root found when searching from '${ownDir}'`);
+ }
+
+ return rootDir;
}
// Hierarchical directory cache shared across all OwnPathsImpl instances.
@@ -199,11 +215,6 @@ class OwnPathsImpl implements OwnPaths {
};
}
-// Finds the root of a given package
-export function findOwnDir(searchDir: string) {
- return OwnPathsImpl.findDir(searchDir);
-}
-
// Used by the test utility in testUtils.ts to override targetPaths
export let targetPathsOverride: TargetPaths | undefined;
diff --git a/packages/cli-common/src/run.test.ts b/packages/cli-common/src/run.test.ts
index 01c6c915d6..f38c1659ba 100644
--- a/packages/cli-common/src/run.test.ts
+++ b/packages/cli-common/src/run.test.ts
@@ -338,5 +338,26 @@ describe('run', () => {
const result = await runCheck(['nonexistent-command-12345']);
expect(result).toBe(false);
});
+
+ it('should not leak stdout or stderr from the child process', async () => {
+ const stdoutSpy = jest.spyOn(process.stdout, 'write');
+ const stderrSpy = jest.spyOn(process.stderr, 'write');
+ const stdoutBefore = stdoutSpy.mock.calls.length;
+ const stderrBefore = stderrSpy.mock.calls.length;
+
+ await runCheck([
+ 'node',
+ '--eval',
+ 'console.log("leaked stdout"); console.error("leaked stderr")',
+ ]);
+
+ const stdoutCalls = stdoutSpy.mock.calls.slice(stdoutBefore);
+ const stderrCalls = stderrSpy.mock.calls.slice(stderrBefore);
+ const stdout = stdoutCalls.map(c => String(c[0])).join('');
+ const stderr = stderrCalls.map(c => String(c[0])).join('');
+
+ expect(stdout).not.toContain('leaked stdout');
+ expect(stderr).not.toContain('leaked stderr');
+ });
});
});
diff --git a/packages/cli-common/src/run.ts b/packages/cli-common/src/run.ts
index 23e71460e4..0e95bd517b 100644
--- a/packages/cli-common/src/run.ts
+++ b/packages/cli-common/src/run.ts
@@ -211,7 +211,7 @@ export async function runOutput(
*/
export async function runCheck(args: string[]): Promise {
try {
- await run(args).waitForExit();
+ await run(args, { stdio: 'ignore' }).waitForExit();
return true;
} catch {
return false;
diff --git a/plugins/scaffolder-backend-module-bitbucket/.eslintrc.js b/packages/cli-defaults/.eslintrc.js
similarity index 100%
rename from plugins/scaffolder-backend-module-bitbucket/.eslintrc.js
rename to packages/cli-defaults/.eslintrc.js
diff --git a/packages/cli-defaults/CHANGELOG.md b/packages/cli-defaults/CHANGELOG.md
new file mode 100644
index 0000000000..df2ea6932b
--- /dev/null
+++ b/packages/cli-defaults/CHANGELOG.md
@@ -0,0 +1,42 @@
+# @backstage/cli-defaults
+
+## 0.1.1-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/cli-module-build@0.1.1-next.0
+ - @backstage/cli-module-config@0.1.1-next.0
+ - @backstage/cli-module-github@0.1.1-next.0
+ - @backstage/cli-module-info@0.1.1-next.0
+ - @backstage/cli-module-lint@0.1.1-next.0
+ - @backstage/cli-module-maintenance@0.1.1-next.0
+ - @backstage/cli-module-migrate@0.1.1-next.0
+ - @backstage/cli-module-new@0.1.1-next.0
+ - @backstage/cli-module-test-jest@0.1.1-next.0
+ - @backstage/cli-module-translations@0.1.1-next.0
+ - @backstage/cli-module-actions@0.0.2-next.0
+ - @backstage/cli-module-auth@0.1.1-next.0
+
+## 0.1.0
+
+### Minor Changes
+
+- 7781ae5: Introduced `@backstage/cli-defaults`, a convenience package that bundles all standard Backstage CLI modules. Install this single package as a `devDependency` to get the full default set of CLI commands without listing each module individually.
+
+### Patch Changes
+
+- 42960f1: Added `@backstage/cli-module-actions` to the default set of CLI modules.
+- Updated dependencies
+ - @backstage/cli-module-actions@0.0.1
+ - @backstage/cli-module-new@0.1.0
+ - @backstage/cli-module-maintenance@0.1.0
+ - @backstage/cli-module-build@0.1.0
+ - @backstage/cli-module-auth@0.1.0
+ - @backstage/cli-module-config@0.1.0
+ - @backstage/cli-module-github@0.1.0
+ - @backstage/cli-module-info@0.1.0
+ - @backstage/cli-module-lint@0.1.0
+ - @backstage/cli-module-migrate@0.1.0
+ - @backstage/cli-module-test-jest@0.1.0
+ - @backstage/cli-module-translations@0.1.0
diff --git a/packages/cli-defaults/README.md b/packages/cli-defaults/README.md
new file mode 100644
index 0000000000..2066aa1e35
--- /dev/null
+++ b/packages/cli-defaults/README.md
@@ -0,0 +1,26 @@
+# @backstage/cli-defaults
+
+The default set of CLI modules for the Backstage CLI. Installing this single package provides all standard CLI commands without needing to list each module individually.
+
+## Included Modules
+
+| Module | Description |
+| :----------------------------------------------------------------- | :--------------------------------------- |
+| [`@backstage/cli-module-auth`](../cli-module-auth) | Authentication commands |
+| [`@backstage/cli-module-build`](../cli-module-build) | Build, start, and packaging commands |
+| [`@backstage/cli-module-config`](../cli-module-config) | Configuration inspection commands |
+| [`@backstage/cli-module-github`](../cli-module-github) | GitHub App creation |
+| [`@backstage/cli-module-info`](../cli-module-info) | Environment and dependency info |
+| [`@backstage/cli-module-lint`](../cli-module-lint) | Linting commands |
+| [`@backstage/cli-module-maintenance`](../cli-module-maintenance) | Repository maintenance commands |
+| [`@backstage/cli-module-migrate`](../cli-module-migrate) | Migration and version management |
+| [`@backstage/cli-module-new`](../cli-module-new) | Scaffolding for new plugins and packages |
+| [`@backstage/cli-module-test-jest`](../cli-module-test-jest) | Jest-based testing commands |
+| [`@backstage/cli-module-translations`](../cli-module-translations) | Translation management commands |
+
+For fine-grained control over which CLI commands are available, you can install individual modules instead.
+
+## Documentation
+
+- [Backstage Readme](https://github.com/backstage/backstage/blob/master/README.md)
+- [Backstage Documentation](https://backstage.io/docs)
diff --git a/packages/cli-defaults/catalog-info.yaml b/packages/cli-defaults/catalog-info.yaml
new file mode 100644
index 0000000000..3cac883c36
--- /dev/null
+++ b/packages/cli-defaults/catalog-info.yaml
@@ -0,0 +1,10 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: backstage-cli-defaults
+ title: '@backstage/cli-defaults'
+ description: Default set of CLI modules for the Backstage CLI
+spec:
+ lifecycle: experimental
+ type: backstage-cli-module
+ owner: tooling-maintainers
diff --git a/packages/cli-defaults/package.json b/packages/cli-defaults/package.json
new file mode 100644
index 0000000000..63f5507729
--- /dev/null
+++ b/packages/cli-defaults/package.json
@@ -0,0 +1,49 @@
+{
+ "name": "@backstage/cli-defaults",
+ "version": "0.1.1-next.0",
+ "description": "Default set of CLI modules for the Backstage CLI",
+ "backstage": {
+ "role": "cli-module"
+ },
+ "publishConfig": {
+ "access": "public",
+ "main": "dist/index.cjs.js",
+ "types": "dist/index.d.ts"
+ },
+ "homepage": "https://backstage.io",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/backstage/backstage",
+ "directory": "packages/cli-defaults"
+ },
+ "license": "Apache-2.0",
+ "main": "src/index.ts",
+ "types": "src/index.ts",
+ "files": [
+ "dist"
+ ],
+ "scripts": {
+ "build": "backstage-cli package build",
+ "clean": "backstage-cli package clean",
+ "lint": "backstage-cli package lint",
+ "prepack": "backstage-cli package prepack",
+ "postpack": "backstage-cli package postpack"
+ },
+ "dependencies": {
+ "@backstage/cli-module-actions": "workspace:^",
+ "@backstage/cli-module-auth": "workspace:^",
+ "@backstage/cli-module-build": "workspace:^",
+ "@backstage/cli-module-config": "workspace:^",
+ "@backstage/cli-module-github": "workspace:^",
+ "@backstage/cli-module-info": "workspace:^",
+ "@backstage/cli-module-lint": "workspace:^",
+ "@backstage/cli-module-maintenance": "workspace:^",
+ "@backstage/cli-module-migrate": "workspace:^",
+ "@backstage/cli-module-new": "workspace:^",
+ "@backstage/cli-module-test-jest": "workspace:^",
+ "@backstage/cli-module-translations": "workspace:^"
+ },
+ "devDependencies": {
+ "@backstage/cli": "workspace:^"
+ }
+}
diff --git a/packages/cli-defaults/report.api.md b/packages/cli-defaults/report.api.md
new file mode 100644
index 0000000000..573f8ee454
--- /dev/null
+++ b/packages/cli-defaults/report.api.md
@@ -0,0 +1,13 @@
+## API Report File for "@backstage/cli-defaults"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { CliModule } from '@backstage/cli-node';
+
+// @public
+const _default: CliModule[];
+export default _default;
+
+// (No @packageDocumentation comment for this package)
+```
diff --git a/packages/cli-defaults/src/index.ts b/packages/cli-defaults/src/index.ts
new file mode 100644
index 0000000000..f167c3c424
--- /dev/null
+++ b/packages/cli-defaults/src/index.ts
@@ -0,0 +1,47 @@
+/*
+ * Copyright 2025 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 actions from '@backstage/cli-module-actions';
+import auth from '@backstage/cli-module-auth';
+import build from '@backstage/cli-module-build';
+import config from '@backstage/cli-module-config';
+import github from '@backstage/cli-module-github';
+import info from '@backstage/cli-module-info';
+import lint from '@backstage/cli-module-lint';
+import maintenance from '@backstage/cli-module-maintenance';
+import migrate from '@backstage/cli-module-migrate';
+import newModule from '@backstage/cli-module-new';
+import testJest from '@backstage/cli-module-test-jest';
+import translations from '@backstage/cli-module-translations';
+
+/**
+ * The default set of CLI modules for the Backstage CLI.
+ *
+ * @public
+ */
+export default [
+ actions,
+ auth,
+ build,
+ config,
+ github,
+ info,
+ lint,
+ maintenance,
+ migrate,
+ newModule,
+ testJest,
+ translations,
+];
diff --git a/packages/cli/templates/backend-plugin-module/.eslintrc.js.hbs b/packages/cli-internal/.eslintrc.js
similarity index 100%
rename from packages/cli/templates/backend-plugin-module/.eslintrc.js.hbs
rename to packages/cli-internal/.eslintrc.js
diff --git a/packages/cli-internal/CHANGELOG.md b/packages/cli-internal/CHANGELOG.md
new file mode 100644
index 0000000000..30a090f3ef
--- /dev/null
+++ b/packages/cli-internal/CHANGELOG.md
@@ -0,0 +1,15 @@
+# @internal/cli
+
+## 0.0.3-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/cli-node@0.3.1-next.0
+
+## 0.0.2
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/cli-node@0.3.0
diff --git a/packages/cli-internal/catalog-info.yaml b/packages/cli-internal/catalog-info.yaml
new file mode 100644
index 0000000000..2f2a1c837a
--- /dev/null
+++ b/packages/cli-internal/catalog-info.yaml
@@ -0,0 +1,9 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: internal-cli
+ title: '@internal/cli'
+spec:
+ lifecycle: experimental
+ type: backstage-node-library
+ owner: tooling-maintainers
diff --git a/packages/cli-internal/package.json b/packages/cli-internal/package.json
new file mode 100644
index 0000000000..79030bdbe0
--- /dev/null
+++ b/packages/cli-internal/package.json
@@ -0,0 +1,30 @@
+{
+ "name": "@internal/cli",
+ "version": "0.0.3-next.0",
+ "backstage": {
+ "role": "node-library",
+ "inline": true
+ },
+ "private": true,
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/backstage/backstage",
+ "directory": "packages/cli-internal"
+ },
+ "license": "Apache-2.0",
+ "main": "src/index.ts",
+ "types": "src/index.ts",
+ "files": [
+ "dist"
+ ],
+ "scripts": {
+ "lint": "backstage-cli package lint",
+ "test": "backstage-cli package test"
+ },
+ "dependencies": {
+ "@backstage/cli-node": "workspace:^"
+ },
+ "devDependencies": {
+ "@backstage/cli": "workspace:^"
+ }
+}
diff --git a/packages/cli-internal/src/InternalCliModule.ts b/packages/cli-internal/src/InternalCliModule.ts
new file mode 100644
index 0000000000..213e309371
--- /dev/null
+++ b/packages/cli-internal/src/InternalCliModule.ts
@@ -0,0 +1,30 @@
+/*
+ * Copyright 2024 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 { CliCommand, CliModule } from '@backstage/cli-node';
+import { OpaqueType } from '@internal/opaque';
+
+export const OpaqueCliModule = OpaqueType.create<{
+ public: CliModule;
+ versions: {
+ readonly version: 'v1';
+ readonly packageName: string;
+ readonly commands: Promise>;
+ };
+}>({
+ type: '@backstage/CliModule',
+ versions: ['v1'],
+});
diff --git a/packages/cli-internal/src/InternalCommandNode.ts b/packages/cli-internal/src/InternalCommandNode.ts
new file mode 100644
index 0000000000..233e9128cb
--- /dev/null
+++ b/packages/cli-internal/src/InternalCommandNode.ts
@@ -0,0 +1,69 @@
+/*
+ * Copyright 2024 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 { CliCommand, CliModule } from '@backstage/cli-node';
+import { OpaqueType } from '@internal/opaque';
+
+/** @internal */
+export interface CommandTreeNode {
+ readonly $$type: '@backstage/CommandTreeNode';
+}
+
+/** @internal */
+export interface CommandLeafNode {
+ readonly $$type: '@backstage/CommandLeafNode';
+}
+
+export type CommandNode = CommandTreeNode | CommandLeafNode;
+
+export const OpaqueCommandTreeNode = OpaqueType.create<{
+ public: CommandTreeNode;
+ versions: {
+ readonly version: 'v1';
+ readonly name: string;
+ readonly children: CommandNode[];
+ };
+}>({
+ type: '@backstage/CommandTreeNode',
+ versions: ['v1'],
+});
+
+export const OpaqueCommandLeafNode = OpaqueType.create<{
+ public: CommandLeafNode;
+ versions: {
+ readonly version: 'v1';
+ readonly name: string;
+ readonly command: CliCommand;
+ readonly module?: CliModule;
+ };
+}>({
+ type: '@backstage/CommandLeafNode',
+ versions: ['v1'],
+});
+
+/**
+ * Checks whether a command node should be hidden from help output.
+ * Leaf nodes are hidden if they are deprecated or experimental.
+ * Tree nodes are hidden if all of their children are hidden.
+ */
+export function isCommandNodeHidden(node: CommandNode): boolean {
+ if (OpaqueCommandLeafNode.isType(node)) {
+ const { command } = OpaqueCommandLeafNode.toInternal(node);
+ return !!command.deprecated || !!command.experimental;
+ }
+ const { children } = OpaqueCommandTreeNode.toInternal(node);
+ return children.every(child => isCommandNodeHidden(child));
+}
diff --git a/packages/cli-internal/src/authIdentifiers.ts b/packages/cli-internal/src/authIdentifiers.ts
new file mode 100644
index 0000000000..6b72554a4f
--- /dev/null
+++ b/packages/cli-internal/src/authIdentifiers.ts
@@ -0,0 +1,20 @@
+/*
+ * Copyright 2025 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.
+ */
+
+/** Returns the secret-store service key for a given auth instance. */
+export function getAuthInstanceService(instanceName: string): string {
+ return `backstage-cli:auth-instance:${instanceName}`;
+}
diff --git a/packages/cli-internal/src/index.ts b/packages/cli-internal/src/index.ts
new file mode 100644
index 0000000000..dfd8968c6a
--- /dev/null
+++ b/packages/cli-internal/src/index.ts
@@ -0,0 +1,37 @@
+/*
+ * Copyright 2024 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 { OpaqueCliModule } from './InternalCliModule';
+export type {
+ CommandNode,
+ CommandTreeNode,
+ CommandLeafNode,
+} from './InternalCommandNode';
+export {
+ OpaqueCommandTreeNode,
+ OpaqueCommandLeafNode,
+ isCommandNodeHidden,
+} from './InternalCommandNode';
+export { getAuthInstanceService } from './authIdentifiers';
+export {
+ getSecretStore,
+ resetSecretStore,
+ type SecretStore,
+} from './secretStore';
+export {
+ knownBackendPluginPackageNameByPluginId,
+ knownFrontendPluginPackageNameByPluginId,
+} from './knownPluginPackages';
diff --git a/packages/cli-internal/src/knownPluginPackages.ts b/packages/cli-internal/src/knownPluginPackages.ts
new file mode 100644
index 0000000000..c5d13beef1
--- /dev/null
+++ b/packages/cli-internal/src/knownPluginPackages.ts
@@ -0,0 +1,65 @@
+/*
+ * Copyright 2025 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.
+ */
+
+const knownBackendPluginIds = [
+ 'app',
+ 'auth',
+ 'catalog',
+ 'events',
+ 'kubernetes',
+ 'notifications',
+ 'permission',
+ 'proxy',
+ 'scaffolder',
+ 'search',
+ 'signals',
+ 'techdocs',
+];
+
+// Only includes plugin IDs that have a corresponding frontend package; some plugins are backend-only and not listed here.
+const knownFrontendPluginIds = [
+ 'app',
+ 'auth',
+ 'catalog',
+ 'kubernetes',
+ 'notifications',
+ 'scaffolder',
+ 'search',
+ 'signals',
+ 'techdocs',
+];
+
+/**
+ * Maps known plugin IDs to their corresponding backend package names.
+ */
+export const knownBackendPluginPackageNameByPluginId: Record =
+ Object.fromEntries(
+ knownBackendPluginIds.map(pluginId => [
+ pluginId,
+ `@backstage/plugin-${pluginId}-backend`,
+ ]),
+ );
+
+/**
+ * Maps known plugin IDs to their corresponding frontend package names.
+ */
+export const knownFrontendPluginPackageNameByPluginId: Record =
+ Object.fromEntries(
+ knownFrontendPluginIds.map(pluginId => [
+ pluginId,
+ `@backstage/plugin-${pluginId}`,
+ ]),
+ );
diff --git a/packages/cli-internal/src/secretStore.ts b/packages/cli-internal/src/secretStore.ts
new file mode 100644
index 0000000000..26c1e6ad2b
--- /dev/null
+++ b/packages/cli-internal/src/secretStore.ts
@@ -0,0 +1,127 @@
+/*
+ * Copyright 2025 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 { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export type SecretStore = {
+ get(service: string, account: string): Promise;
+ set(service: string, account: string, secret: string): Promise;
+ delete(service: string, account: string): Promise;
+};
+
+async function loadKeytar(): Promise {
+ try {
+ // eslint-disable-next-line import/no-extraneous-dependencies, @backstage/no-undeclared-imports
+ const keytar = require('keytar') as typeof import('keytar');
+ if (keytar && typeof keytar.getPassword === 'function') {
+ return keytar;
+ }
+ } catch {
+ // keytar not available
+ }
+ return undefined;
+}
+
+class KeytarSecretStore implements SecretStore {
+ private readonly keytar: typeof import('keytar');
+ constructor(keytar: typeof import('keytar')) {
+ this.keytar = keytar;
+ }
+ async get(service: string, account: string): Promise {
+ const result = await this.keytar.getPassword(service, account);
+ return result ?? undefined;
+ }
+ async set(service: string, account: string, secret: string): Promise {
+ await this.keytar.setPassword(service, account, secret);
+ }
+ async delete(service: string, account: string): Promise {
+ await this.keytar.deletePassword(service, account);
+ }
+}
+
+async function pathExists(p: string): Promise {
+ try {
+ await fs.stat(p);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+class FileSecretStore implements SecretStore {
+ private readonly baseDir: string;
+ constructor() {
+ const root =
+ process.env.XDG_DATA_HOME ||
+ (process.platform === 'win32'
+ ? process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming')
+ : path.join(os.homedir(), '.local', 'share'));
+ this.baseDir = path.join(root, 'backstage-cli', 'auth-secrets');
+ }
+ private filePath(service: string, account: string): string {
+ return path.join(
+ this.baseDir,
+ encodeURIComponent(service),
+ `${encodeURIComponent(account)}.secret`,
+ );
+ }
+ async get(service: string, account: string): Promise {
+ const file = this.filePath(service, account);
+ if (!(await pathExists(file))) {
+ return undefined;
+ }
+ return await fs.readFile(file, 'utf8');
+ }
+ async set(service: string, account: string, secret: string): Promise {
+ const file = this.filePath(service, account);
+ await fs.mkdir(path.dirname(file), { recursive: true });
+ await fs.writeFile(file, secret, { encoding: 'utf8', mode: 0o600 });
+ }
+ async delete(service: string, account: string): Promise {
+ const file = this.filePath(service, account);
+ try {
+ await fs.unlink(file);
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+ throw err;
+ }
+ }
+ }
+}
+
+let singleton: SecretStore | undefined;
+
+export async function getSecretStore(): Promise {
+ if (!singleton) {
+ const keytar = await loadKeytar();
+ if (keytar) {
+ singleton = new KeytarSecretStore(keytar);
+ } else {
+ singleton = new FileSecretStore();
+ }
+ }
+ return singleton;
+}
+
+/**
+ * Reset the singleton instance (for testing purposes only)
+ * @internal
+ */
+export function resetSecretStore(): void {
+ singleton = undefined;
+}
diff --git a/packages/cli/templates/backend-plugin/.eslintrc.js.hbs b/packages/cli-module-actions/.eslintrc.js
similarity index 100%
rename from packages/cli/templates/backend-plugin/.eslintrc.js.hbs
rename to packages/cli-module-actions/.eslintrc.js
diff --git a/packages/cli-module-actions/CHANGELOG.md b/packages/cli-module-actions/CHANGELOG.md
new file mode 100644
index 0000000000..3305dddb37
--- /dev/null
+++ b/packages/cli-module-actions/CHANGELOG.md
@@ -0,0 +1,17 @@
+# @backstage/cli-module-actions
+
+## 0.0.2-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/cli-node@0.3.1-next.0
+ - @backstage/errors@1.2.7
+
+## 0.0.1
+
+### Patch Changes
+
+- 42960f1: Added `actions` CLI module for listing and executing actions from the distributed actions registry. Includes `actions list`, `actions execute`, and `actions sources` commands for managing plugin sources.
+- Updated dependencies
+ - @backstage/cli-node@0.3.0
diff --git a/packages/cli-module-actions/bin/backstage-cli-module-actions b/packages/cli-module-actions/bin/backstage-cli-module-actions
new file mode 100755
index 0000000000..59f8267233
--- /dev/null
+++ b/packages/cli-module-actions/bin/backstage-cli-module-actions
@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/*
+ * Copyright 2025 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.
+ */
+
+const path = require('node:path');
+
+/* eslint-disable-next-line no-restricted-syntax */
+const isLocal = require('node:fs').existsSync(
+ path.resolve(__dirname, '../src'),
+);
+
+if (isLocal) {
+ require('@backstage/cli-node/config/nodeTransform.cjs');
+}
+
+const { runCliModule } = require('@backstage/cli-node');
+const cliModule = require(isLocal ? '../src/index' : '..').default;
+const pkg = require('../package.json');
+runCliModule({ module: cliModule, name: pkg.name, version: pkg.version });
diff --git a/packages/cli-module-actions/catalog-info.yaml b/packages/cli-module-actions/catalog-info.yaml
new file mode 100644
index 0000000000..fd282ca6a3
--- /dev/null
+++ b/packages/cli-module-actions/catalog-info.yaml
@@ -0,0 +1,10 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: backstage-cli-module-actions
+ title: '@backstage/cli-module-actions'
+ description: CLI module for executing distributed actions
+spec:
+ lifecycle: experimental
+ type: backstage-cli-module
+ owner: tooling-maintainers
diff --git a/packages/cli-module-actions/cli-report.md b/packages/cli-module-actions/cli-report.md
new file mode 100644
index 0000000000..bbbab62b3f
--- /dev/null
+++ b/packages/cli-module-actions/cli-report.md
@@ -0,0 +1,94 @@
+## CLI Report file for "@backstage/cli-module-actions"
+
+> Do not edit this file. It is a report generated by `yarn build:api-reports`
+
+### `backstage-cli-module-actions`
+
+```
+Usage: @backstage/cli-module-actions [options] [command]
+
+Options:
+ -V, --version
+ -h, --help
+
+Commands:
+ actions [command]
+ help [command]
+```
+
+### `backstage-cli-module-actions actions`
+
+```
+Usage: @backstage/cli-module-actions actions [options] [command] [command]
+
+Options:
+ -h, --help
+
+Commands:
+ execute
+ help [command]
+ list
+ sources [command]
+```
+
+### `backstage-cli-module-actions actions execute`
+
+```
+Usage: @backstage/cli-module-actions actions execute
+
+Options:
+ --instance
+ -h, --help
+```
+
+### `backstage-cli-module-actions actions list`
+
+```
+Usage: @backstage/cli-module-actions actions list
+
+Options:
+ --instance
+ -h, --help
+```
+
+### `backstage-cli-module-actions actions sources`
+
+```
+Usage: @backstage/cli-module-actions actions sources [options] [command] [command]
+
+Options:
+ -h, --help
+
+Commands:
+ add
+ help [command]
+ list
+ remove
+```
+
+### `backstage-cli-module-actions actions sources add`
+
+```
+Usage: @backstage/cli-module-actions actions sources add
+
+Options:
+ -h, --help
+```
+
+### `backstage-cli-module-actions actions sources list`
+
+```
+Usage: @backstage/cli-module-actions actions sources list
+
+Options:
+ -h, --help
+```
+
+### `backstage-cli-module-actions actions sources remove`
+
+```
+Usage: @backstage/cli-module-actions actions sources remove
+
+Options:
+ -h, --help
+```
diff --git a/packages/cli-module-actions/package.json b/packages/cli-module-actions/package.json
new file mode 100644
index 0000000000..138eff06cf
--- /dev/null
+++ b/packages/cli-module-actions/package.json
@@ -0,0 +1,45 @@
+{
+ "name": "@backstage/cli-module-actions",
+ "version": "0.0.2-next.0",
+ "description": "CLI module for executing distributed actions",
+ "backstage": {
+ "role": "cli-module"
+ },
+ "publishConfig": {
+ "access": "public",
+ "main": "dist/index.cjs.js",
+ "types": "dist/index.d.ts"
+ },
+ "homepage": "https://backstage.io",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/backstage/backstage",
+ "directory": "packages/cli-module-actions"
+ },
+ "license": "Apache-2.0",
+ "main": "src/index.ts",
+ "types": "src/index.ts",
+ "files": [
+ "dist",
+ "bin"
+ ],
+ "bin": "bin/backstage-cli-module-actions",
+ "scripts": {
+ "build": "backstage-cli package build",
+ "clean": "backstage-cli package clean",
+ "lint": "backstage-cli package lint",
+ "prepack": "backstage-cli package prepack",
+ "postpack": "backstage-cli package postpack",
+ "test": "backstage-cli package test"
+ },
+ "dependencies": {
+ "@backstage/cli-node": "workspace:^",
+ "@backstage/errors": "workspace:^",
+ "cleye": "^2.3.0",
+ "zod": "^3.25.76 || ^4.0.0"
+ },
+ "devDependencies": {
+ "@backstage/backend-test-utils": "workspace:^",
+ "@backstage/cli": "workspace:^"
+ }
+}
diff --git a/packages/cli-module-actions/report.api.md b/packages/cli-module-actions/report.api.md
new file mode 100644
index 0000000000..180186482d
--- /dev/null
+++ b/packages/cli-module-actions/report.api.md
@@ -0,0 +1,13 @@
+## API Report File for "@backstage/cli-module-actions"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { CliModule } from '@backstage/cli-node';
+
+// @public (undocumented)
+const _default: CliModule;
+export default _default;
+
+// (No @packageDocumentation comment for this package)
+```
diff --git a/packages/cli-module-actions/src/commands/execute.ts b/packages/cli-module-actions/src/commands/execute.ts
new file mode 100644
index 0000000000..f130c597ce
--- /dev/null
+++ b/packages/cli-module-actions/src/commands/execute.ts
@@ -0,0 +1,109 @@
+/*
+ * Copyright 2025 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 { cli } from 'cleye';
+import type { CliCommandContext } from '@backstage/cli-node';
+import { ActionsClient } from '../lib/ActionsClient';
+import { schemaToFlags } from '../lib/schemaToFlags';
+import { resolveAuth } from '../lib/resolveAuth';
+
+export default async ({ args, info }: CliCommandContext) => {
+ if (args.includes('--help') || args.includes('-h')) {
+ cli(
+ {
+ help: info,
+ parameters: [''],
+ flags: {
+ instance: {
+ type: String,
+ description: 'Name of the instance to use',
+ },
+ },
+ },
+ undefined,
+ args,
+ );
+ return;
+ }
+
+ const instanceIdx = args.indexOf('--instance');
+ const instanceFlag = instanceIdx !== -1 ? args[instanceIdx + 1] : undefined;
+
+ // Skip flag names, flag values (the argument after a known flag), and
+ // the --instance value position so we only pick up positional arguments.
+ const skipIndices = new Set();
+ if (instanceIdx !== -1) {
+ skipIndices.add(instanceIdx);
+ skipIndices.add(instanceIdx + 1);
+ }
+
+ let actionId: string | undefined;
+ let actionIdIdx = -1;
+ for (let i = 0; i < args.length; i++) {
+ if (!skipIndices.has(i) && !args[i].startsWith('-')) {
+ actionId = args[i];
+ actionIdIdx = i;
+ break;
+ }
+ }
+
+ if (!actionId) {
+ process.stderr.write('Usage: actions execute [flags]\n');
+ process.exit(1);
+ }
+
+ const { accessToken, baseUrl } = await resolveAuth(instanceFlag);
+
+ const client = new ActionsClient(baseUrl, accessToken);
+ const actions = await client.listForPlugin(actionId);
+ const action = actions.find(a => a.id === actionId);
+
+ if (!action) {
+ throw new Error(
+ `Action "${actionId}" not found. Run "actions list" to see available actions.`,
+ );
+ }
+
+ const schemaFlags = schemaToFlags(action.schema.input as any);
+
+ const flagArgs = args.filter((_, i) => i !== actionIdIdx);
+
+ const { flags } = cli(
+ {
+ help: info,
+ flags: {
+ instance: {
+ type: String,
+ description: 'Name of the instance to use',
+ },
+ ...schemaFlags,
+ },
+ },
+ undefined,
+ flagArgs,
+ );
+
+ const allFlags = flags as Record;
+ const input: Record = {};
+ for (const [key, value] of Object.entries(allFlags)) {
+ if (key !== 'instance' && value !== undefined) {
+ input[key] = value;
+ }
+ }
+
+ const output = await client.execute(actionId, input);
+ process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+};
diff --git a/packages/cli-module-actions/src/commands/list.ts b/packages/cli-module-actions/src/commands/list.ts
new file mode 100644
index 0000000000..2049fc3e44
--- /dev/null
+++ b/packages/cli-module-actions/src/commands/list.ts
@@ -0,0 +1,62 @@
+/*
+ * Copyright 2025 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 { cli } from 'cleye';
+import type { CliCommandContext } from '@backstage/cli-node';
+import { ActionsClient } from '../lib/ActionsClient';
+import { resolveAuth } from '../lib/resolveAuth';
+
+export default async ({ args, info }: CliCommandContext) => {
+ const {
+ flags: { instance: instanceFlag },
+ } = cli(
+ {
+ help: info,
+ flags: {
+ instance: {
+ type: String,
+ description: 'Name of the instance to use',
+ },
+ },
+ },
+ undefined,
+ args,
+ );
+
+ const { accessToken, pluginSources, baseUrl } = await resolveAuth(
+ instanceFlag,
+ );
+
+ if (!pluginSources.length) {
+ process.stderr.write(
+ 'No plugin sources configured. Run "actions sources add " to add one.\n',
+ );
+ return;
+ }
+
+ const client = new ActionsClient(baseUrl, accessToken);
+ const actions = await client.list(pluginSources);
+
+ if (!actions.length) {
+ process.stderr.write('No actions found.\n');
+ return;
+ }
+
+ for (const action of actions) {
+ const desc = action.description ? ` - ${action.description}` : '';
+ process.stdout.write(`${action.id}${desc}\n`);
+ }
+};
diff --git a/packages/cli-module-actions/src/commands/sourcesAdd.ts b/packages/cli-module-actions/src/commands/sourcesAdd.ts
new file mode 100644
index 0000000000..fee3007637
--- /dev/null
+++ b/packages/cli-module-actions/src/commands/sourcesAdd.ts
@@ -0,0 +1,50 @@
+/*
+ * Copyright 2025 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 { cli } from 'cleye';
+import { CliAuth, type CliCommandContext } from '@backstage/cli-node';
+import { z } from 'zod/v3';
+
+const pluginSourcesSchema = z.array(z.string()).default([]);
+
+export default async ({ args, info }: CliCommandContext) => {
+ const parsed = cli(
+ {
+ help: info,
+ parameters: ['