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

package/dist/doctor/doctor.service.d.ts

@@ -0,0 +1,80 @@
+import type { DoctorReport } from '@marinoscar/platform-contract/doctor';
+import { DoctorStatus } from './doctor-check.interface';
+import { DoctorCheckRegistry } from './doctor-check.registry';
+import { ResolvedDoctorModuleOptions } from './doctor.options';
+/**
+ * Per-check ceiling when a check declares none: the default of `defaultTimeoutMs`.
+ *
+ * @stability stable
+ */
+export declare const DOCTOR_DEFAULT_TIMEOUT_MS = 5000;
+/**
+ * How long a report is served from memory: the default of `cacheTtlMs`.
+ *
+ * @stability stable
+ */
+export declare const DOCTOR_CACHE_TTL_MS = 15000;
+/**
+ * Remedy for a warn/fail with no settings page and no remedy of its own.
+ *
+ * @stability stable
+ */
+export declare const DOCTOR_FALLBACK_REMEDY = "See the API logs for details.";
+/**
+ * What {@link DoctorService.run} takes.
+ *
+ * @stability stable
+ */
+export interface DoctorRunOptions {
+    /** Only the checks in this category (plus, unreported, whatever they depend on). */
+    category?: string;
+    /** Bypass (and replace) the cached report. */
+    refresh?: boolean;
+}
+/**
+ * The worst of `statuses`; `skip` when there are none (nothing was proven).
+ *
+ * @param statuses - the statuses to fold.
+ * @returns the worst, ordered `pass < skip < warn < fail`.
+ *
+ * @stability stable
+ */
+export declare function worstStatus(statuses: DoctorStatus[]): DoctorStatus;
+/**
+ * Runs the registered checks into one report: parallel, dependency-aware,
+ * time-boxed, normalised and briefly cached. Provided by `DoctorModule.forRoot()`.
+ *
+ * @stability stable
+ */
+export declare class DoctorService {
+    private readonly registry;
+    private readonly logger;
+    private readonly cache;
+    private readonly categoryOrder;
+    private readonly defaultTimeoutMs;
+    private readonly cacheTtlMs;
+    /** Overridable in tests. */
+    protected now: () => number;
+    /**
+     * @param registry - the checks to run.
+     * @param options - the module's resolved options; the defaults when absent
+     *   (`PLATFORM_DOCTOR_CATEGORIES`, 5000 ms, 15000 ms).
+     */
+    constructor(registry: DoctorCheckRegistry, options?: Pick<ResolvedDoctorModuleOptions, 'categoryOrder' | 'defaultTimeoutMs' | 'cacheTtlMs'>);
+    /**
+     * The report for every check, or for one `category`. Never throws for a check's sake.
+     *
+     * @param options - the category filter and the cache bypass.
+     * @returns the report; served from the cache for `cacheTtlMs` unless `refresh`.
+     */
+    run(options?: DoctorRunOptions): Promise<DoctorReport>;
+    /** Drops every cached report. */
+    invalidate(): void;
+    private execute;
+    private evaluate;
+    private runGuarded;
+    private toReport;
+    /** Every check id that sits on a `dependsOn` cycle. */
+    private findCycles;
+}
+//# sourceMappingURL=doctor.service.d.ts.map

package/dist/doctor/doctor.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.service.d.ts","sourceRoot":"","sources":["../../src/doctor/doctor.service.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAqB,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAG5F,OAAO,EAML,YAAY,EACb,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAyB,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAEtF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,OAAQ,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAK1C;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,kCAAkC,CAAC;AAEtE;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAOD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,YAAY,CAMlE;AAcD;;;;;GAKG;AACH,qBACa,aAAa;IAgBO,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAfxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoB;IAClD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,4BAA4B;IAC5B,SAAS,CAAC,GAAG,EAAE,MAAM,MAAM,CAAoB;IAE/C;;;;OAIG;gBAE6C,QAAQ,EAAE,mBAAmB,EAG3E,OAAO,CAAC,EAAE,IAAI,CAAC,2BAA2B,EAAE,eAAe,GAAG,kBAAkB,GAAG,YAAY,CAAC;IAOlG;;;;;OAKG;IACG,GAAG,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,YAAY,CAAC;IA2BhE,iCAAiC;IACjC,UAAU,IAAI,IAAI;YAIJ,OAAO;YA2CP,QAAQ;YAyCR,UAAU;IAqCxB,OAAO,CAAC,QAAQ;IA6BhB,uDAAuD;IACvD,OAAO,CAAC,UAAU;CA6BnB"}

