@spinajs/telemetry 2.0.482

package/lib/mjs/controllers/Metrics.js

@@ -0,0 +1,60 @@
+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);
+};
+import { BasePath, BaseController, Get, Policy } from '@spinajs/http';
+import { Autoinject } from '@spinajs/di';
+import { Metrics } from './../metrics.js';
+import { PrometheusResponse } from './../responses.js';
+// Importing the policy modules runs their @Injectable decorators, which is what
+// puts the classes in the DI container under the names the routes below name as
+// STRINGS ( via `telemetry.auth.policies.*` ). Nothing else forces them to load:
+// this controller is mounted by the config-declared directory scan, and that
+// configuration is auto-discovered from node_modules — so an app never has to
+// import the package barrel. And http FAILS OPEN on an unresolvable policy name
+// ( it logs `No policy named ...`, drops it, and a route left with no policies
+// calls next() ), which would serve /metrics unauthenticated.
+import './../policies/TelemetryTokenPolicy.js';
+import './../policies/PublicPolicy.js';
+/**
+ * Prometheus scrape endpoint.
+ *
+ * Deliberately kept at the bare `/metrics` path rather than under the
+ * `/telemetry` prefix used by the JSON api — this is the path existing
+ * `scrape_configs` already point at.
+ */
+let MetricsController = class MetricsController extends BaseController {
+    /**
+     * Prometheus exposition text for every metric on the registry: the `http_*`
+     * request metrics, the `perf_*` bridge metrics, any application metrics
+     * declared through `Metrics.defineMetrics`, and — when
+     * `telemetry.collectDefaultMetrics` is on — the `process_*` / `nodejs_*` set.
+     *
+     * @response 200 {string} Prometheus exposition text ( text/plain )
+     * @response 403 Access token missing or invalid
+     */
+    async getMetrics() {
+        return new PrometheusResponse(this.MetricsService);
+    }
+};
+__decorate([
+    Autoinject(Metrics),
+    __metadata("design:type", Metrics)
+], MetricsController.prototype, "MetricsService", void 0);
+__decorate([
+    Get('/'),
+    Policy('telemetry.auth.policies.metrics'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], MetricsController.prototype, "getMetrics", null);
+MetricsController = __decorate([
+    BasePath('metrics')
+], MetricsController);
+export { MetricsController };
+//# sourceMappingURL=Metrics.js.map

package/lib/mjs/controllers/Metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Metrics.js","sourceRoot":"","sources":["../../../src/controllers/Metrics.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,gFAAgF;AAChF,gFAAgF;AAChF,iFAAiF;AACjF,6EAA6E;AAC7E,8EAA8E;AAC9E,gFAAgF;AAChF,+EAA+E;AAC/E,8DAA8D;AAC9D,OAAO,uCAAuC,CAAC;AAC/C,OAAO,+BAA+B,CAAC;AAEvC;;;;;;GAMG;AAEI,IAAM,iBAAiB,GAAvB,MAAM,iBAAkB,SAAQ,cAAc;IAInD;;;;;;;;OAQG;IAGU,AAAN,KAAK,CAAC,UAAU;QACrB,OAAO,IAAI,kBAAkB,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IACrD,CAAC;CACF,CAAA;AAhBW;IADT,UAAU,CAAC,OAAO,CAAC;8BACM,OAAO;yDAAC;AAarB;IAFZ,GAAG,CAAC,GAAG,CAAC;IACR,MAAM,CAAC,iCAAiC,CAAC;;;;mDAGzC;AAjBU,iBAAiB;IAD7B,QAAQ,CAAC,SAAS,CAAC;GACP,iBAAiB,CAkB7B"}

package/lib/mjs/controllers/Telemetry.d.ts

@@ -0,0 +1,92 @@
+import { BaseController, Ok } from '@spinajs/http';
+import { TelemetryStore } from './../store.js';
+import { InMemoryPerfSink } from './../InMemoryPerfSink.js';
+import { HealthCheckRunner } from './../health.js';
+import { ServiceUnavailable } from './../responses.js';
+import './../dto/index.js';
+import './../policies/TelemetryTokenPolicy.js';
+import './../policies/PublicPolicy.js';
+/**
+ * JSON telemetry API. Machine-facing — consumed by dashboards, uptime monitors
+ * and orchestrator probes.
+ *
+ * The prometheus scrape endpoint deliberately lives on its own controller at
+ * the bare `/metrics` path, not under this prefix.
+ */
+export declare class TelemetryController extends BaseController {
+    protected Store: TelemetryStore;
+    protected PerfSink: InMemoryPerfSink;
+    protected Health: HealthCheckRunner;
+    protected Version: string;
+    /**
+     * Lifetime request statistics plus the rolling timeline.
+     *
+     * @returns {StatsResponse} Lifetime stats and the per-bucket timeline
+     * @response 403 Access token missing or invalid
+     */
+    getStats(): Promise<Ok<{
+        all: import("../requestStats.js").IRequestStatsSnapshot;
+        timeline: import("../timeline.js").ITimelineSnapshot;
+    }>>;
+    /**
+     * The rolling timeline alone, with each bucket annotated with the wall-clock
+     * window it covers so consumers do not have to reverse the bucket key.
+     *
+     * @param buckets - how many of the most recent buckets to return; all of them when omitted
+     * @returns {TimelineResponse} The annotated timeline
+     * @response 400 `buckets` was not a positive integer
+     * @response 403 Access token missing or invalid
+     */
+    getTimeline(buckets?: string): Promise<Ok<{
+        bucketMs: number;
+        length: number;
+        buckets: {
+            key: number;
+            from: number;
+            to: number;
+            stats: import("../requestStats.js").IRequestStatsSnapshot;
+        }[];
+    }>>;
+    /**
+     * Per method+route request breakdown.
+     *
+     * No percentiles — query them from prometheus against the `route`-labelled
+     * `http_request_duration_ms` histogram, which carries the same label values.
+     *
+     * @returns {RoutesResponse} Per-route request statistics
+     * @response 403 Access token missing or invalid
+     */
+    getRoutes(): Promise<Ok<import("../routeStats.js").IRouteStatsSnapshot>>;
+    /**
+     * Aggregated performance measurements collected through the `Perf` facade —
+     * every `Perf.measure`, `@Measure`, `Perf.count` and `Perf.value` in the
+     * process, including the ORM's `orm.query` spans.
+     *
+     * @returns {PerfResponse} Aggregated spans and events
+     * @response 403 Access token missing or invalid
+     */
+    getPerf(): Promise<Ok<import("./../InMemoryPerfSink.js").IPerfSnapshot>>;
+    /**
+     * Liveness. Runs no checks, so it can never be made slow or flaky by a
+     * dependency — if this answers, the process is alive.
+     *
+     * @returns {HealthResponse} Process liveness information
+     */
+    getHealth(): Promise<Ok<{
+        version?: string | undefined;
+        status: string;
+        startedAt: number;
+        uptimeMs: number;
+        pid: number;
+        node: string;
+    }>>;
+    /**
+     * Readiness. Runs every registered `HealthCheck`, each raced against
+     * `telemetry.health.timeoutMs`.
+     *
+     * @returns {ReadyResponse} Overall readiness and the per-check results
+     * @response 503 At least one check is down ( or degraded, when `telemetry.health.failOnDegraded` is set )
+     */
+    getReady(): Promise<ServiceUnavailable<import("./../health.js").IReadyReport> | Ok<import("./../health.js").IReadyReport>>;
+}
+//# sourceMappingURL=Telemetry.d.ts.map

package/lib/mjs/controllers/Telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Telemetry.d.ts","sourceRoot":"","sources":["../../../src/controllers/Telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,cAAc,EAAsB,EAAE,EAAE,MAAM,eAAe,CAAC;AAKjF,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAIvD,OAAO,mBAAmB,CAAC;AAW3B,OAAO,uCAAuC,CAAC;AAC/C,OAAO,+BAA+B,CAAC;AAEvC;;;;;;GAMG;AACH,qBACa,mBAAoB,SAAQ,cAAc;IAErD,SAAS,CAAC,KAAK,EAAE,cAAc,CAAC;IAGhC,SAAS,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IAGrC,SAAS,CAAC,MAAM,EAAE,iBAAiB,CAAC;IAGpC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC;IAE1B;;;;;OAKG;IAGU,QAAQ;;;;IAarB;;;;;;;;OAQG;IAGU,WAAW,CAAU,OAAO,CAAC,EAAE,MAAM;;;;;;;;;;IA0ClD;;;;;;;;OAQG;IAGU,SAAS;IAItB;;;;;;;OAOG;IAGU,OAAO;IAIpB;;;;;OAKG;IAGU,SAAS;;;;;;;;IAetB;;;;;;OAMG;IAGU,QAAQ;CAStB"}

package/lib/mjs/controllers/Telemetry.js

@@ -0,0 +1,223 @@
+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); }
+};
+import { BasePath, BaseController, Get, Policy, Query, Ok } from '@spinajs/http';
+import { Autoinject } from '@spinajs/di';
+import { Config } from '@spinajs/configuration';
+import { BadRequest } from '@spinajs/exceptions';
+import { TelemetryStore } from './../store.js';
+import { InMemoryPerfSink } from './../InMemoryPerfSink.js';
+import { HealthCheckRunner } from './../health.js';
+import { ServiceUnavailable } from './../responses.js';
+// Importing the DTO barrel runs the @Schema decorators, which is what makes the
+// response schemas resolvable by name in the generated OpenAPI document.
+import './../dto/index.js';
+// Same reason, for security rather than documentation: importing the policy
+// modules runs their @Injectable decorators, which is what puts the classes in
+// the DI container under the names the routes below name as STRINGS ( via
+// `telemetry.auth.policies.*` ). Nothing else forces them to load — this
+// controller is mounted by the config-declared directory scan, and that
+// configuration is auto-discovered from node_modules, so an app never has to
+// import the package barrel. And http FAILS OPEN on an unresolvable policy name
+// ( it logs `No policy named ...`, drops it, and a route left with no policies
+// calls next() ), which would serve these endpoints unauthenticated.
+import './../policies/TelemetryTokenPolicy.js';
+import './../policies/PublicPolicy.js';
+/**
+ * JSON telemetry API. Machine-facing — consumed by dashboards, uptime monitors
+ * and orchestrator probes.
+ *
+ * The prometheus scrape endpoint deliberately lives on its own controller at
+ * the bare `/metrics` path, not under this prefix.
+ */
+let TelemetryController = class TelemetryController extends BaseController {
+    /**
+     * Lifetime request statistics plus the rolling timeline.
+     *
+     * @returns {StatsResponse} Lifetime stats and the per-bucket timeline
+     * @response 403 Access token missing or invalid
+     */
+    async getStats() {
+        const stats = this.Store.RequestStats;
+        // Rates are not maintained on the hot path — they are derived here, over the
+        // whole collection window, or `req_rate` / `err_rate` would always read 0.
+        stats.updateRates(Date.now() - this.Store.StartedAt);
+        return new Ok({
+            all: stats.toJSON(),
+            timeline: this.Store.Timeline.toJSON(),
+        });
+    }
+    /**
+     * The rolling timeline alone, with each bucket annotated with the wall-clock
+     * window it covers so consumers do not have to reverse the bucket key.
+     *
+     * @param buckets - how many of the most recent buckets to return; all of them when omitted
+     * @returns {TimelineResponse} The annotated timeline
+     * @response 400 `buckets` was not a positive integer
+     * @response 403 Access token missing or invalid
+     */
+    async getTimeline(buckets) {
+        const timeline = this.Store.Timeline;
+        const snapshot = timeline.toJSON();
+        let keys = Object.keys(snapshot)
+            .map((k) => Number(k))
+            .sort((a, b) => a - b);
+        // Only a genuinely ABSENT `buckets` means "all of them". An explicitly empty
+        // `?buckets=` is a supplied value that is not a positive integer, so it is
+        // rejected like every other invalid one rather than silently meaning "all".
+        if (buckets !== undefined && buckets !== null) {
+            // Taken as a string and parsed here rather than declared `number` and left
+            // to the decorator's schema: a query value arrives as a string, and how the
+            // framework coerces a non-numeric one ( `Number( 'abc' )` -> NaN, rejected
+            // by the arg validator with a generic message ) is not something this
+            // endpoint's contract should depend on.
+            //
+            // `Number( '' )` is 0, not NaN, so the empty string falls through to the
+            // `count < 1` rejection below on its own.
+            const count = Number(buckets);
+            if (!Number.isInteger(count) || count < 1) {
+                throw new BadRequest('buckets must be a positive integer');
+            }
+            // The most recent N — the tail of an ascending key order.
+            keys = keys.slice(-count);
+        }
+        return new Ok({
+            bucketMs: timeline.bucketMs,
+            length: timeline.length,
+            buckets: keys.map((key) => ({
+                key,
+                from: key * timeline.bucketMs,
+                to: (key + 1) * timeline.bucketMs,
+                stats: snapshot[String(key)],
+            })),
+        });
+    }
+    /**
+     * Per method+route request breakdown.
+     *
+     * No percentiles — query them from prometheus against the `route`-labelled
+     * `http_request_duration_ms` histogram, which carries the same label values.
+     *
+     * @returns {RoutesResponse} Per-route request statistics
+     * @response 403 Access token missing or invalid
+     */
+    async getRoutes() {
+        return new Ok(this.Store.RouteStats.toJSON());
+    }
+    /**
+     * Aggregated performance measurements collected through the `Perf` facade —
+     * every `Perf.measure`, `@Measure`, `Perf.count` and `Perf.value` in the
+     * process, including the ORM's `orm.query` spans.
+     *
+     * @returns {PerfResponse} Aggregated spans and events
+     * @response 403 Access token missing or invalid
+     */
+    async getPerf() {
+        return new Ok(this.PerfSink.toJSON());
+    }
+    /**
+     * Liveness. Runs no checks, so it can never be made slow or flaky by a
+     * dependency — if this answers, the process is alive.
+     *
+     * @returns {HealthResponse} Process liveness information
+     */
+    async getHealth() {
+        const uptimeMs = Math.round(process.uptime() * 1000);
+        return new Ok({
+            status: 'up',
+            startedAt: Date.now() - uptimeMs,
+            uptimeMs,
+            pid: process.pid,
+            node: process.version,
+            // omitted rather than reported as null when `telemetry.health.version` is unset
+            ...(this.Version ? { version: this.Version } : {}),
+        });
+    }
+    /**
+     * Readiness. Runs every registered `HealthCheck`, each raced against
+     * `telemetry.health.timeoutMs`.
+     *
+     * @returns {ReadyResponse} Overall readiness and the per-check results
+     * @response 503 At least one check is down ( or degraded, when `telemetry.health.failOnDegraded` is set )
+     */
+    async getReady() {
+        const report = await this.Health.run();
+        if (this.Health.isFailing(report.status)) {
+            return new ServiceUnavailable(report);
+        }
+        return new Ok(report);
+    }
+};
+__decorate([
+    Autoinject(TelemetryStore),
+    __metadata("design:type", TelemetryStore)
+], TelemetryController.prototype, "Store", void 0);
+__decorate([
+    Autoinject(InMemoryPerfSink),
+    __metadata("design:type", InMemoryPerfSink)
+], TelemetryController.prototype, "PerfSink", void 0);
+__decorate([
+    Autoinject(HealthCheckRunner),
+    __metadata("design:type", HealthCheckRunner)
+], TelemetryController.prototype, "Health", void 0);
+__decorate([
+    Config('telemetry.health.version'),
+    __metadata("design:type", String)
+], TelemetryController.prototype, "Version", void 0);
+__decorate([
+    Get('stats'),
+    Policy('telemetry.auth.policies.stats'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], TelemetryController.prototype, "getStats", null);
+__decorate([
+    Get('timeline'),
+    Policy('telemetry.auth.policies.timeline'),
+    __param(0, Query()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], TelemetryController.prototype, "getTimeline", null);
+__decorate([
+    Get('routes'),
+    Policy('telemetry.auth.policies.routes'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], TelemetryController.prototype, "getRoutes", null);
+__decorate([
+    Get('perf'),
+    Policy('telemetry.auth.policies.perf'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], TelemetryController.prototype, "getPerf", null);
+__decorate([
+    Get('health'),
+    Policy('telemetry.auth.policies.health'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], TelemetryController.prototype, "getHealth", null);
+__decorate([
+    Get('ready'),
+    Policy('telemetry.auth.policies.ready'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], TelemetryController.prototype, "getReady", null);
+TelemetryController = __decorate([
+    BasePath('telemetry')
+], TelemetryController);
+export { TelemetryController };
+//# sourceMappingURL=Telemetry.js.map

package/lib/mjs/controllers/Telemetry.js.map

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

package/lib/mjs/dto/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Response shapes for the telemetry endpoints.
+ *
+ * These classes are never instantiated — they exist so `@Schema` registers each
+ * JSON schema under the class name, which is how http-swagger resolves a
+ * `@returns {StatsResponse}` JSDoc tag into a `#/components/schemas/...`
+ * component. The controller imports this module so the decorators run.
+ */
+export declare class StatsResponse {
+}
+export declare class TimelineResponse {
+}
+export declare class RoutesResponse {
+}
+export declare class PerfResponse {
+}
+export declare class HealthResponse {
+}
+export declare class ReadyResponse {
+}
+//# sourceMappingURL=index.d.ts.map

package/lib/mjs/dto/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/dto/index.ts"],"names":[],"mappings":"AASA;;;;;;;GAOG;AAEH,qBACa,aAAa;CAAG;AAE7B,qBACa,gBAAgB;CAAG;AAEhC,qBACa,cAAc;CAAG;AAE9B,qBACa,YAAY;CAAG;AAE5B,qBACa,cAAc;CAAG;AAE9B,qBACa,aAAa;CAAG"}

package/lib/mjs/dto/index.js

@@ -0,0 +1,58 @@
+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;
+};
+import { Schema } from '@spinajs/validation';
+import StatsResponseSchema from './../schemas/StatsResponse.schema.js';
+import TimelineResponseSchema from './../schemas/TimelineResponse.schema.js';
+import RoutesResponseSchema from './../schemas/RoutesResponse.schema.js';
+import PerfResponseSchema from './../schemas/PerfResponse.schema.js';
+import HealthResponseSchema from './../schemas/HealthResponse.schema.js';
+import ReadyResponseSchema from './../schemas/ReadyResponse.schema.js';
+/**
+ * Response shapes for the telemetry endpoints.
+ *
+ * These classes are never instantiated — they exist so `@Schema` registers each
+ * JSON schema under the class name, which is how http-swagger resolves a
+ * `@returns {StatsResponse}` JSDoc tag into a `#/components/schemas/...`
+ * component. The controller imports this module so the decorators run.
+ */
+let StatsResponse = class StatsResponse {
+};
+StatsResponse = __decorate([
+    Schema(StatsResponseSchema)
+], StatsResponse);
+export { StatsResponse };
+let TimelineResponse = class TimelineResponse {
+};
+TimelineResponse = __decorate([
+    Schema(TimelineResponseSchema)
+], TimelineResponse);
+export { TimelineResponse };
+let RoutesResponse = class RoutesResponse {
+};
+RoutesResponse = __decorate([
+    Schema(RoutesResponseSchema)
+], RoutesResponse);
+export { RoutesResponse };
+let PerfResponse = class PerfResponse {
+};
+PerfResponse = __decorate([
+    Schema(PerfResponseSchema)
+], PerfResponse);
+export { PerfResponse };
+let HealthResponse = class HealthResponse {
+};
+HealthResponse = __decorate([
+    Schema(HealthResponseSchema)
+], HealthResponse);
+export { HealthResponse };
+let ReadyResponse = class ReadyResponse {
+};
+ReadyResponse = __decorate([
+    Schema(ReadyResponseSchema)
+], ReadyResponse);
+export { ReadyResponse };
+//# sourceMappingURL=index.js.map

package/lib/mjs/dto/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/dto/index.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C,OAAO,mBAAmB,MAAM,sCAAsC,CAAC;AACvE,OAAO,sBAAsB,MAAM,yCAAyC,CAAC;AAC7E,OAAO,oBAAoB,MAAM,uCAAuC,CAAC;AACzE,OAAO,kBAAkB,MAAM,qCAAqC,CAAC;AACrE,OAAO,oBAAoB,MAAM,uCAAuC,CAAC;AACzE,OAAO,mBAAmB,MAAM,sCAAsC,CAAC;AAEvE;;;;;;;GAOG;AAGI,IAAM,aAAa,GAAnB,MAAM,aAAa;CAAG,CAAA;AAAhB,aAAa;IADzB,MAAM,CAAC,mBAAmB,CAAC;GACf,aAAa,CAAG;;AAGtB,IAAM,gBAAgB,GAAtB,MAAM,gBAAgB;CAAG,CAAA;AAAnB,gBAAgB;IAD5B,MAAM,CAAC,sBAAsB,CAAC;GAClB,gBAAgB,CAAG;;AAGzB,IAAM,cAAc,GAApB,MAAM,cAAc;CAAG,CAAA;AAAjB,cAAc;IAD1B,MAAM,CAAC,oBAAoB,CAAC;GAChB,cAAc,CAAG;;AAGvB,IAAM,YAAY,GAAlB,MAAM,YAAY;CAAG,CAAA;AAAf,YAAY;IADxB,MAAM,CAAC,kBAAkB,CAAC;GACd,YAAY,CAAG;;AAGrB,IAAM,cAAc,GAApB,MAAM,cAAc;CAAG,CAAA;AAAjB,cAAc;IAD1B,MAAM,CAAC,oBAAoB,CAAC;GAChB,cAAc,CAAG;;AAGvB,IAAM,aAAa,GAAnB,MAAM,aAAa;CAAG,CAAA;AAAhB,aAAa;IADzB,MAAM,CAAC,mBAAmB,CAAC;GACf,aAAa,CAAG"}

package/lib/mjs/endpoints.d.ts

@@ -0,0 +1,32 @@
+import { Metrics } from './metrics.js';
+import { TelemetryStore } from './store.js';
+/**
+ * Minimal request/response shapes the endpoint handlers rely on. Kept
+ * intentionally structural ( `setHeader` / `end` ) so the handlers are not
+ * coupled to express beyond what a plain Node `ServerResponse` provides.
+ */
+export interface IMinimalResponse {
+    setHeader(name: string, value: string): void;
+    statusCode?: number;
+    end(body?: string): void;
+}
+export type MinimalRequest = unknown;
+/**
+ * Build the Prometheus `/metrics` scrape handler.
+ *
+ * Sets `Content-Type` from the registry and writes the ( async-rendered )
+ * exposition text.
+ */
+export declare function metricsHandler(metrics: Metrics): (req: MinimalRequest, res: IMinimalResponse) => Promise<void>;
+/**
+ * Build the JSON stats handler.
+ *
+ * Writes `{ all: RequestStats.toJSON(), timeline: Timeline.toJSON() }` read
+ * from the shared telemetry store — the same counters `GET /telemetry/stats`
+ * serves. The rate fields differ though: only the controller endpoint calls
+ * `RequestStats.updateRates( ... )`, and because that MUTATES the shared
+ * `RequestStats`, the `req_rate` / `err_rate` this handler emits are whatever
+ * the last `/telemetry/stats` call left behind ( `0` if nobody has called it ).
+ */
+export declare function statsHandler(store: TelemetryStore): (req: MinimalRequest, res: IMinimalResponse) => void;
+//# sourceMappingURL=endpoints.d.ts.map

package/lib/mjs/endpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoints.d.ts","sourceRoot":"","sources":["../../src/endpoints.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC;AAErC;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAM9G;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,gBAAgB,KAAK,IAAI,CASxG"}

package/lib/mjs/endpoints.js

@@ -0,0 +1,34 @@
+/**
+ * Build the Prometheus `/metrics` scrape handler.
+ *
+ * Sets `Content-Type` from the registry and writes the ( async-rendered )
+ * exposition text.
+ */
+export function metricsHandler(metrics) {
+    return async (_req, res) => {
+        const body = await metrics.render();
+        res.setHeader('Content-Type', metrics.contentType());
+        res.end(body);
+    };
+}
+/**
+ * Build the JSON stats handler.
+ *
+ * Writes `{ all: RequestStats.toJSON(), timeline: Timeline.toJSON() }` read
+ * from the shared telemetry store — the same counters `GET /telemetry/stats`
+ * serves. The rate fields differ though: only the controller endpoint calls
+ * `RequestStats.updateRates( ... )`, and because that MUTATES the shared
+ * `RequestStats`, the `req_rate` / `err_rate` this handler emits are whatever
+ * the last `/telemetry/stats` call left behind ( `0` if nobody has called it ).
+ */
+export function statsHandler(store) {
+    return (_req, res) => {
+        const body = JSON.stringify({
+            all: store.RequestStats.toJSON(),
+            timeline: store.Timeline.toJSON(),
+        });
+        res.setHeader('Content-Type', 'application/json');
+        res.end(body);
+    };
+}
+//# sourceMappingURL=endpoints.js.map

package/lib/mjs/endpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoints.js","sourceRoot":"","sources":["../../src/endpoints.ts"],"names":[],"mappings":"AAgBA;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB;IAC7C,OAAO,KAAK,EAAE,IAAoB,EAAE,GAAqB,EAAiB,EAAE;QAC1E,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC;QACpC,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;QACrD,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,KAAqB;IAChD,OAAO,CAAC,IAAoB,EAAE,GAAqB,EAAQ,EAAE;QAC3D,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;YAC1B,GAAG,EAAE,KAAK,CAAC,YAAY,CAAC,MAAM,EAAE;YAChC,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE;SAClC,CAAC,CAAC;QACH,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,kBAAkB,CAAC,CAAC;QAClD,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}

package/lib/mjs/health.d.ts

@@ -0,0 +1,55 @@
+import { AsyncService } from '@spinajs/di';
+/** Outcome of a single health check. */
+export type HealthStatus = 'up' | 'degraded' | 'down';
+/** What a {@link HealthCheck} returns. */
+export interface IHealthResult {
+    status: HealthStatus;
+    message?: string;
+    data?: Record<string, unknown>;
+}
+/** One check's line in the readiness report. */
+export interface IHealthCheckReport extends IHealthResult {
+    name: string;
+    /** How long the check took, in ms. */
+    durationMs: number;
+}
+/** The body served by `GET /telemetry/ready`. */
+export interface IReadyReport {
+    status: HealthStatus;
+    checks: IHealthCheckReport[];
+}
+/**
+ * A readiness probe for one dependency.
+ *
+ * Register a concrete subclass with `@Injectable( HealthCheck )` and it is
+ * discovered by {@link HealthCheckRunner} via `Array.ofType( HealthCheck )`.
+ * `@spinajs/telemetry` deliberately ships NO concrete checks — a database check
+ * belongs where the database dependency already is, not in the observability
+ * package.
+ *
+ * `check()` may throw; a throw counts as `down`.
+ */
+export declare abstract class HealthCheck extends AsyncService {
+    /** Stable identifier for this check, used as the report key. */
+    abstract Name: string;
+    abstract check(): Promise<IHealthResult>;
+}
+/**
+ * Runs every registered {@link HealthCheck} concurrently, each raced against a
+ * per-check timeout, and reduces the results to one overall status.
+ *
+ * The timeout is the point of the class: a readiness endpoint that can hang is
+ * worse than no readiness endpoint, because a kubelet probe blocks on it.
+ */
+export declare class HealthCheckRunner {
+    protected Checks: HealthCheck[];
+    protected TimeoutMs: number;
+    protected FailOnDegraded: boolean;
+    /**
+     * True when the overall status should be served as HTTP 503.
+     */
+    isFailing(status: HealthStatus): boolean;
+    run(): Promise<IReadyReport>;
+    private runOne;
+}
+//# sourceMappingURL=health.d.ts.map

package/lib/mjs/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/health.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAqC,MAAM,aAAa,CAAC;AAG9E,wCAAwC;AACxC,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,UAAU,GAAG,MAAM,CAAC;AAEtD,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,gDAAgD;AAChD,MAAM,WAAW,kBAAmB,SAAQ,aAAa;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,kBAAkB,EAAE,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,8BAAsB,WAAY,SAAQ,YAAY;IACpD,gEAAgE;IAChE,SAAgB,IAAI,EAAE,MAAM,CAAC;aAEb,KAAK,IAAI,OAAO,CAAC,aAAa,CAAC;CAChD;AAkBD;;;;;;GAMG;AACH,qBAEa,iBAAiB;IAE5B,SAAS,CAAC,MAAM,EAAG,WAAW,EAAE,CAAC;IAGjC,SAAS,CAAC,SAAS,EAAG,MAAM,CAAC;IAG7B,SAAS,CAAC,cAAc,EAAG,OAAO,CAAC;IAEnC;;OAEG;IACI,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO;IAKlC,GAAG,IAAI,OAAO,CAAC,YAAY,CAAC;YAe3B,MAAM;CAqBrB"}