backend-app-api: update API report + fixes

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

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
+/// <reference types="node" />
+/// <reference types="qs" />
+
 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<ConfigService>;
 
+// @public
+export function createHttpServer(
+  listener: RequestListener,
+  options: HttpServerOptions,
+  deps: {
+    logger: LoggerService;
+  },
+): Promise<ExtendedHttpServer>;
+
 // @public (undocumented)
 export function createSpecializedBackend(
   options: CreateSpecializedBackendOptions,
@@ -65,6 +91,16 @@ export const discoveryFactory: (
   options?: undefined,
 ) => ServiceFactory<PluginEndpointDiscovery>;
 
+// @public
+export interface ExtendedHttpServer extends http.Server {
+  // (undocumented)
+  port(): number;
+  // (undocumented)
+  start(): Promise<void>;
+  // (undocumented)
+  stop(): Promise<void>;
+}
+
 // @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<LoggerService>;
 
+// @public
+export class MiddlewareFactory {
+  compression(): RequestHandler<
+    ParamsDictionary,
+    any,
+    any,
+    ParsedQs,
+    Record<string, any>
+  >;
+  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<IncomingMessage>,
+    next: (err?: unknown) => void,
+  ) => void;
+  logging(): (
+    req: IncomingMessage,
+    res: ServerResponse<IncomingMessage>,
+    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<PermissionsService>;
 
+// @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<T = unknown> =
   | ExtensionPoint<T>
   | ServiceRef<T>;
 
+// @public
+export function startHttpServer(
+  listener: RequestListener,
+  options: StartHttpServerOptions,
+): Promise<void>;
+
+// @public
+export interface StartHttpServerOptions {
+  // (undocumented)
+  config: ConfigService;
+  // (undocumented)
+  lifecycle: RootLifecycleService;
+  // (undocumented)
+  logger: RootLoggerService;
+}
+
 // @public (undocumented)
 export const tokenManagerFactory: (
   options?: undefined,

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

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

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

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

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

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;

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<void> {
+  const migrationsDir = resolvePackagePath(
+    '@backstage/backend-tasks',
+    'migrations',
+  );
+
   await knex.migrate.latest({
     directory: migrationsDir,
     tableName: DB_MIGRATIONS_TABLE,