package/dist/doctor/doctor.service.js

@@ -0,0 +1,301 @@
+"use strict";
+// =============================================================================
+// DoctorService — runs the registered checks into one report (issue #634; packaged by #696)
+// =============================================================================
+//
+// WHAT THIS OWNS, so no check has to:
+//
+//   - PARALLELISM. Every check whose dependencies have settled starts at once;
+//     a dependent check starts the moment its last dependency settles. That is
+//     "dependency waves" without a wave barrier: a slow telemetry probe never
+//     delays an unrelated storage one.
+//   - DEPENDENCIES. A check whose `dependsOn` contains a `fail` or a `skip` is
+//     reported as `skip` and never run: "bucket unreachable" beneath "storage
+//     not configured" is noise, and running it would only time out.
+//   - FAILURE CONTAINMENT. A throw becomes `fail` with the error's message; a
+//     hang becomes `fail` after `timeoutMs` (default `defaultTimeoutMs`, 5000). One broken check
+//     never costs the operator the rest of the list.
+//   - NORMALISATION. `detail` is forced to one line; a `warn`/`fail` with no
+//     remedy gets a generic one naming its settings page.
+//   - CACHING. The report is cached for `cacheTtlMs` (15 s) per filter, so a page that polls,
+//     or two admins opening it together, do not multiply the probes. In-flight
+//     runs are shared too. `refresh: true` bypasses (and replaces) the cache.
+//
+// Read-only by construction: this file writes nothing, and the checks it runs
+// are bound by the same rule (see `doctor-check.interface.ts`).
+// =============================================================================
+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); }
+};
+var DoctorService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DoctorService = exports.DOCTOR_FALLBACK_REMEDY = exports.DOCTOR_CACHE_TTL_MS = exports.DOCTOR_DEFAULT_TIMEOUT_MS = void 0;
+exports.worstStatus = worstStatus;
+const common_1 = require("@nestjs/common");
+const doctor_check_interface_1 = require("./doctor-check.interface");
+const doctor_check_registry_1 = require("./doctor-check.registry");
+const doctor_options_1 = require("./doctor.options");
+/**
+ * Per-check ceiling when a check declares none: the default of `defaultTimeoutMs`.
+ *
+ * @stability stable
+ */
+exports.DOCTOR_DEFAULT_TIMEOUT_MS = 5_000;
+/**
+ * How long a report is served from memory: the default of `cacheTtlMs`.
+ *
+ * @stability stable
+ */
+exports.DOCTOR_CACHE_TTL_MS = 15_000;
+/** A `detail` longer than this is cut: it is one line in a table. */
+const MAX_DETAIL_LENGTH = 500;
+/**
+ * Remedy for a warn/fail with no settings page and no remedy of its own.
+ *
+ * @stability stable
+ */
+exports.DOCTOR_FALLBACK_REMEDY = 'See the API logs for details.';
+/**
+ * The worst of `statuses`; `skip` when there are none (nothing was proven).
+ *
+ * @param statuses - the statuses to fold.
+ * @returns the worst, ordered `pass < skip < warn < fail`.
+ *
+ * @stability stable
+ */
+function worstStatus(statuses) {
+    if (statuses.length === 0)
+        return 'skip';
+    return statuses.reduce((worst, status) => doctor_check_interface_1.DOCTOR_STATUS_RANK[status] > doctor_check_interface_1.DOCTOR_STATUS_RANK[worst] ? status : worst);
+}
+function oneLine(text) {
+    const flat = text.replace(/\s*[\r\n]+\s*/g, ' ').trim();
+    return flat.length > MAX_DETAIL_LENGTH ? `${flat.slice(0, MAX_DETAIL_LENGTH - 1)}…` : flat;
+}
+function errorMessage(error) {
+    if (error instanceof Error)
+        return oneLine(error.message || error.name);
+    return oneLine(String(error));
+}
+/**
+ * Runs the registered checks into one report: parallel, dependency-aware,
+ * time-boxed, normalised and briefly cached. Provided by `DoctorModule.forRoot()`.
+ *
+ * @stability stable
+ */
+let DoctorService = DoctorService_1 = class DoctorService {
+    registry;
+    logger = new common_1.Logger(DoctorService_1.name);
+    cache = new Map();
+    categoryOrder;
+    defaultTimeoutMs;
+    cacheTtlMs;
+    /** Overridable in tests. */
+    now = () => Date.now();
+    /**
+     * @param registry - the checks to run.
+     * @param options - the module's resolved options; the defaults when absent
+     *   (`PLATFORM_DOCTOR_CATEGORIES`, 5000 ms, 15000 ms).
+     */
+    constructor(registry, options) {
+        this.registry = registry;
+        this.categoryOrder = options?.categoryOrder ?? doctor_check_interface_1.PLATFORM_DOCTOR_CATEGORIES;
+        this.defaultTimeoutMs = options?.defaultTimeoutMs ?? exports.DOCTOR_DEFAULT_TIMEOUT_MS;
+        this.cacheTtlMs = options?.cacheTtlMs ?? exports.DOCTOR_CACHE_TTL_MS;
+    }
+    /**
+     * The report for every check, or for one `category`. Never throws for a check's sake.
+     *
+     * @param options - the category filter and the cache bypass.
+     * @returns the report; served from the cache for `cacheTtlMs` unless `refresh`.
+     */
+    async run(options = {}) {
+        const key = options.category ?? '*';
+        const cached = this.cache.get(key);
+        if (!options.refresh && cached && this.now() - cached.at < this.cacheTtlMs) {
+            return cached.report;
+        }
+        // Expired entries are dropped here, so arbitrary `category` values cannot
+        // grow the map past what one TTL of requests can put in it.
+        for (const [k, e] of this.cache) {
+            if (this.now() - e.at >= this.cacheTtlMs)
+                this.cache.delete(k);
+        }
+        const report = this.execute(options.category);
+        const entry = { at: this.now(), report };
+        this.cache.set(key, entry);
+        // A run that itself blew up (it should not — every check is guarded) must
+        // not be served from the cache for the next 15 seconds.
+        report.catch(() => {
+            if (this.cache.get(key) === entry)
+                this.cache.delete(key);
+        });
+        return report;
+    }
+    /** Drops every cached report. */
+    invalidate() {
+        this.cache.clear();
+    }
+    async execute(category) {
+        const started = this.now();
+        const all = this.registry.list();
+        const byId = new Map(all.map((check) => [check.id, check]));
+        const order = new Map(all.map((check, index) => [check.id, index]));
+        const reported = category === undefined ? all : all.filter((check) => check.category === category);
+        const cyclic = this.findCycles(all);
+        const results = new Map();
+        const resultFor = (check) => {
+            let result = results.get(check.id);
+            if (!result) {
+                result = this.evaluate(check, byId, cyclic, resultFor);
+                results.set(check.id, result);
+            }
+            return result;
+        };
+        const checks = await Promise.all(reported.map((check) => resultFor(check)));
+        const categoryRank = (category) => {
+            const index = this.categoryOrder.indexOf(category);
+            return index === -1 ? this.categoryOrder.length : index;
+        };
+        checks.sort((a, b) => categoryRank(a.category) - categoryRank(b.category) ||
+            (order.get(a.id) ?? 0) - (order.get(b.id) ?? 0));
+        return {
+            verdict: worstStatus(checks.map((check) => check.status)),
+            generatedAt: new Date(started).toISOString(),
+            durationMs: Math.max(0, Math.round(this.now() - started)),
+            checks,
+        };
+    }
+    async evaluate(check, byId, cyclic, resultFor) {
+        if (cyclic.has(check.id)) {
+            return this.toReport(check, {
+                status: 'fail',
+                detail: `Dependency cycle: "${check.id}" depends on itself through dependsOn.`,
+                remedy: 'Fix the dependsOn declarations of the checks in this cycle.',
+            }, 0);
+        }
+        for (const depId of check.dependsOn ?? []) {
+            const dep = byId.get(depId);
+            if (!dep) {
+                return this.toReport(check, {
+                    status: 'skip',
+                    detail: `Skipped: the check "${depId}" it depends on is not registered`,
+                }, 0);
+            }
+        }
+        const deps = await Promise.all((check.dependsOn ?? []).map((depId) => resultFor(byId.get(depId))));
+        const blocking = deps.find((dep) => dep.status === 'fail' || dep.status === 'skip');
+        if (blocking) {
+            return this.toReport(check, {
+                status: 'skip',
+                detail: `Skipped: ${blocking.label} did not pass`,
+            }, 0);
+        }
+        const started = this.now();
+        const outcome = await this.runGuarded(check);
+        return this.toReport(check, outcome, Math.max(0, Math.round(this.now() - started)));
+    }
+    async runGuarded(check) {
+        const timeoutMs = check.timeoutMs ?? this.defaultTimeoutMs;
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => resolve({
+                status: 'fail',
+                detail: `Timed out after ${timeoutMs}ms`,
+                remedy: check.settingsPath
+                    ? `The probe did not answer in time. Check the service is reachable, then review ${check.settingsPath}.`
+                    : 'The probe did not answer in time. Check the service it probes is reachable from the API.',
+            }), timeoutMs);
+            timer.unref?.();
+        });
+        try {
+            return await Promise.race([
+                Promise.resolve().then(() => check.run()),
+                timeout,
+            ]);
+        }
+        catch (error) {
+            this.logger.warn(`Doctor check "${check.id}" threw: ${errorMessage(error)}`);
+            return {
+                status: 'fail',
+                detail: `The check failed: ${errorMessage(error)}`,
+                error: errorMessage(error),
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    toReport(check, outcome, durationMs) {
+        const valid = doctor_check_interface_1.DOCTOR_STATUSES.includes(outcome?.status);
+        const status = valid ? outcome.status : 'fail';
+        const detail = !valid
+            ? 'The check returned an invalid outcome.'
+            : typeof outcome.detail === 'string' && outcome.detail.trim() !== ''
+                ? oneLine(outcome.detail)
+                : '(no detail)';
+        let remedy = typeof outcome?.remedy === 'string' && outcome.remedy.trim() !== '' ? outcome.remedy.trim() : null;
+        if (!remedy && (status === 'warn' || status === 'fail')) {
+            remedy = check.settingsPath ? `Open ${check.settingsPath} to review.` : exports.DOCTOR_FALLBACK_REMEDY;
+        }
+        return {
+            id: check.id,
+            category: check.category,
+            label: check.label,
+            settingsPath: check.settingsPath ?? null,
+            status,
+            detail,
+            remedy,
+            error: typeof outcome?.error === 'string' && outcome.error !== '' ? oneLine(outcome.error) : null,
+            data: outcome?.data && Object.keys(outcome.data).length > 0 ? { ...outcome.data } : null,
+            durationMs,
+        };
+    }
+    /** Every check id that sits on a `dependsOn` cycle. */
+    findCycles(checks) {
+        const byId = new Map(checks.map((check) => [check.id, check]));
+        const cyclic = new Set();
+        const state = new Map();
+        const stack = [];
+        const visit = (id) => {
+            const seen = state.get(id);
+            if (seen === 'done')
+                return;
+            if (seen === 'visiting') {
+                for (const member of stack.slice(stack.indexOf(id)))
+                    cyclic.add(member);
+                return;
+            }
+            const check = byId.get(id);
+            if (!check)
+                return;
+            state.set(id, 'visiting');
+            stack.push(id);
+            for (const dep of check.dependsOn ?? [])
+                visit(dep);
+            stack.pop();
+            state.set(id, 'done');
+        };
+        for (const check of checks)
+            visit(check.id);
+        return cyclic;
+    }
+};
+exports.DoctorService = DoctorService;
+exports.DoctorService = DoctorService = DoctorService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(doctor_check_registry_1.DoctorCheckRegistry)),
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)(doctor_options_1.DOCTOR_MODULE_OPTIONS)),
+    __metadata("design:paramtypes", [doctor_check_registry_1.DoctorCheckRegistry, Object])
+], DoctorService);
+//# sourceMappingURL=doctor.service.js.map

