@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.4

package/dist/host/health/health.controller.js

@@ -0,0 +1,236 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HealthController = void 0;
+exports.createHealthController = createHealthController;
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+const terminus_1 = require("@nestjs/terminus");
+const index_1 = require("../../core/index");
+const host_access_1 = require("../internal/host-access");
+const health_indicator_runner_1 = require("./health-indicator.runner");
+const maintenance_guard_1 = require("../maintenance/maintenance.guard");
+const maintenance_mode_service_1 = require("../maintenance/maintenance-mode.service");
+/**
+ * The health probes `GET /api/health`, `/live` and `/ready`, public and
+ * reachable during maintenance (moved from the reference app by #901).
+ * Mounted by `PlatformHostCoreModule.forRoot()`.
+ *
+ * WHAT THE PROBES RUN. The indicators registered with `registerHealthIndicator`
+ * (the built-in `database` first): `ready` runs the critical ones, `health`
+ * runs all of them, `live` none. The routes are public, so each indicator's
+ * result is bounded and secret-filtered by `HealthIndicatorRunner`.
+ *
+ * DELIBERATELY ASYMMETRIC UNDER MAINTENANCE (#257, epic #254).
+ *
+ * The whole controller is exempt from the maintenance guard — every route on it
+ * is a probe, and a probe that answers 503 because it was BLOCKED tells an
+ * orchestrator nothing about the process it is probing. What each probe reports
+ * during a window is then decided route by route, below, and the two answers
+ * are deliberately different:
+ *
+ *   * `live` stays 200. Liveness means "this process is not hung"; that is
+ *     still true during a window, and reporting otherwise would have the
+ *     orchestrator KILL AND RESTART THE CONTAINER in the middle of the very
+ *     upgrade the window was opened for.
+ *   * `ready` reports 503. Readiness means "send me traffic", which is exactly
+ *     what must not happen, so a load balancer drains this instance instead.
+ *
+ * Exported for the reference app's wiring and tests; not a stable extension
+ * point (the probes are mounted by `PlatformHostCoreModule.forRoot()`).
+ *
+ * @param host - the app's `definePlatformHost(...)`, whose `access.allowPublic`
+ *   marks the routes public; omitted, the identity slice's `@Public()` is used.
+ * @returns the controller class.
+ *
+ * @internal
+ */
+function createHealthController(host) {
+    const access = (0, host_access_1.resolveHostAccess)(host);
+    const publicRoute = access.allowPublic();
+    let HealthController = class HealthController {
+        health;
+        indicators;
+        maintenance;
+        constructor(health, indicators, maintenance) {
+            this.health = health;
+            this.indicators = indicators;
+            this.maintenance = maintenance;
+        }
+        liveness() {
+            return {
+                status: 'ok',
+                timestamp: new Date().toISOString(),
+            };
+        }
+        async readiness() {
+            // ------------------------------------------------------------------------
+            // BEFORE THE DATABASE PROBE, and that ordering is the requirement.
+            // ------------------------------------------------------------------------
+            //
+            // The case this exists for is the restore swap (#285), which renames the
+            // live database out from under this process: for those seconds there is no
+            // database under the expected name, the probe below would fail on a
+            // connection error, and readiness would report 503 for a reason that reads
+            // like a fault. Answering the maintenance question first means this
+            // instance drains for the reason that is actually true, with a body that
+            // says so — and it means readiness keeps answering correctly at the one
+            // moment the probe cannot reach storage at all.
+            //
+            // `resolve()` never throws: an unreadable row degrades to the last known
+            // state (see MaintenanceModeService.readPersisted), so this cannot turn a
+            // database outage into a 500 on the readiness probe.
+            if (await this.maintenance.isEnabled()) {
+                throw new common_1.ServiceUnavailableException({
+                    message: 'Service is in maintenance mode',
+                    // Same marker the guard puts on a blocked request, under `details` for
+                    // the same reason — `HttpExceptionFilter` rebuilds bodies from a fixed
+                    // key allowlist and would strip a custom top-level field. No
+                    // `Retry-After` header here, though: that header is the guard's
+                    // contract with API CLIENTS, and this response is read by probes.
+                    details: {
+                        reason: maintenance_guard_1.MAINTENANCE_ERROR_MARKER,
+                        retryAfterSeconds: maintenance_guard_1.MAINTENANCE_RETRY_AFTER_SECONDS,
+                    },
+                });
+            }
+            // The CRITICAL indicators: all up is 200, any down is 503.
+            const result = await this.health.check(this.indicators.functions('ready'));
+            return {
+                ...result,
+                timestamp: new Date().toISOString(),
+            };
+        }
+        async fullHealth() {
+            // EVERY registered indicator (`registerHealthIndicator`), critical or not.
+            const result = await this.health.check(this.indicators.functions('full'));
+            return {
+                ...result,
+                timestamp: new Date().toISOString(),
+            };
+        }
+    };
+    __decorate([
+        (0, common_1.Get)('live'),
+        publicRoute,
+        (0, swagger_1.ApiOperation)({
+            summary: 'Liveness probe',
+            description: 'Checks if the application process is running. Used by orchestrators to detect hung processes.',
+        }),
+        (0, swagger_1.ApiResponse)({
+            status: 200,
+            description: 'Application is alive',
+            schema: {
+                type: 'object',
+                properties: {
+                    status: { type: 'string', example: 'ok' },
+                    timestamp: { type: 'string', format: 'date-time' },
+                },
+            },
+        }),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", []),
+        __metadata("design:returntype", void 0)
+    ], HealthController.prototype, "liveness", null);
+    __decorate([
+        (0, common_1.Get)('ready'),
+        publicRoute,
+        (0, terminus_1.HealthCheck)(),
+        (0, swagger_1.ApiOperation)({
+            summary: 'Readiness probe',
+            description: 'Checks if the application is ready to receive traffic. Includes database connectivity check.',
+        }),
+        (0, swagger_1.ApiResponse)({
+            status: 200,
+            description: 'Application is ready',
+            schema: {
+                type: 'object',
+                properties: {
+                    status: { type: 'string', example: 'ok' },
+                    info: {
+                        type: 'object',
+                        properties: {
+                            database: {
+                                type: 'object',
+                                properties: {
+                                    status: { type: 'string', example: 'up' },
+                                },
+                            },
+                        },
+                    },
+                    timestamp: { type: 'string', format: 'date-time' },
+                },
+            },
+        }),
+        (0, swagger_1.ApiResponse)({
+            status: 503,
+            description: 'Application is not ready',
+            schema: {
+                type: 'object',
+                properties: {
+                    status: { type: 'string', example: 'error' },
+                    error: {
+                        type: 'object',
+                        properties: {
+                            database: {
+                                type: 'object',
+                                properties: {
+                                    status: { type: 'string', example: 'down' },
+                                    message: { type: 'string' },
+                                },
+                            },
+                        },
+                    },
+                    timestamp: { type: 'string', format: 'date-time' },
+                },
+            },
+        }),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", []),
+        __metadata("design:returntype", Promise)
+    ], HealthController.prototype, "readiness", null);
+    __decorate([
+        (0, common_1.Get)(),
+        publicRoute,
+        (0, terminus_1.HealthCheck)(),
+        (0, swagger_1.ApiOperation)({
+            summary: 'Full health check',
+            description: 'Comprehensive health check including all dependencies.',
+        }),
+        (0, swagger_1.ApiResponse)({ status: 200, description: 'All checks passed' }),
+        (0, swagger_1.ApiResponse)({ status: 503, description: 'One or more checks failed' }),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", []),
+        __metadata("design:returntype", Promise)
+    ], HealthController.prototype, "fullHealth", null);
+    HealthController = __decorate([
+        (0, swagger_1.ApiTags)('Health'),
+        (0, common_1.Controller)('health'),
+        (0, index_1.AllowDuringMaintenance)(),
+        __param(0, (0, common_1.Inject)(terminus_1.HealthCheckService)),
+        __param(1, (0, common_1.Inject)(health_indicator_runner_1.HealthIndicatorRunner)),
+        __param(2, (0, common_1.Inject)(maintenance_mode_service_1.MaintenanceModeService)),
+        __metadata("design:paramtypes", [terminus_1.HealthCheckService,
+            health_indicator_runner_1.HealthIndicatorRunner,
+            maintenance_mode_service_1.MaintenanceModeService])
+    ], HealthController);
+    return HealthController;
+}
+/**
+ * The health controller with the identity slice's `@Public()` (no `host`).
+ *
+ * @internal
+ */
+exports.HealthController = createHealthController();
+//# sourceMappingURL=health.controller.js.map

