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

package/dist/telemetry/testing/conformance.d.ts

@@ -0,0 +1,257 @@
+import { type Type } from '@nestjs/common';
+import type { NestFastifyApplication } from '@nestjs/platform-fastify';
+import type { ConformanceFinding, ConformanceSuite } from '../../testing/index';
+import { type MetricGroupDef } from '../metrics/metric-group.registry';
+import { type StubTelemetryPortsOptions } from './stub-ports';
+declare module '../../testing/index' {
+    interface PlatformConformanceSuiteOptions {
+        /** The telemetry slice's suite: its options, or `false` to opt out. Registered by importing `@marinoscar/platform-api/telemetry/testing`. */
+        telemetry?: TelemetryConformanceOptions | false;
+    }
+}
+/**
+ * What an app passes as `suites.telemetry` to `runPlatformConformance()`. Both
+ * options are optional: without them the suite checks every metric group in
+ * `metricGroupRegistry` and skips the cron coverage.
+ *
+ * @example
+ * ```ts
+ * import '../../src/platform/telemetry/telemetry.config'; // registers the app's metric groups
+ * runPlatformConformance({
+ *   sourceRoots: [join(__dirname, '../../src')],
+ *   suites: { telemetry: { cronSourceRoots: CRON_SOURCE_ROOTS } },
+ * });
+ * ```
+ *
+ * @stability experimental
+ */
+export interface TelemetryConformanceOptions {
+    /**
+     * The metric groups to check. Default: every group in `metricGroupRegistry`
+     * (the platform's six plus whatever the app registered when its module
+     * code ran: import the module that calls `TelemetryModule.forRoot` first).
+     */
+    metricGroups?: readonly MetricGroupDef[];
+    /**
+     * The roots the app's `cron-enqueue-only` suite scans. When given, the
+     * telemetry retention cron (`tasks/telemetry-retention.task.ts`) must be
+     * inside them, so the queue rule is enforced on the slice's own cron.
+     */
+    cronSourceRoots?: readonly string[];
+}
+/**
+ * Check 1, static half: every group has a unique id matching
+ * {@link METRIC_GROUP_ID_PATTERN} and a non-empty label; family, ratio and table
+ * keys are unique across groups; every unit is in `METRIC_UNITS`; every filter
+ * key is a `METRIC_FILTER_COLUMNS` key; every entry names the group that holds it.
+ *
+ * @param groups - the groups to check.
+ * @returns the violations; empty means conformant.
+ *
+ * @stability experimental
+ */
+export declare function checkMetricGroups(groups: readonly MetricGroupDef[]): ConformanceFinding[];
+/**
+ * The part of a computed group {@link checkMetricGroupsOnEmptySchema} reads.
+ *
+ * @stability experimental
+ */
+export interface ComputedMetricGroup {
+    /** Whether any family of the group has data. */
+    available: boolean;
+    /** The rendered tiles. */
+    tiles: readonly unknown[];
+    /** The rendered series. */
+    series: readonly unknown[];
+    /** The rendered tables. */
+    tables: readonly unknown[];
+    /** The keys of the families, ratios and tables that were skipped. */
+    skipped: readonly string[];
+}
+/**
+ * What {@link checkMetricGroupsOnEmptySchema} runs per group; `computeMetricGroup` by default.
+ *
+ * @stability experimental
+ */
+export type ComputeMetricGroup = (group: string) => Promise<ComputedMetricGroup>;
+/**
+ * Check 1, dynamic half: every group computes against an EMPTY schema (the
+ * store has no metric table) without throwing, reporting everything in
+ * `skipped` and nothing as a tile, series or table. A group that errors, or one
+ * that renders a number out of nothing, would break the dashboard of a fresh stack.
+ *
+ * @param groups - the groups; each must be registered in `metricGroupRegistry` (the computation reads it).
+ * @param compute - what runs one group; default `computeMetricGroup` with an empty schema. A test passes a broken one.
+ * @returns the violations; empty means conformant.
+ *
+ * @stability experimental
+ */
+export declare function checkMetricGroupsOnEmptySchema(groups: readonly MetricGroupDef[], compute?: ComputeMetricGroup): Promise<ConformanceFinding[]>;
+/**
+ * One route of a controller, read from the Nest metadata.
+ *
+ * @stability experimental
+ */
+export interface TelemetryRoute {
+    /** The HTTP method (`GET`, `PUT`, ...). */
+    method: string;
+    /** The path without leading or trailing slash, controller prefix included. */
+    path: string;
+    /** The permissions its access decorator recorded, or `undefined` when it has none (a public route). */
+    permissions: readonly string[] | undefined;
+    /** The guard classes on the handler and its controller. */
+    guards: readonly unknown[];
+    /** The handler function, for reading further metadata (a route's documented query parameters). */
+    handler: unknown;
+}
+/**
+ * Every route of `controllers`, from `@Controller`/`@Get`/... metadata and the
+ * permissions recorded by the package's test host (`createTestPlatformHost`).
+ *
+ * @param controllers - controller classes, e.g. `TelemetryModule.forRoot(...).controllers`.
+ * @returns the routes, in declaration order.
+ *
+ * @stability experimental
+ */
+export declare function discoverRoutes(controllers: readonly Type<unknown>[]): TelemetryRoute[];
+/**
+ * Check 2: every route under `admin/telemetry` and `telemetry` declares exactly
+ * the permissions its shape requires (the table in the slice README, heading
+ * "Permissions and settings"), every permission is one of the slice's exact
+ * strings, no route is public, the assistant route sits behind the AI-enabled
+ * guard, and every rule matches at least one route (a renamed route fails here
+ * rather than silently dropping out of the check).
+ *
+ * @param routes - the routes, from {@link discoverRoutes}.
+ * @returns the violations; empty means conformant.
+ *
+ * @stability experimental
+ */
+export declare function checkRoutePermissions(routes: readonly TelemetryRoute[]): ConformanceFinding[];
+/**
+ * The providers that register themselves as Doctor checks: classes with a
+ * `run` method whose constructor injects the `DoctorCheckRegistry`.
+ *
+ * @param providers - a module's provider list, e.g. `TelemetryModule.forRoot(...).providers`.
+ * @returns the check classes.
+ *
+ * @stability experimental
+ */
+export declare function discoverDoctorChecks(providers: readonly unknown[]): Array<Type<unknown>>;
+/**
+ * Check 3: no Doctor check of the slice injects the audited connection test,
+ * the audited dashboard service, the audit sink or the jobs port. The check
+ * reads the constructor's `design:paramtypes` and `@Inject` tokens
+ * (`self:paramtypes`).
+ *
+ * @param checks - the check classes, from {@link discoverDoctorChecks}.
+ * @returns the violations; empty means conformant.
+ *
+ * @stability experimental
+ */
+export declare function checkDoctorReadOnly(checks: readonly Type<unknown>[]): ConformanceFinding[];
+/**
+ * The slice's cron, relative to its source root.
+ *
+ * @stability experimental
+ */
+export declare const TELEMETRY_CRON_FILE = "tasks/telemetry-retention.task.ts";
+/**
+ * Check 5: the app's `cron-enqueue-only` scan roots hold the slice's retention
+ * cron, so the queue rule ("a `@Cron` only enqueues") is enforced on it. Runs
+ * the cron suite's own scan over `roots` and looks for the file.
+ *
+ * @param roots - the roots the app's cron suite scans.
+ * @returns the violations; empty means conformant.
+ *
+ * @stability experimental
+ */
+export declare function checkCronCoverage(roots: readonly string[]): ConformanceFinding[];
+/**
+ * Boots the telemetry module on Fastify with the stub ports, for checks 4 and 6.
+ *
+ * @stability experimental
+ */
+export interface StubAppInput {
+    /** What the credential and settings stores hold. */
+    ports?: StubTelemetryPortsOptions;
+    /** The `greptime` configuration namespace (the deployment default), or none. */
+    greptime?: Record<string, unknown>;
+}
+/**
+ * Builds the app a booted check talks to; the default is {@link bootStubApp}.
+ *
+ * @stability experimental
+ */
+export type CreateConformanceApp = (input: StubAppInput) => Promise<NestFastifyApplication>;
+/**
+ * Boots `TelemetryModule.forRoot` with the stub ports, the package's test host,
+ * the Doctor module and an `OTEL_ENABLED=false` configuration. Nothing listens
+ * on a port; requests go through Fastify's `inject`.
+ *
+ * @param input - what the stubs and the configuration hold.
+ * @returns the initialised application; the caller closes it.
+ *
+ * @stability experimental
+ */
+export declare const bootStubApp: CreateConformanceApp;
+/**
+ * The four passwords check 4 seeds.
+ *
+ * @stability experimental
+ */
+export interface ConformanceSecrets {
+    /** The reader password in the credential store. */
+    readonly storedReader: string;
+    /** The admin password in the credential store. */
+    readonly storedAdmin: string;
+    /** The reader password in the `greptime` deployment default. */
+    readonly environmentReader: string;
+    /** The admin password in the `greptime` deployment default. */
+    readonly environmentAdmin: string;
+}
+/**
+ * The passwords check 4 seeds. Distinctive on purpose: a substring match can
+ * only be the secret.
+ *
+ * @stability experimental
+ */
+export declare const CONFORMANCE_SECRETS: ConformanceSecrets;
+/**
+ * Check 4: `GET /admin/telemetry/connection` and `GET /admin/telemetry/config`
+ * never carry a stored password. Boots the module with known passwords in the
+ * credential store (and in the `greptime` deployment default), a stored custom
+ * connection row, and asserts none of the four appears in the serialised
+ * responses. `TELEMETRY_CONNECTION_CARRIES_NO_SECRET` (the contract's
+ * compile-time proof that the connection type has no field able to hold one)
+ * must still be `true`.
+ *
+ * @param createApp - builds the app; default {@link bootStubApp}. A test passes a leaky one.
+ * @returns the violations; empty means conformant.
+ *
+ * @stability experimental
+ */
+export declare function checkNoSecretsInResponses(createApp?: CreateConformanceApp): Promise<ConformanceFinding[]>;
+/**
+ * Check 6: `TelemetryModule.forRoot` boots with `OTEL_ENABLED=false`, no
+ * GreptimeDB and an empty configuration, and every dashboard route answers
+ * with its documented response: `200` (a route that reads only memory) or `503`
+ * with `details.reason` `TELEMETRY_NOT_CONFIGURED`. Never a `500`.
+ *
+ * @param createApp - builds the app; default {@link bootStubApp}.
+ * @returns the violations; empty means conformant.
+ *
+ * @stability experimental
+ */
+export declare function checkBootsWithoutTelemetry(createApp?: CreateConformanceApp): Promise<ConformanceFinding[]>;
+/**
+ * The suite behind `runPlatformConformance({ suites: { telemetry } })`: the
+ * telemetry slice's invariants 1 to 6 (see this file's header). Registered in
+ * {@link conformanceSuites} when `@marinoscar/platform-api/telemetry/testing`
+ * is imported.
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare const telemetryConformanceSuite: ConformanceSuite<TelemetryConformanceOptions>;
+//# sourceMappingURL=conformance.d.ts.map

package/dist/telemetry/testing/conformance.d.ts.map

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