package/dist/doctor/doctor.service.js.map

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

package/dist/doctor/dto/doctor-query.dto.d.ts

@@ -0,0 +1,15 @@
+declare const DoctorQueryDto_base: import("nestjs-zod").ZodDto<import("zod").ZodObject<{
+    category: import("zod").ZodOptional<import("zod").ZodString>;
+    refresh: import("zod").ZodOptional<import("zod").ZodPipe<import("zod").ZodEnum<import("@marinoscar/platform-contract/doctor").DoctorBooleanStringEnum>, import("zod").ZodTransform<boolean, "true" | "false">>>;
+}, import("zod/v4/core").$strip>, false>;
+/**
+ * The validated query of `GET /api/admin/doctor`: the nestjs-zod DTO of
+ * `doctorQuerySchema` from `@marinoscar/platform-contract/doctor` (#701), where
+ * the schema and its parsed type `DoctorQuery` live.
+ *
+ * @stability stable
+ */
+export declare class DoctorQueryDto extends DoctorQueryDto_base {
+}
+export {};
+//# sourceMappingURL=doctor-query.dto.d.ts.map

package/dist/doctor/dto/doctor-query.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-query.dto.d.ts","sourceRoot":"","sources":["../../../src/doctor/dto/doctor-query.dto.ts"],"names":[],"mappings":";;;;AAGA;;;;;;GAMG;AACH,qBAAa,cAAe,SAAQ,mBAA+B;CAAG"}

