From 16054afdeccca5df01bd4d7bc2b56d7f7da0edeb Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 3 Jan 2023 14:46:04 +0100 Subject: [PATCH 1/3] backend-plugin-api: document core service refs Signed-off-by: Patrik Oldsberg --- .changeset/rich-clouds-smile.md | 5 + packages/backend-plugin-api/api-report.md | 78 ++------ .../{cacheServiceRef.ts => CacheService.ts} | 8 - .../{configServiceRef.ts => ConfigService.ts} | 9 - ...tabaseServiceRef.ts => DatabaseService.ts} | 8 - ...overyServiceRef.ts => DiscoveryService.ts} | 9 - ...uterServiceRef.ts => HttpRouterService.ts} | 8 - ...cycleServiceRef.ts => LifecycleService.ts} | 10 - .../{loggerServiceRef.ts => LoggerService.ts} | 11 +- ...onsServiceRef.ts => PermissionsService.ts} | 8 - ...ServiceRef.ts => PluginMetadataService.ts} | 11 -- ...eServiceRef.ts => RootLifecycleService.ts} | 11 +- ...ggerServiceRef.ts => RootLoggerService.ts} | 11 +- ...dulerServiceRef.ts => SchedulerService.ts} | 8 - ...erServiceRef.ts => TokenManagerService.ts} | 8 - ...eaderServiceRef.ts => UrlReaderService.ts} | 8 - .../src/services/definitions/coreServices.ts | 176 ++++++++++++++++-- .../src/services/definitions/index.ts | 32 ++-- 18 files changed, 203 insertions(+), 216 deletions(-) create mode 100644 .changeset/rich-clouds-smile.md rename packages/backend-plugin-api/src/services/definitions/{cacheServiceRef.ts => CacheService.ts} (82%) rename packages/backend-plugin-api/src/services/definitions/{configServiceRef.ts => ConfigService.ts} (79%) rename packages/backend-plugin-api/src/services/definitions/{databaseServiceRef.ts => DatabaseService.ts} (81%) rename packages/backend-plugin-api/src/services/definitions/{discoveryServiceRef.ts => DiscoveryService.ts} (93%) rename packages/backend-plugin-api/src/services/definitions/{httpRouterServiceRef.ts => HttpRouterService.ts} (80%) rename packages/backend-plugin-api/src/services/definitions/{lifecycleServiceRef.ts => LifecycleService.ts} (83%) rename packages/backend-plugin-api/src/services/definitions/{loggerServiceRef.ts => LoggerService.ts} (85%) rename packages/backend-plugin-api/src/services/definitions/{permissionsServiceRef.ts => PermissionsService.ts} (81%) rename packages/backend-plugin-api/src/services/definitions/{pluginMetadataServiceRef.ts => PluginMetadataService.ts} (77%) rename packages/backend-plugin-api/src/services/definitions/{rootLifecycleServiceRef.ts => RootLifecycleService.ts} (72%) rename packages/backend-plugin-api/src/services/definitions/{rootLoggerServiceRef.ts => RootLoggerService.ts} (73%) rename packages/backend-plugin-api/src/services/definitions/{schedulerServiceRef.ts => SchedulerService.ts} (81%) rename packages/backend-plugin-api/src/services/definitions/{tokenManagerServiceRef.ts => TokenManagerService.ts} (80%) rename packages/backend-plugin-api/src/services/definitions/{urlReaderServiceRef.ts => UrlReaderService.ts} (97%) diff --git a/.changeset/rich-clouds-smile.md b/.changeset/rich-clouds-smile.md new file mode 100644 index 0000000000..ee7b70644d --- /dev/null +++ b/.changeset/rich-clouds-smile.md @@ -0,0 +1,5 @@ +--- +'@backstage/backend-plugin-api': patch +--- + +Documented `coreServices` an all of its members. diff --git a/packages/backend-plugin-api/api-report.md b/packages/backend-plugin-api/api-report.md index e0fa44eb20..7176fd2d19 100644 --- a/packages/backend-plugin-api/api-report.md +++ b/packages/backend-plugin-api/api-report.md @@ -69,34 +69,26 @@ export interface BackendRegistrationPoints { // @public (undocumented) export type CacheService = PluginCacheManager; -// @public (undocumented) -const cacheServiceRef: ServiceRef; - // @public (undocumented) export type ConfigService = Config; -// @public (undocumented) -const configServiceRef: ServiceRef; - -declare namespace coreServices { - export { - configServiceRef as config, - httpRouterServiceRef as httpRouter, - loggerServiceRef as logger, - urlReaderServiceRef as urlReader, - cacheServiceRef as cache, - databaseServiceRef as database, - discoveryServiceRef as discovery, - tokenManagerServiceRef as tokenManager, - permissionsServiceRef as permissions, - schedulerServiceRef as scheduler, - rootLifecycleServiceRef as rootLifecycle, - rootLoggerServiceRef as rootLogger, - pluginMetadataServiceRef as pluginMetadata, - lifecycleServiceRef as lifecycle, - }; +// @public +export namespace coreServices { + const cache: ServiceRef; + const config: ServiceRef; + const database: ServiceRef; + const discovery: ServiceRef; + const httpRouter: ServiceRef; + const lifecycle: ServiceRef; + const logger: ServiceRef; + const permissions: ServiceRef; + const pluginMetadata: ServiceRef; + const rootLifecycle: ServiceRef; + const rootLogger: ServiceRef; + const scheduler: ServiceRef; + const tokenManager: ServiceRef; + const urlReader: ServiceRef; } -export { coreServices }; // @public export function createBackendModule< @@ -165,18 +157,12 @@ export function createServiceRef(options: { // @public (undocumented) export type DatabaseService = PluginDatabaseManager; -// @public (undocumented) -const databaseServiceRef: ServiceRef; - // @public export type DiscoveryService = { getBaseUrl(pluginId: string): Promise; getExternalBaseUrl(pluginId: string): Promise; }; -// @public (undocumented) -const discoveryServiceRef: ServiceRef; - // @public export type ExtensionPoint = { id: string; @@ -191,24 +177,18 @@ export interface HttpRouterService { use(handler: Handler): void; } -// @public (undocumented) -const httpRouterServiceRef: ServiceRef; - // @public (undocumented) export interface LifecycleService { addShutdownHook(options: LifecycleServiceShutdownHook): void; } -// @public (undocumented) -const lifecycleServiceRef: ServiceRef; - // @public (undocumented) export type LifecycleServiceShutdownHook = { fn: () => void | Promise; labels?: Record; }; -// @public (undocumented) +// @public export interface LoggerService { // (undocumented) child(meta: LogMeta): LoggerService; @@ -222,9 +202,6 @@ export interface LoggerService { warn(message: string, meta?: Error | LogMeta): void; } -// @public (undocumented) -const loggerServiceRef: ServiceRef; - // @public (undocumented) export function loggerToWinstonLogger( logger: LoggerService, @@ -239,18 +216,12 @@ export type LogMeta = { // @public (undocumented) export type PermissionsService = PermissionEvaluator | PermissionAuthorizer; -// @public (undocumented) -const permissionsServiceRef: ServiceRef; - // @public (undocumented) export interface PluginMetadataService { // (undocumented) getId(): string; } -// @public (undocumented) -const pluginMetadataServiceRef: ServiceRef; - // @public export type ReadTreeOptions = { filter?( @@ -298,21 +269,12 @@ export type ReadUrlResponse = { // @public (undocumented) export type RootLifecycleService = LifecycleService; -// @public (undocumented) -const rootLifecycleServiceRef: ServiceRef; - // @public (undocumented) export type RootLoggerService = LoggerService; -// @public (undocumented) -const rootLoggerServiceRef: ServiceRef; - // @public (undocumented) export type SchedulerService = PluginTaskScheduler; -// @public (undocumented) -const schedulerServiceRef: ServiceRef; - // @public export type SearchOptions = { etag?: string; @@ -373,9 +335,6 @@ export type ServiceRef< // @public (undocumented) export type TokenManagerService = TokenManager; -// @public (undocumented) -const tokenManagerServiceRef: ServiceRef; - // @public (undocumented) export type TypesToServiceRef = { [key in keyof T]: ServiceRef; @@ -387,7 +346,4 @@ export type UrlReaderService = { readTree(url: string, options?: ReadTreeOptions): Promise; search(url: string, options?: SearchOptions): Promise; }; - -// @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/CacheService.ts similarity index 82% rename from packages/backend-plugin-api/src/services/definitions/cacheServiceRef.ts rename to packages/backend-plugin-api/src/services/definitions/CacheService.ts index aff913b06a..3311816410 100644 --- a/packages/backend-plugin-api/src/services/definitions/cacheServiceRef.ts +++ b/packages/backend-plugin-api/src/services/definitions/CacheService.ts @@ -14,15 +14,7 @@ * limitations under the License. */ -import { createServiceRef } from '../system/types'; import { PluginCacheManager } from '@backstage/backend-common'; /** @public */ export type CacheService = PluginCacheManager; - -/** - * @public - */ -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/ConfigService.ts similarity index 79% rename from packages/backend-plugin-api/src/services/definitions/configServiceRef.ts rename to packages/backend-plugin-api/src/services/definitions/ConfigService.ts index 15e9cb9aa6..4b57e617fc 100644 --- a/packages/backend-plugin-api/src/services/definitions/configServiceRef.ts +++ b/packages/backend-plugin-api/src/services/definitions/ConfigService.ts @@ -15,17 +15,8 @@ */ import { Config } from '@backstage/config'; -import { createServiceRef } from '../system/types'; /** * @public */ 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/DatabaseService.ts similarity index 81% rename from packages/backend-plugin-api/src/services/definitions/databaseServiceRef.ts rename to packages/backend-plugin-api/src/services/definitions/DatabaseService.ts index aaea5d304f..afb3081a78 100644 --- a/packages/backend-plugin-api/src/services/definitions/databaseServiceRef.ts +++ b/packages/backend-plugin-api/src/services/definitions/DatabaseService.ts @@ -15,14 +15,6 @@ */ import { PluginDatabaseManager } from '@backstage/backend-common'; -import { createServiceRef } from '../system/types'; /** @public */ export type DatabaseService = PluginDatabaseManager; - -/** - * @public - */ -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/DiscoveryService.ts similarity index 93% rename from packages/backend-plugin-api/src/services/definitions/discoveryServiceRef.ts rename to packages/backend-plugin-api/src/services/definitions/DiscoveryService.ts index fb508a7ae1..dec61ab56f 100644 --- a/packages/backend-plugin-api/src/services/definitions/discoveryServiceRef.ts +++ b/packages/backend-plugin-api/src/services/definitions/DiscoveryService.ts @@ -14,8 +14,6 @@ * limitations under the License. */ -import { createServiceRef } from '../system/types'; - /** * The DiscoveryService is used to provide a mechanism for backend * plugins to discover the endpoints for itself or other backend plugins. @@ -63,10 +61,3 @@ export type DiscoveryService = { */ getExternalBaseUrl(pluginId: string): Promise; }; - -/** - * @public - */ -export const discoveryServiceRef = createServiceRef({ - id: 'core.discovery', -}); diff --git a/packages/backend-plugin-api/src/services/definitions/httpRouterServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/HttpRouterService.ts similarity index 80% rename from packages/backend-plugin-api/src/services/definitions/httpRouterServiceRef.ts rename to packages/backend-plugin-api/src/services/definitions/HttpRouterService.ts index fbc5a27e87..3c45ef1da1 100644 --- a/packages/backend-plugin-api/src/services/definitions/httpRouterServiceRef.ts +++ b/packages/backend-plugin-api/src/services/definitions/HttpRouterService.ts @@ -14,7 +14,6 @@ * limitations under the License. */ -import { createServiceRef } from '../system/types'; import { Handler } from 'express'; /** @@ -23,10 +22,3 @@ import { Handler } from 'express'; export interface HttpRouterService { use(handler: Handler): void; } - -/** - * @public - */ -export const httpRouterServiceRef = createServiceRef({ - id: 'core.httpRouter', -}); diff --git a/packages/backend-plugin-api/src/services/definitions/lifecycleServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/LifecycleService.ts similarity index 83% rename from packages/backend-plugin-api/src/services/definitions/lifecycleServiceRef.ts rename to packages/backend-plugin-api/src/services/definitions/LifecycleService.ts index e54f650fcc..b6f2b69e1c 100644 --- a/packages/backend-plugin-api/src/services/definitions/lifecycleServiceRef.ts +++ b/packages/backend-plugin-api/src/services/definitions/LifecycleService.ts @@ -14,8 +14,6 @@ * limitations under the License. */ -import { createServiceRef } from '../system/types'; - /** * @public **/ @@ -35,11 +33,3 @@ export interface LifecycleService { */ addShutdownHook(options: LifecycleServiceShutdownHook): void; } - -/** - * @public - */ -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/LoggerService.ts similarity index 85% rename from packages/backend-plugin-api/src/services/definitions/loggerServiceRef.ts rename to packages/backend-plugin-api/src/services/definitions/LoggerService.ts index 1c094549c1..269dfa0166 100644 --- a/packages/backend-plugin-api/src/services/definitions/loggerServiceRef.ts +++ b/packages/backend-plugin-api/src/services/definitions/LoggerService.ts @@ -14,14 +14,14 @@ * limitations under the License. */ -import { createServiceRef } from '../system/types'; - /** * @public */ export type LogMeta = { [name: string]: unknown }; /** + * A service that provides a logging facility. + * * @public */ export interface LoggerService { @@ -32,10 +32,3 @@ export interface LoggerService { child(meta: LogMeta): LoggerService; } - -/** - * @public - */ -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/PermissionsService.ts similarity index 81% rename from packages/backend-plugin-api/src/services/definitions/permissionsServiceRef.ts rename to packages/backend-plugin-api/src/services/definitions/PermissionsService.ts index b24b2f5f46..0a3c045ea7 100644 --- a/packages/backend-plugin-api/src/services/definitions/permissionsServiceRef.ts +++ b/packages/backend-plugin-api/src/services/definitions/PermissionsService.ts @@ -14,7 +14,6 @@ * limitations under the License. */ -import { createServiceRef } from '../system/types'; import { PermissionAuthorizer, PermissionEvaluator, @@ -22,10 +21,3 @@ import { /** @public */ export type PermissionsService = PermissionEvaluator | PermissionAuthorizer; - -/** - * @public - */ -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/PluginMetadataService.ts similarity index 77% rename from packages/backend-plugin-api/src/services/definitions/pluginMetadataServiceRef.ts rename to packages/backend-plugin-api/src/services/definitions/PluginMetadataService.ts index 4c1ecb130e..48328e4db9 100644 --- a/packages/backend-plugin-api/src/services/definitions/pluginMetadataServiceRef.ts +++ b/packages/backend-plugin-api/src/services/definitions/PluginMetadataService.ts @@ -14,20 +14,9 @@ * limitations under the License. */ -import { createServiceRef } from '../system/types'; - /** * @public */ export interface PluginMetadataService { getId(): string; } - -/** - * @public - */ -export const pluginMetadataServiceRef = createServiceRef( - { - id: 'core.plugin-metadata', - }, -); diff --git a/packages/backend-plugin-api/src/services/definitions/rootLifecycleServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/RootLifecycleService.ts similarity index 72% rename from packages/backend-plugin-api/src/services/definitions/rootLifecycleServiceRef.ts rename to packages/backend-plugin-api/src/services/definitions/RootLifecycleService.ts index e0d5355983..d97278da88 100644 --- a/packages/backend-plugin-api/src/services/definitions/rootLifecycleServiceRef.ts +++ b/packages/backend-plugin-api/src/services/definitions/RootLifecycleService.ts @@ -14,16 +14,7 @@ * limitations under the License. */ -import { createServiceRef } from '../system/types'; -import { LifecycleService } from './lifecycleServiceRef'; +import { LifecycleService } from './LifecycleService'; /** @public */ export type RootLifecycleService = LifecycleService; - -/** - * @public - */ -export const rootLifecycleServiceRef = createServiceRef({ - id: 'core.rootLifecycle', - scope: 'root', -}); diff --git a/packages/backend-plugin-api/src/services/definitions/rootLoggerServiceRef.ts b/packages/backend-plugin-api/src/services/definitions/RootLoggerService.ts similarity index 73% rename from packages/backend-plugin-api/src/services/definitions/rootLoggerServiceRef.ts rename to packages/backend-plugin-api/src/services/definitions/RootLoggerService.ts index af26ce8899..5fc595d91b 100644 --- a/packages/backend-plugin-api/src/services/definitions/rootLoggerServiceRef.ts +++ b/packages/backend-plugin-api/src/services/definitions/RootLoggerService.ts @@ -14,16 +14,7 @@ * limitations under the License. */ -import { createServiceRef } from '../system/types'; -import { LoggerService } from './loggerServiceRef'; +import { LoggerService } from './LoggerService'; /** @public */ export type RootLoggerService = LoggerService; - -/** - * @public - */ -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/SchedulerService.ts similarity index 81% rename from packages/backend-plugin-api/src/services/definitions/schedulerServiceRef.ts rename to packages/backend-plugin-api/src/services/definitions/SchedulerService.ts index 160f2fbb93..f47e67596b 100644 --- a/packages/backend-plugin-api/src/services/definitions/schedulerServiceRef.ts +++ b/packages/backend-plugin-api/src/services/definitions/SchedulerService.ts @@ -14,15 +14,7 @@ * limitations under the License. */ -import { createServiceRef } from '../system/types'; import { PluginTaskScheduler } from '@backstage/backend-tasks'; /** @public */ export type SchedulerService = PluginTaskScheduler; - -/** - * @public - */ -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/TokenManagerService.ts similarity index 80% rename from packages/backend-plugin-api/src/services/definitions/tokenManagerServiceRef.ts rename to packages/backend-plugin-api/src/services/definitions/TokenManagerService.ts index 4b12acdc58..0e7536fe93 100644 --- a/packages/backend-plugin-api/src/services/definitions/tokenManagerServiceRef.ts +++ b/packages/backend-plugin-api/src/services/definitions/TokenManagerService.ts @@ -14,15 +14,7 @@ * limitations under the License. */ -import { createServiceRef } from '../system/types'; import { TokenManager } from '@backstage/backend-common'; /** @public */ export type TokenManagerService = TokenManager; - -/** - * @public - */ -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/UrlReaderService.ts similarity index 97% rename from packages/backend-plugin-api/src/services/definitions/urlReaderServiceRef.ts rename to packages/backend-plugin-api/src/services/definitions/UrlReaderService.ts index db296b5807..082d4fe91e 100644 --- a/packages/backend-plugin-api/src/services/definitions/urlReaderServiceRef.ts +++ b/packages/backend-plugin-api/src/services/definitions/UrlReaderService.ts @@ -14,7 +14,6 @@ * limitations under the License. */ -import { createServiceRef } from '../system/types'; import { Readable } from 'stream'; /** @@ -280,10 +279,3 @@ export type SearchResponseFile = { */ content(): Promise; }; - -/** - * @public - */ -export const urlReaderServiceRef = createServiceRef({ - id: 'core.urlReader', -}); diff --git a/packages/backend-plugin-api/src/services/definitions/coreServices.ts b/packages/backend-plugin-api/src/services/definitions/coreServices.ts index a2b1a04d41..f932dbd379 100644 --- a/packages/backend-plugin-api/src/services/definitions/coreServices.ts +++ b/packages/backend-plugin-api/src/services/definitions/coreServices.ts @@ -14,17 +14,165 @@ * limitations under the License. */ -export { configServiceRef as config } from './configServiceRef'; -export { httpRouterServiceRef as httpRouter } from './httpRouterServiceRef'; -export { loggerServiceRef as logger } from './loggerServiceRef'; -export { urlReaderServiceRef as urlReader } from './urlReaderServiceRef'; -export { cacheServiceRef as cache } from './cacheServiceRef'; -export { databaseServiceRef as database } from './databaseServiceRef'; -export { discoveryServiceRef as discovery } from './discoveryServiceRef'; -export { tokenManagerServiceRef as tokenManager } from './tokenManagerServiceRef'; -export { permissionsServiceRef as permissions } from './permissionsServiceRef'; -export { schedulerServiceRef as scheduler } from './schedulerServiceRef'; -export { rootLifecycleServiceRef as rootLifecycle } from './rootLifecycleServiceRef'; -export { rootLoggerServiceRef as rootLogger } from './rootLoggerServiceRef'; -export { pluginMetadataServiceRef as pluginMetadata } from './pluginMetadataServiceRef'; -export { lifecycleServiceRef as lifecycle } from './lifecycleServiceRef'; +import { createServiceRef } from '../system'; + +/** + * All core services references + * + * @public + */ +export namespace coreServices { + /** + * The service reference for the plugin scoped {@link CacheService}. + * + * @public + */ + export const cache = createServiceRef({ + id: 'core.cache', + }); + + /** + * The service reference for the root scoped {@link ConfigService}. + * + * @public + */ + export const config = createServiceRef< + import('./ConfigService').ConfigService + >({ + id: 'core.root.config', + scope: 'root', + }); + + /** + * The service reference for the plugin scoped {@link DatabaseService}. + * + * @public + */ + export const database = createServiceRef< + import('./DatabaseService').DatabaseService + >({ + id: 'core.database', + }); + + /** + * The service reference for the plugin scoped {@link DiscoveryService}. + * + * @public + */ + export const discovery = createServiceRef< + import('./DiscoveryService').DiscoveryService + >({ + id: 'core.discovery', + }); + + /** + * The service reference for the plugin scoped {@link HttpRouterService}. + * + * @public + */ + export const httpRouter = createServiceRef< + import('./HttpRouterService').HttpRouterService + >({ id: 'core.httpRouter' }); + + /** + * The service reference for the plugin scoped {@link LifecycleService}. + * + * @public + */ + export const lifecycle = createServiceRef< + import('./LifecycleService').LifecycleService + >({ + id: 'core.lifecycle', + scope: 'plugin', + }); + + /** + * The service reference for the plugin scoped {@link LoggerService}. + * + * @public + */ + export const logger = createServiceRef< + import('./LoggerService').LoggerService + >({ + id: 'core.logger', + }); + + /** + * The service reference for the plugin scoped {@link PermissionsService}. + * + * @public + */ + export const permissions = createServiceRef< + import('./PermissionsService').PermissionsService + >({ + id: 'core.permissions', + }); + + /** + * The service reference for the plugin scoped {@link PluginMetadataService}. + * + * @public + */ + export const pluginMetadata = createServiceRef< + import('./PluginMetadataService').PluginMetadataService + >({ + id: 'core.plugin-metadata', + }); + + /** + * The service reference for the root scoped {@link RootLifecycleService}. + * + * @public + */ + export const rootLifecycle = createServiceRef< + import('./RootLifecycleService').RootLifecycleService + >({ + id: 'core.rootLifecycle', + scope: 'root', + }); + + /** + * The service reference for the root scoped {@link RootLoggerService}. + * + * @public + */ + export const rootLogger = createServiceRef< + import('./RootLoggerService').RootLoggerService + >({ + id: 'core.root.logger', + scope: 'root', + }); + + /** + * The service reference for the plugin scoped {@link SchedulerService}. + * + * @public + */ + export const scheduler = createServiceRef< + import('./SchedulerService').SchedulerService + >({ + id: 'core.scheduler', + }); + + /** + * The service reference for the plugin scoped {@link TokenManagerService}. + * + * @public + */ + export const tokenManager = createServiceRef< + import('./TokenManagerService').TokenManagerService + >({ + id: 'core.tokenManager', + }); + + /** + * The service reference for the plugin scoped {@link UrlReaderService}. + * + * @public + */ + export const urlReader = createServiceRef< + import('./UrlReaderService').UrlReaderService + >({ + id: 'core.urlReader', + }); +} diff --git a/packages/backend-plugin-api/src/services/definitions/index.ts b/packages/backend-plugin-api/src/services/definitions/index.ts index 953d4b28ad..dedfd6223e 100644 --- a/packages/backend-plugin-api/src/services/definitions/index.ts +++ b/packages/backend-plugin-api/src/services/definitions/index.ts @@ -14,25 +14,23 @@ * limitations under the License. */ -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 { coreServices } from './coreServices'; +export type { CacheService } from './CacheService'; +export type { ConfigService } from './ConfigService'; +export type { DatabaseService } from './DatabaseService'; +export type { DiscoveryService } from './DiscoveryService'; +export type { HttpRouterService } from './HttpRouterService'; export type { LifecycleService, LifecycleServiceShutdownHook, -} from './lifecycleServiceRef'; -export type { LoggerService, LogMeta } from './loggerServiceRef'; -export type { PermissionsService } from './permissionsServiceRef'; -export type { PluginMetadataService } from './pluginMetadataServiceRef'; -export type { RootLifecycleService } from './rootLifecycleServiceRef'; -export type { RootLoggerService } from './rootLoggerServiceRef'; -export type { SchedulerService } from './schedulerServiceRef'; -export type { TokenManagerService } from './tokenManagerServiceRef'; +} from './LifecycleService'; +export type { LoggerService, LogMeta } from './LoggerService'; +export type { PermissionsService } from './PermissionsService'; +export type { PluginMetadataService } from './PluginMetadataService'; +export type { RootLifecycleService } from './RootLifecycleService'; +export type { RootLoggerService } from './RootLoggerService'; +export type { SchedulerService } from './SchedulerService'; +export type { TokenManagerService } from './TokenManagerService'; export type { ReadTreeOptions, ReadTreeResponse, @@ -44,4 +42,4 @@ export type { SearchResponse, SearchResponseFile, UrlReaderService, -} from './urlReaderServiceRef'; +} from './UrlReaderService'; From 6a4419041b0065a6d49fccd3140eaec131b295b4 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 3 Jan 2023 14:50:39 +0100 Subject: [PATCH 2/3] backend-plugin-api: convert all core service definitions to interfaces Signed-off-by: Patrik Oldsberg --- packages/backend-app-api/api-report.md | 28 +++++++------ packages/backend-plugin-api/api-report.md | 41 +++++++++---------- .../src/services/definitions/CacheService.ts | 2 +- .../src/services/definitions/ConfigService.ts | 2 +- .../services/definitions/DatabaseService.ts | 2 +- .../services/definitions/DiscoveryService.ts | 4 +- .../definitions/PermissionsService.ts | 7 +--- .../definitions/RootLifecycleService.ts | 2 +- .../services/definitions/RootLoggerService.ts | 2 +- .../services/definitions/SchedulerService.ts | 2 +- .../definitions/TokenManagerService.ts | 2 +- .../services/definitions/UrlReaderService.ts | 4 +- 12 files changed, 49 insertions(+), 49 deletions(-) diff --git a/packages/backend-app-api/api-report.md b/packages/backend-app-api/api-report.md index ef88d9a9d0..fa3f3bec2e 100644 --- a/packages/backend-app-api/api-report.md +++ b/packages/backend-app-api/api-report.md @@ -4,19 +4,21 @@ ```ts import { BackendFeature } from '@backstage/backend-plugin-api'; -import { Config } from '@backstage/config'; +import { CacheService } from '@backstage/backend-plugin-api'; +import { ConfigService } from '@backstage/backend-plugin-api'; +import { DatabaseService } from '@backstage/backend-plugin-api'; import { ExtensionPoint } from '@backstage/backend-plugin-api'; import { HttpRouterService } from '@backstage/backend-plugin-api'; import { LifecycleService } from '@backstage/backend-plugin-api'; import { LoggerService } from '@backstage/backend-plugin-api'; import { PermissionsService } from '@backstage/backend-plugin-api'; -import { PluginCacheManager } from '@backstage/backend-common'; -import { PluginDatabaseManager } from '@backstage/backend-common'; import { PluginEndpointDiscovery } from '@backstage/backend-common'; -import { PluginTaskScheduler } from '@backstage/backend-tasks'; +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 { ServiceRef } from '@backstage/backend-plugin-api'; -import { TokenManager } from '@backstage/backend-common'; +import { TokenManagerService } from '@backstage/backend-plugin-api'; import { UrlReader } from '@backstage/backend-common'; // @public (undocumented) @@ -32,10 +34,12 @@ export interface Backend { // @public (undocumented) export const cacheFactory: ( options?: undefined, -) => ServiceFactory; +) => ServiceFactory; // @public (undocumented) -export const configFactory: (options?: undefined) => ServiceFactory; +export const configFactory: ( + options?: undefined, +) => ServiceFactory; // @public (undocumented) export function createSpecializedBackend( @@ -51,7 +55,7 @@ export interface CreateSpecializedBackendOptions { // @public (undocumented) export const databaseFactory: ( options?: undefined, -) => ServiceFactory; +) => ServiceFactory; // @public (undocumented) export const discoveryFactory: ( @@ -86,17 +90,17 @@ export const permissionsFactory: ( // @public export const rootLifecycleFactory: ( options?: undefined, -) => ServiceFactory; +) => ServiceFactory; // @public (undocumented) export const rootLoggerFactory: ( options?: undefined, -) => ServiceFactory; +) => ServiceFactory; // @public (undocumented) export const schedulerFactory: ( options?: undefined, -) => ServiceFactory; +) => ServiceFactory; // @public (undocumented) export type ServiceOrExtensionPoint = @@ -106,7 +110,7 @@ export type ServiceOrExtensionPoint = // @public (undocumented) export const tokenManagerFactory: ( options?: undefined, -) => ServiceFactory; +) => ServiceFactory; // @public (undocumented) export const urlReaderFactory: ( diff --git a/packages/backend-plugin-api/api-report.md b/packages/backend-plugin-api/api-report.md index 7176fd2d19..9c6ffe6dd5 100644 --- a/packages/backend-plugin-api/api-report.md +++ b/packages/backend-plugin-api/api-report.md @@ -8,7 +8,6 @@ import { Config } from '@backstage/config'; import { Handler } from 'express'; import { Logger } from 'winston'; -import { PermissionAuthorizer } from '@backstage/plugin-permission-common'; import { PermissionEvaluator } from '@backstage/plugin-permission-common'; import { PluginCacheManager } from '@backstage/backend-common'; import { PluginDatabaseManager } from '@backstage/backend-common'; @@ -67,26 +66,26 @@ export interface BackendRegistrationPoints { } // @public (undocumented) -export type CacheService = PluginCacheManager; +export interface CacheService extends PluginCacheManager {} // @public (undocumented) -export type ConfigService = Config; +export interface ConfigService extends Config {} // @public export namespace coreServices { - const cache: ServiceRef; - const config: ServiceRef; - const database: ServiceRef; + const cache: ServiceRef; + const config: ServiceRef; + const database: ServiceRef; const discovery: ServiceRef; const httpRouter: ServiceRef; const lifecycle: ServiceRef; const logger: ServiceRef; const permissions: ServiceRef; const pluginMetadata: ServiceRef; - const rootLifecycle: ServiceRef; - const rootLogger: ServiceRef; - const scheduler: ServiceRef; - const tokenManager: ServiceRef; + const rootLifecycle: ServiceRef; + const rootLogger: ServiceRef; + const scheduler: ServiceRef; + const tokenManager: ServiceRef; const urlReader: ServiceRef; } @@ -155,13 +154,13 @@ export function createServiceRef(options: { }): ServiceRef; // @public (undocumented) -export type DatabaseService = PluginDatabaseManager; +export interface DatabaseService extends PluginDatabaseManager {} // @public -export type DiscoveryService = { +export interface DiscoveryService { getBaseUrl(pluginId: string): Promise; getExternalBaseUrl(pluginId: string): Promise; -}; +} // @public export type ExtensionPoint = { @@ -214,7 +213,7 @@ export type LogMeta = { }; // @public (undocumented) -export type PermissionsService = PermissionEvaluator | PermissionAuthorizer; +export interface PermissionsService extends PermissionEvaluator {} // @public (undocumented) export interface PluginMetadataService { @@ -267,13 +266,13 @@ export type ReadUrlResponse = { }; // @public (undocumented) -export type RootLifecycleService = LifecycleService; +export interface RootLifecycleService extends LifecycleService {} // @public (undocumented) -export type RootLoggerService = LoggerService; +export interface RootLoggerService extends LoggerService {} // @public (undocumented) -export type SchedulerService = PluginTaskScheduler; +export interface SchedulerService extends PluginTaskScheduler {} // @public export type SearchOptions = { @@ -333,7 +332,7 @@ export type ServiceRef< }; // @public (undocumented) -export type TokenManagerService = TokenManager; +export interface TokenManagerService extends TokenManager {} // @public (undocumented) export type TypesToServiceRef = { @@ -341,9 +340,9 @@ export type TypesToServiceRef = { }; // @public -export type UrlReaderService = { - readUrl(url: string, options?: ReadUrlOptions): Promise; +export interface UrlReaderService { readTree(url: string, options?: ReadTreeOptions): Promise; + readUrl(url: string, options?: ReadUrlOptions): Promise; search(url: string, options?: SearchOptions): Promise; -}; +} ``` diff --git a/packages/backend-plugin-api/src/services/definitions/CacheService.ts b/packages/backend-plugin-api/src/services/definitions/CacheService.ts index 3311816410..79c930f435 100644 --- a/packages/backend-plugin-api/src/services/definitions/CacheService.ts +++ b/packages/backend-plugin-api/src/services/definitions/CacheService.ts @@ -17,4 +17,4 @@ import { PluginCacheManager } from '@backstage/backend-common'; /** @public */ -export type CacheService = PluginCacheManager; +export interface CacheService extends PluginCacheManager {} diff --git a/packages/backend-plugin-api/src/services/definitions/ConfigService.ts b/packages/backend-plugin-api/src/services/definitions/ConfigService.ts index 4b57e617fc..db9aa88dda 100644 --- a/packages/backend-plugin-api/src/services/definitions/ConfigService.ts +++ b/packages/backend-plugin-api/src/services/definitions/ConfigService.ts @@ -19,4 +19,4 @@ import { Config } from '@backstage/config'; /** * @public */ -export type ConfigService = Config; +export interface ConfigService extends Config {} diff --git a/packages/backend-plugin-api/src/services/definitions/DatabaseService.ts b/packages/backend-plugin-api/src/services/definitions/DatabaseService.ts index afb3081a78..30f1f574f2 100644 --- a/packages/backend-plugin-api/src/services/definitions/DatabaseService.ts +++ b/packages/backend-plugin-api/src/services/definitions/DatabaseService.ts @@ -17,4 +17,4 @@ import { PluginDatabaseManager } from '@backstage/backend-common'; /** @public */ -export type DatabaseService = PluginDatabaseManager; +export interface DatabaseService extends PluginDatabaseManager {} diff --git a/packages/backend-plugin-api/src/services/definitions/DiscoveryService.ts b/packages/backend-plugin-api/src/services/definitions/DiscoveryService.ts index dec61ab56f..c3f0820c28 100644 --- a/packages/backend-plugin-api/src/services/definitions/DiscoveryService.ts +++ b/packages/backend-plugin-api/src/services/definitions/DiscoveryService.ts @@ -28,7 +28,7 @@ * * @public */ -export type DiscoveryService = { +export interface DiscoveryService { /** * Returns the internal HTTP base URL for a given plugin, without a trailing slash. * @@ -60,4 +60,4 @@ export type DiscoveryService = { * like `https://backstage.example.com/api/catalog` */ getExternalBaseUrl(pluginId: string): Promise; -}; +} diff --git a/packages/backend-plugin-api/src/services/definitions/PermissionsService.ts b/packages/backend-plugin-api/src/services/definitions/PermissionsService.ts index 0a3c045ea7..5847f55ee6 100644 --- a/packages/backend-plugin-api/src/services/definitions/PermissionsService.ts +++ b/packages/backend-plugin-api/src/services/definitions/PermissionsService.ts @@ -14,10 +14,7 @@ * limitations under the License. */ -import { - PermissionAuthorizer, - PermissionEvaluator, -} from '@backstage/plugin-permission-common'; +import { PermissionEvaluator } from '@backstage/plugin-permission-common'; /** @public */ -export type PermissionsService = PermissionEvaluator | PermissionAuthorizer; +export interface PermissionsService extends PermissionEvaluator {} diff --git a/packages/backend-plugin-api/src/services/definitions/RootLifecycleService.ts b/packages/backend-plugin-api/src/services/definitions/RootLifecycleService.ts index d97278da88..e0e09cb859 100644 --- a/packages/backend-plugin-api/src/services/definitions/RootLifecycleService.ts +++ b/packages/backend-plugin-api/src/services/definitions/RootLifecycleService.ts @@ -17,4 +17,4 @@ import { LifecycleService } from './LifecycleService'; /** @public */ -export type RootLifecycleService = LifecycleService; +export interface RootLifecycleService extends LifecycleService {} diff --git a/packages/backend-plugin-api/src/services/definitions/RootLoggerService.ts b/packages/backend-plugin-api/src/services/definitions/RootLoggerService.ts index 5fc595d91b..ad318ef53f 100644 --- a/packages/backend-plugin-api/src/services/definitions/RootLoggerService.ts +++ b/packages/backend-plugin-api/src/services/definitions/RootLoggerService.ts @@ -17,4 +17,4 @@ import { LoggerService } from './LoggerService'; /** @public */ -export type RootLoggerService = LoggerService; +export interface RootLoggerService extends LoggerService {} diff --git a/packages/backend-plugin-api/src/services/definitions/SchedulerService.ts b/packages/backend-plugin-api/src/services/definitions/SchedulerService.ts index f47e67596b..07c436bd6b 100644 --- a/packages/backend-plugin-api/src/services/definitions/SchedulerService.ts +++ b/packages/backend-plugin-api/src/services/definitions/SchedulerService.ts @@ -17,4 +17,4 @@ import { PluginTaskScheduler } from '@backstage/backend-tasks'; /** @public */ -export type SchedulerService = PluginTaskScheduler; +export interface SchedulerService extends PluginTaskScheduler {} diff --git a/packages/backend-plugin-api/src/services/definitions/TokenManagerService.ts b/packages/backend-plugin-api/src/services/definitions/TokenManagerService.ts index 0e7536fe93..7fccb60c7a 100644 --- a/packages/backend-plugin-api/src/services/definitions/TokenManagerService.ts +++ b/packages/backend-plugin-api/src/services/definitions/TokenManagerService.ts @@ -17,4 +17,4 @@ import { TokenManager } from '@backstage/backend-common'; /** @public */ -export type TokenManagerService = TokenManager; +export interface TokenManagerService extends TokenManager {} diff --git a/packages/backend-plugin-api/src/services/definitions/UrlReaderService.ts b/packages/backend-plugin-api/src/services/definitions/UrlReaderService.ts index 082d4fe91e..ef825a7fcd 100644 --- a/packages/backend-plugin-api/src/services/definitions/UrlReaderService.ts +++ b/packages/backend-plugin-api/src/services/definitions/UrlReaderService.ts @@ -21,7 +21,7 @@ import { Readable } from 'stream'; * * @public */ -export type UrlReaderService = { +export interface UrlReaderService { /** * Reads a single file and return its content. */ @@ -36,7 +36,7 @@ export type UrlReaderService = { * Searches for a file in a tree using a glob pattern. */ search(url: string, options?: SearchOptions): Promise; -}; +} /** * An options object for readUrl operations. From 4907f721580adf8cf9fd100a0514571da212ce8c Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 3 Jan 2023 16:59:54 +0100 Subject: [PATCH 3/3] backend-plugin-api: align core service ID style Signed-off-by: Patrik Oldsberg --- .../src/services/definitions/coreServices.ts | 52 +++++-------------- 1 file changed, 12 insertions(+), 40 deletions(-) diff --git a/packages/backend-plugin-api/src/services/definitions/coreServices.ts b/packages/backend-plugin-api/src/services/definitions/coreServices.ts index f932dbd379..fc96ec8be9 100644 --- a/packages/backend-plugin-api/src/services/definitions/coreServices.ts +++ b/packages/backend-plugin-api/src/services/definitions/coreServices.ts @@ -38,10 +38,7 @@ export namespace coreServices { */ export const config = createServiceRef< import('./ConfigService').ConfigService - >({ - id: 'core.root.config', - scope: 'root', - }); + >({ id: 'core.config', scope: 'root' }); /** * The service reference for the plugin scoped {@link DatabaseService}. @@ -50,9 +47,7 @@ export namespace coreServices { */ export const database = createServiceRef< import('./DatabaseService').DatabaseService - >({ - id: 'core.database', - }); + >({ id: 'core.database' }); /** * The service reference for the plugin scoped {@link DiscoveryService}. @@ -61,9 +56,7 @@ export namespace coreServices { */ export const discovery = createServiceRef< import('./DiscoveryService').DiscoveryService - >({ - id: 'core.discovery', - }); + >({ id: 'core.discovery' }); /** * The service reference for the plugin scoped {@link HttpRouterService}. @@ -81,10 +74,7 @@ export namespace coreServices { */ export const lifecycle = createServiceRef< import('./LifecycleService').LifecycleService - >({ - id: 'core.lifecycle', - scope: 'plugin', - }); + >({ id: 'core.lifecycle' }); /** * The service reference for the plugin scoped {@link LoggerService}. @@ -93,9 +83,7 @@ export namespace coreServices { */ export const logger = createServiceRef< import('./LoggerService').LoggerService - >({ - id: 'core.logger', - }); + >({ id: 'core.logger' }); /** * The service reference for the plugin scoped {@link PermissionsService}. @@ -104,9 +92,7 @@ export namespace coreServices { */ export const permissions = createServiceRef< import('./PermissionsService').PermissionsService - >({ - id: 'core.permissions', - }); + >({ id: 'core.permissions' }); /** * The service reference for the plugin scoped {@link PluginMetadataService}. @@ -115,9 +101,7 @@ export namespace coreServices { */ export const pluginMetadata = createServiceRef< import('./PluginMetadataService').PluginMetadataService - >({ - id: 'core.plugin-metadata', - }); + >({ id: 'core.pluginMetadata' }); /** * The service reference for the root scoped {@link RootLifecycleService}. @@ -126,10 +110,7 @@ export namespace coreServices { */ export const rootLifecycle = createServiceRef< import('./RootLifecycleService').RootLifecycleService - >({ - id: 'core.rootLifecycle', - scope: 'root', - }); + >({ id: 'core.rootLifecycle', scope: 'root' }); /** * The service reference for the root scoped {@link RootLoggerService}. @@ -138,10 +119,7 @@ export namespace coreServices { */ export const rootLogger = createServiceRef< import('./RootLoggerService').RootLoggerService - >({ - id: 'core.root.logger', - scope: 'root', - }); + >({ id: 'core.rootLogger', scope: 'root' }); /** * The service reference for the plugin scoped {@link SchedulerService}. @@ -150,9 +128,7 @@ export namespace coreServices { */ export const scheduler = createServiceRef< import('./SchedulerService').SchedulerService - >({ - id: 'core.scheduler', - }); + >({ id: 'core.scheduler' }); /** * The service reference for the plugin scoped {@link TokenManagerService}. @@ -161,9 +137,7 @@ export namespace coreServices { */ export const tokenManager = createServiceRef< import('./TokenManagerService').TokenManagerService - >({ - id: 'core.tokenManager', - }); + >({ id: 'core.tokenManager' }); /** * The service reference for the plugin scoped {@link UrlReaderService}. @@ -172,7 +146,5 @@ export namespace coreServices { */ export const urlReader = createServiceRef< import('./UrlReaderService').UrlReaderService - >({ - id: 'core.urlReader', - }); + >({ id: 'core.urlReader' }); }