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

Merge pull request #25570 from backstage/rugvip/callback

Browse Source 
backend-plugin-api: deprecate service factories with callback form
This commit is contained in:
Patrik Oldsberg
2024-07-16 09:15:47 +02:00
committed by GitHub
parent febf7d6041 87d3f665f8
commit d7b5854157
28 changed files with 354 additions and 180 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/hot-items-kick.md
+9
View File
@@ -0,0 +1,9 @@
---
'@backstage/backend-dynamic-feature-service': patch
'@backstage/backend-test-utils': patch
'@backstage/backend-defaults': patch
'@backstage/backend-app-api': patch
'@backstage/plugin-events-node': patch
---
Service factories exported by this package have been updated to use the new service factory format that doesn't use a callback.
.changeset/spotty-apricots-tan.md
+57
View File
@@ -0,0 +1,57 @@
---
'@backstage/backend-plugin-api': patch
---
Deprecated the ability to define options for service factories through `createServiceFactory`. In the future all service factories will return a plain `ServiceFactory` object, rather than allowing users to pass options to the factory. To allow for customization of a service implementation one can instead export one or a few building blocks that allows for simple re-implementation of the service instead.
For example, instead of:
```ts
export const fooServiceFactory = createServiceFactory<FooService>(
(options?: { bar: string }) => ({
service: fooServiceRef,
deps: { logger: coreServices.logger },
factory({ logger }) {
return {
// Implementation of the foo service using the `bar` option.
};
},
}),
);
```
We instead encourage service implementations to provide an easy to use API for re-implementing the service for advanced use-cases:
```ts
/** @public */
export class DefaultFooService implements FooService {
static create(options: { bar: string; logger: LoggerService }) {
return new DefaultFooService(options.logger, options.bar ?? 'default');
}
private constructor(
private readonly logger: string,
private readonly bar: string,
) {}
// The rest of the implementation
}
```
A user that wishes to customize the service can then easily do so by defining their own factory:
```ts
export const customFooServiceFactory = createServiceFactory<FooService>({
service: fooServiceRef,
deps: { logger: coreServices.logger },
factory({ logger }) {
return DefaultFooService.create({ logger, bar: 'baz' });
},
});
```
This is of course more verbose than the previous solution where the factory could be customized through `fooServiceFactory({ bar: 'baz' })`, but this is a simplified which in practice should be using static configuration instead.
This change is being made because the ability to define an options callback encourages bad design of services factories. When possible, a service should be configurable through static configuration, and the existence of options may discourage that. More importantly though, the existing options do not work well with the dependency injection system of services, which is a problem for callbacks an other more advanced options. This lead to a bad pattern where only a few explicit dependencies where made available in callbacks, rather than providing an API that allowed simple re-implementation of the service with full access to dependency injection.
A separate benefit of this change is that it simplifies the TypeScript types in a way that allows TypeScript to provide a much better error message when a service factory doesn't properly implement the service interface.
docs/backend-system/architecture/03-services.md
+22 -29
View File
@@ -190,43 +190,36 @@ If a service defines a default factory, that factory will be used if there is no
When defining a default factory for a service, it is possible for it to end up with duplicate implementations at runtime. This applies both to any shared root context in your factory, as well as plugin specific instances of your service. This is because package dependency version ranges may not line up perfectly, causing duplicate installations of the same package. This can happen both for two different plugins using the same service, but also across a plugin and its modules. If your service would break in this scenario, you should not define a default factory for it, but instead require that users of your service explicitly install a factory in their backend instance.
## Service Factory Options
## Service Factory Customization
:::note Note
This pattern is discouraged, only use it when necessary. If possible you should prefer to make services configurable via static configuration instead.
:::
When declaring a service factory it's possible to include an options callback. This allows you to customize the factory through code when installing it in the backend. For example, this is how you install an explicit factory instance in the backend without any options:
When declaring a service factory you may also want to make the export the building blocks of the implementation itself. This is to allow for further customization of the service implementation through code, beyond what is possible with static configuration, without the need to re-implement the entire service from scratch. For example, we might export our example `DefaultFooService` class, while moving construction to a static `create` factory method to make it easier to evolve:
```ts
const backend = createBackend();
export class DefaultFooService {
static create(options: { transform: (foo: string) => string }) {
return new DefaultFooService(options.transform ?? (foo) => foo);
}
backend.add(fooServiceFactory());
```
private constructor(private readonly transform: (foo: string) => string) {}
Note that we call `fooServiceFactory` to create the service factory instance. This is because `createServiceFactory` always returns a factory function that creates the actual service factory. To add options to your service factory, you wrap the object passed to `createServiceFactory` in a callback that accepts the desired options. Note that the options must always be optional. For example:
```ts
export interface FooFactoryOptions {
transform: (foo: string) => string;
foo(foo: string): string {
return this.transform(foo);
}
}
export const fooServiceFactory = createServiceFactory(
(options?: FooFactoryOptions) => ({
service: fooServiceRef,
factory() {
return new DefaultFooService(options?.transform);
},
}),
);
```
This lets us use the options to customize the factory implementation in any way we want. From the outside the service factory looks just like before, except that we're now also able to pass options when installing the factory:
By exporting `DefaultFooService` we now make it relatively simple for advanced users of our service to customize the implementation. To do so, they can define their own service factory that uses our provided implementation:
```ts
const backend = createBackend();
backend.add(fooServiceFactory({ transform: foo => foo.toUpperCase() }));
export const customFooServiceFactory = createServiceFactory({
service: fooServiceRef,
deps: {},
factory() {
return DefaultFooService.create({
transform: foo => foo.toUpperCase(),
});
},
});
```
This allows you to provide more advanced options for the service implementation that couldn't be expressed through static configuration. It also gives users of the service implementation access to other services through dependency injection, which can be useful for their customizations.
packages/backend-app-api/api-report-alpha.md
+4 -3
View File
@@ -4,12 +4,13 @@
```ts
import { FeatureDiscoveryService } from '@backstage/backend-plugin-api/alpha';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
// @alpha (undocumented)
export const featureDiscoveryServiceFactory: () => ServiceFactory<
export const featureDiscoveryServiceFactory: ServiceFactoryCompat<
FeatureDiscoveryService,
'root'
'root',
undefined
>;
// (No @packageDocumentation comment for this package)
packages/backend-app-api/api-report.md
+65 -38
View File
@@ -38,7 +38,7 @@ import { RootLifecycleService } from '@backstage/backend-plugin-api';
import { RootLoggerService } from '@backstage/backend-plugin-api';
import { SchedulerService } from '@backstage/backend-plugin-api';
import type { Server } from 'node:http';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
import { ServiceFactoryOrFunction } from '@backstage/backend-plugin-api';
import { TokenManagerService } from '@backstage/backend-plugin-api';
import { transport } from 'winston';
@@ -46,7 +46,11 @@ import { UrlReaderService } from '@backstage/backend-plugin-api';
import { UserInfoService } from '@backstage/backend-plugin-api';
// @public @deprecated (undocumented)
export const authServiceFactory: () => ServiceFactory<AuthService, 'plugin'>;
export const authServiceFactory: ServiceFactoryCompat<
AuthService,
'plugin',
undefined
>;
// @public (undocumented)
export interface Backend {
@@ -66,7 +70,11 @@ export interface Backend {
}
// @public @deprecated (undocumented)
export const cacheServiceFactory: () => ServiceFactory<CacheService, 'plugin'>;
export const cacheServiceFactory: ServiceFactoryCompat<
CacheService,
'plugin',
undefined
>;
// Warning: (ae-forgotten-export) The symbol "createConfigSecretEnumerator_2" needs to be exported by the entry point index.d.ts
//
@@ -95,9 +103,10 @@ export interface CreateSpecializedBackendOptions {
}
// @public @deprecated (undocumented)
export const databaseServiceFactory: () => ServiceFactory<
export const databaseServiceFactory: ServiceFactoryCompat<
DatabaseService,
'plugin'
'plugin',
undefined
>;
// @public @deprecated
@@ -116,9 +125,10 @@ export class DefaultRootHttpRouter implements RootHttpRouterService {
export type DefaultRootHttpRouterOptions = DefaultRootHttpRouterOptions_2;
// @public @deprecated (undocumented)
export const discoveryServiceFactory: () => ServiceFactory<
export const discoveryServiceFactory: ServiceFactoryCompat<
DiscoveryService,
'plugin'
'plugin',
undefined
>;
// Warning: (ae-forgotten-export) The symbol "ExtendedHttpServer_2" needs to be exported by the entry point index.d.ts
@@ -141,15 +151,17 @@ export class HostDiscovery implements DiscoveryService {
}
// @public @deprecated (undocumented)
export const httpAuthServiceFactory: () => ServiceFactory<
export const httpAuthServiceFactory: ServiceFactoryCompat<
HttpAuthService,
'plugin'
'plugin',
undefined
>;
// @public @deprecated
export const httpRouterServiceFactory: () => ServiceFactory<
export const httpRouterServiceFactory: ServiceFactoryCompat<
HttpRouterService,
'plugin'
'plugin',
undefined
>;
// Warning: (ae-forgotten-export) The symbol "HttpServerCertificateOptions_2" needs to be exported by the entry point index.d.ts
@@ -169,9 +181,11 @@ export type IdentityFactoryOptions = {
};
// @public @deprecated (undocumented)
export const identityServiceFactory: (
options?: IdentityFactoryOptions | undefined,
) => ServiceFactory<IdentityService, 'plugin'>;
export const identityServiceFactory: ServiceFactoryCompat<
IdentityService,
'plugin',
IdentityFactoryOptions
>;
// Warning: (ae-forgotten-export) The symbol "LifecycleMiddlewareOptions_2" needs to be exported by the entry point index.d.ts
//
@@ -179,9 +193,10 @@ export const identityServiceFactory: (
export type LifecycleMiddlewareOptions = LifecycleMiddlewareOptions_2;
// @public @deprecated
export const lifecycleServiceFactory: () => ServiceFactory<
export const lifecycleServiceFactory: ServiceFactoryCompat<
LifecycleService,
'plugin'
'plugin',
undefined
>;
// @public @deprecated
@@ -195,9 +210,10 @@ export function loadBackendConfig(options: {
}>;
// @public @deprecated
export const loggerServiceFactory: () => ServiceFactory<
export const loggerServiceFactory: ServiceFactoryCompat<
LoggerService,
'plugin'
'plugin',
undefined
>;
// @public @deprecated (undocumented)
@@ -222,9 +238,10 @@ export type MiddlewareFactoryErrorOptions = MiddlewareFactoryErrorOptions_2;
export type MiddlewareFactoryOptions = MiddlewareFactoryOptions_2;
// @public @deprecated (undocumented)
export const permissionsServiceFactory: () => ServiceFactory<
export const permissionsServiceFactory: ServiceFactoryCompat<
PermissionsService,
'plugin'
'plugin',
undefined
>;
// Warning: (ae-forgotten-export) The symbol "readCorsOptions_2" needs to be exported by the entry point index.d.ts
@@ -251,9 +268,11 @@ export interface RootConfigFactoryOptions {
}
// @public @deprecated (undocumented)
export const rootConfigServiceFactory: (
options?: RootConfigFactoryOptions | undefined,
) => ServiceFactory<RootConfigService, 'root'>;
export const rootConfigServiceFactory: ServiceFactoryCompat<
RootConfigService,
'root',
RootConfigFactoryOptions
>;
// Warning: (ae-forgotten-export) The symbol "RootHttpRouterConfigureContext_2" needs to be exported by the entry point index.d.ts
//
@@ -266,44 +285,52 @@ export type RootHttpRouterConfigureContext = RootHttpRouterConfigureContext_2;
export type RootHttpRouterFactoryOptions = RootHttpRouterFactoryOptions_2;
// @public @deprecated (undocumented)
export const rootHttpRouterServiceFactory: (
options?: RootHttpRouterFactoryOptions_2 | undefined,
) => ServiceFactory<RootHttpRouterService, 'root'>;
export const rootHttpRouterServiceFactory: ServiceFactoryCompat<
RootHttpRouterService,
'root',
RootHttpRouterFactoryOptions_2
>;
// @public @deprecated
export const rootLifecycleServiceFactory: () => ServiceFactory<
export const rootLifecycleServiceFactory: ServiceFactoryCompat<
RootLifecycleService,
'root'
'root',
undefined
>;
// @public @deprecated
export const rootLoggerServiceFactory: () => ServiceFactory<
export const rootLoggerServiceFactory: ServiceFactoryCompat<
RootLoggerService,
'root'
'root',
undefined
>;
// @public @deprecated (undocumented)
export const schedulerServiceFactory: () => ServiceFactory<
export const schedulerServiceFactory: ServiceFactoryCompat<
SchedulerService,
'plugin'
'plugin',
undefined
>;
// @public @deprecated (undocumented)
export const tokenManagerServiceFactory: () => ServiceFactory<
export const tokenManagerServiceFactory: ServiceFactoryCompat<
TokenManagerService,
'plugin'
'plugin',
undefined
>;
// @public @deprecated (undocumented)
export const urlReaderServiceFactory: () => ServiceFactory<
export const urlReaderServiceFactory: ServiceFactoryCompat<
UrlReaderService,
'plugin'
'plugin',
undefined
>;
// @public @deprecated (undocumented)
export const userInfoServiceFactory: () => ServiceFactory<
export const userInfoServiceFactory: ServiceFactoryCompat<
UserInfoService,
'plugin'
'plugin',
undefined
>;
// @public @deprecated
packages/backend-defaults/api-report-auth.md
+6 -2
View File
@@ -4,10 +4,14 @@
```ts
import { AuthService } from '@backstage/backend-plugin-api';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
// @public
export const authServiceFactory: () => ServiceFactory<AuthService, 'plugin'>;
export const authServiceFactory: ServiceFactoryCompat<
AuthService,
'plugin',
undefined
>;
// (No @packageDocumentation comment for this package)
```
packages/backend-defaults/api-report-cache.md
+6 -2
View File
@@ -7,7 +7,7 @@ import { CacheService } from '@backstage/backend-plugin-api';
import { CacheServiceOptions } from '@backstage/backend-plugin-api';
import { Config } from '@backstage/config';
import { LoggerService } from '@backstage/backend-plugin-api';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
// @public
export class CacheManager {
@@ -25,7 +25,11 @@ export type CacheManagerOptions = {
};
// @public
export const cacheServiceFactory: () => ServiceFactory<CacheService, 'plugin'>;
export const cacheServiceFactory: ServiceFactoryCompat<
CacheService,
'plugin',
undefined
>;
// @public (undocumented)
export interface PluginCacheManager {
packages/backend-defaults/api-report-database.md
+4 -3
View File
@@ -8,7 +8,7 @@ import { DatabaseService } from '@backstage/backend-plugin-api';
import { LifecycleService } from '@backstage/backend-plugin-api';
import { LoggerService } from '@backstage/backend-plugin-api';
import { PluginMetadataService } from '@backstage/backend-plugin-api';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
// @public
export class DatabaseManager implements LegacyRootDatabaseService {
@@ -32,9 +32,10 @@ export type DatabaseManagerOptions = {
};
// @public
export const databaseServiceFactory: () => ServiceFactory<
export const databaseServiceFactory: ServiceFactoryCompat<
DatabaseService,
'plugin'
'plugin',
undefined
>;
// @public @deprecated
packages/backend-defaults/api-report-discovery.md
+4 -3
View File
@@ -5,12 +5,13 @@
```ts
import { Config } from '@backstage/config';
import { DiscoveryService } from '@backstage/backend-plugin-api';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
// @public
export const discoveryServiceFactory: () => ServiceFactory<
export const discoveryServiceFactory: ServiceFactoryCompat<
DiscoveryService,
'plugin'
'plugin',
undefined
>;
// @public
packages/backend-defaults/api-report-httpAuth.md
+4 -3
View File
@@ -4,12 +4,13 @@
```ts
import { HttpAuthService } from '@backstage/backend-plugin-api';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
// @public
export const httpAuthServiceFactory: () => ServiceFactory<
export const httpAuthServiceFactory: ServiceFactoryCompat<
HttpAuthService,
'plugin'
'plugin',
undefined
>;
// (No @packageDocumentation comment for this package)
packages/backend-defaults/api-report-httpRouter.md
+4 -3
View File
@@ -7,7 +7,7 @@ import { HttpRouterService } from '@backstage/backend-plugin-api';
import { HumanDuration } from '@backstage/types';
import { LifecycleService } from '@backstage/backend-plugin-api';
import { RequestHandler } from 'express';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
// @public
export function createLifecycleMiddleware(
@@ -15,9 +15,10 @@ export function createLifecycleMiddleware(
): RequestHandler;
// @public
export const httpRouterServiceFactory: () => ServiceFactory<
export const httpRouterServiceFactory: ServiceFactoryCompat<
HttpRouterService,
'plugin'
'plugin',
undefined
>;
// @public
packages/backend-defaults/api-report-lifecycle.md
+4 -3
View File
@@ -4,12 +4,13 @@
```ts
import { LifecycleService } from '@backstage/backend-plugin-api';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
// @public
export const lifecycleServiceFactory: () => ServiceFactory<
export const lifecycleServiceFactory: ServiceFactoryCompat<
LifecycleService,
'plugin'
'plugin',
undefined
>;
// (No @packageDocumentation comment for this package)
packages/backend-defaults/api-report-logger.md
+4 -3
View File
@@ -4,12 +4,13 @@
```ts
import { LoggerService } from '@backstage/backend-plugin-api';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
// @public
export const loggerServiceFactory: () => ServiceFactory<
export const loggerServiceFactory: ServiceFactoryCompat<
LoggerService,
'plugin'
'plugin',
undefined
>;
// (No @packageDocumentation comment for this package)
packages/backend-defaults/api-report-permissions.md
+4 -3
View File
@@ -4,12 +4,13 @@
```ts
import { PermissionsService } from '@backstage/backend-plugin-api';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
// @public
export const permissionsServiceFactory: () => ServiceFactory<
export const permissionsServiceFactory: ServiceFactoryCompat<
PermissionsService,
'plugin'
'plugin',
undefined
>;
// (No @packageDocumentation comment for this package)
packages/backend-defaults/api-report-rootConfig.md
+6 -4
View File
@@ -8,7 +8,7 @@ import { ConfigSchema } from '@backstage/config-loader';
import { LoggerService } from '@backstage/backend-plugin-api';
import { RemoteConfigSourceOptions } from '@backstage/config-loader';
import { RootConfigService } from '@backstage/backend-plugin-api';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
// @public (undocumented)
export function createConfigSecretEnumerator(options: {
@@ -26,9 +26,11 @@ export interface RootConfigFactoryOptions {
}
// @public (undocumented)
export const rootConfigServiceFactory: (
options?: RootConfigFactoryOptions | undefined,
) => ServiceFactory<RootConfigService, 'root'>;
export const rootConfigServiceFactory: ServiceFactoryCompat<
RootConfigService,
'root',
RootConfigFactoryOptions
>;
// (No @packageDocumentation comment for this package)
```
packages/backend-defaults/api-report-rootHealth.md
+4 -3
View File
@@ -4,12 +4,13 @@
```ts
import { RootHealthService } from '@backstage/backend-plugin-api';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
// @public (undocumented)
export const rootHealthServiceFactory: () => ServiceFactory<
export const rootHealthServiceFactory: ServiceFactoryCompat<
RootHealthService,
'root'
'root',
undefined
>;
// (No @packageDocumentation comment for this package)
packages/backend-defaults/api-report-rootHttpRouter.md
+6 -4
View File
@@ -19,7 +19,7 @@ import { RequestListener } from 'http';
import { RootConfigService } from '@backstage/backend-plugin-api';
import { RootHttpRouterService } from '@backstage/backend-plugin-api';
import type { Server } from 'node:http';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
// @public
export function createHttpServer(
@@ -141,9 +141,11 @@ export type RootHttpRouterFactoryOptions = {
};
// @public (undocumented)
export const rootHttpRouterServiceFactory: (
options?: RootHttpRouterFactoryOptions | undefined,
) => ServiceFactory<RootHttpRouterService, 'root'>;
export const rootHttpRouterServiceFactory: ServiceFactoryCompat<
RootHttpRouterService,
'root',
RootHttpRouterFactoryOptions
>;
// (No @packageDocumentation comment for this package)
```
packages/backend-defaults/api-report-rootLifecycle.md
+4 -3
View File
@@ -4,12 +4,13 @@
```ts
import { RootLifecycleService } from '@backstage/backend-plugin-api';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
// @public
export const rootLifecycleServiceFactory: () => ServiceFactory<
export const rootLifecycleServiceFactory: ServiceFactoryCompat<
RootLifecycleService,
'root'
'root',
undefined
>;
// (No @packageDocumentation comment for this package)
packages/backend-defaults/api-report-rootLogger.md
+4 -3
View File
@@ -7,13 +7,14 @@ import { Format } from 'logform';
import { JsonObject } from '@backstage/types';
import { LoggerService } from '@backstage/backend-plugin-api';
import { RootLoggerService } from '@backstage/backend-plugin-api';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
import { transport } from 'winston';
// @public
export const rootLoggerServiceFactory: () => ServiceFactory<
export const rootLoggerServiceFactory: ServiceFactoryCompat<
RootLoggerService,
'root'
'root',
undefined
>;
// @public
packages/backend-defaults/api-report-scheduler.md
+4 -3
View File
@@ -6,7 +6,7 @@
import { DatabaseService } from '@backstage/backend-plugin-api';
import { LoggerService } from '@backstage/backend-plugin-api';
import { SchedulerService } from '@backstage/backend-plugin-api';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
// @public
export class DefaultSchedulerService {
@@ -18,9 +18,10 @@ export class DefaultSchedulerService {
}
// @public
export const schedulerServiceFactory: () => ServiceFactory<
export const schedulerServiceFactory: ServiceFactoryCompat<
SchedulerService,
'plugin'
'plugin',
undefined
>;
// (No @packageDocumentation comment for this package)
packages/backend-defaults/api-report-urlReader.md
+4 -3
View File
@@ -21,7 +21,7 @@ import { GitLabIntegration } from '@backstage/integration';
import { HarnessIntegration } from '@backstage/integration';
import { LoggerService } from '@backstage/backend-plugin-api';
import { Readable } from 'stream';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
import { UrlReaderService } from '@backstage/backend-plugin-api';
import { UrlReaderServiceReadTreeOptions } from '@backstage/backend-plugin-api';
import { UrlReaderServiceReadTreeResponse } from '@backstage/backend-plugin-api';
@@ -426,9 +426,10 @@ export class UrlReaders {
}
// @public
export const urlReaderServiceFactory: () => ServiceFactory<
export const urlReaderServiceFactory: ServiceFactoryCompat<
UrlReaderService,
'plugin'
'plugin',
undefined
>;
// @public
packages/backend-defaults/api-report-userInfo.md
+4 -3
View File
@@ -3,13 +3,14 @@
> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
```ts
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
import { UserInfoService } from '@backstage/backend-plugin-api';
// @public
export const userInfoServiceFactory: () => ServiceFactory<
export const userInfoServiceFactory: ServiceFactoryCompat<
UserInfoService,
'plugin'
'plugin',
undefined
>;
// (No @packageDocumentation comment for this package)
packages/backend-dynamic-feature-service/api-report.md
+17 -11
View File
@@ -28,7 +28,7 @@ import { PluginEndpointDiscovery } from '@backstage/backend-common';
import { PluginTaskScheduler } from '@backstage/backend-tasks';
import { RootLoggerService } from '@backstage/backend-plugin-api';
import { Router } from 'express';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
import { ServiceRef } from '@backstage/backend-plugin-api';
import { TaskRunner } from '@backstage/backend-tasks';
import { TemplateAction } from '@backstage/plugin-scaffolder-node';
@@ -114,18 +114,20 @@ export interface DynamicPluginsFactoryOptions {
}
// @public (undocumented)
export const dynamicPluginsFeatureDiscoveryServiceFactory: () => ServiceFactory<
export const dynamicPluginsFeatureDiscoveryServiceFactory: ServiceFactoryCompat<
FeatureDiscoveryService,
'root'
'root',
undefined
>;
// @public (undocumented)
export const dynamicPluginsFrontendSchemas: BackendFeatureCompat;
// @public (undocumented)
export const dynamicPluginsRootLoggerServiceFactory: () => ServiceFactory<
export const dynamicPluginsRootLoggerServiceFactory: ServiceFactoryCompat<
RootLoggerService,
'root'
'root',
undefined
>;
// @public (undocumented)
@@ -142,14 +144,18 @@ export interface DynamicPluginsSchemasService {
}
// @public (undocumented)
export const dynamicPluginsSchemasServiceFactory: (
options?: DynamicPluginsSchemasOptions | undefined,
) => ServiceFactory<DynamicPluginsSchemasService, 'root'>;
export const dynamicPluginsSchemasServiceFactory: ServiceFactoryCompat<
DynamicPluginsSchemasService,
'root',
DynamicPluginsSchemasOptions
>;
// @public (undocumented)
export const dynamicPluginsServiceFactory: (
options?: DynamicPluginsFactoryOptions | undefined,
) => ServiceFactory<DynamicPluginProvider, 'root'>;
export const dynamicPluginsServiceFactory: ServiceFactoryCompat<
DynamicPluginProvider,
'root',
DynamicPluginsFactoryOptions
>;
// @public (undocumented)
export const dynamicPluginsServiceRef: ServiceRef<
packages/backend-plugin-api/api-report.md
+25 -9
View File
@@ -258,9 +258,9 @@ export function createServiceFactory<
TOpts extends object | undefined = undefined,
>(
options: RootServiceFactoryOptions<TService, TImpl, TDeps>,
): () => ServiceFactory<TService, 'root'>;
): ServiceFactoryCompat<TService, 'root'>;
// @public
// @public @deprecated
export function createServiceFactory<
TService,
TImpl extends TService,
@@ -272,7 +272,7 @@ export function createServiceFactory<
options: (
options?: TOpts,
) => RootServiceFactoryOptions<TService, TImpl, TDeps>,
): (options?: TOpts) => ServiceFactory<TService, 'root'>;
): ServiceFactoryCompat<TService, 'root', TOpts>;
// @public
export function createServiceFactory<
@@ -285,9 +285,9 @@ export function createServiceFactory<
TOpts extends object | undefined = undefined,
>(
options: PluginServiceFactoryOptions<TService, TContext, TImpl, TDeps>,
): () => ServiceFactory<TService, 'plugin'>;
): ServiceFactoryCompat<TService, 'plugin'>;
// @public
// @public @deprecated
export function createServiceFactory<
TService,
TImpl extends TService,
@@ -300,7 +300,7 @@ export function createServiceFactory<
options: (
options?: TOpts,
) => PluginServiceFactoryOptions<TService, TContext, TImpl, TDeps>,
): (options?: TOpts) => ServiceFactory<TService, 'plugin'>;
): ServiceFactoryCompat<TService, 'plugin', TOpts>;
// @public
export function createServiceRef<TService>(
@@ -644,7 +644,19 @@ export interface ServiceFactory<
service: ServiceRef<TService, TScope>;
}
// @public
// @public @deprecated (undocumented)
export interface ServiceFactoryCompat<
TService = unknown,
TScope extends 'plugin' | 'root' = 'plugin' | 'root',
TOpts extends object | undefined = undefined,
> extends ServiceFactory<TService, TScope> {
// @deprecated (undocumented)
(
...options: undefined extends TOpts ? [] : [options?: TOpts]
): ServiceFactory<TService, TScope>;
}
// @public @deprecated
export type ServiceFactoryOrFunction = ServiceFactory | (() => ServiceFactory);
// @public
@@ -667,9 +679,13 @@ export type ServiceRefConfig<
// @public (undocumented)
export interface ServiceRefOptions<TService, TScope extends 'root' | 'plugin'> {
// (undocumented)
defaultFactory?: (
defaultFactory?(
service: ServiceRef<TService, TScope>,
) => Promise<ServiceFactoryOrFunction>;
): Promise<ServiceFactory>;
// @deprecated (undocumented)
defaultFactory?(
service: ServiceRef<TService, TScope>,
): Promise<() => ServiceFactory>;
// (undocumented)
id: string;
// (undocumented)
packages/backend-plugin-api/src/services/system/index.ts
+1
View File
@@ -21,5 +21,6 @@ export type {
PluginServiceFactoryOptions,
RootServiceFactoryOptions,
ServiceFactoryOrFunction,
ServiceFactoryCompat,
} from './types';
export { createServiceRef, createServiceFactory } from './types';
packages/backend-plugin-api/src/services/system/types.ts
+47 -12
View File
@@ -55,6 +55,23 @@ export interface ServiceFactory<
service: ServiceRef<TService, TScope>;
}
/**
* @public
* @deprecated This type exists only as a helper for old code that relied on `createServiceFactory` to return `() => ServiceFactory` instead of `ServiceFactory`. You should remove the `()` parentheses at the end of your usages. This type will be removed in a future release.
*/
export interface ServiceFactoryCompat<
TService = unknown,
TScope extends 'plugin' | 'root' = 'plugin' | 'root',
TOpts extends object | undefined = undefined,
> extends ServiceFactory<TService, TScope> {
/**
* @deprecated Callable service factories will be removed in a future release, please re-implement the service factory using the available APIs instead. If no options are being passed, you can simply remove the trailing `()`.
*/
(
...options: undefined extends TOpts ? [] : [options?: TOpts]
): ServiceFactory<TService, TScope>;
}
/** @internal */
export interface InternalServiceFactory<
TService = unknown,
@@ -73,6 +90,7 @@ export interface InternalServiceFactory<
/**
* Represents either a {@link ServiceFactory} or a function that returns one.
*
* @deprecated The support for service factory functions is deprecated and will be removed.
* @public
*/
export type ServiceFactoryOrFunction = ServiceFactory | (() => ServiceFactory);
@@ -81,9 +99,15 @@ export type ServiceFactoryOrFunction = ServiceFactory | (() => ServiceFactory);
export interface ServiceRefOptions<TService, TScope extends 'root' | 'plugin'> {
id: string;
scope?: TScope;
defaultFactory?: (
defaultFactory?(
service: ServiceRef<TService, TScope>,
) => Promise<ServiceFactoryOrFunction>;
): Promise<ServiceFactory>;
/**
* @deprecated The defaultFactory must return a plain `ServiceFactory` object, support for returning a function will be removed.
*/
defaultFactory?(
service: ServiceRef<TService, TScope>,
): Promise<() => ServiceFactory>;
}
/**
@@ -198,10 +222,14 @@ export function createServiceFactory<
TOpts extends object | undefined = undefined,
>(
options: RootServiceFactoryOptions<TService, TImpl, TDeps>,
): () => ServiceFactory<TService, 'root'>;
): ServiceFactoryCompat<TService, 'root'>;
/**
* Creates a root scoped service factory with optional options.
*
* @deprecated The ability to define options for service factories is deprecated
* and will be removed. Please use the non-callback form of createServiceFactory
* and provide an API that allows for a simple re-implementation of the service
* factory instead.
* @public
* @param options - The service factory configuration.
*/
@@ -214,7 +242,7 @@ export function createServiceFactory<
options: (
options?: TOpts,
) => RootServiceFactoryOptions<TService, TImpl, TDeps>,
): (options?: TOpts) => ServiceFactory<TService, 'root'>;
): ServiceFactoryCompat<TService, 'root', TOpts>;
/**
* Creates a plugin scoped service factory without options.
*
@@ -229,10 +257,14 @@ export function createServiceFactory<
TOpts extends object | undefined = undefined,
>(
options: PluginServiceFactoryOptions<TService, TContext, TImpl, TDeps>,
): () => ServiceFactory<TService, 'plugin'>;
): ServiceFactoryCompat<TService, 'plugin'>;
/**
* Creates a plugin scoped service factory with optional options.
*
* @deprecated The ability to define options for service factories is deprecated
* and will be removed. Please use the non-callback form of createServiceFactory
* and provide an API that allows for a simple re-implementation of the service
* factory instead.
* @public
* @param options - The service factory configuration.
*/
@@ -246,7 +278,7 @@ export function createServiceFactory<
options: (
options?: TOpts,
) => PluginServiceFactoryOptions<TService, TContext, TImpl, TDeps>,
): (options?: TOpts) => ServiceFactory<TService, 'plugin'>;
): ServiceFactoryCompat<TService, 'plugin', TOpts>;
export function createServiceFactory<
TService,
TImpl extends TService,
@@ -263,13 +295,13 @@ export function createServiceFactory<
) => PluginServiceFactoryOptions<TService, TContext, TImpl, TDeps>)
| (() => RootServiceFactoryOptions<TService, TImpl, TDeps>)
| (() => PluginServiceFactoryOptions<TService, TContext, TImpl, TDeps>),
): (options: TOpts) => ServiceFactory {
): ServiceFactoryCompat<TService, 'root' | 'plugin', TOpts> {
const configCallback =
typeof options === 'function' ? options : () => options;
const factory = (
o: TOpts,
o?: TOpts,
): InternalServiceFactory<TService, 'plugin' | 'root'> => {
const anyConf = configCallback(o);
const anyConf = configCallback(o!);
if (anyConf.service.scope === 'root') {
const c = anyConf as RootServiceFactoryOptions<TService, TImpl, TDeps>;
return {
@@ -303,7 +335,10 @@ export function createServiceFactory<
};
};
factory.$$type = '@backstage/BackendFeatureFactory';
return factory;
// This constructs the `ServiceFactoryCompat` type, which is both a plain
// factory object as well as a function that can be called to construct a
// factory, potentially with options. In the future only the plain factory
// form will be supported, but for now we need to allow callers to call the
// factory too.
return Object.assign(factory, factory(undefined as TOpts));
}
packages/backend-test-utils/api-report.md
+27 -24
View File
@@ -38,6 +38,7 @@ import { RootLifecycleService } from '@backstage/backend-plugin-api';
import { RootLoggerService } from '@backstage/backend-plugin-api';
import { SchedulerService } from '@backstage/backend-plugin-api';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
import { ServiceRef } from '@backstage/backend-plugin-api';
import { TokenManagerService } from '@backstage/backend-plugin-api';
import { UrlReaderService } from '@backstage/backend-plugin-api';
@@ -155,7 +156,7 @@ export namespace mockServices {
// (undocumented)
export namespace auth {
const // (undocumented)
factory: () => ServiceFactory<AuthService, 'plugin'>;
factory: ServiceFactoryCompat<AuthService, 'plugin', undefined>;
const // (undocumented)
mock: (
partialImpl?: Partial<AuthService> | undefined,
@@ -164,7 +165,7 @@ export namespace mockServices {
// (undocumented)
export namespace cache {
const // (undocumented)
factory: () => ServiceFactory<CacheService, 'plugin'>;
factory: ServiceFactoryCompat<CacheService, 'plugin', undefined>;
const // (undocumented)
mock: (
partialImpl?: Partial<CacheService> | undefined,
@@ -173,7 +174,7 @@ export namespace mockServices {
// (undocumented)
export namespace database {
const // (undocumented)
factory: () => ServiceFactory<DatabaseService, 'plugin'>;
factory: ServiceFactoryCompat<DatabaseService, 'plugin', undefined>;
const // (undocumented)
mock: (
partialImpl?: Partial<DatabaseService> | undefined,
@@ -184,7 +185,7 @@ export namespace mockServices {
// (undocumented)
export namespace discovery {
const // (undocumented)
factory: () => ServiceFactory<DiscoveryService, 'plugin'>;
factory: ServiceFactoryCompat<DiscoveryService, 'plugin', undefined>;
const // (undocumented)
mock: (
partialImpl?: Partial<DiscoveryService> | undefined,
@@ -193,7 +194,7 @@ export namespace mockServices {
// (undocumented)
export namespace events {
const // (undocumented)
factory: () => ServiceFactory<EventsService, 'plugin'>;
factory: ServiceFactoryCompat<EventsService, 'plugin', undefined>;
const // (undocumented)
mock: (
partialImpl?: Partial<EventsService> | undefined,
@@ -205,13 +206,13 @@ export namespace mockServices {
}): HttpAuthService;
// (undocumented)
export namespace httpAuth {
const factory: (
options?:
| {
defaultCredentials?: BackstageCredentials | undefined;
}
| undefined,
) => ServiceFactory<HttpAuthService, 'plugin'>;
const factory: ServiceFactoryCompat<
HttpAuthService,
'plugin',
{
defaultCredentials?: BackstageCredentials | undefined;
}
>;
const // (undocumented)
mock: (
partialImpl?: Partial<HttpAuthService> | undefined,
@@ -220,7 +221,7 @@ export namespace mockServices {
// (undocumented)
export namespace httpRouter {
const // (undocumented)
factory: () => ServiceFactory<HttpRouterService, 'plugin'>;
factory: ServiceFactoryCompat<HttpRouterService, 'plugin', undefined>;
const // (undocumented)
mock: (
partialImpl?: Partial<HttpRouterService> | undefined,
@@ -240,7 +241,7 @@ export namespace mockServices {
// (undocumented)
export namespace lifecycle {
const // (undocumented)
factory: () => ServiceFactory<LifecycleService, 'plugin'>;
factory: ServiceFactoryCompat<LifecycleService, 'plugin', undefined>;
const // (undocumented)
mock: (
partialImpl?: Partial<LifecycleService> | undefined,
@@ -249,7 +250,7 @@ export namespace mockServices {
// (undocumented)
export namespace logger {
const // (undocumented)
factory: () => ServiceFactory<LoggerService, 'plugin'>;
factory: ServiceFactoryCompat<LoggerService, 'plugin', undefined>;
const // (undocumented)
mock: (
partialImpl?: Partial<LoggerService> | undefined,
@@ -258,7 +259,7 @@ export namespace mockServices {
// (undocumented)
export namespace permissions {
const // (undocumented)
factory: () => ServiceFactory<PermissionsService, 'plugin'>;
factory: ServiceFactoryCompat<PermissionsService, 'plugin', undefined>;
const // (undocumented)
mock: (
partialImpl?: Partial<PermissionsService> | undefined,
@@ -280,7 +281,7 @@ export namespace mockServices {
// (undocumented)
export namespace rootHealth {
const // (undocumented)
factory: () => ServiceFactory<RootHealthService, 'root'>;
factory: ServiceFactoryCompat<RootHealthService, 'root', undefined>;
const // (undocumented)
mock: (
partialImpl?: Partial<RootHealthService> | undefined,
@@ -289,9 +290,11 @@ export namespace mockServices {
// (undocumented)
export namespace rootHttpRouter {
const // (undocumented)
factory: (
options?: RootHttpRouterFactoryOptions | undefined,
) => ServiceFactory<RootHttpRouterService, 'root'>;
factory: ServiceFactoryCompat<
RootHttpRouterService,
'root',
RootHttpRouterFactoryOptions
>;
const // (undocumented)
mock: (
partialImpl?: Partial<RootHttpRouterService> | undefined,
@@ -300,7 +303,7 @@ export namespace mockServices {
// (undocumented)
export namespace rootLifecycle {
const // (undocumented)
factory: () => ServiceFactory<RootLifecycleService, 'root'>;
factory: ServiceFactoryCompat<RootLifecycleService, 'root', undefined>;
const // (undocumented)
mock: (
partialImpl?: Partial<RootLifecycleService> | undefined,
@@ -326,7 +329,7 @@ export namespace mockServices {
// (undocumented)
export namespace scheduler {
const // (undocumented)
factory: () => ServiceFactory<SchedulerService, 'plugin'>;
factory: ServiceFactoryCompat<SchedulerService, 'plugin', undefined>;
const // (undocumented)
mock: (
partialImpl?: Partial<SchedulerService> | undefined,
@@ -346,7 +349,7 @@ export namespace mockServices {
// (undocumented)
export namespace urlReader {
const // (undocumented)
factory: () => ServiceFactory<UrlReaderService, 'plugin'>;
factory: ServiceFactoryCompat<UrlReaderService, 'plugin', undefined>;
const // (undocumented)
mock: (
partialImpl?: Partial<UrlReaderService> | undefined,
@@ -357,7 +360,7 @@ export namespace mockServices {
): UserInfoService;
// (undocumented)
export namespace userInfo {
const factory: () => ServiceFactory<UserInfoService, 'plugin'>;
const factory: ServiceFactoryCompat<UserInfoService, 'plugin', undefined>;
const // (undocumented)
mock: (
partialImpl?: Partial<UserInfoService> | undefined,
plugins/events-node/api-report.md
+4 -3
View File
@@ -4,7 +4,7 @@
```ts
import { LoggerService } from '@backstage/backend-plugin-api';
import { ServiceFactory } from '@backstage/backend-plugin-api';
import { ServiceFactoryCompat } from '@backstage/backend-plugin-api';
import { ServiceRef } from '@backstage/backend-plugin-api';
// @public
@@ -63,9 +63,10 @@ export interface EventsService {
export type EventsServiceEventHandler = (params: EventParams) => Promise<void>;
// @public (undocumented)
export const eventsServiceFactory: () => ServiceFactory<
export const eventsServiceFactory: ServiceFactoryCompat<
EventsService,
'plugin'
'plugin',
undefined
>;
// @public