package/dist/host/health/health.controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.controller.js","sourceRoot":"","sources":["../../../src/host/health/health.controller.ts"],"names":[],"mappings":"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"}

package/dist/host/host-core.module.d.ts

@@ -0,0 +1,41 @@
+import { type DynamicModule, type MiddlewareConsumer, type NestModule } from '@nestjs/common';
+import { type PlatformHostCoreOptions } from './host-core.options';
+/**
+ * The API host core: the event bus, the platform's app metrics, maintenance
+ * mode (the platform's `APP_GUARD`), the `{ data }` envelope, the request log line,
+ * the exception filter and request ids. Global.
+ *
+ * @stability experimental
+ */
+export declare class PlatformHostCoreModule implements NestModule {
+    /**
+     * The host core for one app. Registers the platform's app metrics and the
+     * `maintenance` settings namespace unless they already are (call it before
+     * `SettingsModule.forRoot()`, or register the namespace in the app's
+     * manifest), then returns the global module. Import it exactly once.
+     *
+     * @param options - see {@link PlatformHostCoreOptions}; all optional.
+     * @returns the global dynamic module. It exports `EVENT_BUS`,
+     *   `EVENT_BUS_SELECTION`, `AppMetricsService`, `MaintenanceModeService`,
+     *   `MaintenanceGuard` and `PLATFORM_HOST_CORE_OPTIONS`.
+     * @throws Error when an option is invalid, or when `SettingsModule.forRoot()`
+     *   already composed the settings bodies without the `maintenance` namespace.
+     *
+     * @example
+     * ```ts
+     * // apps/api/src/platform/host-core.config.ts
+     * export const hostCoreModule = PlatformHostCoreModule.forRoot();
+     * ```
+     *
+     * @extensionPoint option
+     * @stability experimental
+     */
+    static forRoot(options?: PlatformHostCoreOptions): DynamicModule;
+    /**
+     * Applies {@link RequestIdMiddleware} to every route.
+     *
+     * @param consumer - Nest's middleware consumer.
+     */
+    configure(consumer: MiddlewareConsumer): void;
+}
+//# sourceMappingURL=host-core.module.d.ts.map

