diff --git a/packages/backend-app-api/api-report.md b/packages/backend-app-api/api-report.md index 45525efa75..94eb164f8a 100644 --- a/packages/backend-app-api/api-report.md +++ b/packages/backend-app-api/api-report.md @@ -162,7 +162,7 @@ export interface HttpRouterFactoryOptions { getPath?(pluginId: string): string; } -// @public (undocumented) +// @public export const httpRouterServiceFactory: ( options?: HttpRouterFactoryOptions | undefined, ) => ServiceFactory; @@ -224,7 +224,7 @@ export function loadBackendConfig(options: { config: Config; }>; -// @public (undocumented) +// @public export const loggerServiceFactory: () => ServiceFactory< LoggerService, 'plugin' @@ -303,7 +303,7 @@ export interface RootHttpRouterConfigureContext { server: Server; } -// @public (undocumented) +// @public export type RootHttpRouterFactoryOptions = { indexPath?: string | false; configure?(context: RootHttpRouterConfigureContext): void; @@ -320,7 +320,7 @@ export const rootLifecycleServiceFactory: () => ServiceFactory< 'root' >; -// @public (undocumented) +// @public export const rootLoggerServiceFactory: () => ServiceFactory< RootLoggerService, 'root' diff --git a/packages/backend-app-api/src/services/implementations/httpRouter/httpRouterServiceFactory.ts b/packages/backend-app-api/src/services/implementations/httpRouter/httpRouterServiceFactory.ts index 5e3a26252f..4a0dec49e6 100644 --- a/packages/backend-app-api/src/services/implementations/httpRouter/httpRouterServiceFactory.ts +++ b/packages/backend-app-api/src/services/implementations/httpRouter/httpRouterServiceFactory.ts @@ -36,7 +36,15 @@ export interface HttpRouterFactoryOptions { getPath?(pluginId: string): string; } -/** @public */ +/** + * HTTP route registration for plugins. + * + * See {@link @backstage/code-plugin-api#HttpRouterService} + * and {@link https://backstage.io/docs/backend-system/core-services/http-router | the service docs} + * for more information. + * + * @public + */ export const httpRouterServiceFactory = createServiceFactory( (options?: HttpRouterFactoryOptions) => ({ service: coreServices.httpRouter, diff --git a/packages/backend-app-api/src/services/implementations/logger/loggerServiceFactory.ts b/packages/backend-app-api/src/services/implementations/logger/loggerServiceFactory.ts index d9158529ca..4eff798e11 100644 --- a/packages/backend-app-api/src/services/implementations/logger/loggerServiceFactory.ts +++ b/packages/backend-app-api/src/services/implementations/logger/loggerServiceFactory.ts @@ -19,7 +19,15 @@ import { coreServices, } from '@backstage/backend-plugin-api'; -/** @public */ +/** + * Plugin-level logging. + * + * See {@link @backstage/code-plugin-api#LoggerService} + * and {@link https://backstage.io/docs/backend-system/core-services/logger | the service docs} + * for more information. + * + * @public + */ export const loggerServiceFactory = createServiceFactory({ service: coreServices.logger, deps: { diff --git a/packages/backend-app-api/src/services/implementations/rootHttpRouter/rootHttpRouterServiceFactory.ts b/packages/backend-app-api/src/services/implementations/rootHttpRouter/rootHttpRouterServiceFactory.ts index a469a2f303..88cc863374 100644 --- a/packages/backend-app-api/src/services/implementations/rootHttpRouter/rootHttpRouterServiceFactory.ts +++ b/packages/backend-app-api/src/services/implementations/rootHttpRouter/rootHttpRouterServiceFactory.ts @@ -45,6 +45,12 @@ export interface RootHttpRouterConfigureContext { } /** + * HTTP route registration for root services. + * + * See {@link @backstage/code-plugin-api#RootHttpRouterService} + * and {@link https://backstage.io/docs/backend-system/core-services/root-http-router | the service docs} + * for more information. + * * @public */ export type RootHttpRouterFactoryOptions = { diff --git a/packages/backend-app-api/src/services/implementations/rootLogger/rootLoggerServiceFactory.ts b/packages/backend-app-api/src/services/implementations/rootLogger/rootLoggerServiceFactory.ts index bd45df383f..e33de09297 100644 --- a/packages/backend-app-api/src/services/implementations/rootLogger/rootLoggerServiceFactory.ts +++ b/packages/backend-app-api/src/services/implementations/rootLogger/rootLoggerServiceFactory.ts @@ -22,7 +22,15 @@ import { WinstonLogger } from '../../../logging'; import { transports, format } from 'winston'; import { createConfigSecretEnumerator } from '../../../config'; -/** @public */ +/** + * Root-level logging. + * + * See {@link @backstage/code-plugin-api#RootLoggerService} + * and {@link https://backstage.io/docs/backend-system/core-services/root-logger | the service docs} + * for more information. + * + * @public + */ export const rootLoggerServiceFactory = createServiceFactory({ service: coreServices.rootLogger, deps: { diff --git a/packages/backend-defaults/api-report-cache.md b/packages/backend-defaults/api-report-cache.md index c41d553ac8..0bfd7eb463 100644 --- a/packages/backend-defaults/api-report-cache.md +++ b/packages/backend-defaults/api-report-cache.md @@ -24,7 +24,7 @@ export type CacheManagerOptions = { onError?: (err: Error) => void; }; -// @public (undocumented) +// @public export const cacheServiceFactory: () => ServiceFactory; // @public (undocumented) diff --git a/packages/backend-defaults/api-report-database.md b/packages/backend-defaults/api-report-database.md index 728c228899..116830343a 100644 --- a/packages/backend-defaults/api-report-database.md +++ b/packages/backend-defaults/api-report-database.md @@ -31,7 +31,7 @@ export type DatabaseManagerOptions = { logger?: LoggerService; }; -// @public (undocumented) +// @public export const databaseServiceFactory: () => ServiceFactory< DatabaseService, 'plugin' diff --git a/packages/backend-defaults/api-report-discovery.md b/packages/backend-defaults/api-report-discovery.md index 0ff734b8a7..b434dab6fc 100644 --- a/packages/backend-defaults/api-report-discovery.md +++ b/packages/backend-defaults/api-report-discovery.md @@ -7,7 +7,7 @@ import { Config } from '@backstage/config'; import { DiscoveryService } from '@backstage/backend-plugin-api'; import { ServiceFactory } from '@backstage/backend-plugin-api'; -// @public (undocumented) +// @public export const discoveryServiceFactory: () => ServiceFactory< DiscoveryService, 'plugin' diff --git a/packages/backend-defaults/api-report-permissions.md b/packages/backend-defaults/api-report-permissions.md index 9006a62018..c436443ff1 100644 --- a/packages/backend-defaults/api-report-permissions.md +++ b/packages/backend-defaults/api-report-permissions.md @@ -6,7 +6,7 @@ import { PermissionsService } from '@backstage/backend-plugin-api'; import { ServiceFactory } from '@backstage/backend-plugin-api'; -// @public (undocumented) +// @public export const permissionsServiceFactory: () => ServiceFactory< PermissionsService, 'plugin' diff --git a/packages/backend-defaults/api-report-rootConfig.md b/packages/backend-defaults/api-report-rootConfig.md index 60c8fbcb57..2d46370c27 100644 --- a/packages/backend-defaults/api-report-rootConfig.md +++ b/packages/backend-defaults/api-report-rootConfig.md @@ -7,7 +7,7 @@ import { RemoteConfigSourceOptions } from '@backstage/config-loader'; import { RootConfigService } from '@backstage/backend-plugin-api'; import { ServiceFactory } from '@backstage/backend-plugin-api'; -// @public (undocumented) +// @public export interface RootConfigFactoryOptions { argv?: string[]; remote?: Pick; diff --git a/packages/backend-defaults/api-report-urlReader.md b/packages/backend-defaults/api-report-urlReader.md index a1976f5a1c..c56cdba69b 100644 --- a/packages/backend-defaults/api-report-urlReader.md +++ b/packages/backend-defaults/api-report-urlReader.md @@ -425,7 +425,7 @@ export class UrlReaders { static default(options: UrlReadersOptions): UrlReaderService; } -// @public (undocumented) +// @public export const urlReaderServiceFactory: () => ServiceFactory< UrlReaderService, 'plugin' diff --git a/packages/backend-defaults/src/entrypoints/auth/authServiceFactory.ts b/packages/backend-defaults/src/entrypoints/auth/authServiceFactory.ts index 6a1aa51604..e275e2be00 100644 --- a/packages/backend-defaults/src/entrypoints/auth/authServiceFactory.ts +++ b/packages/backend-defaults/src/entrypoints/auth/authServiceFactory.ts @@ -25,7 +25,11 @@ import { createPluginKeySource } from './plugin/keys/createPluginKeySource'; import { UserTokenHandler } from './user/UserTokenHandler'; /** - * Token authentication and credentials management. + * Handles token authentication and credentials management. + * + * See {@link @backstage/code-plugin-api#AuthService} + * and {@link https://backstage.io/docs/backend-system/core-services/auth | the service docs} + * for more information. * * @public */ diff --git a/packages/backend-defaults/src/entrypoints/cache/cacheServiceFactory.ts b/packages/backend-defaults/src/entrypoints/cache/cacheServiceFactory.ts index f60d770644..f16b306d81 100644 --- a/packages/backend-defaults/src/entrypoints/cache/cacheServiceFactory.ts +++ b/packages/backend-defaults/src/entrypoints/cache/cacheServiceFactory.ts @@ -21,6 +21,12 @@ import { import { CacheManager } from './CacheManager'; /** + * Key-value store for caching data. + * + * See {@link @backstage/code-plugin-api#CacheService} + * and {@link https://backstage.io/docs/backend-system/core-services/cache | the service docs} + * for more information. + * * @public */ export const cacheServiceFactory = createServiceFactory({ diff --git a/packages/backend-defaults/src/entrypoints/database/databaseServiceFactory.ts b/packages/backend-defaults/src/entrypoints/database/databaseServiceFactory.ts index 0720d05b43..3bdf1790f3 100644 --- a/packages/backend-defaults/src/entrypoints/database/databaseServiceFactory.ts +++ b/packages/backend-defaults/src/entrypoints/database/databaseServiceFactory.ts @@ -22,6 +22,12 @@ import { ConfigReader } from '@backstage/config'; import { DatabaseManager } from './DatabaseManager'; /** + * Database access and management via `knex`. + * + * See {@link @backstage/code-plugin-api#DatabaseService} + * and {@link https://backstage.io/docs/backend-system/core-services/database | the service docs} + * for more information. + * * @public */ export const databaseServiceFactory = createServiceFactory({ diff --git a/packages/backend-defaults/src/entrypoints/discovery/discoveryServiceFactory.ts b/packages/backend-defaults/src/entrypoints/discovery/discoveryServiceFactory.ts index bfc5a6a489..18ceac4a91 100644 --- a/packages/backend-defaults/src/entrypoints/discovery/discoveryServiceFactory.ts +++ b/packages/backend-defaults/src/entrypoints/discovery/discoveryServiceFactory.ts @@ -20,7 +20,15 @@ import { } from '@backstage/backend-plugin-api'; import { HostDiscovery } from './HostDiscovery'; -/** @public */ +/** + * Service discovery for inter-plugin communication. + * + * See {@link @backstage/code-plugin-api#DiscoveryService} + * and {@link https://backstage.io/docs/backend-system/core-services/discovery | the service docs} + * for more information. + * + * @public + */ export const discoveryServiceFactory = createServiceFactory({ service: coreServices.discovery, deps: { diff --git a/packages/backend-defaults/src/entrypoints/httpAuth/httpAuthServiceFactory.ts b/packages/backend-defaults/src/entrypoints/httpAuth/httpAuthServiceFactory.ts index e24c80aa6a..76550873f6 100644 --- a/packages/backend-defaults/src/entrypoints/httpAuth/httpAuthServiceFactory.ts +++ b/packages/backend-defaults/src/entrypoints/httpAuth/httpAuthServiceFactory.ts @@ -275,6 +275,10 @@ class DefaultHttpAuthService implements HttpAuthService { /** * Authentication of HTTP requests. * + * See {@link @backstage/code-plugin-api#HttpAuthService} + * and {@link https://backstage.io/docs/backend-system/core-services/http-auth | the service docs} + * for more information. + * * @public */ export const httpAuthServiceFactory = createServiceFactory({ diff --git a/packages/backend-defaults/src/entrypoints/lifecycle/lifecycleServiceFactory.ts b/packages/backend-defaults/src/entrypoints/lifecycle/lifecycleServiceFactory.ts index 3eb43d6c6e..192886ca61 100644 --- a/packages/backend-defaults/src/entrypoints/lifecycle/lifecycleServiceFactory.ts +++ b/packages/backend-defaults/src/entrypoints/lifecycle/lifecycleServiceFactory.ts @@ -85,7 +85,11 @@ export class BackendPluginLifecycleImpl implements LifecycleService { } /** - * Allows plugins to register shutdown hooks that are run when the process is about to exit. + * Registration of plugin startup and shutdown lifecycle hooks. + * + * See {@link @backstage/code-plugin-api#LifecycleService} + * and {@link https://backstage.io/docs/backend-system/core-services/lifecycle | the service docs} + * for more information. * * @public */ diff --git a/packages/backend-defaults/src/entrypoints/permissions/permissionsServiceFactory.ts b/packages/backend-defaults/src/entrypoints/permissions/permissionsServiceFactory.ts index f675dd6719..873d6a4fa0 100644 --- a/packages/backend-defaults/src/entrypoints/permissions/permissionsServiceFactory.ts +++ b/packages/backend-defaults/src/entrypoints/permissions/permissionsServiceFactory.ts @@ -21,6 +21,12 @@ import { import { ServerPermissionClient } from '@backstage/plugin-permission-node'; /** + * Permission system integration for authorization of user actions. + * + * See {@link @backstage/code-plugin-api#PermissionsService} + * and {@link https://backstage.io/docs/backend-system/core-services/permissions | the service docs} + * for more information. + * * @public */ export const permissionsServiceFactory = createServiceFactory({ diff --git a/packages/backend-defaults/src/entrypoints/rootConfig/rootConfigServiceFactory.ts b/packages/backend-defaults/src/entrypoints/rootConfig/rootConfigServiceFactory.ts index 92d1a89c0f..5752a9c634 100644 --- a/packages/backend-defaults/src/entrypoints/rootConfig/rootConfigServiceFactory.ts +++ b/packages/backend-defaults/src/entrypoints/rootConfig/rootConfigServiceFactory.ts @@ -24,6 +24,12 @@ import { } from '@backstage/config-loader'; /** + * Access to static configuration. + * + * See {@link @backstage/code-plugin-api#RootConfigService} + * and {@link https://backstage.io/docs/backend-system/core-services/root-config | the service docs} + * for more information. + * * @public */ export interface RootConfigFactoryOptions { diff --git a/packages/backend-defaults/src/entrypoints/rootLifecycle/rootLifecycleServiceFactory.ts b/packages/backend-defaults/src/entrypoints/rootLifecycle/rootLifecycleServiceFactory.ts index 197f99b97a..e724c2f5cb 100644 --- a/packages/backend-defaults/src/entrypoints/rootLifecycle/rootLifecycleServiceFactory.ts +++ b/packages/backend-defaults/src/entrypoints/rootLifecycle/rootLifecycleServiceFactory.ts @@ -105,7 +105,11 @@ export class BackendLifecycleImpl implements RootLifecycleService { } /** - * Allows plugins to register shutdown hooks that are run when the process is about to exit. + * Registration of backend startup and shutdown lifecycle hooks. + * + * See {@link @backstage/code-plugin-api#RootLifecycleService} + * and {@link https://backstage.io/docs/backend-system/core-services/root-lifecycle | the service docs} + * for more information. * * @public */ diff --git a/packages/backend-defaults/src/entrypoints/scheduler/schedulerServiceFactory.ts b/packages/backend-defaults/src/entrypoints/scheduler/schedulerServiceFactory.ts index 1105c86332..effa5c5925 100644 --- a/packages/backend-defaults/src/entrypoints/scheduler/schedulerServiceFactory.ts +++ b/packages/backend-defaults/src/entrypoints/scheduler/schedulerServiceFactory.ts @@ -21,7 +21,11 @@ import { import { DefaultSchedulerService } from './lib/DefaultSchedulerService'; /** - * The default service factory for {@link @backstage/backend-plugin-api#coreServices.scheduler}. + * Scheduling of distributed background tasks. + * + * See {@link @backstage/code-plugin-api#SchedulerService} + * and {@link https://backstage.io/docs/backend-system/core-services/scheduler | the service docs} + * for more information. * * @public */ diff --git a/packages/backend-defaults/src/entrypoints/urlReader/urlReaderServiceFactory.ts b/packages/backend-defaults/src/entrypoints/urlReader/urlReaderServiceFactory.ts index dae8d692cb..810882edf8 100644 --- a/packages/backend-defaults/src/entrypoints/urlReader/urlReaderServiceFactory.ts +++ b/packages/backend-defaults/src/entrypoints/urlReader/urlReaderServiceFactory.ts @@ -20,7 +20,15 @@ import { createServiceFactory, } from '@backstage/backend-plugin-api'; -/** @public */ +/** + * Reading content from external systems. + * + * See {@link @backstage/code-plugin-api#UrlReaderService} + * and {@link https://backstage.io/docs/backend-system/core-services/url-reader | the service docs} + * for more information. + * + * @public + */ export const urlReaderServiceFactory = createServiceFactory({ service: coreServices.urlReader, deps: { diff --git a/packages/backend-defaults/src/entrypoints/userInfo/userInfoServiceFactory.ts b/packages/backend-defaults/src/entrypoints/userInfo/userInfoServiceFactory.ts index db550bf9e8..fe8c398bca 100644 --- a/packages/backend-defaults/src/entrypoints/userInfo/userInfoServiceFactory.ts +++ b/packages/backend-defaults/src/entrypoints/userInfo/userInfoServiceFactory.ts @@ -15,83 +15,20 @@ */ import { - UserInfoService, - BackstageUserInfo, coreServices, createServiceFactory, - DiscoveryService, - BackstageCredentials, } from '@backstage/backend-plugin-api'; -import { ResponseError } from '@backstage/errors'; -import { decodeJwt } from 'jose'; -import fetch from 'node-fetch'; -import { toInternalBackstageCredentials } from '../auth/helpers'; +import { DefaultUserInfoService } from './DefaultUserInfoService'; -type Options = { - discovery: DiscoveryService; -}; - -export class DefaultUserInfoService implements UserInfoService { - private readonly discovery: DiscoveryService; - - constructor(options: Options) { - this.discovery = options.discovery; - } - - async getUserInfo( - credentials: BackstageCredentials, - ): Promise { - const internalCredentials = toInternalBackstageCredentials(credentials); - if (internalCredentials.principal.type !== 'user') { - throw new Error('Only user credentials are supported'); - } - if (!internalCredentials.token) { - throw new Error('User credentials is unexpectedly missing token'); - } - const { sub: userEntityRef, ent: tokenEnt } = decodeJwt( - internalCredentials.token, - ); - - if (typeof userEntityRef !== 'string') { - throw new Error('User entity ref must be a string'); - } - - let ownershipEntityRefs = tokenEnt; - - if (!ownershipEntityRefs) { - const userInfoResp = await fetch( - `${await this.discovery.getBaseUrl('auth')}/v1/userinfo`, - { - headers: { - Authorization: `Bearer ${internalCredentials.token}`, - }, - }, - ); - - if (!userInfoResp.ok) { - throw await ResponseError.fromResponse(userInfoResp); - } - - const { - claims: { ent }, - } = await userInfoResp.json(); - ownershipEntityRefs = ent; - } - - if (!ownershipEntityRefs) { - throw new Error('Ownership entity refs can not be determined'); - } else if ( - !Array.isArray(ownershipEntityRefs) || - ownershipEntityRefs.some(ref => typeof ref !== 'string') - ) { - throw new Error('Ownership entity refs must be an array of strings'); - } - - return { userEntityRef, ownershipEntityRefs }; - } -} - -/** @public */ +/** + * Authenticated user information retrieval. + * + * See {@link @backstage/code-plugin-api#UserInfoService} + * and {@link https://backstage.io/docs/backend-system/core-services/user-info | the service docs} + * for more information. + * + * @public + */ export const userInfoServiceFactory = createServiceFactory({ service: coreServices.userInfo, deps: {