From a0251905524ca010538957dfa4ab40b874a4f9f2 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 14 Dec 2022 14:33:33 +0100 Subject: [PATCH] backend-plugin-api: suffix all service interfaces with *Service Co-authored-by: Johan Haals Signed-off-by: Patrik Oldsberg --- .changeset/sweet-olives-return.md | 5 ++ .../implementations/rootLoggerService.ts | 6 +- packages/backend-plugin-api/api-report.md | 72 ++++++++++++------- .../services/definitions/cacheServiceRef.ts | 5 +- .../services/definitions/configServiceRef.ts | 7 +- .../definitions/databaseServiceRef.ts | 5 +- .../definitions/discoveryServiceRef.ts | 5 +- .../src/services/definitions/index.ts | 17 +++-- .../definitions/lifecycleServiceRef.ts | 8 +-- .../services/definitions/loggerServiceRef.ts | 6 +- .../definitions/permissionsServiceRef.ts | 7 +- .../definitions/pluginMetadataServiceRef.ts | 10 +-- .../definitions/rootLoggerServiceRef.ts | 7 +- .../definitions/schedulerServiceRef.ts | 5 +- .../definitions/tokenManagerServiceRef.ts | 5 +- .../definitions/urlReaderServiceRef.ts | 5 +- .../services/helpers/loggerToWinstonLogger.ts | 6 +- 17 files changed, 124 insertions(+), 57 deletions(-) create mode 100644 .changeset/sweet-olives-return.md diff --git a/.changeset/sweet-olives-return.md b/.changeset/sweet-olives-return.md new file mode 100644 index 0000000000..9ce2aa49d1 --- /dev/null +++ b/.changeset/sweet-olives-return.md @@ -0,0 +1,5 @@ +--- +'@backstage/backend-plugin-api': minor +--- + +**BREAKING**: All service interfaces are now suffixed with `*Service`. diff --git a/packages/backend-app-api/src/services/implementations/rootLoggerService.ts b/packages/backend-app-api/src/services/implementations/rootLoggerService.ts index d2bb406adb..064091a122 100644 --- a/packages/backend-app-api/src/services/implementations/rootLoggerService.ts +++ b/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)); } } diff --git a/packages/backend-plugin-api/api-report.md b/packages/backend-plugin-api/api-report.md index 17cae29bff..d3c1292b7e 100644 --- a/packages/backend-plugin-api/api-report.md +++ b/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; -}; - // @public (undocumented) export interface BackendModuleConfig { // (undocumented) @@ -75,9 +65,15 @@ export interface BackendRegistrationPoints { }): void; } +// @public (undocumented) +export type CacheService = PluginCacheManager; + // @public (undocumented) const cacheServiceRef: ServiceRef; +// @public (undocumented) +export type ConfigService = Config; + // @public (undocumented) const configServiceRef: ServiceRef; @@ -164,9 +160,15 @@ export function createServiceRef(options: { ) => Promise | (() => ServiceFactory)>; }): ServiceRef; +// @public (undocumented) +export type DatabaseService = PluginDatabaseManager; + // @public (undocumented) const databaseServiceRef: ServiceRef; +// @public (undocumented) +export type DiscoveryService = PluginEndpointDiscovery; + // @public (undocumented) const discoveryServiceRef: ServiceRef; @@ -188,42 +190,58 @@ export interface HttpRouterService { const httpRouterServiceRef: ServiceRef; // @public (undocumented) -const lifecycleServiceRef: ServiceRef; +export interface LifecycleService { + addShutdownHook(options: LifecycleServiceShutdownHook): void; +} // @public (undocumented) -export interface Logger { +const lifecycleServiceRef: ServiceRef; + +// @public (undocumented) +export type LifecycleServiceShutdownHook = { + fn: () => void | Promise; +}; + +// @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; +const loggerServiceRef: ServiceRef; // @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; + +// @public (undocumented) +export interface PluginMetadataService { // (undocumented) getId(): string; } // @public (undocumented) -const pluginMetadataServiceRef: ServiceRef; +const pluginMetadataServiceRef: ServiceRef; // @public (undocumented) -const rootLoggerServiceRef: ServiceRef; +export type RootLoggerService = LoggerService; + +// @public (undocumented) +const rootLoggerServiceRef: ServiceRef; + +// @public (undocumented) +export type SchedulerService = PluginTaskScheduler; // @public (undocumented) const schedulerServiceRef: ServiceRef; @@ -267,6 +285,9 @@ export type ServiceRef< $$ref: 'service'; }; +// @public (undocumented) +export type TokenManagerService = TokenManager; + // @public (undocumented) const tokenManagerServiceRef: ServiceRef; @@ -275,6 +296,9 @@ export type TypesToServiceRef = { [key in keyof T]: ServiceRef; }; +// @public (undocumented) +export type UrlReaderService = UrlReader; + // @public (undocumented) const urlReaderServiceRef: ServiceRef; ``` diff --git a/packages/backend-plugin-api/src/services/definitions/cacheServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/cacheServiceRef.ts index 0b572f1712..aff913b06a 100644 --- a/packages/backend-plugin-api/src/services/definitions/cacheServiceRef.ts +++ b/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({ +export const cacheServiceRef = createServiceRef({ id: 'core.cache', }); diff --git a/packages/backend-plugin-api/src/services/definitions/configServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/configServiceRef.ts index f17c5f57bc..15e9cb9aa6 100644 --- a/packages/backend-plugin-api/src/services/definitions/configServiceRef.ts +++ b/packages/backend-plugin-api/src/services/definitions/configServiceRef.ts @@ -20,7 +20,12 @@ import { createServiceRef } from '../system/types'; /** * @public */ -export const configServiceRef = createServiceRef({ +export type ConfigService = Config; + +/** + * @public + */ +export const configServiceRef = createServiceRef({ id: 'core.root.config', scope: 'root', }); diff --git a/packages/backend-plugin-api/src/services/definitions/databaseServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/databaseServiceRef.ts index b41159dc9e..aaea5d304f 100644 --- a/packages/backend-plugin-api/src/services/definitions/databaseServiceRef.ts +++ b/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({ +export const databaseServiceRef = createServiceRef({ id: 'core.database', }); diff --git a/packages/backend-plugin-api/src/services/definitions/discoveryServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/discoveryServiceRef.ts index 675ac206a2..41505e7756 100644 --- a/packages/backend-plugin-api/src/services/definitions/discoveryServiceRef.ts +++ b/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({ +export const discoveryServiceRef = createServiceRef({ id: 'core.discovery', }); diff --git a/packages/backend-plugin-api/src/services/definitions/index.ts b/packages/backend-plugin-api/src/services/definitions/index.ts index 1ff33362fa..e2f361ff01 100644 --- a/packages/backend-plugin-api/src/services/definitions/index.ts +++ b/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'; diff --git a/packages/backend-plugin-api/src/services/definitions/lifecycleServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/lifecycleServiceRef.ts index 15610e2643..4061cc1da2 100644 --- a/packages/backend-plugin-api/src/services/definitions/lifecycleServiceRef.ts +++ b/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; }; /** * @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({ +export const lifecycleServiceRef = createServiceRef({ id: 'core.lifecycle', scope: 'plugin', }); diff --git a/packages/backend-plugin-api/src/services/definitions/loggerServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/loggerServiceRef.ts index e99bc4e7d4..b135ccc8e6 100644 --- a/packages/backend-plugin-api/src/services/definitions/loggerServiceRef.ts +++ b/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({ +export const loggerServiceRef = createServiceRef({ id: 'core.logger', }); diff --git a/packages/backend-plugin-api/src/services/definitions/permissionsServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/permissionsServiceRef.ts index b13ca9e240..b24b2f5f46 100644 --- a/packages/backend-plugin-api/src/services/definitions/permissionsServiceRef.ts +++ b/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({ id: 'core.permissions', }); diff --git a/packages/backend-plugin-api/src/services/definitions/pluginMetadataServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/pluginMetadataServiceRef.ts index 3af6e54900..4c1ecb130e 100644 --- a/packages/backend-plugin-api/src/services/definitions/pluginMetadataServiceRef.ts +++ b/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({ - id: 'core.plugin-metadata', -}); +export const pluginMetadataServiceRef = createServiceRef( + { + id: 'core.plugin-metadata', + }, +); diff --git a/packages/backend-plugin-api/src/services/definitions/rootLoggerServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/rootLoggerServiceRef.ts index 62e22c53d9..af26ce8899 100644 --- a/packages/backend-plugin-api/src/services/definitions/rootLoggerServiceRef.ts +++ b/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({ +export const rootLoggerServiceRef = createServiceRef({ id: 'core.root.logger', scope: 'root', }); diff --git a/packages/backend-plugin-api/src/services/definitions/schedulerServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/schedulerServiceRef.ts index ca442dd34d..160f2fbb93 100644 --- a/packages/backend-plugin-api/src/services/definitions/schedulerServiceRef.ts +++ b/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({ +export const schedulerServiceRef = createServiceRef({ id: 'core.scheduler', }); diff --git a/packages/backend-plugin-api/src/services/definitions/tokenManagerServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/tokenManagerServiceRef.ts index 6995033e81..4b12acdc58 100644 --- a/packages/backend-plugin-api/src/services/definitions/tokenManagerServiceRef.ts +++ b/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({ +export const tokenManagerServiceRef = createServiceRef({ id: 'core.tokenManager', }); diff --git a/packages/backend-plugin-api/src/services/definitions/urlReaderServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/urlReaderServiceRef.ts index ebb32f1aed..4fc3680763 100644 --- a/packages/backend-plugin-api/src/services/definitions/urlReaderServiceRef.ts +++ b/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({ +export const urlReaderServiceRef = createServiceRef({ id: 'core.urlReader', }); diff --git a/packages/backend-plugin-api/src/services/helpers/loggerToWinstonLogger.ts b/packages/backend-plugin-api/src/services/helpers/loggerToWinstonLogger.ts index b9ccd70d3f..418f669a75 100644 --- a/packages/backend-plugin-api/src/services/helpers/loggerToWinstonLogger.ts +++ b/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({