backend-plugin-api: suffix all service interfaces with *Service

Co-authored-by: Johan Haals <johan.haals@gmail.com>
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/sweet-olives-return.md

@@ -0,0 +1,5 @@
+---
+'@backstage/backend-plugin-api': minor
+---
+
+**BREAKING**: All service interfaces are now suffixed with `*Service`.

packages/backend-app-api/src/services/implementations/rootLoggerService.ts

@@ -17,12 +17,12 @@
 import { createRootLogger } from '@backstage/backend-common';
 import {
   createServiceFactory,
-  Logger,
+  LoggerService,
   coreServices,
 } from '@backstage/backend-plugin-api';
 import { Logger as WinstonLogger } from 'winston';
 
-class BackstageLogger implements Logger {
+class BackstageLogger implements LoggerService {
   static fromWinston(logger: WinstonLogger): BackstageLogger {
     return new BackstageLogger(logger);
   }
@@ -33,7 +33,7 @@ class BackstageLogger implements Logger {
     this.winston.info(message, ...meta);
   }
 
-  child(fields: { [name: string]: string }): Logger {
+  child(fields: { [name: string]: string }): LoggerService {
     return new BackstageLogger(this.winston.child(fields));
   }
 }

packages/backend-plugin-api/api-report.md

@@ -5,7 +5,7 @@
 ```ts
 import { Config } from '@backstage/config';
 import { Handler } from 'express';
-import { Logger as Logger_2 } from 'winston';
+import { Logger } from 'winston';
 import { PermissionAuthorizer } from '@backstage/plugin-permission-common';
 import { PermissionEvaluator } from '@backstage/plugin-permission-common';
 import { PluginCacheManager } from '@backstage/backend-common';
@@ -24,16 +24,6 @@ export interface BackendFeature {
   register(reg: BackendRegistrationPoints): void;
 }
 
-// @public (undocumented)
-export interface BackendLifecycle {
-  addShutdownHook(options: BackendLifecycleShutdownHook): void;
-}
-
-// @public (undocumented)
-export type BackendLifecycleShutdownHook = {
-  fn: () => void | Promise<void>;
-};
-
 // @public (undocumented)
 export interface BackendModuleConfig<TOptions> {
   // (undocumented)
@@ -75,9 +65,15 @@ export interface BackendRegistrationPoints {
   }): void;
 }
 
+// @public (undocumented)
+export type CacheService = PluginCacheManager;
+
 // @public (undocumented)
 const cacheServiceRef: ServiceRef<PluginCacheManager, 'plugin'>;
 
+// @public (undocumented)
+export type ConfigService = Config;
+
 // @public (undocumented)
 const configServiceRef: ServiceRef<Config, 'root'>;
 
@@ -164,9 +160,15 @@ export function createServiceRef<T>(options: {
   ) => Promise<ServiceFactory<T> | (() => ServiceFactory<T>)>;
 }): ServiceRef<T, 'root'>;
 
+// @public (undocumented)
+export type DatabaseService = PluginDatabaseManager;
+
 // @public (undocumented)
 const databaseServiceRef: ServiceRef<PluginDatabaseManager, 'plugin'>;
 
+// @public (undocumented)
+export type DiscoveryService = PluginEndpointDiscovery;
+
 // @public (undocumented)
 const discoveryServiceRef: ServiceRef<PluginEndpointDiscovery, 'plugin'>;
 
@@ -188,42 +190,58 @@ export interface HttpRouterService {
 const httpRouterServiceRef: ServiceRef<HttpRouterService, 'plugin'>;
 
 // @public (undocumented)
-const lifecycleServiceRef: ServiceRef<BackendLifecycle, 'plugin'>;
+export interface LifecycleService {
+  addShutdownHook(options: LifecycleServiceShutdownHook): void;
+}
 
 // @public (undocumented)
-export interface Logger {
+const lifecycleServiceRef: ServiceRef<LifecycleService, 'plugin'>;
+
+// @public (undocumented)
+export type LifecycleServiceShutdownHook = {
+  fn: () => void | Promise<void>;
+};
+
+// @public (undocumented)
+export interface LoggerService {
   // (undocumented)
-  child(fields: { [name: string]: string }): Logger;
+  child(fields: { [name: string]: string }): LoggerService;
   // (undocumented)
   info(message: string): void;
 }
 
 // @public (undocumented)
-const loggerServiceRef: ServiceRef<Logger, 'plugin'>;
+const loggerServiceRef: ServiceRef<LoggerService, 'plugin'>;
 
 // @public (undocumented)
 export function loggerToWinstonLogger(
-  logger: Logger,
+  logger: LoggerService,
   opts?: TransportStreamOptions,
-): Logger_2;
+): Logger;
 
 // @public (undocumented)
-const permissionsServiceRef: ServiceRef<
-  PermissionAuthorizer | PermissionEvaluator,
-  'plugin'
->;
+export type PermissionsService = PermissionEvaluator | PermissionAuthorizer;
 
 // @public (undocumented)
-export interface PluginMetadata {
+const permissionsServiceRef: ServiceRef<PermissionsService, 'plugin'>;
+
+// @public (undocumented)
+export interface PluginMetadataService {
   // (undocumented)
   getId(): string;
 }
 
 // @public (undocumented)
-const pluginMetadataServiceRef: ServiceRef<PluginMetadata, 'plugin'>;
+const pluginMetadataServiceRef: ServiceRef<PluginMetadataService, 'plugin'>;
 
 // @public (undocumented)
-const rootLoggerServiceRef: ServiceRef<Logger, 'root'>;
+export type RootLoggerService = LoggerService;
+
+// @public (undocumented)
+const rootLoggerServiceRef: ServiceRef<LoggerService, 'root'>;
+
+// @public (undocumented)
+export type SchedulerService = PluginTaskScheduler;
 
 // @public (undocumented)
 const schedulerServiceRef: ServiceRef<PluginTaskScheduler, 'plugin'>;
@@ -267,6 +285,9 @@ export type ServiceRef<
   $$ref: 'service';
 };
 
+// @public (undocumented)
+export type TokenManagerService = TokenManager;
+
 // @public (undocumented)
 const tokenManagerServiceRef: ServiceRef<TokenManager, 'plugin'>;
 
@@ -275,6 +296,9 @@ export type TypesToServiceRef<T> = {
   [key in keyof T]: ServiceRef<T[key]>;
 };
 
+// @public (undocumented)
+export type UrlReaderService = UrlReader;
+
 // @public (undocumented)
 const urlReaderServiceRef: ServiceRef<UrlReader, 'plugin'>;
 ```

packages/backend-plugin-api/src/services/definitions/cacheServiceRef.ts

@@ -17,9 +17,12 @@
 import { createServiceRef } from '../system/types';
 import { PluginCacheManager } from '@backstage/backend-common';
 
+/** @public */
+export type CacheService = PluginCacheManager;
+
 /**
  * @public
  */
-export const cacheServiceRef = createServiceRef<PluginCacheManager>({
+export const cacheServiceRef = createServiceRef<CacheService>({
   id: 'core.cache',
 });

packages/backend-plugin-api/src/services/definitions/configServiceRef.ts

@@ -20,7 +20,12 @@ import { createServiceRef } from '../system/types';
 /**
  * @public
  */
-export const configServiceRef = createServiceRef<Config>({
+export type ConfigService = Config;
+
+/**
+ * @public
+ */
+export const configServiceRef = createServiceRef<ConfigService>({
   id: 'core.root.config',
   scope: 'root',
 });

packages/backend-plugin-api/src/services/definitions/databaseServiceRef.ts

@@ -17,9 +17,12 @@
 import { PluginDatabaseManager } from '@backstage/backend-common';
 import { createServiceRef } from '../system/types';
 
+/** @public */
+export type DatabaseService = PluginDatabaseManager;
+
 /**
  * @public
  */
-export const databaseServiceRef = createServiceRef<PluginDatabaseManager>({
+export const databaseServiceRef = createServiceRef<DatabaseService>({
   id: 'core.database',
 });

packages/backend-plugin-api/src/services/definitions/discoveryServiceRef.ts

@@ -17,9 +17,12 @@
 import { createServiceRef } from '../system/types';
 import { PluginEndpointDiscovery } from '@backstage/backend-common';
 
+/** @public */
+export type DiscoveryService = PluginEndpointDiscovery;
+
 /**
  * @public
  */
-export const discoveryServiceRef = createServiceRef<PluginEndpointDiscovery>({
+export const discoveryServiceRef = createServiceRef<DiscoveryService>({
   id: 'core.discovery',
 });

packages/backend-plugin-api/src/services/definitions/index.ts

@@ -17,10 +17,19 @@
 import * as coreServices from './coreServices';
 
 export { coreServices };
+export type { CacheService } from './cacheServiceRef';
+export type { ConfigService } from './configServiceRef';
+export type { DatabaseService } from './databaseServiceRef';
+export type { DiscoveryService } from './discoveryServiceRef';
 export type { HttpRouterService } from './httpRouterServiceRef';
-export type { Logger } from './loggerServiceRef';
 export type {
-  BackendLifecycle,
-  BackendLifecycleShutdownHook,
+  LifecycleService,
+  LifecycleServiceShutdownHook,
 } from './lifecycleServiceRef';
-export type { PluginMetadata } from './pluginMetadataServiceRef';
+export type { LoggerService } from './loggerServiceRef';
+export type { PermissionsService } from './permissionsServiceRef';
+export type { PluginMetadataService } from './pluginMetadataServiceRef';
+export type { RootLoggerService } from './rootLoggerServiceRef';
+export type { SchedulerService } from './schedulerServiceRef';
+export type { TokenManagerService } from './tokenManagerServiceRef';
+export type { UrlReaderService } from './urlReaderServiceRef';

packages/backend-plugin-api/src/services/definitions/lifecycleServiceRef.ts

@@ -19,24 +19,24 @@ import { createServiceRef } from '../system/types';
 /**
  * @public
  **/
-export type BackendLifecycleShutdownHook = {
+export type LifecycleServiceShutdownHook = {
   fn: () => void | Promise<void>;
 };
 
 /**
  * @public
  **/
-export interface BackendLifecycle {
+export interface LifecycleService {
   /**
    * Register a function to be called when the backend is shutting down.
    */
-  addShutdownHook(options: BackendLifecycleShutdownHook): void;
+  addShutdownHook(options: LifecycleServiceShutdownHook): void;
 }
 
 /**
  * @public
  */
-export const lifecycleServiceRef = createServiceRef<BackendLifecycle>({
+export const lifecycleServiceRef = createServiceRef<LifecycleService>({
   id: 'core.lifecycle',
   scope: 'plugin',
 });

packages/backend-plugin-api/src/services/definitions/loggerServiceRef.ts

@@ -19,14 +19,14 @@ import { createServiceRef } from '../system/types';
 /**
  * @public
  */
-export interface Logger {
+export interface LoggerService {
   info(message: string): void;
-  child(fields: { [name: string]: string }): Logger;
+  child(fields: { [name: string]: string }): LoggerService;
 }
 
 /**
  * @public
  */
-export const loggerServiceRef = createServiceRef<Logger>({
+export const loggerServiceRef = createServiceRef<LoggerService>({
   id: 'core.logger',
 });

packages/backend-plugin-api/src/services/definitions/permissionsServiceRef.ts

@@ -20,11 +20,12 @@ import {
   PermissionEvaluator,
 } from '@backstage/plugin-permission-common';
 
+/** @public */
+export type PermissionsService = PermissionEvaluator | PermissionAuthorizer;
+
 /**
  * @public
  */
-export const permissionsServiceRef = createServiceRef<
-  PermissionEvaluator | PermissionAuthorizer
->({
+export const permissionsServiceRef = createServiceRef<PermissionsService>({
   id: 'core.permissions',
 });

packages/backend-plugin-api/src/services/definitions/pluginMetadataServiceRef.ts

@@ -19,13 +19,15 @@ import { createServiceRef } from '../system/types';
 /**
  * @public
  */
-export interface PluginMetadata {
+export interface PluginMetadataService {
   getId(): string;
 }
 
 /**
  * @public
  */
-export const pluginMetadataServiceRef = createServiceRef<PluginMetadata>({
-  id: 'core.plugin-metadata',
-});
+export const pluginMetadataServiceRef = createServiceRef<PluginMetadataService>(
+  {
+    id: 'core.plugin-metadata',
+  },
+);

packages/backend-plugin-api/src/services/definitions/rootLoggerServiceRef.ts

@@ -15,12 +15,15 @@
  */
 
 import { createServiceRef } from '../system/types';
-import { Logger } from './loggerServiceRef';
+import { LoggerService } from './loggerServiceRef';
+
+/** @public */
+export type RootLoggerService = LoggerService;
 
 /**
  * @public
  */
-export const rootLoggerServiceRef = createServiceRef<Logger>({
+export const rootLoggerServiceRef = createServiceRef<RootLoggerService>({
   id: 'core.root.logger',
   scope: 'root',
 });

packages/backend-plugin-api/src/services/definitions/schedulerServiceRef.ts

@@ -17,9 +17,12 @@
 import { createServiceRef } from '../system/types';
 import { PluginTaskScheduler } from '@backstage/backend-tasks';
 
+/** @public */
+export type SchedulerService = PluginTaskScheduler;
+
 /**
  * @public
  */
-export const schedulerServiceRef = createServiceRef<PluginTaskScheduler>({
+export const schedulerServiceRef = createServiceRef<SchedulerService>({
   id: 'core.scheduler',
 });

packages/backend-plugin-api/src/services/definitions/tokenManagerServiceRef.ts

@@ -17,9 +17,12 @@
 import { createServiceRef } from '../system/types';
 import { TokenManager } from '@backstage/backend-common';
 
+/** @public */
+export type TokenManagerService = TokenManager;
+
 /**
  * @public
  */
-export const tokenManagerServiceRef = createServiceRef<TokenManager>({
+export const tokenManagerServiceRef = createServiceRef<TokenManagerService>({
   id: 'core.tokenManager',
 });

packages/backend-plugin-api/src/services/definitions/urlReaderServiceRef.ts

@@ -17,9 +17,12 @@
 import { createServiceRef } from '../system/types';
 import { UrlReader } from '@backstage/backend-common';
 
+/** @public */
+export type UrlReaderService = UrlReader;
+
 /**
  * @public
  */
-export const urlReaderServiceRef = createServiceRef<UrlReader>({
+export const urlReaderServiceRef = createServiceRef<UrlReaderService>({
   id: 'core.urlReader',
 });

packages/backend-plugin-api/src/services/helpers/loggerToWinstonLogger.ts

@@ -14,13 +14,13 @@
  * limitations under the License.
  */
 
-import { Logger as BackstageLogger } from '../definitions';
+import { LoggerService } from '../definitions';
 import { Logger as WinstonLogger, createLogger } from 'winston';
 import Transport, { TransportStreamOptions } from 'winston-transport';
 
 class BackstageLoggerTransport extends Transport {
   constructor(
-    private readonly backstageLogger: BackstageLogger,
+    private readonly backstageLogger: LoggerService,
     opts?: TransportStreamOptions,
   ) {
     super(opts);
@@ -35,7 +35,7 @@ class BackstageLoggerTransport extends Transport {
 
 /** @public */
 export function loggerToWinstonLogger(
-  logger: BackstageLogger,
+  logger: LoggerService,
   opts?: TransportStreamOptions,
 ): WinstonLogger {
   return createLogger({