HTTP Services

/**
 * Creates an HTTP server instance with the specified configuration
 * @param options - HTTP server configuration options
 * @returns Extended HTTP server instance with Backstage-specific features
 */
function createHttpServer(options: HttpServerOptions): ExtendedHttpServer;

/**
 * Reads HTTP server options from Backstage configuration
 * @param config - Backstage configuration object
 * @returns Parsed HTTP server options
 */
function readHttpServerOptions(config: Config): HttpServerOptions;

interface HttpServerOptions {
  listen: {
    port: number;
    host: string;
  };
  https?: {
    certificate: HttpServerCertificateOptions;
  };
}

interface HttpServerCertificateOptions {
  type: 'pem';
  key: string;
  cert: string;
} | {
  type: 'generated';
  hostname: string;
}

interface ExtendedHttpServer extends Server {
  start(): Promise<void>;
  stop(): Promise<void>;
  port(): number;
}

/**
 * Default implementation of root HTTP router
 */
class DefaultRootHttpRouter implements RootHttpRouter {
  constructor(options: DefaultRootHttpRouterOptions);
  use(path: string, handler: RequestHandler): void;
  use(handler: RequestHandler): void;
}

interface DefaultRootHttpRouterOptions {
  logger: Logger;
  config: Config;
  lifecycle: LifecycleService;
}

interface RootHttpRouterConfigureContext {
  config: Config;
  logger: Logger;
}

interface RootHttpRouterFactoryOptions {
  configure?: (context: RootHttpRouterConfigureContext) => Promise<void>;
}

/**
 * Creates router for authentication integrations
 * Handles OAuth callbacks and authentication flows
 * @returns Express router for authentication
 */
function createAuthIntegrationRouter(): Router;

/**
 * Creates middleware for credentials validation
 * Validates incoming requests have proper authentication
 * @returns Express middleware function
 */
function createCredentialsBarrier(): RequestHandler;

/**
 * Creates middleware for cookie authentication refresh
 * Handles cookie-based authentication token refresh
 * @returns Express middleware function
 */
function createCookieAuthRefreshMiddleware(): RequestHandler;

/**
 * Creates middleware for lifecycle management
 * Handles graceful shutdown and startup coordination
 * @param options - Lifecycle middleware configuration
 * @returns Express middleware function
 */
function createLifecycleMiddleware(options: LifecycleMiddlewareOptions): RequestHandler;

interface LifecycleMiddlewareOptions {
  lifecycle: LifecycleService;
  logger?: Logger;
}

/**
 * Default implementation of HTTP authentication service
 */
class DefaultHttpAuthService implements HttpAuthService {
  constructor(options: DefaultHttpAuthServiceOptions);
  
  /**
   * Extract credentials from HTTP request
   * @param req - Express request object
   * @returns Backstage credentials or undefined
   */
  credentials(req: Request): Promise<BackstageCredentials | undefined>;
}

interface DefaultHttpAuthServiceOptions {
  defaultCredentials?: BackstageCredentials;
}

/**
 * Factory for creating HTTP middleware
 */
class MiddlewareFactory {
  constructor(options: MiddlewareFactoryOptions);
  
  /**
   * Create error handling middleware
   * @param options - Error handling options
   * @returns Express error middleware
   */
  error(options?: MiddlewareFactoryErrorOptions): ErrorRequestHandler;
  
  /**
   * Create CORS middleware
   * @returns Express CORS middleware
   */
  cors(): RequestHandler;
  
  /**
   * Create Helmet security middleware
   * @returns Express Helmet middleware
   */
  helmet(): RequestHandler;
  
  /**
   * Create compression middleware
   * @returns Express compression middleware
   */
  compression(): RequestHandler;
}

interface MiddlewareFactoryOptions {
  config: Config;
  logger: Logger;
}

interface MiddlewareFactoryErrorOptions {
  showStackTraces?: boolean;
  logClientErrors?: boolean;
}

/**
 * Reads CORS options from Backstage configuration
 * @param config - Backstage configuration object
 * @returns CORS configuration options
 */
function readCorsOptions(config: Config): CorsOptions;

/**
 * Reads Helmet security options from Backstage configuration  
 * @param config - Backstage configuration object
 * @returns Helmet security configuration
 */
function readHelmetOptions(config: Config): HelmetOptions;

/**
 * Creates a health check router with standard endpoints
 * Provides /healthcheck and /ready endpoints
 * @returns Express router with health check endpoints
 */
function createHealthRouter(): Router;

import { createHttpServer, readHttpServerOptions } from "@backstage/backend-defaults/rootHttpRouter";
import { ConfigReader } from "@backstage/config";

const config = new ConfigReader({
  backend: {
    listen: { port: 7007 },
    https: true
  }
});

const serverOptions = readHttpServerOptions(config);
const server = createHttpServer(serverOptions);

await server.start();

import { 
  createAuthIntegrationRouter,
  createCredentialsBarrier,
  createLifecycleMiddleware 
} from "@backstage/backend-defaults/httpRouter";
import express from "express";

const app = express();

// Add authentication middleware
app.use(createCredentialsBarrier());

// Add auth integration router
app.use('/auth', createAuthIntegrationRouter());

// Add lifecycle middleware
app.use(createLifecycleMiddleware({ lifecycle: lifecycleService }));

import { MiddlewareFactory } from "@backstage/backend-defaults/rootHttpRouter";
import express from "express";

const middlewareFactory = new MiddlewareFactory({
  config: backstageConfig,
  logger: backstageLogger
});

const app = express();

// Add security and utility middleware
app.use(middlewareFactory.helmet());
app.use(middlewareFactory.cors());
app.use(middlewareFactory.compression());

// Add error handling middleware last
app.use(middlewareFactory.error({
  showStackTraces: process.env.NODE_ENV === 'development',
  logClientErrors: true
}));