backend-plugin-api: deprecate service factories with callback form

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/spotty-apricots-tan.md

@@ -0,0 +1,55 @@
+---
+'@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 fooServiceFactory = 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.

packages/backend-app-api/api-report-alpha.md

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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,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

@@ -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,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,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,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

@@ -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,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

@@ -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,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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -257,9 +257,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,
@@ -271,7 +271,7 @@ export function createServiceFactory<
   options: (
     options?: TOpts,
   ) => RootServiceFactoryOptions<TService, TImpl, TDeps>,
-): (options?: TOpts) => ServiceFactory<TService, 'root'>;
+): ServiceFactoryCompat<TService, 'root', TOpts>;
 
 // @public
 export function createServiceFactory<
@@ -284,9 +284,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,
@@ -299,7 +299,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>(
@@ -645,7 +645,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
@@ -668,9 +680,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

@@ -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

@@ -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 You do not need to use this call signature; use the type directly instead by removing the `()` parentheses at the end. This call signature will be removed in a future release.
+   */
+  (
+    ...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

@@ -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,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