package/dist/doctor/dto/doctor-query.dto.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DoctorQueryDto = void 0;
+const doctor_1 = require("@marinoscar/platform-contract/doctor");
+const nestjs_zod_1 = require("nestjs-zod");
+/**
+ * The validated query of `GET /api/admin/doctor`: the nestjs-zod DTO of
+ * `doctorQuerySchema` from `@marinoscar/platform-contract/doctor` (#701), where
+ * the schema and its parsed type `DoctorQuery` live.
+ *
+ * @stability stable
+ */
+class DoctorQueryDto extends (0, nestjs_zod_1.createZodDto)(doctor_1.doctorQuerySchema) {
+}
+exports.DoctorQueryDto = DoctorQueryDto;
+//# sourceMappingURL=doctor-query.dto.js.map

package/dist/doctor/dto/doctor-query.dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-query.dto.js","sourceRoot":"","sources":["../../../src/doctor/dto/doctor-query.dto.ts"],"names":[],"mappings":";;;AAAA,iEAAyE;AACzE,2CAA0C;AAE1C;;;;;;GAMG;AACH,MAAa,cAAe,SAAQ,IAAA,yBAAY,EAAC,0BAAiB,CAAC;CAAG;AAAtE,wCAAsE"}

package/dist/doctor/dto/doctor-report.dto.d.ts

