backend-common: add missing exports and clean up API report warnings

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/wise-monkeys-enjoy.md

@@ -0,0 +1,5 @@
+---
+'@backstage/backend-common': patch
+---
+
+Properly export all used types.

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<void>;
   get(key: string): Promise<JsonValue | undefined>;
-  // 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<void>;
+  set(
+    key: string,
+    value: JsonValue,
+    options?: CacheClientSetOptions,
+  ): Promise<void>;
 }
 
-// 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<void>;
 }
 
-// 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.Config>,
 ): Knex<any, unknown[]>;
 
-// 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<express.Router>;
+export function createStatusCheckRouter(options: {
+  logger: Logger_2;
+  path?: string;
+  statusCheck?: StatusCheck;
+}): Promise<express.Router>;
 
-// 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<void>;
 }
 
-// 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<string>
 ): Promise<void>;
 
-// 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<string>;
 }
 
-// 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<Config>;
+export function loadBackendConfig(options: {
+  logger: Logger_2;
+  argv: string[];
+}): Promise<Config>;
 
-// 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<Knex>;
 }
 
-// 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<string>;
   getExternalBaseUrl(pluginId: string): Promise<string>;
 };
 
-// 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<ReadTreeResponseFile[]>;
@@ -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<ReadTreeResponse>;
+  fromTarArchive(
+    options: ReadTreeResponseFactoryOptions,
+  ): Promise<ReadTreeResponse>;
   // (undocumented)
-  fromZipArchive(options: FromArchiveOptions): Promise<ReadTreeResponse>;
+  fromZipArchive(
+    options: ReadTreeResponseFactoryOptions,
+  ): Promise<ReadTreeResponse>;
 }
 
-// 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<Buffer>;
 };
 
-// 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<Buffer>;
   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<Buffer>;
 };
 
-// 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<Server>;
 };
 
-// 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<string>;
 }
 
-// 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<any>;
 
-// 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<RequestHandler>;
 
-// 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<Buffer>;
@@ -608,56 +547,33 @@ export type UrlReader = {
   search(url: string, options?: SearchOptions): Promise<SearchResponse>;
 };
 
-// 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<T>(_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)
 ```

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<void>;
+  set(
+    key: string,
+    value: JsonValue,
+    options?: CacheClientSetOptions,
+  ): Promise<void>;
 
   /**
    * 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<void> {
     const k = this.getNormalizedKey(key);
     await this.client.set(k, value, opts.ttl);

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 {

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';

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;
 };

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<Config> {
+export async function loadBackendConfig(options: {
+  logger: Logger;
+  // process.argv or any other overrides
+  argv: string[];
+}): Promise<Config> {
   const args = parseArgs(options.argv);
   const configPaths: string[] = [args.config ?? []].flat();
 

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`.
    */

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;

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
  */

packages/backend-common/src/database/connection.ts

@@ -40,8 +40,9 @@ const ConnectorMapping: Record<DatabaseClient, DatabaseConnector> = {
 /**
  * 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,

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 {
   /**

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 {
   /**

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 = {
   /**

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<T>(
   _module: NodeModule,

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({

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,

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({

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(

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 {

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 {

packages/backend-common/src/middleware/statusCheckHandler.ts

@@ -16,8 +16,10 @@
 
 import { NextFunction, Request, Response, RequestHandler } from 'express';
 
+/** @public */
 export type StatusCheck = () => Promise<any>;
 
+/** @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(

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 {

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);

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 }) => {

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 {
   /**

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 }) => {

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);

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')) {

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,

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';

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<ReadTreeResponse> {
+  async fromTarArchive(
+    options: ReadTreeResponseFactoryOptions,
+  ): Promise<ReadTreeResponse> {
     return new TarArchiveResponse(
       options.stream,
       options.subpath ?? '',
@@ -44,7 +46,9 @@ export class DefaultReadTreeResponseFactory implements ReadTreeResponseFactory {
     );
   }
 
-  async fromZipArchive(options: FromArchiveOptions): Promise<ReadTreeResponse> {
+  async fromZipArchive(
+    options: ReadTreeResponseFactoryOptions,
+  ): Promise<ReadTreeResponse> {
     return new ZipArchiveResponse(
       options.stream,
       options.subpath ?? '',

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<SearchResponse>;
 };
 
+/** @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<Buffer>;
 };
 
-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<ReadTreeResponse>;
-  fromZipArchive(options: FromArchiveOptions): Promise<ReadTreeResponse>;
+  fromTarArchive(
+    options: ReadTreeResponseFactoryOptions,
+  ): Promise<ReadTreeResponse>;
+  fromZipArchive(
+    options: ReadTreeResponseFactoryOptions,
+  ): Promise<ReadTreeResponse>;
 }
 
 /**
  * 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 = {
   /**

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: {

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);
 }

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<express.Router> {
+}): Promise<express.Router> {
   const router = Router();
   const { path = '/healthcheck', statusCheck } = options;
 

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<Server>;
 };
 
+/** @public */
 export type RequestLoggingHandlerFactory = (logger?: Logger) => RequestHandler;

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<void>;
 }

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;