package/dist/host/host-core.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-core.module.d.ts","sourceRoot":"","sources":["../../src/host/host-core.module.ts"],"names":[],"mappings":"AAoDA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EAEhB,MAAM,gBAAgB,CAAC;AAuBxB,OAAO,EAGL,KAAK,uBAAuB,EAE7B,MAAM,qBAAqB,CAAC;AAe7B;;;;;;GAMG;AACH,qBAEa,sBAAuB,YAAW,UAAU;IACvD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,uBAA4B,GAAG,aAAa;IAoHpE;;;;OAIG;IACH,SAAS,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI;CAG9C"}

package/dist/host/host-core.module.js

@@ -0,0 +1,249 @@
+"use strict";
+// =============================================================================
+// PlatformHostCoreModule: the API host core every slice assumes (issue #867)
+// =============================================================================
+//
+// One global module the app imports once, with everything a working platform
+// API needs around its slices (all of it was the reference app's own code):
+//
+//   - `EVENT_BUS` (and `EVENT_BUS_SELECTION`): the cross-replica event bus,
+//     `in-process` or `postgres` by `EVENT_BUS_ADAPTER` (or any adapter the app
+//     registered with `registerEventBusAdapter`, or a whole bus bound with the
+//     `eventBus` option), with its `core.event-bus` Doctor check;
+//   - `AppMetricsService`: the platform's typed metric recorders and the
+//     generic `add`/`record`, on otel-core's metrics host, plus the platform's
+//     `app.*` metric declarations (`registerPlatformHostAppMetrics`);
+//   - maintenance mode: `MaintenanceModeService`, `/api/admin/maintenance`, the
+//     `maintenance.mode` Doctor check and `MaintenanceGuard` as the platform's
+//     `APP_GUARD`, which runs first (there is no global JWT guard; an app's own
+//     global guard, a throttler, is declared to the `host` conformance suite);
+//   - the `{ data }` response envelope (`TransformInterceptor`), the request
+//     log line (`LoggingInterceptor`) and core's `HttpExceptionFilter`, as
+//     global enhancers;
+//   - request ids (`RequestIdMiddleware`, every route);
+//   - the health probes (`GET /api/health`, `/live`, `/ready`: public, reachable
+//     during maintenance; they run the indicators registered with
+//     `registerHealthIndicator`, the built-in `database` one a `SELECT 1`
+//     through `PLATFORM_PRISMA`; #901);
+//   - the deployment facts (`DeploymentModeService` for `DEPLOYMENT_MODE`,
+//     `DeploymentNetworkService` for `DEPLOYMENT_NETWORK`, bound as the doctor
+//     slice's `DEPLOYMENT_NETWORK_SOURCE`) and the generic Doctor checks:
+//     `db.connection`, `db.migrations`, `db.rls_role`, `secrets.encryption-key`,
+//     `core.deployment-mode` and `network.egress` (#879).
+//
+// The OpenAPI document and `/api/docs` are bootstrap-time, because they need
+// the built application: `registerPlatformDocs(app, openApi)` in `main.ts`.
+//
+// REQUIRES core's `PlatformHostModule.forRoot()` (`AUDIT_SINK`, and
+// `PLATFORM_PRISMA` for the `postgres` bus and the gauges), the global
+// settings module (the `maintenance` namespace, `MAINTENANCE_SYSTEM_SETTINGS`:
+// `forRoot()` registers it unless the app's manifest did, so call it before
+// `SettingsModule.forRoot()` or register it there), a global `ConfigModule`
+// carrying `jwt.secret` (the identity slice's configuration; `deployment.mode`
+// and `deployment.network` too when published, else `DEPLOYMENT_MODE` and
+// `DEPLOYMENT_NETWORK` are read from the environment) and, for the Doctor
+// checks, the doctor module. The database checks read through `PLATFORM_PRISMA`
+// and report `skip` when it is unbound.
+//
+// WHERE TO IMPORT IT. Only the health and maintenance controllers have
+// routes, and the generated OpenAPI document lists paths in module order, so
+// the app places this module where `/api/health` and `/api/admin/maintenance`
+// belong in its document (the reference app: right after `ProfileImageModule`).
+// =============================================================================
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var PlatformHostCoreModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlatformHostCoreModule = void 0;
+const common_1 = require("@nestjs/common");
+const config_1 = require("@nestjs/config");
+const core_1 = require("@nestjs/core");
+const jwt_1 = require("@nestjs/jwt");
+const terminus_1 = require("@nestjs/terminus");
+const index_1 = require("../core/index");
+const index_2 = require("../identity/index");
+const index_3 = require("../otel-core/index");
+const index_4 = require("../settings/index");
+const index_5 = require("../doctor/index");
+const deployment_mode_service_1 = require("./deployment/deployment-mode.service");
+const deployment_network_service_1 = require("./deployment/deployment-network.service");
+const db_connection_doctor_check_1 = require("./doctor/db-connection.doctor-check");
+const db_migrations_doctor_check_1 = require("./doctor/db-migrations.doctor-check");
+const deployment_mode_doctor_check_1 = require("./doctor/deployment-mode.doctor-check");
+const encryption_key_doctor_check_1 = require("./doctor/encryption-key.doctor-check");
+const rls_role_doctor_check_1 = require("./doctor/rls-role.doctor-check");
+const event_bus_doctor_check_1 = require("./event-bus/doctor/event-bus.doctor-check");
+const event_bus_config_1 = require("./event-bus/event-bus.config");
+const event_bus_factory_1 = require("./event-bus/event-bus.factory");
+const event_bus_interface_1 = require("./event-bus/event-bus.interface");
+const host_core_options_1 = require("./host-core.options");
+const database_indicator_1 = require("./health/database.indicator");
+const health_controller_1 = require("./health/health.controller");
+const health_indicator_runner_1 = require("./health/health-indicator.runner");
+const logging_interceptor_1 = require("./http/logging.interceptor");
+const request_id_middleware_1 = require("./http/request-id.middleware");
+const transform_interceptor_1 = require("./http/transform.interceptor");
+const maintenance_mode_doctor_check_1 = require("./maintenance/doctor/maintenance-mode.doctor-check");
+const maintenance_mode_service_1 = require("./maintenance/maintenance-mode.service");
+const maintenance_controller_1 = require("./maintenance/maintenance.controller");
+const maintenance_guard_1 = require("./maintenance/maintenance.guard");
+const maintenance_system_settings_1 = require("./maintenance/maintenance.system-settings");
+const app_metrics_service_1 = require("./metrics/app-metrics.service");
+const register_1 = require("./metrics/register");
+/**
+ * The API host core: the event bus, the platform's app metrics, maintenance
+ * mode (the platform's `APP_GUARD`), the `{ data }` envelope, the request log line,
+ * the exception filter and request ids. Global.
+ *
+ * @stability experimental
+ */
+let PlatformHostCoreModule = PlatformHostCoreModule_1 = class PlatformHostCoreModule {
+    /**
+     * The host core for one app. Registers the platform's app metrics and the
+     * `maintenance` settings namespace unless they already are (call it before
+     * `SettingsModule.forRoot()`, or register the namespace in the app's
+     * manifest), then returns the global module. Import it exactly once.
+     *
+     * @param options - see {@link PlatformHostCoreOptions}; all optional.
+     * @returns the global dynamic module. It exports `EVENT_BUS`,
+     *   `EVENT_BUS_SELECTION`, `AppMetricsService`, `MaintenanceModeService`,
+     *   `MaintenanceGuard` and `PLATFORM_HOST_CORE_OPTIONS`.
+     * @throws Error when an option is invalid, or when `SettingsModule.forRoot()`
+     *   already composed the settings bodies without the `maintenance` namespace.
+     *
+     * @example
+     * ```ts
+     * // apps/api/src/platform/host-core.config.ts
+     * export const hostCoreModule = PlatformHostCoreModule.forRoot();
+     * ```
+     *
+     * @extensionPoint option
+     * @stability experimental
+     */
+    static forRoot(options = {}) {
+        const resolved = (0, host_core_options_1.resolvePlatformHostCoreOptions)(options);
+        (0, register_1.registerPlatformHostAppMetrics)();
+        (0, index_4.ensureSystemSettingsNamespaces)([maintenance_system_settings_1.MAINTENANCE_SYSTEM_SETTINGS], 'PlatformHostCoreModule.forRoot()');
+        return {
+            global: true,
+            module: PlatformHostCoreModule_1,
+            imports: [
+                // The metrics host (otel-core): instruments, label bounding, gauges.
+                index_3.OtelMetricsModule.forRootAsync({
+                    useFactory: () => ({ gauges: resolved.metricsGauges ?? process.env.OTEL_ENABLED === 'true' }),
+                }),
+                // The maintenance guard verifies an admin bearer itself (it runs before
+                // any route guard), against the SAME `jwt.secret` the identity slice
+                // signs with. Its own JwtModule, never re-exported: the guard must not
+                // pull the whole auth graph in front of every request.
+                jwt_1.JwtModule.registerAsync({
+                    imports: [config_1.ConfigModule],
+                    inject: [config_1.ConfigService],
+                    useFactory: (config) => ({ secret: (0, index_2.requireJwtSecret)(config) }),
+                }),
+                // The health probes' Terminus services.
+                terminus_1.TerminusModule,
+                ...resolved.imports,
+            ],
+            // Health first: `/api/health` has always preceded
+            // `/api/admin/maintenance` in the generated OpenAPI document.
+            controllers: [
+                (0, health_controller_1.createHealthController)(resolved.host),
+                (0, maintenance_controller_1.createMaintenanceController)({
+                    host: resolved.host,
+                    readPermission: resolved.permissions.maintenanceRead,
+                    writePermission: resolved.permissions.maintenanceWrite,
+                }),
+            ],
+            providers: [
+                { provide: host_core_options_1.PLATFORM_HOST_CORE_OPTIONS, useValue: resolved },
+                {
+                    provide: event_bus_config_1.EVENT_BUS_SELECTION,
+                    inject: [host_core_options_1.PLATFORM_HOST_CORE_OPTIONS],
+                    useFactory: (opts) => opts.eventBus
+                        ? event_bus_config_1.BOUND_EVENT_BUS_SELECTION
+                        : // The option is code: an id nobody registered fails the boot. The
+                            // environment variable stays fail-safe (one warning, `in-process`).
+                            opts.eventBusAdapter !== undefined
+                                ? (0, event_bus_factory_1.selectEventBus)(opts.eventBusAdapter, { strict: true })
+                                : (0, event_bus_factory_1.selectEventBus)(process.env.EVENT_BUS_ADAPTER),
+                },
+                // A bound bus (`eventBus`) replaces the adapter lookup entirely. It is
+                // provided HERE, in the global module every consumer resolves `EVENT_BUS`
+                // from, which is what makes the override reach them (PP-14.2).
+                resolved.eventBus
+                    ? { provide: event_bus_interface_1.EVENT_BUS, ...resolved.eventBus }
+                    : {
+                        provide: event_bus_interface_1.EVENT_BUS,
+                        inject: [event_bus_config_1.EVENT_BUS_SELECTION, { token: index_1.PLATFORM_PRISMA, optional: true }, app_metrics_service_1.AppMetricsService, config_1.ConfigService],
+                        useFactory: (selection, sql, metrics, config) => (0, event_bus_factory_1.createEventBus)(selection, sql ?? undefined, metrics, config),
+                    },
+                // The deployment facts (`DEPLOYMENT_MODE`, `DEPLOYMENT_NETWORK`) and the
+                // generic Doctor checks, in the order the report lists them within the
+                // `core` category: the event bus, the deployment mode, then the
+                // database and secrets checks (registration order is report order).
+                deployment_mode_service_1.DeploymentModeService,
+                deployment_network_service_1.DeploymentNetworkService,
+                { provide: index_5.DEPLOYMENT_NETWORK_SOURCE, useExisting: deployment_network_service_1.DeploymentNetworkService },
+                event_bus_doctor_check_1.EventBusDoctorCheck,
+                deployment_mode_doctor_check_1.DeploymentModeDoctorCheck,
+                db_connection_doctor_check_1.DbConnectionDoctorCheck,
+                db_migrations_doctor_check_1.DbMigrationsDoctorCheck,
+                encryption_key_doctor_check_1.EncryptionKeyDoctorCheck,
+                rls_role_doctor_check_1.RlsRoleDoctorCheck,
+                index_5.NetworkEgressDoctorCheck,
+                app_metrics_service_1.AppMetricsService,
+                database_indicator_1.DatabaseHealthIndicator,
+                health_indicator_runner_1.HealthIndicatorRunner,
+                maintenance_mode_service_1.MaintenanceModeService,
+                maintenance_guard_1.MaintenanceGuard,
+                maintenance_mode_doctor_check_1.MaintenanceModeDoctorCheck,
+                // The platform's global guard, and the first one: this module is imported
+                // once, ahead of the app's own guards (the `host` conformance suite checks
+                // the order). `useExisting`, so the instance is the one constructed here,
+                // next to its JwtService.
+                { provide: core_1.APP_GUARD, useExisting: maintenance_guard_1.MaintenanceGuard },
+                // The error mappers reach the filter through its own options token, bound
+                // HERE (the global module the APP_FILTER is created in).
+                {
+                    provide: index_1.HTTP_EXCEPTION_FILTER_OPTIONS,
+                    inject: [host_core_options_1.PLATFORM_HOST_CORE_OPTIONS],
+                    useFactory: (opts) => ({ mappers: opts.errorMappers }),
+                },
+                { provide: core_1.APP_FILTER, useClass: index_1.HttpExceptionFilter },
+                // Order matters: the log line wraps the envelope.
+                { provide: core_1.APP_INTERCEPTOR, useClass: logging_interceptor_1.LoggingInterceptor },
+                { provide: core_1.APP_INTERCEPTOR, useClass: transform_interceptor_1.TransformInterceptor },
+            ],
+            exports: [
+                host_core_options_1.PLATFORM_HOST_CORE_OPTIONS,
+                event_bus_interface_1.EVENT_BUS,
+                event_bus_config_1.EVENT_BUS_SELECTION,
+                app_metrics_service_1.AppMetricsService,
+                maintenance_mode_service_1.MaintenanceModeService,
+                maintenance_guard_1.MaintenanceGuard,
+                deployment_mode_service_1.DeploymentModeService,
+                deployment_network_service_1.DeploymentNetworkService,
+                index_5.DEPLOYMENT_NETWORK_SOURCE,
+            ],
+        };
+    }
+    /**
+     * Applies {@link RequestIdMiddleware} to every route.
+     *
+     * @param consumer - Nest's middleware consumer.
+     */
+    configure(consumer) {
+        consumer.apply(request_id_middleware_1.RequestIdMiddleware).forRoutes('*');
+    }
+};
+exports.PlatformHostCoreModule = PlatformHostCoreModule;
+exports.PlatformHostCoreModule = PlatformHostCoreModule = PlatformHostCoreModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({})
+], PlatformHostCoreModule);
+//# sourceMappingURL=host-core.module.js.map

package/dist/host/host-core.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-core.module.js","sourceRoot":"","sources":["../../src/host/host-core.module.ts"],"names":[],"mappings":"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"}