@@ -0,0 +1,27 @@
+declare const DoctorReportDto_base: import("nestjs-zod").ZodDto<import("zod").ZodObject<{
+    verdict: import("zod").ZodEnum<import("@marinoscar/platform-contract/doctor").DoctorStatusEnum>;
+    generatedAt: import("zod").ZodISODateTime;
+    durationMs: import("zod").ZodNumber;
+    checks: import("zod").ZodArray<import("zod").ZodObject<{
+        id: import("zod").ZodString;
+        category: import("zod").ZodString;
+        label: import("zod").ZodString;
+        settingsPath: import("zod").ZodNullable<import("zod").ZodString>;
+        status: import("zod").ZodEnum<import("@marinoscar/platform-contract/doctor").DoctorStatusEnum>;
+        detail: import("zod").ZodString;
+        remedy: import("zod").ZodNullable<import("zod").ZodString>;
+        error: import("zod").ZodNullable<import("zod").ZodString>;
+        data: import("zod").ZodNullable<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnion<readonly [import("zod").ZodString, import("zod").ZodNumber, import("zod").ZodBoolean, import("zod").ZodNull]>>>;
+        durationMs: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>, false>;
+/**
+ * The OpenAPI response DTO of `GET /api/admin/doctor`: the nestjs-zod DTO of
+ * `doctorReportSchema` from `@marinoscar/platform-contract/doctor`.
+ *
+ * @stability stable
+ */
+export declare class DoctorReportDto extends DoctorReportDto_base {
+}
+export {};
+//# sourceMappingURL=doctor-report.dto.d.ts.map

package/dist/doctor/dto/doctor-report.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-report.dto.d.ts","sourceRoot":"","sources":["../../../src/doctor/dto/doctor-report.dto.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAYA;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,oBAAgC;CAAG"}

package/dist/doctor/dto/doctor-report.dto.js

@@ -0,0 +1,23 @@
+"use strict";
+// =============================================================================
+// What `GET /api/admin/doctor` answers with (issue #634)
+// =============================================================================
+//
+// The schemas and their types live in `@marinoscar/platform-contract/doctor`
+// (#701), shared with the web client; this file only wraps the report schema
+// as the nestjs-zod DTO the controller names in its OpenAPI response.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DoctorReportDto = void 0;
+const doctor_1 = require("@marinoscar/platform-contract/doctor");
+const nestjs_zod_1 = require("nestjs-zod");
+/**
+ * The OpenAPI response DTO of `GET /api/admin/doctor`: the nestjs-zod DTO of
+ * `doctorReportSchema` from `@marinoscar/platform-contract/doctor`.
+ *
+ * @stability stable
+ */
+class DoctorReportDto extends (0, nestjs_zod_1.createZodDto)(doctor_1.doctorReportSchema) {
+}
+exports.DoctorReportDto = DoctorReportDto;
+//# sourceMappingURL=doctor-report.dto.js.map

package/dist/doctor/dto/doctor-report.dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-report.dto.js","sourceRoot":"","sources":["../../../src/doctor/dto/doctor-report.dto.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,yDAAyD;AACzD,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,sEAAsE;AACtE,gFAAgF;;;AAEhF,iEAA0E;AAC1E,2CAA0C;AAE1C;;;;;GAKG;AACH,MAAa,eAAgB,SAAQ,IAAA,yBAAY,EAAC,2BAAkB,CAAC;CAAG;AAAxE,0CAAwE"}

package/dist/doctor/egress/classify-host.d.ts

@@ -0,0 +1,73 @@
+import type { EgressDependency, EgressDependencyInput, EgressScope } from './egress.types';
+/**
+ * Reduces a URL, a `host:port` string or a bare name to its lower-case
+ * hostname: no scheme, userinfo, port, path, query or fragment, and no IPv6
+ * brackets. Returns `null` for an empty or unparsable value. Pure.
+ *
+ * @param value - `https://user:pw@api.openai.com:443/v1?x=1`, `minio:9000`, `[::1]`, `smtp.corp.internal`.
+ * @returns `api.openai.com`, `minio`, `::1`, `smtp.corp.internal`; or `null`.
+ *
+ * @example
+ * ```ts
+ * hostnameOf('http://ollama:11434/v1'); // 'ollama'
+ * ```
+ *
+ * @stability experimental
+ */
+export declare function hostnameOf(value: string | null | undefined): string | null;
+/**
+ * Where `host` lives, judged by its shape alone. No DNS lookup, no network I/O.
+ *
+ * Private: `localhost`; single-label names (Docker service names such as
+ * `minio`, `greptimedb`, `ollama`); IPv4 in 10/8, 172.16/12, 192.168/16, 127/8,
+ * 169.254/16; IPv6 `::1`, `fc00::/7`, `fe80::/10`; names ending in `.internal`,
+ * `.local`, `.lan`, `.home.arpa`, `.svc`, `.cluster.local` (or `.localhost`).
+ * Everything else is public. Empty or unparsable is `unknown`. A port, scheme,
+ * path or brackets are stripped first ({@link hostnameOf}).
+ *
+ * @param host - a hostname, `host:port`, IP literal or URL.
+ * @returns the scope.
+ *
+ * @example
+ * ```ts
+ * classifyHost('minio:9000');                   // 'private'
+ * classifyHost('contoso.openai.azure.com');     // 'public'
+ * classifyHost('');                             // 'unknown'
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare function classifyHost(host: string | null | undefined): EgressScope;
+/**
+ * The worst scope over `hosts` (`public`, then `unknown`, then `private`); `unknown`
+ * when there is no host at all. Pure.
+ *
+ * @param hosts - hostnames (or anything {@link classifyHost} accepts).
+ * @returns the scope the dependency is graded on.
+ *
+ * @stability experimental
+ */
+export declare function scopeOfHosts(hosts: readonly string[]): EgressScope;
+/**
+ * Builds an {@link EgressDependency} from a contributor's input: every entry of
+ * `hosts` is reduced to its hostname ({@link hostnameOf}; empty and unparsable
+ * ones are dropped), de-duplicated in order, capped at {@link EGRESS_MAX_HOSTS},
+ * and `scope` is computed with {@link scopeOfHosts}. This is the one way a
+ * contributor should build an entry: it guarantees no URL path, query, port or
+ * userinfo leaves `describe()`.
+ *
+ * @param input - the dependency, with raw `hosts`.
+ * @returns the normalised dependency.
+ *
+ * @example
+ * ```ts
+ * egressDependency({ id: 'email.smtp', capability: 'Email (SMTP)', direction: 'server',
+ *   enabled: true, required: false, hosts: ['smtp.corp.internal'], degradation: 'No email is sent' });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare function egressDependency(input: EgressDependencyInput): EgressDependency;
+//# sourceMappingURL=classify-host.d.ts.map

package/dist/doctor/egress/classify-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify-host.d.ts","sourceRoot":"","sources":["../../../src/doctor/egress/classify-host.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAoD3F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CA8B1E;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,CAYzE;AAID;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,CAKlE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,gBAAgB,CAQ/E"}