better doc comments

Signed-off-by: Fredrik Adelöw <freben@gmail.com>
2024-06-17 13:52:07 +02:00
parent 9539a0b0a9
commit 1fbd0c4f27
23 changed files with 119 additions and 92 deletions
@@ -162,7 +162,7 @@ export interface HttpRouterFactoryOptions {
  getPath?(pluginId: string): string;
 }

-// @public (undocumented)
+// @public
 export const httpRouterServiceFactory: (
  options?: HttpRouterFactoryOptions | undefined,
 ) => ServiceFactory<HttpRouterService, 'plugin'>;
@@ -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'
@@ -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,
@@ -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: {
@@ -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 = {
@@ -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: {
@@ -24,7 +24,7 @@ export type CacheManagerOptions = {
  onError?: (err: Error) => void;
 };

-// @public (undocumented)
+// @public
 export const cacheServiceFactory: () => ServiceFactory<CacheService, 'plugin'>;

 // @public (undocumented)
@@ -31,7 +31,7 @@ export type DatabaseManagerOptions = {
  logger?: LoggerService;
 };

-// @public (undocumented)
+// @public
 export const databaseServiceFactory: () => ServiceFactory<
  DatabaseService,
  'plugin'
@@ -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'
@@ -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'
@@ -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<RemoteConfigSourceOptions, 'reloadInterval'>;
@@ -425,7 +425,7 @@ export class UrlReaders {
  static default(options: UrlReadersOptions): UrlReaderService;
 }

-// @public (undocumented)
+// @public
 export const urlReaderServiceFactory: () => ServiceFactory<
  UrlReaderService,
  'plugin'
@@ -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
 */
@@ -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({
@@ -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({
@@ -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: {
@@ -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({
@@ -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
 */
@@ -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({
@@ -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 {
@@ -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
 */
@@ -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
 */
@@ -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: {
@@ -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<BackstageUserInfo> {
-    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: {