diff --git a/packages/backend-app-api/api-report.md b/packages/backend-app-api/api-report.md index a402150755..24499f6c86 100644 --- a/packages/backend-app-api/api-report.md +++ b/packages/backend-app-api/api-report.md @@ -3,21 +3,38 @@ > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). ```ts +/// +/// + import { BackendFeature } from '@backstage/backend-plugin-api'; +import { Config } from '@backstage/config'; import { ConfigService } from '@backstage/backend-plugin-api'; +import cors from 'cors'; +import { CorsOptions } from 'cors'; +import { ErrorRequestHandler } from 'express'; +import { Express as Express_2 } from 'express'; import { ExtensionPoint } from '@backstage/backend-plugin-api'; -import { Handler } from 'express'; +import { HelmetOptions } from 'helmet'; +import * as http from 'http'; import { HttpRouterService } from '@backstage/backend-plugin-api'; +import { IncomingMessage } from 'http'; import { LifecycleService } from '@backstage/backend-plugin-api'; import { LoggerService } from '@backstage/backend-plugin-api'; +import { ParamsDictionary } from 'express-serve-static-core'; +import { ParsedQs } from 'qs'; import { PermissionsService } from '@backstage/backend-plugin-api'; import { PluginCacheManager } from '@backstage/backend-common'; import { PluginDatabaseManager } from '@backstage/backend-common'; import { PluginEndpointDiscovery } from '@backstage/backend-common'; +import { Request as Request_2 } from 'express'; +import { RequestHandler } from 'express'; +import { RequestListener } from 'http'; +import { Response as Response_2 } from 'express'; import { RootHttpRouterService } from '@backstage/backend-plugin-api'; import { RootLifecycleService } from '@backstage/backend-plugin-api'; import { RootLoggerService } from '@backstage/backend-plugin-api'; import { SchedulerService } from '@backstage/backend-plugin-api'; +import { ServerResponse } from 'http'; import { ServiceFactory } from '@backstage/backend-plugin-api'; import { ServiceFactoryOrFunction } from '@backstage/backend-plugin-api'; import { ServiceRef } from '@backstage/backend-plugin-api'; @@ -44,6 +61,15 @@ export const configFactory: ( options?: undefined, ) => ServiceFactory; +// @public +export function createHttpServer( + listener: RequestListener, + options: HttpServerOptions, + deps: { + logger: LoggerService; + }, +): Promise; + // @public (undocumented) export function createSpecializedBackend( options: CreateSpecializedBackendOptions, @@ -65,6 +91,16 @@ export const discoveryFactory: ( options?: undefined, ) => ServiceFactory; +// @public +export interface ExtendedHttpServer extends http.Server { + // (undocumented) + port(): number; + // (undocumented) + start(): Promise; + // (undocumented) + stop(): Promise; +} + // @public (undocumented) export const httpRouterFactory: ( options?: HttpRouterFactoryOptions | undefined, @@ -75,6 +111,29 @@ export type HttpRouterFactoryOptions = { getPath(pluginId: string): string; }; +// @public +export type HttpServerCertificateOptions = + | { + type: 'plain'; + key: string; + cert: string; + } + | { + type: 'generated'; + hostname: string; + }; + +// @public +export type HttpServerOptions = { + listen: { + port: number; + host: string; + }; + https?: { + certificate: HttpServerCertificateOptions; + }; +}; + // @public export const lifecycleFactory: ( options?: undefined, @@ -85,11 +144,83 @@ export const loggerFactory: ( options?: undefined, ) => ServiceFactory; +// @public +export class MiddlewareFactory { + compression(): RequestHandler< + ParamsDictionary, + any, + any, + ParsedQs, + Record + >; + cors(): ( + req: cors.CorsRequest, + res: { + statusCode?: number | undefined; + setHeader(key: string, value: string): any; + end(): any; + }, + next: (err?: any) => any, + ) => void; + static create(options: MiddlewareFactoryOptions): MiddlewareFactory; + error(options?: MiddlewareFactoryErrorOptions): ErrorRequestHandler; + helmet(): ( + req: IncomingMessage, + res: ServerResponse, + next: (err?: unknown) => void, + ) => void; + logging(): ( + req: IncomingMessage, + res: ServerResponse, + callback: (err?: Error | undefined) => void, + ) => void; + notFound(): (_req: Request_2, res: Response_2) => void; +} + +// @public +export interface MiddlewareFactoryErrorOptions { + logAllErrors?: boolean; + showStackTraces?: boolean; +} + +// @public +export interface MiddlewareFactoryOptions { + // (undocumented) + config: ConfigService; + // (undocumented) + logger: LoggerService; +} + // @public (undocumented) export const permissionsFactory: ( options?: undefined, ) => ServiceFactory; +// @public +export function readCorsOptions(config?: Config): CorsOptions; + +// @public +export function readHelmetOptions(config?: Config): HelmetOptions; + +// @public +export function readHttpServerOptions(config?: Config): HttpServerOptions; + +// @public (undocumented) +export interface RootHttpRouterConfigureOptions { + // (undocumented) + app: Express_2; + // (undocumented) + config: ConfigService; + // (undocumented) + lifecycle: LifecycleService; + // (undocumented) + logger: LoggerService; + // (undocumented) + middleware: MiddlewareFactory; + // (undocumented) + routes: RequestHandler; +} + // @public (undocumented) export const rootHttpRouterFactory: ( options?: RootHttpRouterFactoryOptions | undefined, @@ -98,7 +229,7 @@ export const rootHttpRouterFactory: ( // @public (undocumented) export type RootHttpRouterFactoryOptions = { indexPath?: string | false; - middleware?: Handler[]; + configure?(options: RootHttpRouterConfigureOptions): void; }; // @public @@ -121,6 +252,22 @@ export type ServiceOrExtensionPoint = | ExtensionPoint | ServiceRef; +// @public +export function startHttpServer( + listener: RequestListener, + options: StartHttpServerOptions, +): Promise; + +// @public +export interface StartHttpServerOptions { + // (undocumented) + config: ConfigService; + // (undocumented) + lifecycle: RootLifecycleService; + // (undocumented) + logger: RootLoggerService; +} + // @public (undocumented) export const tokenManagerFactory: ( options?: undefined, diff --git a/packages/backend-app-api/src/http/MiddlewareFactory.ts b/packages/backend-app-api/src/http/MiddlewareFactory.ts index 4be8467db3..09e6709793 100644 --- a/packages/backend-app-api/src/http/MiddlewareFactory.ts +++ b/packages/backend-app-api/src/http/MiddlewareFactory.ts @@ -44,7 +44,7 @@ export interface MiddlewareFactoryOptions { } /** - * Options passed to the {@link errorHandler} middleware. + * Options passed to the {@link MiddlewareFactory.error} middleware. * * @public */ diff --git a/packages/backend-app-api/src/http/index.ts b/packages/backend-app-api/src/http/index.ts index 8f1a8c5d92..5bd54ec4a5 100644 --- a/packages/backend-app-api/src/http/index.ts +++ b/packages/backend-app-api/src/http/index.ts @@ -14,16 +14,19 @@ * limitations under the License. */ +export { readHttpServerOptions } from './config'; export { createHttpServer } from './createHttpServer'; +export { MiddlewareFactory } from './MiddlewareFactory'; +export type { + MiddlewareFactoryErrorOptions, + MiddlewareFactoryOptions, +} from './MiddlewareFactory'; +export { readCorsOptions } from './readCorsOptions'; +export { readHelmetOptions } from './readHelmetOptions'; export { startHttpServer } from './startHttpServer'; export type { StartHttpServerOptions } from './startHttpServer'; -export { readHttpServerOptions } from './config'; export type { - HttpServerOptions, - HttpServerCertificateOptions, ExtendedHttpServer, + HttpServerCertificateOptions, + HttpServerOptions, } from './types'; -export { MiddlewareFactory } from './MiddlewareFactory'; -export { readHelmetOptions } from './readHelmetOptions'; -export { readCorsOptions } from './readCorsOptions'; -export type { MiddlewareFactoryOptions } from './MiddlewareFactory'; diff --git a/packages/backend-app-api/src/http/readCorsOptions.ts b/packages/backend-app-api/src/http/readCorsOptions.ts index 98b548d02e..b58cae5ded 100644 --- a/packages/backend-app-api/src/http/readCorsOptions.ts +++ b/packages/backend-app-api/src/http/readCorsOptions.ts @@ -21,6 +21,7 @@ import { Minimatch } from 'minimatch'; /** * Attempts to read a CORS options object from the backend configuration object. * + * @public * @param config - The backend configuration object. * @returns A CORS options object, or undefined if no cors configuration is present. * diff --git a/packages/backend-app-api/src/http/readHelmetOptions.ts b/packages/backend-app-api/src/http/readHelmetOptions.ts index 9cdf339844..0555bdef00 100644 --- a/packages/backend-app-api/src/http/readHelmetOptions.ts +++ b/packages/backend-app-api/src/http/readHelmetOptions.ts @@ -22,6 +22,7 @@ import { ContentSecurityPolicyOptions } from 'helmet/dist/types/middlewares/cont /** * Attempts to read Helmet options from the backend configuration object. * + * @public * @param config - The backend configuration object. * @returns A Helmet options object, or undefined if no Helmet configuration is present. * diff --git a/packages/backend-app-api/src/services/implementations/rootHttpRouter/index.ts b/packages/backend-app-api/src/services/implementations/rootHttpRouter/index.ts index 9b72f17060..1dfd72273d 100644 --- a/packages/backend-app-api/src/services/implementations/rootHttpRouter/index.ts +++ b/packages/backend-app-api/src/services/implementations/rootHttpRouter/index.ts @@ -15,4 +15,7 @@ */ export { rootHttpRouterFactory } from './rootHttpRouterFactory'; -export type { RootHttpRouterFactoryOptions } from './rootHttpRouterFactory'; +export type { + RootHttpRouterFactoryOptions, + RootHttpRouterConfigureOptions, +} from './rootHttpRouterFactory'; diff --git a/packages/backend-app-api/src/services/implementations/rootHttpRouter/rootHttpRouterFactory.ts b/packages/backend-app-api/src/services/implementations/rootHttpRouter/rootHttpRouterFactory.ts index ebd2945545..284b019a2e 100644 --- a/packages/backend-app-api/src/services/implementations/rootHttpRouter/rootHttpRouterFactory.ts +++ b/packages/backend-app-api/src/services/implementations/rootHttpRouter/rootHttpRouterFactory.ts @@ -25,7 +25,10 @@ import express, { RequestHandler, Express } from 'express'; import { MiddlewareFactory, startHttpServer } from '../../../http'; import { RestrictedIndexedRouter } from './RestrictedIndexedRouter'; -interface RootHttpRouterConfigureOptions { +/** + * @public + */ +export interface RootHttpRouterConfigureOptions { app: Express; middleware: MiddlewareFactory; routes: RequestHandler; diff --git a/packages/backend-tasks/src/database/migrateBackendTasks.ts b/packages/backend-tasks/src/database/migrateBackendTasks.ts index cc0f4349ac..9530668e3e 100644 --- a/packages/backend-tasks/src/database/migrateBackendTasks.ts +++ b/packages/backend-tasks/src/database/migrateBackendTasks.ts @@ -18,12 +18,12 @@ import { resolvePackagePath } from '@backstage/backend-common'; import { Knex } from 'knex'; import { DB_MIGRATIONS_TABLE } from './tables'; -const migrationsDir = resolvePackagePath( - '@backstage/backend-tasks', - 'migrations', -); - export async function migrateBackendTasks(knex: Knex): Promise { + const migrationsDir = resolvePackagePath( + '@backstage/backend-tasks', + 'migrations', + ); + await knex.migrate.latest({ directory: migrationsDir, tableName: DB_MIGRATIONS_TABLE,