diff --git a/.changeset/wise-monkeys-enjoy.md b/.changeset/wise-monkeys-enjoy.md new file mode 100644 index 0000000000..446d5bbfad --- /dev/null +++ b/.changeset/wise-monkeys-enjoy.md @@ -0,0 +1,5 @@ +--- +'@backstage/backend-common': patch +--- + +Properly export all used types. diff --git a/packages/backend-common/api-report.md b/packages/backend-common/api-report.md index de8c1d4101..eb1f9ad31f 100644 --- a/packages/backend-common/api-report.md +++ b/packages/backend-common/api-report.md @@ -9,7 +9,6 @@ import { AzureIntegration } from '@backstage/integration'; import { BitbucketIntegration } from '@backstage/integration'; import { Config } from '@backstage/config'; -import { ConfigReader } from '@backstage/config'; import cors from 'cors'; import Docker from 'dockerode'; import { ErrorRequestHandler } from 'express'; @@ -17,7 +16,6 @@ import express from 'express'; import { GithubCredentialsProvider } from '@backstage/integration'; import { GitHubIntegration } from '@backstage/integration'; import { GitLabIntegration } from '@backstage/integration'; -import * as http from 'http'; import { isChildPath } from '@backstage/cli-common'; import { JsonValue } from '@backstage/config'; import { Knex } from 'knex'; @@ -32,8 +30,6 @@ import { Server } from 'http'; import * as winston from 'winston'; import { Writable } from 'stream'; -// Warning: (ae-missing-release-tag) "AzureUrlReader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export class AzureUrlReader implements UrlReader { constructor( @@ -56,8 +52,6 @@ export class AzureUrlReader implements UrlReader { toString(): string; } -// Warning: (ae-missing-release-tag) "BitbucketUrlReader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class BitbucketUrlReader implements UrlReader { constructor( @@ -80,92 +74,82 @@ export class BitbucketUrlReader implements UrlReader { toString(): string; } -// Warning: (ae-missing-release-tag) "CacheClient" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export interface CacheClient { delete(key: string): Promise; get(key: string): Promise; - // Warning: (ae-forgotten-export) The symbol "CacheSetOptions" needs to be exported by the entry point index.d.ts - set(key: string, value: JsonValue, options?: CacheSetOptions): Promise; + set( + key: string, + value: JsonValue, + options?: CacheClientSetOptions, + ): Promise; } -// Warning: (ae-missing-release-tag) "CacheManager" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// +// @public (undocumented) +export type CacheClientOptions = { + defaultTtl?: number; +}; + +// @public (undocumented) +export type CacheClientSetOptions = { + ttl?: number; +}; + // @public export class CacheManager { - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen forPlugin(pluginId: string): PluginCacheManager; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (ae-forgotten-export) The symbol "CacheManagerOptions" needs to be exported by the entry point index.d.ts static fromConfig( config: Config, options?: CacheManagerOptions, ): CacheManager; } -// Warning: (ae-missing-release-tag) "coloredFormat" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// +// @public (undocumented) +export type CacheManagerOptions = { + logger?: Logger_2; + onError?: (err: Error) => void; +}; + // @public (undocumented) export const coloredFormat: winston.Logform.Format; -// Warning: (ae-missing-release-tag) "ContainerRunner" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export interface ContainerRunner { // (undocumented) runContainer(opts: RunContainerOptions): Promise; } -// Warning: (ae-missing-release-tag) "createDatabase" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public @deprecated export const createDatabase: typeof createDatabaseClient; -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (ae-missing-release-tag) "createDatabaseClient" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function createDatabaseClient( dbConfig: Config, overrides?: Partial, ): Knex; -// Warning: (ae-missing-release-tag) "createRootLogger" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export function createRootLogger( options?: winston.LoggerOptions, env?: NodeJS.ProcessEnv, ): winston.Logger; -// Warning: (ae-forgotten-export) The symbol "ServiceBuilderImpl" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "createServiceBuilder" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public -export function createServiceBuilder(_module: NodeModule): ServiceBuilderImpl; +export function createServiceBuilder(_module: NodeModule): ServiceBuilder; -// Warning: (ae-forgotten-export) The symbol "StatusCheckRouterOptions" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "createStatusCheckRouter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) -export function createStatusCheckRouter( - options: StatusCheckRouterOptions, -): Promise; +export function createStatusCheckRouter(options: { + logger: Logger_2; + path?: string; + statusCheck?: StatusCheck; +}): Promise; -// Warning: (ae-missing-release-tag) "DatabaseManager" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export class DatabaseManager { - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen forPlugin(pluginId: string): PluginDatabaseManager; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen static fromConfig(config: Config): DatabaseManager; } -// Warning: (ae-missing-release-tag) "DockerContainerRunner" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export class DockerContainerRunner implements ContainerRunner { constructor({ dockerClient }: { dockerClient: Docker }); @@ -182,23 +166,17 @@ export class DockerContainerRunner implements ContainerRunner { }: RunContainerOptions): Promise; } -// Warning: (ae-missing-release-tag) "ensureDatabaseExists" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function ensureDatabaseExists( dbConfig: Config, ...databases: Array ): Promise; -// Warning: (ae-missing-release-tag) "errorHandler" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function errorHandler( options?: ErrorHandlerOptions, ): ErrorRequestHandler; -// Warning: (ae-missing-release-tag) "ErrorHandlerOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type ErrorHandlerOptions = { showStackTraces?: boolean; @@ -206,18 +184,12 @@ export type ErrorHandlerOptions = { logClientErrors?: boolean; }; -// Warning: (ae-missing-release-tag) "getRootLogger" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export function getRootLogger(): winston.Logger; -// Warning: (ae-missing-release-tag) "getVoidLogger" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function getVoidLogger(): winston.Logger; -// Warning: (ae-missing-release-tag) "Git" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export class Git { // (undocumented) @@ -322,8 +294,6 @@ export class Git { resolveRef({ dir, ref }: { dir: string; ref: string }): Promise; } -// Warning: (ae-missing-release-tag) "GithubUrlReader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class GithubUrlReader implements UrlReader { constructor( @@ -347,8 +317,6 @@ export class GithubUrlReader implements UrlReader { toString(): string; } -// Warning: (ae-missing-release-tag) "GitlabUrlReader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export class GitlabUrlReader implements UrlReader { constructor( @@ -373,41 +341,31 @@ export class GitlabUrlReader implements UrlReader { export { isChildPath }; -// Warning: (ae-forgotten-export) The symbol "Options" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "loadBackendConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public -export function loadBackendConfig(options: Options): Promise; +export function loadBackendConfig(options: { + logger: Logger_2; + argv: string[]; +}): Promise; -// Warning: (ae-missing-release-tag) "notFoundHandler" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function notFoundHandler(): RequestHandler; -// Warning: (ae-missing-release-tag) "PluginCacheManager" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type PluginCacheManager = { - getClient: (options?: ClientOptions) => CacheClient; + getClient: (options?: CacheClientOptions) => CacheClient; }; -// Warning: (ae-missing-release-tag) "PluginDatabaseManager" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export interface PluginDatabaseManager { getClient(): Promise; } -// Warning: (ae-missing-release-tag) "PluginEndpointDiscovery" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type PluginEndpointDiscovery = { getBaseUrl(pluginId: string): Promise; getExternalBaseUrl(pluginId: string): Promise; }; -// Warning: (ae-missing-release-tag) "ReaderFactory" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type ReaderFactory = (options: { config: Config; @@ -415,8 +373,6 @@ export type ReaderFactory = (options: { treeResponseFactory: ReadTreeResponseFactory; }) => UrlReaderPredicateTuple[]; -// Warning: (ae-missing-release-tag) "ReadTreeOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type ReadTreeOptions = { filter?( @@ -428,8 +384,6 @@ export type ReadTreeOptions = { etag?: string; }; -// Warning: (ae-missing-release-tag) "ReadTreeResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type ReadTreeResponse = { files(): Promise; @@ -438,68 +392,67 @@ export type ReadTreeResponse = { etag: string; }; -// Warning: (ae-missing-release-tag) "ReadTreeResponseFactory" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// +// @public (undocumented) +export type ReadTreeResponseDirOptions = { + targetDir?: string; +}; + // @public (undocumented) export interface ReadTreeResponseFactory { - // Warning: (ae-forgotten-export) The symbol "FromArchiveOptions" needs to be exported by the entry point index.d.ts - // // (undocumented) - fromTarArchive(options: FromArchiveOptions): Promise; + fromTarArchive( + options: ReadTreeResponseFactoryOptions, + ): Promise; // (undocumented) - fromZipArchive(options: FromArchiveOptions): Promise; + fromZipArchive( + options: ReadTreeResponseFactoryOptions, + ): Promise; } -// Warning: (ae-missing-release-tag) "ReadTreeResponseFile" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// +// @public (undocumented) +export type ReadTreeResponseFactoryOptions = { + stream: Readable; + subpath?: string; + etag: string; + filter?: ( + path: string, + info?: { + size: number; + }, + ) => boolean; +}; + // @public export type ReadTreeResponseFile = { path: string; content(): Promise; }; -// Warning: (ae-missing-release-tag) "ReadUrlOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type ReadUrlOptions = { etag?: string; }; -// Warning: (ae-missing-release-tag) "ReadUrlResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type ReadUrlResponse = { buffer(): Promise; etag?: string; }; -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (ae-missing-release-tag) "requestLoggingHandler" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function requestLoggingHandler(logger?: Logger_2): RequestHandler; -// Warning: (ae-missing-release-tag) "RequestLoggingHandlerFactory" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type RequestLoggingHandlerFactory = ( logger?: Logger_2, ) => RequestHandler; -// Warning: (ae-missing-release-tag) "resolvePackagePath" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function resolvePackagePath(name: string, ...paths: string[]): string; -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (ae-missing-release-tag) "resolveSafeChildPath" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function resolveSafeChildPath(base: string, path: string): string; -// Warning: (ae-missing-release-tag) "RunContainerOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type RunContainerOptions = { imageName: string; @@ -512,39 +465,40 @@ export type RunContainerOptions = { pullImage?: boolean; }; -// Warning: (ae-missing-release-tag) "SearchOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type SearchOptions = { etag?: string; }; -// Warning: (ae-missing-release-tag) "SearchResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type SearchResponse = { files: SearchResponseFile[]; etag: string; }; -// Warning: (ae-missing-release-tag) "SearchResponseFile" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type SearchResponseFile = { url: string; content(): Promise; }; -// Warning: (ae-missing-release-tag) "ServiceBuilder" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type ServiceBuilder = { - loadConfig(config: ConfigReader): ServiceBuilder; + loadConfig(config: Config): ServiceBuilder; setPort(port: number): ServiceBuilder; setHost(host: string): ServiceBuilder; setLogger(logger: Logger_2): ServiceBuilder; enableCors(options: cors.CorsOptions): ServiceBuilder; - setHttpsSettings(settings: HttpsSettings): ServiceBuilder; + setHttpsSettings(settings: { + certificate: + | { + key: string; + cert: string; + } + | { + hostname: string; + }; + }): ServiceBuilder; addRouter(root: string, router: Router | RequestHandler): ServiceBuilder; setRequestLoggingHandler( requestLoggingHandler: RequestLoggingHandlerFactory, @@ -552,18 +506,12 @@ export type ServiceBuilder = { start(): Promise; }; -// Warning: (ae-missing-release-tag) "setRootLogger" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export function setRootLogger(newLogger: winston.Logger): void; -// Warning: (ae-missing-release-tag) "SingleConnectionDatabaseManager" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public @deprecated export const SingleConnectionDatabaseManager: typeof DatabaseManager; -// Warning: (ae-missing-release-tag) "SingleHostDiscovery" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class SingleHostDiscovery implements PluginEndpointDiscovery { static fromConfig( @@ -578,28 +526,19 @@ export class SingleHostDiscovery implements PluginEndpointDiscovery { getExternalBaseUrl(pluginId: string): Promise; } -// Warning: (ae-missing-release-tag) "StatusCheck" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type StatusCheck = () => Promise; -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (ae-missing-release-tag) "statusCheckHandler" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function statusCheckHandler( options?: StatusCheckHandlerOptions, ): Promise; -// Warning: (ae-missing-release-tag) "StatusCheckHandlerOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export interface StatusCheckHandlerOptions { statusCheck?: StatusCheck; } -// Warning: (ae-missing-release-tag) "UrlReader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type UrlReader = { read(url: string): Promise; @@ -608,56 +547,33 @@ export type UrlReader = { search(url: string, options?: SearchOptions): Promise; }; -// Warning: (ae-missing-release-tag) "UrlReaderPredicateTuple" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type UrlReaderPredicateTuple = { predicate: (url: URL) => boolean; reader: UrlReader; }; -// Warning: (ae-missing-release-tag) "UrlReaders" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class UrlReaders { - // Warning: (ae-forgotten-export) The symbol "CreateOptions" needs to be exported by the entry point index.d.ts - static create({ logger, config, factories }: CreateOptions): UrlReader; - static default({ logger, config, factories }: CreateOptions): UrlReader; + static create({ logger, config, factories }: UrlReadersOptions): UrlReader; + static default({ logger, config, factories }: UrlReadersOptions): UrlReader; } -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (ae-missing-release-tag) "useHotCleanup" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// +// @public (undocumented) +export type UrlReadersOptions = { + config: Config; + logger: Logger_2; + factories?: ReaderFactory[]; +}; + // @public export function useHotCleanup( _module: NodeModule, cancelEffect: () => void, ): void; -// Warning: (tsdoc-undefined-tag) The TSDoc tag "@warning" is not defined in this configuration -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (ae-missing-release-tag) "useHotMemoize" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function useHotMemoize(_module: NodeModule, valueFactory: () => T): T; -// Warnings were encountered during analysis: -// -// src/cache/types.d.ts:34:5 - (ae-forgotten-export) The symbol "ClientOptions" needs to be exported by the entry point index.d.ts -// src/middleware/errorHandler.d.ts:17:26 - (tsdoc-malformed-html-name) Invalid HTML element: A space is not allowed here -// src/reading/types.d.ts:108:5 - (ae-forgotten-export) The symbol "ReadTreeResponseDirOptions" needs to be exported by the entry point index.d.ts -// src/service/types.d.ts:12:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/service/types.d.ts:22:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/service/types.d.ts:30:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/service/types.d.ts:38:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/service/types.d.ts:47:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/service/types.d.ts:55:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/service/types.d.ts:57:5 - (ae-forgotten-export) The symbol "HttpsSettings" needs to be exported by the entry point index.d.ts -// src/service/types.d.ts:61:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/service/types.d.ts:62:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/service/types.d.ts:70:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // (No @packageDocumentation comment for this package) ``` diff --git a/packages/backend-common/src/cache/CacheClient.ts b/packages/backend-common/src/cache/CacheClient.ts index 860754aae1..79f48a2757 100644 --- a/packages/backend-common/src/cache/CacheClient.ts +++ b/packages/backend-common/src/cache/CacheClient.ts @@ -22,7 +22,8 @@ type CacheClientArgs = { client: Keyv; }; -type CacheSetOptions = { +/** @public */ +export type CacheClientSetOptions = { /** * Optional TTL in milliseconds. Defaults to the TTL provided when the client * was set up (or no TTL if none are provided). @@ -33,6 +34,8 @@ type CacheSetOptions = { /** * A pre-configured, storage agnostic cache client suitable for use by * Backstage plugins. + * + * @public */ export interface CacheClient { /** @@ -46,7 +49,11 @@ export interface CacheClient { * optional TTL may also be provided, otherwise it defaults to the TTL that * was provided when the client was instantiated. */ - set(key: string, value: JsonValue, options?: CacheSetOptions): Promise; + set( + key: string, + value: JsonValue, + options?: CacheClientSetOptions, + ): Promise; /** * Removes the given key from the cache store. @@ -73,7 +80,7 @@ export class DefaultCacheClient implements CacheClient { async set( key: string, value: JsonValue, - opts: CacheSetOptions = {}, + opts: CacheClientSetOptions = {}, ): Promise { const k = this.getNormalizedKey(key); await this.client.set(k, value, opts.ttl); diff --git a/packages/backend-common/src/cache/CacheManager.ts b/packages/backend-common/src/cache/CacheManager.ts index 9d1afdaaeb..d3a1504187 100644 --- a/packages/backend-common/src/cache/CacheManager.ts +++ b/packages/backend-common/src/cache/CacheManager.ts @@ -22,16 +22,14 @@ import { Logger } from 'winston'; import { getRootLogger } from '../logging'; import { DefaultCacheClient, CacheClient } from './CacheClient'; import { NoStore } from './NoStore'; -import { - CacheManagerOptions, - OptionalOnError, - PluginCacheManager, -} from './types'; +import { CacheManagerOptions, PluginCacheManager } from './types'; /** * Implements a Cache Manager which will automatically create new cache clients * for plugins when requested. All requested cache clients are created with the * connection details provided. + * + * @public */ export class CacheManager { /** @@ -47,13 +45,13 @@ export class CacheManager { private readonly logger: Logger; private readonly store: keyof CacheManager['storeFactories']; private readonly connection: string; - private readonly errorHandler: OptionalOnError; + private readonly errorHandler: CacheManagerOptions['onError']; /** * Creates a new CacheManager instance by reading from the `backend` config * section, specifically the `.cache` key. * - * @param config The loaded application configuration. + * @param config - The loaded application configuration. */ static fromConfig( config: Config, @@ -74,7 +72,7 @@ export class CacheManager { store: string, connectionString: string, logger: Logger, - errorHandler: OptionalOnError, + errorHandler: CacheManagerOptions['onError'], ) { if (!this.storeFactories.hasOwnProperty(store)) { throw new Error(`Unknown cache store: ${store}`); @@ -88,7 +86,7 @@ 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/index.ts b/packages/backend-common/src/cache/index.ts index 45eb431ed1..26e6c102d8 100644 --- a/packages/backend-common/src/cache/index.ts +++ b/packages/backend-common/src/cache/index.ts @@ -14,6 +14,10 @@ * limitations under the License. */ -export type { CacheClient } from './CacheClient'; +export type { CacheClient, CacheClientSetOptions } from './CacheClient'; export { CacheManager } from './CacheManager'; -export type { PluginCacheManager } from './types'; +export type { + PluginCacheManager, + CacheManagerOptions, + CacheClientOptions, +} from './types'; diff --git a/packages/backend-common/src/cache/types.ts b/packages/backend-common/src/cache/types.ts index ac5bb91b21..70c46770a8 100644 --- a/packages/backend-common/src/cache/types.ts +++ b/packages/backend-common/src/cache/types.ts @@ -17,7 +17,8 @@ import { Logger } from 'winston'; import { CacheClient } from './CacheClient'; -type ClientOptions = { +/** @public */ +export type CacheClientOptions = { /** * An optional default TTL (in milliseconds) to be set when getting a client * instance. If not provided, data will persist indefinitely by default (or @@ -26,8 +27,7 @@ type ClientOptions = { defaultTtl?: number; }; -export type OptionalOnError = ((err: Error) => void) | undefined; - +/** @public */ export type CacheManagerOptions = { /** * An optional logger for use by the PluginCacheManager. @@ -38,11 +38,13 @@ export type CacheManagerOptions = { * An optional handler for connection errors emitted from the underlying data * store. */ - onError?: OptionalOnError; + onError?: (err: Error) => void; }; /** * The PluginCacheManager manages access to cache stores that Plugins get. + * + * @public */ export type PluginCacheManager = { /** @@ -52,5 +54,5 @@ export type PluginCacheManager = { * stores so that plugins are discouraged from cache-level integration * and/or cache key collisions. */ - getClient: (options?: ClientOptions) => CacheClient; + getClient: (options?: CacheClientOptions) => CacheClient; }; diff --git a/packages/backend-common/src/config.ts b/packages/backend-common/src/config.ts index 7c660ee4e6..96907870cb 100644 --- a/packages/backend-common/src/config.ts +++ b/packages/backend-common/src/config.ts @@ -101,12 +101,6 @@ class ObservableConfigProxy implements Config { } } -type Options = { - logger: Logger; - // process.argv or any other overrides - argv: string[]; -}; - // A global used to ensure that only a single file watcher is active at a time. let currentCancelFunc: () => void; @@ -114,8 +108,14 @@ let currentCancelFunc: () => void; * Load configuration for a Backend. * * This function should only be called once, during the initialization of the backend. + * + * @public */ -export async function loadBackendConfig(options: Options): Promise { +export async function loadBackendConfig(options: { + logger: Logger; + // process.argv or any other overrides + argv: string[]; +}): Promise { const args = parseArgs(options.argv); const configPaths: string[] = [args.config ?? []].flat(); diff --git a/packages/backend-common/src/database/DatabaseManager.ts b/packages/backend-common/src/database/DatabaseManager.ts index 2d60104bcb..de39279a4f 100644 --- a/packages/backend-common/src/database/DatabaseManager.ts +++ b/packages/backend-common/src/database/DatabaseManager.ts @@ -31,6 +31,7 @@ function pluginPath(pluginId: string): string { return `plugin.${pluginId}`; } +/** @public */ export class DatabaseManager { /** * Creates a DatabaseManager from `backend.database` config. @@ -40,7 +41,7 @@ export class DatabaseManager { * defaults. Optionally, a user may set `prefix` which is used to prefix generated database * names if config is not provided. * - * @param config The loaded application configuration. + * @param config - The loaded application configuration. */ static fromConfig(config: Config): DatabaseManager { const databaseConfig = config.getConfig('backend.database'); @@ -59,7 +60,7 @@ export class DatabaseManager { /** * Generates a PluginDatabaseManager for consumption by plugins. * - * @param pluginId The plugin that the database manager should be created for. Plugin names + * @param pluginId - The plugin that the database manager should be created for. Plugin names * should be unique as they are used to look up database config overrides under * `backend.database.plugin`. */ diff --git a/packages/backend-common/src/database/SingleConnection.ts b/packages/backend-common/src/database/SingleConnection.ts index 153aea7f38..a81d60fe83 100644 --- a/packages/backend-common/src/database/SingleConnection.ts +++ b/packages/backend-common/src/database/SingleConnection.ts @@ -22,6 +22,7 @@ import { DatabaseManager } from './DatabaseManager'; * credentials provided; if the database already exists no attempt to create * the database will be made. * + * @public * @deprecated Use `DatabaseManager` from `@backend-common` instead. */ export const SingleConnectionDatabaseManager = DatabaseManager; diff --git a/packages/backend-common/src/database/config.ts b/packages/backend-common/src/database/config.ts index b771811e8c..cf821087d7 100644 --- a/packages/backend-common/src/database/config.ts +++ b/packages/backend-common/src/database/config.ts @@ -19,6 +19,7 @@ import { merge } from 'lodash'; /** * Merges database objects together * + * @public * @param config The base config. The input is not modified * @param overrides Any additional overrides */ diff --git a/packages/backend-common/src/database/connection.ts b/packages/backend-common/src/database/connection.ts index 6fdb5554bd..8ea46070eb 100644 --- a/packages/backend-common/src/database/connection.ts +++ b/packages/backend-common/src/database/connection.ts @@ -40,8 +40,9 @@ const ConnectorMapping: Record = { /** * Creates a knex database connection * - * @param dbConfig The database config - * @param overrides Additional options to merge with the config + * @public + * @param dbConfig - The database config + * @param overrides - Additional options to merge with the config */ export function createDatabaseClient( dbConfig: Config, @@ -57,12 +58,16 @@ export function createDatabaseClient( /** * Alias for createDatabaseClient + * + * @public * @deprecated Use createDatabaseClient instead */ export const createDatabase = createDatabaseClient; /** * Ensures that the given databases all exist, creating them if they do not. + * + * @public */ export async function ensureDatabaseExists( dbConfig: Config, diff --git a/packages/backend-common/src/database/types.ts b/packages/backend-common/src/database/types.ts index c1647862af..edcba1e643 100644 --- a/packages/backend-common/src/database/types.ts +++ b/packages/backend-common/src/database/types.ts @@ -19,6 +19,8 @@ import { Knex } from 'knex'; /** * The PluginDatabaseManager manages access to databases that Plugins get. + * + * @public */ export interface PluginDatabaseManager { /** diff --git a/packages/backend-common/src/discovery/SingleHostDiscovery.ts b/packages/backend-common/src/discovery/SingleHostDiscovery.ts index 7d19284d9a..c1e092706b 100644 --- a/packages/backend-common/src/discovery/SingleHostDiscovery.ts +++ b/packages/backend-common/src/discovery/SingleHostDiscovery.ts @@ -26,6 +26,8 @@ import { DEFAULT_PORT } from '../service/lib/ServiceBuilderImpl'; * The deployment may be scaled horizontally, as long as the external URL * is the same for all instances. However, internal URLs will always be * resolved to the same host, so there won't be any balancing of internal traffic. + * + * @public */ export class SingleHostDiscovery implements PluginEndpointDiscovery { /** diff --git a/packages/backend-common/src/discovery/types.ts b/packages/backend-common/src/discovery/types.ts index a5915be773..0b502bf88c 100644 --- a/packages/backend-common/src/discovery/types.ts +++ b/packages/backend-common/src/discovery/types.ts @@ -25,6 +25,8 @@ * Implementations of the discovery API can be as simple as a URL pattern * using the pluginId, but could also have overrides for individual plugins, * or query a separate discovery service. + * + * @public */ export type PluginEndpointDiscovery = { /** diff --git a/packages/backend-common/src/hot.ts b/packages/backend-common/src/hot.ts index 951e29da6a..7148778b8c 100644 --- a/packages/backend-common/src/hot.ts +++ b/packages/backend-common/src/hot.ts @@ -46,13 +46,14 @@ function findAllAncestors(_module: NodeModule): NodeModule[] { * * Useful for cleaning intervals, timers, requests etc * + * @public * @example * ```ts * const intervalId = setInterval(doStuff, 1000); * useHotCleanup(module, () => clearInterval(intervalId)); * ``` - * @param _module Reference to the current module where you invoke the fn - * @param cancelEffect Fn that cleans up the ongoing effects + * @param _module - Reference to the current module where you invoke the fn + * @param cancelEffect - Fn that cleans up the ongoing effects */ export function useHotCleanup(_module: NodeModule, cancelEffect: () => void) { if (_module.hot) { @@ -78,16 +79,17 @@ const CURRENT_HOT_MEMOIZE_INDEX_KEY = 'backstage.io/hmr-memoize-key'; * Memoizes a generated value across hot-module reloads. This is useful for * stateful parts of the backend, e.g. to retain a database. * + * @public * @example * ```ts * const db = useHotMemoize(module, () => createDB(dbParams)); * ``` * - * @warning Don't use inside conditionals or loops, + * **NOTE:** Do not use inside conditionals or loops, * same rules as for hooks apply (https://reactjs.org/docs/hooks-rules.html) * - * @param _module Reference to the current module where you invoke the fn - * @param valueFactory Fn that returns the value you want to memoize + * @param _module - Reference to the current module where you invoke the fn + * @param valueFactory - Fn that returns the value you want to memoize */ export function useHotMemoize( _module: NodeModule, diff --git a/packages/backend-common/src/logging/formats.ts b/packages/backend-common/src/logging/formats.ts index 870eeafa2a..0477136e63 100644 --- a/packages/backend-common/src/logging/formats.ts +++ b/packages/backend-common/src/logging/formats.ts @@ -31,6 +31,7 @@ const coloredTemplate = (info: TransformableInfo) => { return `${timestampColor} ${prefixColor} ${level} ${message} ${extraFields}`; }; +/** @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 58b675d9cf..d06037863c 100644 --- a/packages/backend-common/src/logging/rootLogger.ts +++ b/packages/backend-common/src/logging/rootLogger.ts @@ -21,14 +21,17 @@ import { coloredFormat } from './formats'; let rootLogger: winston.Logger; +/** @public */ export function getRootLogger(): winston.Logger { return rootLogger; } +/** @public */ export function setRootLogger(newLogger: winston.Logger) { rootLogger = newLogger; } +/** @public */ export function createRootLogger( options: winston.LoggerOptions = {}, env = process.env, diff --git a/packages/backend-common/src/logging/voidLogger.ts b/packages/backend-common/src/logging/voidLogger.ts index 0afc1fc8c7..eb9993fe7f 100644 --- a/packages/backend-common/src/logging/voidLogger.ts +++ b/packages/backend-common/src/logging/voidLogger.ts @@ -19,6 +19,8 @@ import * as winston from 'winston'; /** * A logger that just throws away all messages. + * + * @public */ export function getVoidLogger(): winston.Logger { return winston.createLogger({ diff --git a/packages/backend-common/src/middleware/errorHandler.ts b/packages/backend-common/src/middleware/errorHandler.ts index ee7995f2c6..47c9285b18 100644 --- a/packages/backend-common/src/middleware/errorHandler.ts +++ b/packages/backend-common/src/middleware/errorHandler.ts @@ -28,6 +28,7 @@ import { ErrorRequestHandler, NextFunction, Request, Response } from 'express'; import { Logger } from 'winston'; import { getRootLogger } from '../logging'; +/** @public */ export type ErrorHandlerOptions = { /** * Whether error response bodies should show error stack traces or not. @@ -44,9 +45,9 @@ export type ErrorHandlerOptions = { logger?: Logger; /** - * Whether any error < 4XX should be logged or not. + * Whether any 4xx errors should be logged or not. * - * If not specified, by default log any 5xx errors. + * If not specified, default to only logging 5xx errors. */ logClientErrors?: boolean; }; @@ -62,6 +63,7 @@ export type ErrorHandlerOptions = { * error types (such as http-error exceptions) and returns the enclosed status * code accordingly. * + * @public * @returns An Express error request handler */ export function errorHandler( diff --git a/packages/backend-common/src/middleware/notFoundHandler.ts b/packages/backend-common/src/middleware/notFoundHandler.ts index 59ca957cc1..53a548c0ad 100644 --- a/packages/backend-common/src/middleware/notFoundHandler.ts +++ b/packages/backend-common/src/middleware/notFoundHandler.ts @@ -22,6 +22,7 @@ import { NextFunction, Request, RequestHandler, Response } from 'express'; * Should be used as the very last handler in the chain, as it unconditionally * returns a 404 status. * + * @public * @returns An Express request handler */ export function notFoundHandler(): RequestHandler { diff --git a/packages/backend-common/src/middleware/requestLoggingHandler.ts b/packages/backend-common/src/middleware/requestLoggingHandler.ts index f2f5cbda27..fa114411e1 100644 --- a/packages/backend-common/src/middleware/requestLoggingHandler.ts +++ b/packages/backend-common/src/middleware/requestLoggingHandler.ts @@ -22,7 +22,8 @@ import { getRootLogger } from '../logging'; /** * Logs incoming requests. * - * @param logger An optional logger to use. If not specified, the root logger will be used. + * @public + * @param logger - An optional logger to use. If not specified, the root logger will be used. * @returns An Express request handler */ export function requestLoggingHandler(logger?: Logger): RequestHandler { diff --git a/packages/backend-common/src/middleware/statusCheckHandler.ts b/packages/backend-common/src/middleware/statusCheckHandler.ts index 243d6533c8..a0ba59fac4 100644 --- a/packages/backend-common/src/middleware/statusCheckHandler.ts +++ b/packages/backend-common/src/middleware/statusCheckHandler.ts @@ -16,8 +16,10 @@ import { NextFunction, Request, Response, RequestHandler } from 'express'; +/** @public */ export type StatusCheck = () => Promise; +/** @public */ export interface StatusCheckHandlerOptions { /** * Optional status function which returns a message. @@ -30,7 +32,8 @@ export interface StatusCheckHandlerOptions { * * This is commonly used to implement healthcheck and readiness routes. * - * @param options An optional configuration object. + * @public + * @param options - An optional configuration object. * @returns An Express error request handler */ export async function statusCheckHandler( diff --git a/packages/backend-common/src/paths.ts b/packages/backend-common/src/paths.ts index ffe99fe762..c8a8849d6c 100644 --- a/packages/backend-common/src/paths.ts +++ b/packages/backend-common/src/paths.ts @@ -25,6 +25,8 @@ import { resolve as resolvePath } from 'path'; * This is particularly useful when you want to access assets shipped with * your backend plugin package. When doing so, do not forget to include the assets * in your published package by adding them to `files` in your `package.json`. + * + * @public */ export function resolvePackagePath(name: string, ...paths: string[]) { const req = @@ -40,8 +42,9 @@ export function resolvePackagePath(name: string, ...paths: string[]) { * a path that point to or within the base path. This is useful for resolving * paths from user input, as it otherwise opens up for vulnerabilities. * - * @param base The base directory to resolve the path from. - * @param path The target path, relative or absolute + * @public + * @param base - The base directory to resolve the path from. + * @param path - The target path, relative or absolute * @returns A path that is guaranteed to point to or within the base path. */ export function resolveSafeChildPath(base: string, path: string): string { diff --git a/packages/backend-common/src/reading/AzureUrlReader.ts b/packages/backend-common/src/reading/AzureUrlReader.ts index 7b4b1e345e..910e8e04a5 100644 --- a/packages/backend-common/src/reading/AzureUrlReader.ts +++ b/packages/backend-common/src/reading/AzureUrlReader.ts @@ -40,6 +40,7 @@ import { ReadUrlResponse, } from './types'; +/** @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 7925212b20..4965d5a370 100644 --- a/packages/backend-common/src/reading/BitbucketUrlReader.ts +++ b/packages/backend-common/src/reading/BitbucketUrlReader.ts @@ -43,6 +43,8 @@ import { /** * A processor that adds the ability to read files from Bitbucket v1 and v2 APIs, such as * the one exposed by Bitbucket Cloud itself. + * + * @public */ export class BitbucketUrlReader implements UrlReader { static factory: ReaderFactory = ({ config, treeResponseFactory }) => { diff --git a/packages/backend-common/src/reading/FetchUrlReader.ts b/packages/backend-common/src/reading/FetchUrlReader.ts index 6b45d99cc3..732d3b9f59 100644 --- a/packages/backend-common/src/reading/FetchUrlReader.ts +++ b/packages/backend-common/src/reading/FetchUrlReader.ts @@ -27,6 +27,8 @@ import { /** * A UrlReader that does a plain fetch of the URL. + * + * @public */ export class FetchUrlReader implements UrlReader { /** diff --git a/packages/backend-common/src/reading/GithubUrlReader.ts b/packages/backend-common/src/reading/GithubUrlReader.ts index 5dc1430ea8..1eed5764ef 100644 --- a/packages/backend-common/src/reading/GithubUrlReader.ts +++ b/packages/backend-common/src/reading/GithubUrlReader.ts @@ -51,6 +51,8 @@ export type GhBlobResponse = /** * A processor that adds the ability to read files from GitHub v3 APIs, such as * the one exposed by GitHub itself. + * + * @public */ export class GithubUrlReader implements UrlReader { static factory: ReaderFactory = ({ config, treeResponseFactory }) => { diff --git a/packages/backend-common/src/reading/GitlabUrlReader.ts b/packages/backend-common/src/reading/GitlabUrlReader.ts index baee64fab2..b78add6916 100644 --- a/packages/backend-common/src/reading/GitlabUrlReader.ts +++ b/packages/backend-common/src/reading/GitlabUrlReader.ts @@ -38,6 +38,7 @@ import { ReadUrlOptions, } from './types'; +/** @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 9f3fbad302..f1684c2945 100644 --- a/packages/backend-common/src/reading/GoogleGcsUrlReader.ts +++ b/packages/backend-common/src/reading/GoogleGcsUrlReader.ts @@ -48,6 +48,7 @@ const parseURL = ( }; }; +/** @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 f9a4865717..7120a9570f 100644 --- a/packages/backend-common/src/reading/UrlReaders.ts +++ b/packages/backend-common/src/reading/UrlReaders.ts @@ -27,7 +27,8 @@ import { FetchUrlReader } from './FetchUrlReader'; import { GoogleGcsUrlReader } from './GoogleGcsUrlReader'; import { AwsS3UrlReader } from './AwsS3UrlReader'; -type CreateOptions = { +/** @public */ +export type UrlReadersOptions = { /** Root config object */ config: Config; /** Logger used by all the readers */ @@ -38,12 +39,14 @@ type CreateOptions = { /** * UrlReaders provide various utilities related to the UrlReader interface. + * + * @public */ export class UrlReaders { /** * Creates a UrlReader without any known types. */ - static create({ logger, config, factories }: CreateOptions): UrlReader { + static create({ logger, config, factories }: UrlReadersOptions): UrlReader { const mux = new UrlReaderPredicateMux(logger); const treeResponseFactory = DefaultReadTreeResponseFactory.create({ config, @@ -65,7 +68,7 @@ export class UrlReaders { * * Any additional factories passed will be loaded before the default ones. */ - static default({ logger, config, factories = [] }: CreateOptions) { + static default({ logger, config, factories = [] }: UrlReadersOptions) { return UrlReaders.create({ logger, config, diff --git a/packages/backend-common/src/reading/index.ts b/packages/backend-common/src/reading/index.ts index 207f01b37f..097f604987 100644 --- a/packages/backend-common/src/reading/index.ts +++ b/packages/backend-common/src/reading/index.ts @@ -24,6 +24,8 @@ export type { ReadTreeResponse, ReadTreeResponseFactory, ReadTreeResponseFile, + ReadTreeResponseDirOptions, + ReadTreeResponseFactoryOptions, ReadUrlOptions, ReadUrlResponse, SearchOptions, @@ -33,3 +35,4 @@ export type { UrlReaderPredicateTuple, } from './types'; export { UrlReaders } from './UrlReaders'; +export type { UrlReadersOptions } from './UrlReaders'; diff --git a/packages/backend-common/src/reading/tree/ReadTreeResponseFactory.ts b/packages/backend-common/src/reading/tree/ReadTreeResponseFactory.ts index 912fddf965..5fdd633102 100644 --- a/packages/backend-common/src/reading/tree/ReadTreeResponseFactory.ts +++ b/packages/backend-common/src/reading/tree/ReadTreeResponseFactory.ts @@ -18,7 +18,7 @@ import os from 'os'; import { Config } from '@backstage/config'; import { ReadTreeResponse, - FromArchiveOptions, + ReadTreeResponseFactoryOptions, ReadTreeResponseFactory, } from '../types'; import { TarArchiveResponse } from './TarArchiveResponse'; @@ -34,7 +34,9 @@ export class DefaultReadTreeResponseFactory implements ReadTreeResponseFactory { constructor(private readonly workDir: string) {} - async fromTarArchive(options: FromArchiveOptions): Promise { + async fromTarArchive( + options: ReadTreeResponseFactoryOptions, + ): Promise { return new TarArchiveResponse( options.stream, options.subpath ?? '', @@ -44,7 +46,9 @@ export class DefaultReadTreeResponseFactory implements ReadTreeResponseFactory { ); } - async fromZipArchive(options: FromArchiveOptions): Promise { + async fromZipArchive( + options: ReadTreeResponseFactoryOptions, + ): Promise { return new ZipArchiveResponse( options.stream, options.subpath ?? '', diff --git a/packages/backend-common/src/reading/types.ts b/packages/backend-common/src/reading/types.ts index 93f287d4fe..b7e1ff823f 100644 --- a/packages/backend-common/src/reading/types.ts +++ b/packages/backend-common/src/reading/types.ts @@ -20,6 +20,8 @@ import { Config } from '@backstage/config'; /** * A generic interface for fetching plain data from URLs. + * + * @public */ export type UrlReader = { /* Used to read a single file and return its content. */ @@ -39,6 +41,7 @@ export type UrlReader = { search(url: string, options?: SearchOptions): Promise; }; +/** @public */ export type UrlReaderPredicateTuple = { predicate: (url: URL) => boolean; reader: UrlReader; @@ -47,6 +50,8 @@ export type UrlReaderPredicateTuple = { /** * A factory function that can read config to construct zero or more * UrlReaders along with a predicate for when it should be used. + * + * @public */ export type ReaderFactory = (options: { config: Config; @@ -56,6 +61,8 @@ export type ReaderFactory = (options: { /** * An options object for readUrl operations. + * + * @public */ export type ReadUrlOptions = { /** @@ -74,6 +81,8 @@ export type ReadUrlOptions = { /** * A response object for readUrl operations. + * + * @public */ export type ReadUrlResponse = { /** @@ -90,6 +99,8 @@ export type ReadUrlResponse = { /** * An options object for readTree operations. + * + * @public */ export type ReadTreeOptions = { /** @@ -120,8 +131,16 @@ export type ReadTreeOptions = { etag?: string; }; +/** @public */ +export type ReadTreeResponseDirOptions = { + /** The directory to write files to. Defaults to the OS tmpdir or `backend.workingDirectory` if set in config */ + targetDir?: string; +}; + /** * A response object for readTree operations. + * + * @public */ export type ReadTreeResponse = { /** @@ -142,20 +161,18 @@ export type ReadTreeResponse = { etag: string; }; -export type ReadTreeResponseDirOptions = { - /** The directory to write files to. Defaults to the OS tmpdir or `backend.workingDirectory` if set in config */ - targetDir?: string; -}; - /** * Represents a single file in a readTree response. + * + * @public */ export type ReadTreeResponseFile = { path: string; content(): Promise; }; -export type FromArchiveOptions = { +/** @public */ +export type ReadTreeResponseFactoryOptions = { // A binary stream of a tar archive. stream: Readable; // If unset, the files at the root of the tree will be read. @@ -167,13 +184,20 @@ export type FromArchiveOptions = { filter?: (path: string, info?: { size: number }) => boolean; }; +/** @public */ export interface ReadTreeResponseFactory { - fromTarArchive(options: FromArchiveOptions): Promise; - fromZipArchive(options: FromArchiveOptions): Promise; + fromTarArchive( + options: ReadTreeResponseFactoryOptions, + ): Promise; + fromZipArchive( + options: ReadTreeResponseFactoryOptions, + ): Promise; } /** * An options object for search operations. + * + * @public */ export type SearchOptions = { /** @@ -192,6 +216,8 @@ export type SearchOptions = { /** * The output of a search operation. + * + * @public */ export type SearchResponse = { /** @@ -207,6 +233,8 @@ export type SearchResponse = { /** * Represents a single file in a search response. + * + * @public */ export type SearchResponseFile = { /** diff --git a/packages/backend-common/src/scm/git.ts b/packages/backend-common/src/scm/git.ts index e786c279a1..00b103b240 100644 --- a/packages/backend-common/src/scm/git.ts +++ b/packages/backend-common/src/scm/git.ts @@ -31,6 +31,8 @@ From : https://isomorphic-git.org/docs/en/onAuth with fix for GitHub Azure 'notempty' token */ + +/** @public */ export class Git { private constructor( private readonly config: { diff --git a/packages/backend-common/src/service/createServiceBuilder.ts b/packages/backend-common/src/service/createServiceBuilder.ts index 17d69e7082..a6ca25415e 100644 --- a/packages/backend-common/src/service/createServiceBuilder.ts +++ b/packages/backend-common/src/service/createServiceBuilder.ts @@ -15,10 +15,13 @@ */ import { ServiceBuilderImpl } from './lib/ServiceBuilderImpl'; +import { ServiceBuilder } from './types'; /** * Creates a new service builder. + * + * @public */ -export function createServiceBuilder(_module: NodeModule) { +export function createServiceBuilder(_module: NodeModule): ServiceBuilder { return new ServiceBuilderImpl(_module); } diff --git a/packages/backend-common/src/service/createStatusCheckRouter.ts b/packages/backend-common/src/service/createStatusCheckRouter.ts index fd794cc9c4..0d0f93f25c 100644 --- a/packages/backend-common/src/service/createStatusCheckRouter.ts +++ b/packages/backend-common/src/service/createStatusCheckRouter.ts @@ -19,7 +19,8 @@ import Router from 'express-promise-router'; import express from 'express'; import { errorHandler, statusCheckHandler, StatusCheck } from '../middleware'; -export interface StatusCheckRouterOptions { +/** @public */ +export async function createStatusCheckRouter(options: { logger: Logger; path?: string; /** @@ -27,11 +28,7 @@ export interface StatusCheckRouterOptions { * Override this to implement your own logic for a health check. */ statusCheck?: StatusCheck; -} - -export async function createStatusCheckRouter( - options: StatusCheckRouterOptions, -): Promise { +}): Promise { const router = Router(); const { path = '/healthcheck', statusCheck } = options; diff --git a/packages/backend-common/src/service/types.ts b/packages/backend-common/src/service/types.ts index f845397ca2..3765cbcfdd 100644 --- a/packages/backend-common/src/service/types.ts +++ b/packages/backend-common/src/service/types.ts @@ -14,20 +14,20 @@ * limitations under the License. */ -import { ConfigReader } from '@backstage/config'; +import { Config } from '@backstage/config'; import cors from 'cors'; import { Router, RequestHandler } from 'express'; import { Server } from 'http'; import { Logger } from 'winston'; -import { HttpsSettings } from './lib/config'; +/** @public */ export type ServiceBuilder = { /** * Sets the service parameters based on configuration. * - * @param config The configuration to read + * @param config - The configuration to read */ - loadConfig(config: ConfigReader): ServiceBuilder; + loadConfig(config: Config): ServiceBuilder; /** * Sets the port to listen on. @@ -36,7 +36,7 @@ export type ServiceBuilder = { * variable named PORT and use that if present, otherwise it picks a default * port (7000). * - * @param port The port to listen on + * @param port - The port to listen on */ setPort(port: number): ServiceBuilder; @@ -45,7 +45,7 @@ export type ServiceBuilder = { * * '' is express default, which listens to all interfaces. * - * @param host The host to listen on + * @param host - The host to listen on */ setHost(host: string): ServiceBuilder; @@ -54,7 +54,7 @@ export type ServiceBuilder = { * * If no logger is given, the default root logger is used. * - * @param logger A winston logger + * @param logger - A winston logger */ setLogger(logger: Logger): ServiceBuilder; @@ -64,7 +64,7 @@ export type ServiceBuilder = { * If this method is not called, the resulting service will not have any * built in CORS handling. * - * @param options Standard CORS options + * @param options - Standard CORS options */ enableCors(options: cors.CorsOptions): ServiceBuilder; @@ -73,15 +73,17 @@ export type ServiceBuilder = { * * If this method is not called, the resulting service will use sensible defaults * - * @param options Standard certificate options + * @param options - Standard certificate options */ - setHttpsSettings(settings: HttpsSettings): ServiceBuilder; + setHttpsSettings(settings: { + certificate: { key: string; cert: string } | { hostname: string }; + }): ServiceBuilder; /** * Adds a router (similar to the express .use call) to the service. * - * @param root The root URL to bind to (e.g. "/api/function1") - * @param router An express router + * @param root - The root URL to bind to (e.g. "/api/function1") + * @param router - An express router */ addRouter(root: string, router: Router | RequestHandler): ServiceBuilder; @@ -90,7 +92,7 @@ export type ServiceBuilder = { * * If no handler is given the default one is used * - * @param requestLoggingHandler a factory function that given a logger returns an handler + * @param requestLoggingHandler - a factory function that given a logger returns an handler */ setRequestLoggingHandler( requestLoggingHandler: RequestLoggingHandlerFactory, @@ -102,4 +104,5 @@ export type ServiceBuilder = { start(): Promise; }; +/** @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 8a73be42ba..be861501c3 100644 --- a/packages/backend-common/src/util/ContainerRunner.ts +++ b/packages/backend-common/src/util/ContainerRunner.ts @@ -16,6 +16,7 @@ import { Writable } from 'stream'; +/** @public */ export type RunContainerOptions = { imageName: string; command?: string | string[]; @@ -27,6 +28,7 @@ export type RunContainerOptions = { pullImage?: boolean; }; +/** @public */ export interface ContainerRunner { runContainer(opts: RunContainerOptions): Promise; } diff --git a/packages/backend-common/src/util/DockerContainerRunner.ts b/packages/backend-common/src/util/DockerContainerRunner.ts index 33a4874151..da3ce66ec2 100644 --- a/packages/backend-common/src/util/DockerContainerRunner.ts +++ b/packages/backend-common/src/util/DockerContainerRunner.ts @@ -23,6 +23,7 @@ export type UserOptions = { User?: string; }; +/** @public */ export class DockerContainerRunner implements ContainerRunner { private readonly dockerClient: Docker;