Merge pull request #15527 from backstage/rugvip/csdocs

backend-plugin-api: nicer docs for core services
This commit is contained in:
Patrik Oldsberg
2023-01-03 17:32:53 +01:00
committed by GitHub
22 changed files with 271 additions and 312 deletions
+30 -75
View File
@@ -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,36 +66,28 @@ export interface BackendRegistrationPoints {
}
// @public (undocumented)
export type CacheService = PluginCacheManager;
export interface CacheService extends PluginCacheManager {}
// @public (undocumented)
const cacheServiceRef: ServiceRef<PluginCacheManager, 'plugin'>;
export interface ConfigService extends Config {}
// @public (undocumented)
export type ConfigService = Config;
// @public (undocumented)
const configServiceRef: ServiceRef<Config, 'root'>;
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<CacheService, 'plugin'>;
const config: ServiceRef<ConfigService, 'root'>;
const database: ServiceRef<DatabaseService, 'plugin'>;
const discovery: ServiceRef<DiscoveryService, 'plugin'>;
const httpRouter: ServiceRef<HttpRouterService, 'plugin'>;
const lifecycle: ServiceRef<LifecycleService, 'plugin'>;
const logger: ServiceRef<LoggerService, 'plugin'>;
const permissions: ServiceRef<PermissionsService, 'plugin'>;
const pluginMetadata: ServiceRef<PluginMetadataService, 'plugin'>;
const rootLifecycle: ServiceRef<RootLifecycleService, 'root'>;
const rootLogger: ServiceRef<RootLoggerService, 'root'>;
const scheduler: ServiceRef<SchedulerService, 'plugin'>;
const tokenManager: ServiceRef<TokenManagerService, 'plugin'>;
const urlReader: ServiceRef<UrlReaderService, 'plugin'>;
}
export { coreServices };
// @public
export function createBackendModule<
@@ -163,19 +154,13 @@ export function createServiceRef<T>(options: {
}): ServiceRef<T, 'root'>;
// @public (undocumented)
export type DatabaseService = PluginDatabaseManager;
// @public (undocumented)
const databaseServiceRef: ServiceRef<PluginDatabaseManager, 'plugin'>;
export interface DatabaseService extends PluginDatabaseManager {}
// @public
export type DiscoveryService = {
export interface DiscoveryService {
getBaseUrl(pluginId: string): Promise<string>;
getExternalBaseUrl(pluginId: string): Promise<string>;
};
// @public (undocumented)
const discoveryServiceRef: ServiceRef<DiscoveryService, 'plugin'>;
}
// @public
export type ExtensionPoint<T> = {
@@ -191,24 +176,18 @@ export interface HttpRouterService {
use(handler: Handler): void;
}
// @public (undocumented)
const httpRouterServiceRef: ServiceRef<HttpRouterService, 'plugin'>;
// @public (undocumented)
export interface LifecycleService {
addShutdownHook(options: LifecycleServiceShutdownHook): void;
}
// @public (undocumented)
const lifecycleServiceRef: ServiceRef<LifecycleService, 'plugin'>;
// @public (undocumented)
export type LifecycleServiceShutdownHook = {
fn: () => void | Promise<void>;
labels?: Record<string, string>;
};
// @public (undocumented)
// @public
export interface LoggerService {
// (undocumented)
child(meta: LogMeta): LoggerService;
@@ -222,9 +201,6 @@ export interface LoggerService {
warn(message: string, meta?: Error | LogMeta): void;
}
// @public (undocumented)
const loggerServiceRef: ServiceRef<LoggerService, 'plugin'>;
// @public (undocumented)
export function loggerToWinstonLogger(
logger: LoggerService,
@@ -237,10 +213,7 @@ export type LogMeta = {
};
// @public (undocumented)
export type PermissionsService = PermissionEvaluator | PermissionAuthorizer;
// @public (undocumented)
const permissionsServiceRef: ServiceRef<PermissionsService, 'plugin'>;
export interface PermissionsService extends PermissionEvaluator {}
// @public (undocumented)
export interface PluginMetadataService {
@@ -248,9 +221,6 @@ export interface PluginMetadataService {
getId(): string;
}
// @public (undocumented)
const pluginMetadataServiceRef: ServiceRef<PluginMetadataService, 'plugin'>;
// @public
export type ReadTreeOptions = {
filter?(
@@ -296,22 +266,13 @@ export type ReadUrlResponse = {
};
// @public (undocumented)
export type RootLifecycleService = LifecycleService;
export interface RootLifecycleService extends LifecycleService {}
// @public (undocumented)
const rootLifecycleServiceRef: ServiceRef<LifecycleService, 'root'>;
export interface RootLoggerService extends LoggerService {}
// @public (undocumented)
export type RootLoggerService = LoggerService;
// @public (undocumented)
const rootLoggerServiceRef: ServiceRef<LoggerService, 'root'>;
// @public (undocumented)
export type SchedulerService = PluginTaskScheduler;
// @public (undocumented)
const schedulerServiceRef: ServiceRef<PluginTaskScheduler, 'plugin'>;
export interface SchedulerService extends PluginTaskScheduler {}
// @public
export type SearchOptions = {
@@ -371,10 +332,7 @@ export type ServiceRef<
};
// @public (undocumented)
export type TokenManagerService = TokenManager;
// @public (undocumented)
const tokenManagerServiceRef: ServiceRef<TokenManager, 'plugin'>;
export interface TokenManagerService extends TokenManager {}
// @public (undocumented)
export type TypesToServiceRef<T> = {
@@ -382,12 +340,9 @@ export type TypesToServiceRef<T> = {
};
// @public
export type UrlReaderService = {
readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
export interface UrlReaderService {
readTree(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
search(url: string, options?: SearchOptions): Promise<SearchResponse>;
};
// @public (undocumented)
const urlReaderServiceRef: ServiceRef<UrlReaderService, 'plugin'>;
}
```
@@ -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<CacheService>({
id: 'core.cache',
});
export interface CacheService extends PluginCacheManager {}
@@ -15,17 +15,8 @@
*/
import { Config } from '@backstage/config';
import { createServiceRef } from '../system/types';
/**
* @public
*/
export type ConfigService = Config;
/**
* @public
*/
export const configServiceRef = createServiceRef<ConfigService>({
id: 'core.root.config',
scope: 'root',
});
export interface ConfigService extends Config {}
@@ -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<DatabaseService>({
id: 'core.database',
});
export interface DatabaseService extends PluginDatabaseManager {}
@@ -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.
@@ -30,7 +28,7 @@ import { createServiceRef } from '../system/types';
*
* @public
*/
export type DiscoveryService = {
export interface DiscoveryService {
/**
* Returns the internal HTTP base URL for a given plugin, without a trailing slash.
*
@@ -62,11 +60,4 @@ export type DiscoveryService = {
* like `https://backstage.example.com/api/catalog`
*/
getExternalBaseUrl(pluginId: string): Promise<string>;
};
/**
* @public
*/
export const discoveryServiceRef = createServiceRef<DiscoveryService>({
id: 'core.discovery',
});
}
@@ -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<HttpRouterService>({
id: 'core.httpRouter',
});
@@ -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<LifecycleService>({
id: 'core.lifecycle',
scope: 'plugin',
});
@@ -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<LoggerService>({
id: 'core.logger',
});
@@ -0,0 +1,20 @@
/*
* Copyright 2022 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { PermissionEvaluator } from '@backstage/plugin-permission-common';
/** @public */
export interface PermissionsService extends PermissionEvaluator {}
@@ -14,20 +14,9 @@
* limitations under the License.
*/
import { createServiceRef } from '../system/types';
/**
* @public
*/
export interface PluginMetadataService {
getId(): string;
}
/**
* @public
*/
export const pluginMetadataServiceRef = createServiceRef<PluginMetadataService>(
{
id: 'core.plugin-metadata',
},
);
@@ -0,0 +1,20 @@
/*
* Copyright 2022 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { LifecycleService } from './LifecycleService';
/** @public */
export interface RootLifecycleService extends LifecycleService {}
@@ -0,0 +1,20 @@
/*
* Copyright 2022 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { LoggerService } from './LoggerService';
/** @public */
export interface RootLoggerService extends LoggerService {}
@@ -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<SchedulerService>({
id: 'core.scheduler',
});
export interface SchedulerService extends PluginTaskScheduler {}
@@ -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<TokenManagerService>({
id: 'core.tokenManager',
});
export interface TokenManagerService extends TokenManager {}
@@ -14,7 +14,6 @@
* limitations under the License.
*/
import { createServiceRef } from '../system/types';
import { Readable } from 'stream';
/**
@@ -22,7 +21,7 @@ import { Readable } from 'stream';
*
* @public
*/
export type UrlReaderService = {
export interface UrlReaderService {
/**
* Reads a single file and return its content.
*/
@@ -37,7 +36,7 @@ export type UrlReaderService = {
* Searches for a file in a tree using a glob pattern.
*/
search(url: string, options?: SearchOptions): Promise<SearchResponse>;
};
}
/**
* An options object for readUrl operations.
@@ -280,10 +279,3 @@ export type SearchResponseFile = {
*/
content(): Promise<Buffer>;
};
/**
* @public
*/
export const urlReaderServiceRef = createServiceRef<UrlReaderService>({
id: 'core.urlReader',
});
@@ -14,17 +14,137 @@
* 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<import('./CacheService').CacheService>({
id: 'core.cache',
});
/**
* The service reference for the root scoped {@link ConfigService}.
*
* @public
*/
export const config = createServiceRef<
import('./ConfigService').ConfigService
>({ id: 'core.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' });
/**
* 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.pluginMetadata' });
/**
* 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.rootLogger', 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' });
}
@@ -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';
@@ -1,31 +0,0 @@
/*
* Copyright 2022 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { createServiceRef } from '../system/types';
import {
PermissionAuthorizer,
PermissionEvaluator,
} from '@backstage/plugin-permission-common';
/** @public */
export type PermissionsService = PermissionEvaluator | PermissionAuthorizer;
/**
* @public
*/
export const permissionsServiceRef = createServiceRef<PermissionsService>({
id: 'core.permissions',
});
@@ -1,29 +0,0 @@
/*
* Copyright 2022 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { createServiceRef } from '../system/types';
import { LifecycleService } from './lifecycleServiceRef';
/** @public */
export type RootLifecycleService = LifecycleService;
/**
* @public
*/
export const rootLifecycleServiceRef = createServiceRef<RootLifecycleService>({
id: 'core.rootLifecycle',
scope: 'root',
});
@@ -1,29 +0,0 @@
/*
* Copyright 2022 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { createServiceRef } from '../system/types';
import { LoggerService } from './loggerServiceRef';
/** @public */
export type RootLoggerService = LoggerService;
/**
* @public
*/
export const rootLoggerServiceRef = createServiceRef<RootLoggerService>({
id: 'core.root.logger',
scope: 'root',
});