diff --git a/packages/core/src/node/backend-application.ts b/packages/core/src/node/backend-application.ts index de13d2790c324..bf28c3ab97085 100644 --- a/packages/core/src/node/backend-application.ts +++ b/packages/core/src/node/backend-application.ts @@ -30,14 +30,48 @@ import { AddressInfo } from 'net'; import { ApplicationPackage } from '@theia/application-package'; export const BackendApplicationContribution = Symbol('BackendApplicationContribution'); + +/** + * Entry point for hooking into the backend lifecycle. + */ export interface BackendApplicationContribution { - initialize?(): void; - configure?(app: express.Application): void; + /** + * Called during the initialization of the backend application. + * Use this for functionality which has to run as early as possible. + * + * @returns Either `undefined` (i.e. void) or a Promise resolving to `undefined`. + * Note that returning a Promise will still block initialization as the Promise is awaited. + */ + initialize?(): MaybePromise; + + /** + * Called after the initialization of the backend application is complete. + * Use this to configure the Express app before it is started, for example + * to offer additional endpoints. + * + * @param app the express application to configure. + * + * @returns Either `undefined` (i.e. void) or a Promise resolving to `undefined`. + * Note that returning a Promise will still block configuration as the Promise is awaited. + */ + configure?(app: express.Application): MaybePromise; + + /** + * Called right after the server for the Express app is started. + * Use this to additionally configure the server or as ready-signal for your service. + * + * @param server the backend server running the express app. + * + * @returns Either `undefined` (i.e. void) or a Promise resolving to `undefined`. + * Note that returning a Promise will still block startup as the Promise is awaited. + */ onStart?(server: http.Server | https.Server): MaybePromise; /** * Called when the backend application shuts down. Contributions must perform only synchronous operations. * Any kind of additional asynchronous work queued in the event loop will be ignored and abandoned. + * + * @param app the express application. */ onStop?(app?: express.Application): void; }