From f77bd5c8ff955d2842579706297cc70e25fd5f7f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Sun, 9 Jan 2022 15:21:44 +0100 Subject: [PATCH] Clean up API reports in backend-common MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- .changeset/twelve-panthers-move.md | 5 ++ packages/backend-common/api-report.md | 53 ++++++------- .../backend-common/src/cache/CacheClient.ts | 6 +- .../backend-common/src/cache/CacheManager.ts | 7 +- packages/backend-common/src/cache/types.ts | 24 ++++-- .../src/database/DatabaseManager.ts | 75 +++++++++++-------- .../backend-common/src/database/connection.ts | 11 ++- packages/backend-common/src/database/types.ts | 2 +- .../backend-common/src/logging/formats.ts | 6 +- .../backend-common/src/logging/rootLogger.ts | 33 +++++++- .../src/middleware/errorHandler.ts | 6 +- .../src/middleware/statusCheckHandler.ts | 13 +++- .../src/reading/AwsS3UrlReader.ts | 5 ++ .../src/reading/AzureUrlReader.ts | 6 +- .../src/reading/BitbucketUrlReader.ts | 4 +- .../src/reading/FetchUrlReader.ts | 2 +- .../src/reading/GithubUrlReader.ts | 2 +- .../src/reading/GitlabUrlReader.ts | 6 +- .../src/reading/GoogleGcsUrlReader.ts | 6 +- .../backend-common/src/reading/UrlReaders.ts | 13 +++- packages/backend-common/src/reading/types.ts | 7 +- packages/backend-common/src/scm/git.ts | 6 +- .../src/service/createStatusCheckRouter.ts | 19 ++++- packages/backend-common/src/service/types.ts | 12 ++- .../src/util/ContainerRunner.ts | 15 +++- .../src/util/DockerContainerRunner.ts | 6 +- 26 files changed, 246 insertions(+), 104 deletions(-) create mode 100644 .changeset/twelve-panthers-move.md diff --git a/.changeset/twelve-panthers-move.md b/.changeset/twelve-panthers-move.md new file mode 100644 index 0000000000..f52050a488 --- /dev/null +++ b/.changeset/twelve-panthers-move.md @@ -0,0 +1,5 @@ +--- +'@backstage/backend-common': patch +--- + +Clean up API reports diff --git a/packages/backend-common/api-report.md b/packages/backend-common/api-report.md index a62a280dc9..d63416571d 100644 --- a/packages/backend-common/api-report.md +++ b/packages/backend-common/api-report.md @@ -34,9 +34,7 @@ import { Server } from 'http'; import * as winston from 'winston'; import { Writable } from 'stream'; -// Warning: (ae-missing-release-tag) "AwsS3UrlReader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export class AwsS3UrlReader implements UrlReader { constructor( integration: AwsS3Integration, @@ -59,7 +57,7 @@ export class AwsS3UrlReader implements UrlReader { toString(): string; } -// @public (undocumented) +// @public export class AzureUrlReader implements UrlReader { constructor( integration: AzureIntegration, @@ -114,12 +112,12 @@ export interface CacheClient { ): Promise; } -// @public (undocumented) +// @public export type CacheClientOptions = { defaultTtl?: number; }; -// @public (undocumented) +// @public export type CacheClientSetOptions = { ttl?: number; }; @@ -133,18 +131,17 @@ export class CacheManager { ): CacheManager; } -// @public (undocumented) +// @public export type CacheManagerOptions = { logger?: Logger_2; onError?: (err: Error) => void; }; -// @public (undocumented) +// @public export const coloredFormat: winston.Logform.Format; -// @public (undocumented) +// @public export interface ContainerRunner { - // (undocumented) runContainer(opts: RunContainerOptions): Promise; } @@ -157,7 +154,7 @@ export function createDatabaseClient( overrides?: Partial, ): Knex; -// @public (undocumented) +// @public export function createRootLogger( options?: winston.LoggerOptions, env?: NodeJS.ProcessEnv, @@ -166,14 +163,14 @@ export function createRootLogger( // @public export function createServiceBuilder(_module: NodeModule): ServiceBuilder; -// @public (undocumented) +// @public export function createStatusCheckRouter(options: { logger: Logger_2; path?: string; statusCheck?: StatusCheck; }): Promise; -// @public (undocumented) +// @public export class DatabaseManager { forPlugin(pluginId: string): PluginDatabaseManager; static fromConfig( @@ -187,7 +184,7 @@ export type DatabaseManagerOptions = { migrations?: PluginDatabaseManager['migrations']; }; -// @public (undocumented) +// @public export class DockerContainerRunner implements ContainerRunner { constructor(options: { dockerClient: Docker }); // (undocumented) @@ -205,7 +202,7 @@ export function errorHandler( options?: ErrorHandlerOptions, ): ErrorRequestHandler; -// @public (undocumented) +// @public export type ErrorHandlerOptions = { showStackTraces?: boolean; logger?: Logger_2; @@ -218,13 +215,13 @@ export type FromReadableArrayOptions = Array<{ path: string; }>; -// @public (undocumented) +// @public export function getRootLogger(): winston.Logger; // @public export function getVoidLogger(): winston.Logger; -// @public (undocumented) +// @public export class Git { // (undocumented) add(options: { dir: string; filepath: string }): Promise; @@ -310,7 +307,7 @@ export class GithubUrlReader implements UrlReader { toString(): string; } -// @public (undocumented) +// @public export class GitlabUrlReader implements UrlReader { constructor( integration: GitLabIntegration, @@ -398,7 +395,7 @@ export type ReadTreeResponseDirOptions = { targetDir?: string; }; -// @public (undocumented) +// @public export interface ReadTreeResponseFactory { // (undocumented) fromReadableArray( @@ -448,7 +445,7 @@ export type ReadUrlResponse = { // @public export function requestLoggingHandler(logger?: Logger_2): RequestHandler; -// @public (undocumented) +// @public export type RequestLoggingHandlerFactory = ( logger?: Logger_2, ) => RequestHandler; @@ -459,7 +456,7 @@ export function resolvePackagePath(name: string, ...paths: string[]): string; // @public export function resolveSafeChildPath(base: string, path: string): string; -// @public (undocumented) +// @public export type RunContainerOptions = { imageName: string; command?: string | string[]; @@ -508,7 +505,7 @@ export class ServerTokenManager implements TokenManager { static noop(): TokenManager; } -// @public (undocumented) +// @public export type ServiceBuilder = { loadConfig(config: Config): ServiceBuilder; setPort(port: number): ServiceBuilder; @@ -534,7 +531,7 @@ export type ServiceBuilder = { start(): Promise; }; -// @public (undocumented) +// @public export function setRootLogger(newLogger: winston.Logger): void; // @public @deprecated @@ -554,7 +551,7 @@ export class SingleHostDiscovery implements PluginEndpointDiscovery { getExternalBaseUrl(pluginId: string): Promise; } -// @public (undocumented) +// @public export type StatusCheck = () => Promise; // @public @@ -562,7 +559,7 @@ export function statusCheckHandler( options?: StatusCheckHandlerOptions, ): Promise; -// @public (undocumented) +// @public export interface StatusCheckHandlerOptions { statusCheck?: StatusCheck; } @@ -597,7 +594,7 @@ export class UrlReaders { static default(options: UrlReadersOptions): UrlReader; } -// @public (undocumented) +// @public export type UrlReadersOptions = { config: Config; logger: Logger_2; @@ -612,8 +609,4 @@ export function useHotCleanup( // @public export function useHotMemoize(_module: NodeModule, valueFactory: () => T): T; - -// Warnings were encountered during analysis: -// -// src/database/types.d.ts:23:12 - (tsdoc-undefined-tag) The TSDoc tag "@default" is not defined in this configuration ``` diff --git a/packages/backend-common/src/cache/CacheClient.ts b/packages/backend-common/src/cache/CacheClient.ts index 8e046f7f19..96982edeaa 100644 --- a/packages/backend-common/src/cache/CacheClient.ts +++ b/packages/backend-common/src/cache/CacheClient.ts @@ -22,7 +22,11 @@ type CacheClientArgs = { client: Keyv; }; -/** @public */ +/** + * Options passed to {@link CacheClient.set}. + * + * @public + */ export type CacheClientSetOptions = { /** * Optional TTL in milliseconds. Defaults to the TTL provided when the client diff --git a/packages/backend-common/src/cache/CacheManager.ts b/packages/backend-common/src/cache/CacheManager.ts index 896c08fb94..66e9849e77 100644 --- a/packages/backend-common/src/cache/CacheManager.ts +++ b/packages/backend-common/src/cache/CacheManager.ts @@ -55,8 +55,8 @@ export class CacheManager { private readonly errorHandler: CacheManagerOptions['onError']; /** - * Creates a new CacheManager instance by reading from the `backend` config - * section, specifically the `.cache` key. + * Creates a new {@link CacheManager} instance by reading from the `backend` + * config section, specifically the `.cache` key. * * @param config - The loaded application configuration. */ @@ -93,7 +93,8 @@ export class CacheManager { /** * Generates a PluginCacheManager for consumption by plugins. * - * @param pluginId - The plugin that the cache manager should be created for. Plugin names should be unique. + * @param pluginId - The plugin that the cache manager should be created for. + * Plugin names should be unique. */ forPlugin(pluginId: string): PluginCacheManager { return { diff --git a/packages/backend-common/src/cache/types.ts b/packages/backend-common/src/cache/types.ts index 70c46770a8..5cf8323c52 100644 --- a/packages/backend-common/src/cache/types.ts +++ b/packages/backend-common/src/cache/types.ts @@ -17,7 +17,11 @@ import { Logger } from 'winston'; import { CacheClient } from './CacheClient'; -/** @public */ +/** + * Options given when constructing a {@link CacheClient}. + * + * @public + */ export type CacheClientOptions = { /** * An optional default TTL (in milliseconds) to be set when getting a client @@ -27,7 +31,11 @@ export type CacheClientOptions = { defaultTtl?: number; }; -/** @public */ +/** + * Options given when constructing a {@link CacheManager}. + * + * @public + */ export type CacheManagerOptions = { /** * An optional logger for use by the PluginCacheManager. @@ -42,17 +50,19 @@ export type CacheManagerOptions = { }; /** - * The PluginCacheManager manages access to cache stores that Plugins get. + * Manages access to cache stores that plugins get. * * @public */ export type PluginCacheManager = { /** - * getClient provides backend plugins cache connections for itself. + * Provides backend plugins cache connections for themselves. * - * The purpose of this method is to allow plugins to get isolated data - * stores so that plugins are discouraged from cache-level integration - * and/or cache key collisions. + * @remarks + * + * The purpose of this method is to allow plugins to get isolated data stores + * so that plugins are discouraged from cache-level integration and/or cache + * key collisions. */ getClient: (options?: CacheClientOptions) => CacheClient; }; diff --git a/packages/backend-common/src/database/DatabaseManager.ts b/packages/backend-common/src/database/DatabaseManager.ts index 5959c60c83..3aadd30148 100644 --- a/packages/backend-common/src/database/DatabaseManager.ts +++ b/packages/backend-common/src/database/DatabaseManager.ts @@ -38,7 +38,7 @@ function pluginPath(pluginId: string): string { } /** - * Configuration options object. + * Creation options for {@link DatabaseManager}. * * @public */ @@ -46,15 +46,20 @@ export type DatabaseManagerOptions = { migrations?: PluginDatabaseManager['migrations']; }; -/** @public */ +/** + * Manages database connections for Backstage backend plugins. + * + * The database manager allows the user to set connection and client settings on + * a per pluginId basis by defining a database config block under + * `plugin.` in addition to top level defaults. Optionally, a user may + * set `prefix` which is used to prefix generated database names if config is + * not provided. + * + * @public + */ export class DatabaseManager { /** - * Creates a DatabaseManager from `backend.database` config. - * - * The database manager allows the user to set connection and client settings on a per pluginId - * basis by defining a database config block under `plugin.` in addition to top level - * defaults. Optionally, a user may set `prefix` which is used to prefix generated database - * names if config is not provided. + * Creates a {@link DatabaseManager} from `backend.database` config. * * @param config - The loaded application configuration. * @param options - An optional configuration object. @@ -108,7 +113,7 @@ export class DatabaseManager { * which is the pluginId prefixed with 'backstage_plugin_'. If `pluginDivisionMode` is * `schema`, it will fallback to using the default database for the knex instance. * - * @param pluginId Lookup the database name for given plugin + * @param pluginId - Lookup the database name for given plugin * @returns String representing the plugin's database name */ private getDatabaseName(pluginId: string): string | undefined { @@ -143,12 +148,13 @@ export class DatabaseManager { /** * Provides the client type which should be used for a given plugin. * - * The client type is determined by plugin specific config if present. Otherwise the base - * client is used as the fallback. + * The client type is determined by plugin specific config if present. + * Otherwise the base client is used as the fallback. * - * @param pluginId Plugin to get the client type for - * @returns Object with client type returned as `client` and boolean representing whether - * or not the client was overridden as `overridden` + * @param pluginId - Plugin to get the client type for + * @returns Object with client type returned as `client` and boolean + * representing whether or not the client was overridden as + * `overridden` */ private getClientType(pluginId: string): { client: string; @@ -169,8 +175,8 @@ export class DatabaseManager { /** * Provides the knexConfig which should be used for a given plugin. * - * @param pluginId Plugin to get the knexConfig for - * @returns the merged kexConfig value or undefined if it isn't specified + * @param pluginId - Plugin to get the knexConfig for + * @returns The merged knexConfig value or undefined if it isn't specified */ private getAdditionalKnexConfig(pluginId: string): JsonObject | undefined { const pluginConfig = this.config @@ -197,13 +203,15 @@ export class DatabaseManager { } /** - * Provides a Knex connection plugin config by combining base and plugin config. + * Provides a Knex connection plugin config by combining base and plugin + * config. * - * This method provides a baseConfig for a plugin database connector. If the client type - * has not been overridden, the global connection config will be included with plugin - * specific config as the base. Values from the plugin connection take precedence over the - * base. Base database name is omitted for all supported databases excluding SQLite unless - * `pluginDivisionMode` is set to `schema`. + * This method provides a baseConfig for a plugin database connector. If the + * client type has not been overridden, the global connection config will be + * included with plugin specific config as the base. Values from the plugin + * connection take precedence over the base. Base database name is omitted for + * all supported databases excluding SQLite unless `pluginDivisionMode` is set + * to `schema`. */ private getConnectionConfig( pluginId: string, @@ -249,9 +257,10 @@ export class DatabaseManager { /** * Provides a Knex database config for a given plugin. * - * This method provides a Knex configuration object along with the plugin's client type. + * This method provides a Knex configuration object along with the plugin's + * client type. * - * @param pluginId The plugin that the database config should correspond with + * @param pluginId - The plugin that the database config should correspond with */ private getConfigForPlugin(pluginId: string): Knex.Config { const { client } = this.getClientType(pluginId); @@ -264,20 +273,21 @@ export class DatabaseManager { } /** - * Provides a partial Knex.Config database schema override for a given plugin. + * Provides a partial `Knex.Config` database schema override for a given + * plugin. * - * @param pluginId Target plugin to get database schema override - * @returns Partial Knex.Config with database schema override + * @param pluginId - Target plugin to get database schema override + * @returns Partial `Knex.Config` with database schema override */ private getSchemaOverrides(pluginId: string): Knex.Config | undefined { return createSchemaOverride(this.getClientType(pluginId).client, pluginId); } /** - * Provides a partial Knex.Config database name override for a given plugin. + * Provides a partial `Knex.Config`• database name override for a given plugin. * - * @param pluginId Target plugin to get database name override - * @returns Partial Knex.Config with database name override + * @param pluginId - Target plugin to get database name override + * @returns Partial `Knex.Config` with database name override */ private getDatabaseOverrides(pluginId: string): Knex.Config { const databaseName = this.getDatabaseName(pluginId); @@ -289,8 +299,9 @@ export class DatabaseManager { /** * Provides a scoped Knex client for a plugin as per application config. * - * @param pluginId Plugin to get a Knex client for - * @returns Promise which resolves to a scoped Knex database client for a plugin + * @param pluginId - Plugin to get a Knex client for + * @returns Promise which resolves to a scoped Knex database client for a + * plugin */ private async getDatabase(pluginId: string): Promise { const pluginConfig = new ConfigReader( diff --git a/packages/backend-common/src/database/connection.ts b/packages/backend-common/src/database/connection.ts index 3308a26573..7fc9df060d 100644 --- a/packages/backend-common/src/database/connection.ts +++ b/packages/backend-common/src/database/connection.ts @@ -58,7 +58,7 @@ export function createDatabaseClient( } /** - * Alias for createDatabaseClient + * Alias for {@link createDatabaseClient} * * @public * @deprecated Use createDatabaseClient instead @@ -100,7 +100,8 @@ export async function ensureSchemaExists( } /** - * Provides a Knex.Config object with the provided database name for a given client. + * Provides a `Knex.Config` object with the provided database name for a given + * client. */ export function createNameOverride( client: string, @@ -117,7 +118,8 @@ export function createNameOverride( } /** - * Provides a Knex.Config object with the provided database schema for a given client. Currently only supported by `pg`. + * Provides a `Knex.Config` object with the provided database schema for a given + * client. Currently only supported by `pg`. */ export function createSchemaOverride( client: string, @@ -156,7 +158,8 @@ export function parseConnectionString( } /** - * Normalizes a connection config or string into an object which can be passed to Knex. + * Normalizes a connection config or string into an object which can be passed + * to Knex. */ export function normalizeConnection( connection: Knex.StaticConnectionConfig | JsonObject | string | undefined, diff --git a/packages/backend-common/src/database/types.ts b/packages/backend-common/src/database/types.ts index 344f1088b8..2fa8b749a8 100644 --- a/packages/backend-common/src/database/types.ts +++ b/packages/backend-common/src/database/types.ts @@ -38,7 +38,7 @@ export interface PluginDatabaseManager { /** * skip database migrations. Useful if connecting to a read-only database. * - * @default false + * @defaultValue false */ skip?: boolean; }; diff --git a/packages/backend-common/src/logging/formats.ts b/packages/backend-common/src/logging/formats.ts index 0477136e63..53eb55e790 100644 --- a/packages/backend-common/src/logging/formats.ts +++ b/packages/backend-common/src/logging/formats.ts @@ -31,7 +31,11 @@ const coloredTemplate = (info: TransformableInfo) => { return `${timestampColor} ${prefixColor} ${level} ${message} ${extraFields}`; }; -/** @public */ +/** + * A logging format that adds coloring to console output. + * + * @public + */ export const coloredFormat = winston.format.combine( winston.format.timestamp(), winston.format.colorize({ diff --git a/packages/backend-common/src/logging/rootLogger.ts b/packages/backend-common/src/logging/rootLogger.ts index 12db7d42a1..87180bde8f 100644 --- a/packages/backend-common/src/logging/rootLogger.ts +++ b/packages/backend-common/src/logging/rootLogger.ts @@ -23,12 +23,29 @@ import { escapeRegExp } from '../util/escapeRegExp'; let rootLogger: winston.Logger; let redactionRegExp: RegExp | undefined; -/** @public */ +/** + * Gets the current root logger. + * + * @public + */ export function getRootLogger(): winston.Logger { return rootLogger; } -/** @public */ +/** + * Sets a completely custom default "root" logger. + * + * @remarks + * + * This is the logger instance that will be the foundation for all other logger + * instances passed to plugins etc, in a given backend. + * + * Only use this if you absolutely need to make a completely custom logger. + * Normally if you want to make light adaptations to the default logger + * behavior, you would instead call {@link createRootLogger}. + * + * @public + */ export function setRootLogger(newLogger: winston.Logger) { rootLogger = newLogger; } @@ -67,7 +84,17 @@ function redactLogLine(info: winston.Logform.TransformableInfo) { return info; } -/** @public */ +/** + * Creates a default "root" logger. This also calls {@link setRootLogger} under + * the hood. + * + * @remarks + * + * This is the logger instance that will be the foundation for all other logger + * instances passed to plugins etc, in a given backend. + * + * @public + */ export function createRootLogger( options: winston.LoggerOptions = {}, env = process.env, diff --git a/packages/backend-common/src/middleware/errorHandler.ts b/packages/backend-common/src/middleware/errorHandler.ts index 47c9285b18..6077b6a140 100644 --- a/packages/backend-common/src/middleware/errorHandler.ts +++ b/packages/backend-common/src/middleware/errorHandler.ts @@ -28,7 +28,11 @@ import { ErrorRequestHandler, NextFunction, Request, Response } from 'express'; import { Logger } from 'winston'; import { getRootLogger } from '../logging'; -/** @public */ +/** + * Options passed to the {@link errorHandler} middleware. + * + * @public + */ export type ErrorHandlerOptions = { /** * Whether error response bodies should show error stack traces or not. diff --git a/packages/backend-common/src/middleware/statusCheckHandler.ts b/packages/backend-common/src/middleware/statusCheckHandler.ts index a0ba59fac4..4655d610fe 100644 --- a/packages/backend-common/src/middleware/statusCheckHandler.ts +++ b/packages/backend-common/src/middleware/statusCheckHandler.ts @@ -16,10 +16,19 @@ import { NextFunction, Request, Response, RequestHandler } from 'express'; -/** @public */ +/** + * A custom status checking function, passed to {@link statusCheckHandler} and + * {@link createStatusCheckRouter}. + * + * @public + */ export type StatusCheck = () => Promise; -/** @public */ +/** + * Options passed to {@link statusCheckHandler}. + * + * @public + */ export interface StatusCheckHandlerOptions { /** * Optional status function which returns a message. diff --git a/packages/backend-common/src/reading/AwsS3UrlReader.ts b/packages/backend-common/src/reading/AwsS3UrlReader.ts index 1fca72e91c..e64334321d 100644 --- a/packages/backend-common/src/reading/AwsS3UrlReader.ts +++ b/packages/backend-common/src/reading/AwsS3UrlReader.ts @@ -94,6 +94,11 @@ const parseURL = ( }; }; +/** + * Implements a {@link UrlReader} for AWS S3 buckets. + * + * @public + */ export class AwsS3UrlReader implements UrlReader { static factory: ReaderFactory = ({ config, treeResponseFactory }) => { const integrations = ScmIntegrations.fromConfig(config); diff --git a/packages/backend-common/src/reading/AzureUrlReader.ts b/packages/backend-common/src/reading/AzureUrlReader.ts index 37d97b8941..d6ceaec258 100644 --- a/packages/backend-common/src/reading/AzureUrlReader.ts +++ b/packages/backend-common/src/reading/AzureUrlReader.ts @@ -38,7 +38,11 @@ import { ReadUrlResponse, } from './types'; -/** @public */ +/** + * Implements a {@link UrlReader} for Azure repos. + * + * @public + */ export class AzureUrlReader implements UrlReader { static factory: ReaderFactory = ({ config, treeResponseFactory }) => { const integrations = ScmIntegrations.fromConfig(config); diff --git a/packages/backend-common/src/reading/BitbucketUrlReader.ts b/packages/backend-common/src/reading/BitbucketUrlReader.ts index b0e8056370..2006637545 100644 --- a/packages/backend-common/src/reading/BitbucketUrlReader.ts +++ b/packages/backend-common/src/reading/BitbucketUrlReader.ts @@ -41,8 +41,8 @@ import { } from './types'; /** - * A processor that adds the ability to read files from Bitbucket v1 and v2 APIs, such as - * the one exposed by Bitbucket Cloud itself. + * Implements a {@link UrlReader} for files from Bitbucket v1 and v2 APIs, such + * as the one exposed by Bitbucket Cloud itself. * * @public */ diff --git a/packages/backend-common/src/reading/FetchUrlReader.ts b/packages/backend-common/src/reading/FetchUrlReader.ts index 7090d26d35..cb873ebdf8 100644 --- a/packages/backend-common/src/reading/FetchUrlReader.ts +++ b/packages/backend-common/src/reading/FetchUrlReader.ts @@ -27,7 +27,7 @@ import { import path from 'path'; /** - * A UrlReader that does a plain fetch of the URL. + * A {@link UrlReader} that does a plain fetch of the URL. * * @public */ diff --git a/packages/backend-common/src/reading/GithubUrlReader.ts b/packages/backend-common/src/reading/GithubUrlReader.ts index 6b18cfbe1a..72a8f0b90e 100644 --- a/packages/backend-common/src/reading/GithubUrlReader.ts +++ b/packages/backend-common/src/reading/GithubUrlReader.ts @@ -50,7 +50,7 @@ export type GhBlobResponse = RestEndpointMethodTypes['git']['getBlob']['response']['data']; /** - * A processor that adds the ability to read files from GitHub v3 APIs, such as + * Implements a {@link UrlReader} for files through the GitHub v3 APIs, such as * the one exposed by GitHub itself. * * @public diff --git a/packages/backend-common/src/reading/GitlabUrlReader.ts b/packages/backend-common/src/reading/GitlabUrlReader.ts index 2444e317a7..d0e43fea59 100644 --- a/packages/backend-common/src/reading/GitlabUrlReader.ts +++ b/packages/backend-common/src/reading/GitlabUrlReader.ts @@ -39,7 +39,11 @@ import { } from './types'; import { trimEnd } from 'lodash'; -/** @public */ +/** + * Implements a {@link UrlReader} for files on GitLab. + * + * @public + */ export class GitlabUrlReader implements UrlReader { static factory: ReaderFactory = ({ config, treeResponseFactory }) => { const integrations = ScmIntegrations.fromConfig(config); diff --git a/packages/backend-common/src/reading/GoogleGcsUrlReader.ts b/packages/backend-common/src/reading/GoogleGcsUrlReader.ts index f1684c2945..baa9477c6a 100644 --- a/packages/backend-common/src/reading/GoogleGcsUrlReader.ts +++ b/packages/backend-common/src/reading/GoogleGcsUrlReader.ts @@ -48,7 +48,11 @@ const parseURL = ( }; }; -/** @public */ +/** + * Implements a {@link UrlReader} for files on Google GCS. + * + * @public + */ export class GoogleGcsUrlReader implements UrlReader { static factory: ReaderFactory = ({ config, logger }) => { if (!config.has('integrations.googleGcs')) { diff --git a/packages/backend-common/src/reading/UrlReaders.ts b/packages/backend-common/src/reading/UrlReaders.ts index a920ec080b..c0aae25808 100644 --- a/packages/backend-common/src/reading/UrlReaders.ts +++ b/packages/backend-common/src/reading/UrlReaders.ts @@ -27,7 +27,11 @@ import { FetchUrlReader } from './FetchUrlReader'; import { GoogleGcsUrlReader } from './GoogleGcsUrlReader'; import { AwsS3UrlReader } from './AwsS3UrlReader'; -/** @public */ +/** + * Creation options for {@link UrlReaders}. + * + * @public + */ export type UrlReadersOptions = { /** Root config object */ config: Config; @@ -38,13 +42,13 @@ export type UrlReadersOptions = { }; /** - * UrlReaders provide various utilities related to the UrlReader interface. + * Helps construct {@link UrlReader}s. * * @public */ export class UrlReaders { /** - * Creates a UrlReader without any known types. + * Creates a custom {@link UrlReader} wrapper for your own set of factories. */ static create(options: UrlReadersOptions): UrlReader { const { logger, config, factories } = options; @@ -65,7 +69,8 @@ export class UrlReaders { } /** - * Creates a UrlReader that includes all the default factories from this package. + * Creates a {@link UrlReader} wrapper that includes all the default factories + * from this package. * * Any additional factories passed will be loaded before the default ones. */ diff --git a/packages/backend-common/src/reading/types.ts b/packages/backend-common/src/reading/types.ts index 46be7aa1b6..9505778705 100644 --- a/packages/backend-common/src/reading/types.ts +++ b/packages/backend-common/src/reading/types.ts @@ -281,7 +281,12 @@ export type FromReadableArrayOptions = Array<{ path: string; }>; -/** @public */ +/** + * A factory for response factories that handle the unpacking and inspection of + * complex responses such as archive data. + * + * @public + */ export interface ReadTreeResponseFactory { fromTarArchive( options: ReadTreeResponseFactoryOptions, diff --git a/packages/backend-common/src/scm/git.ts b/packages/backend-common/src/scm/git.ts index 0446f08767..9cf84e9872 100644 --- a/packages/backend-common/src/scm/git.ts +++ b/packages/backend-common/src/scm/git.ts @@ -33,7 +33,11 @@ From : https://isomorphic-git.org/docs/en/onAuth with fix for GitHub Azure 'notempty' token */ -/** @public */ +/** + * A convenience wrapper around the `isomorphic-git` library. + * + * @public + */ export class Git { private constructor( private readonly config: { diff --git a/packages/backend-common/src/service/createStatusCheckRouter.ts b/packages/backend-common/src/service/createStatusCheckRouter.ts index 0d0f93f25c..7c916da0e7 100644 --- a/packages/backend-common/src/service/createStatusCheckRouter.ts +++ b/packages/backend-common/src/service/createStatusCheckRouter.ts @@ -19,9 +19,26 @@ import Router from 'express-promise-router'; import express from 'express'; import { errorHandler, statusCheckHandler, StatusCheck } from '../middleware'; -/** @public */ +/** + * Creates a default status checking router, that you can add to your express + * app. + * + * @remarks + * + * This adds a `/healthcheck` route (or any other path, if given as an + * argument), which your infra can call to see if the service is ready to serve + * requests. + * + * @public + */ export async function createStatusCheckRouter(options: { logger: Logger; + /** + * The path (including a leading slash) that the health check should be + * mounted on. + * + * @defaultValue '/healthcheck' + */ path?: string; /** * If not implemented, the default express middleware always returns 200. diff --git a/packages/backend-common/src/service/types.ts b/packages/backend-common/src/service/types.ts index 3e94196006..5df9f3fa5d 100644 --- a/packages/backend-common/src/service/types.ts +++ b/packages/backend-common/src/service/types.ts @@ -20,7 +20,11 @@ import { Router, RequestHandler, ErrorRequestHandler } from 'express'; import { Server } from 'http'; import { Logger } from 'winston'; -/** @public */ +/** + * A helper for building backend service instances. + * + * @public + */ export type ServiceBuilder = { /** * Sets the service parameters based on configuration. @@ -119,5 +123,9 @@ export type ServiceBuilder = { start(): Promise; }; -/** @public */ +/** + * A factory for request loggers. + * + * @public + */ export type RequestLoggingHandlerFactory = (logger?: Logger) => RequestHandler; diff --git a/packages/backend-common/src/util/ContainerRunner.ts b/packages/backend-common/src/util/ContainerRunner.ts index be861501c3..22e40ec455 100644 --- a/packages/backend-common/src/util/ContainerRunner.ts +++ b/packages/backend-common/src/util/ContainerRunner.ts @@ -16,7 +16,11 @@ import { Writable } from 'stream'; -/** @public */ +/** + * Options passed to the {@link ContainerRunner.runContainer} method. + * + * @public + */ export type RunContainerOptions = { imageName: string; command?: string | string[]; @@ -28,7 +32,14 @@ export type RunContainerOptions = { pullImage?: boolean; }; -/** @public */ +/** + * Handles the running of containers, on behalf of others. + * + * @public + */ export interface ContainerRunner { + /** + * Runs a container image to completion. + */ runContainer(opts: RunContainerOptions): Promise; } diff --git a/packages/backend-common/src/util/DockerContainerRunner.ts b/packages/backend-common/src/util/DockerContainerRunner.ts index 424913f316..522328c2ec 100644 --- a/packages/backend-common/src/util/DockerContainerRunner.ts +++ b/packages/backend-common/src/util/DockerContainerRunner.ts @@ -24,7 +24,11 @@ export type UserOptions = { User?: string; }; -/** @public */ +/** + * A {@link ContainerRunner} for Docker containers. + * + * @public + */ export class DockerContainerRunner implements ContainerRunner { private readonly dockerClient: Docker;