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

package/dist/telemetry/connection/telemetry-connection.service.d.ts

@@ -0,0 +1,197 @@
+import { OnModuleDestroy, OnModuleInit } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { type TelemetryCredentialInfo as CredentialInfo, type TelemetryCredentialStore, type TelemetrySettingsStore } from '../ports';
+import { type TelemetryConnectionRole, type TelemetryConnectionValue } from './telemetry-connection.schema';
+/**
+ * What an administrator is told when the GreptimeDB deployed with this
+ * application lacks a login. Administrator language: no file, variable or
+ * command names — fixing it is an application update, not a form field.
+ */
+export declare const DEPLOYMENT_READER_MISSING_MESSAGE: string;
+export declare const DEPLOYMENT_ADMIN_MISSING_MESSAGE: string;
+/** How often every instance re-reads the stored connection. */
+export declare const TELEMETRY_CONNECTION_REFRESH_MS = 5000;
+/** `auto`: the host is the deployment host, resolved at refresh. `custom`: a literal someone chose. */
+export type TelemetryHostMode = 'auto' | 'custom';
+/** Where the resolved connection came from. */
+export type TelemetryConnectionSource = 'stored' | 'environment' | 'none';
+/** The `greptime` block of `config/configuration.ts` — the deployment default. */
+export interface GreptimeEnvironmentConfig {
+    host: string;
+    pgPort: number;
+    database: string;
+    readerUser: string;
+    readerPassword: string;
+    adminUser: string;
+    adminPassword: string;
+    available: boolean;
+}
+interface LoginSnapshot {
+    user: string;
+    passwordSet: boolean;
+    /** Changes whenever the password does. Part of the pool fingerprint. */
+    version: string | null;
+}
+/** The resolved connection, minus every secret. */
+export interface TelemetryConnectionSnapshot {
+    source: TelemetryConnectionSource;
+    /** The EFFECTIVE host — what a pool connects to. Empty when there is none (source `none`, or an unusable row). */
+    host: string;
+    /**
+     * `auto` when the host is the deployment host (a stored `host: null`, the
+     * environment source — `GREPTIME_HOST` is the deployment host — or no
+     * connection at all), `custom` when it is a literal an administrator stored.
+     */
+    hostMode: TelemetryHostMode;
+    /**
+     * The whole connection — port, database, logins and passwords — comes from
+     * the deployment (`GREPTIME_*`), not the admin page: source `environment`,
+     * or a stored automatic (null) host (issue #570). False for a custom host,
+     * an unusable row and `none`.
+     */
+    deploymentManaged: boolean;
+    pgPort: number;
+    database: string;
+    reader: LoginSnapshot;
+    /** Null when no admin login is configured. */
+    admin: LoginSnapshot | null;
+}
+/**
+ * The GreptimeDB deployed with this application, as the deployment describes
+ * it — what an automatic connection resolves to. Non-secret: whether each
+ * login is complete, never its password.
+ */
+export interface TelemetryDeploymentConnection {
+    host: string;
+    pgPort: number;
+    database: string;
+    readerUser: string;
+    adminUser: string | null;
+    /** A reader user and its password are both provisioned. */
+    readerConfigured: boolean;
+    /** An admin user and its password are both provisioned. */
+    adminConfigured: boolean;
+}
+/** What a pool is built from. Holds a plaintext password: use it and drop it. */
+export interface TelemetryConnectionCredentials {
+    host: string;
+    /** `host` is the deployment host of an automatic (null) host, not a literal override. */
+    automaticHost: boolean;
+    port: number;
+    database: string;
+    user: string;
+    password: string;
+    /** Identifies this exact connection; a pool built from it is stale once it differs. */
+    fingerprint: string;
+}
+/** A fresh read of everything the admin page shows. Non-secret. */
+export interface TelemetryConnectionState {
+    snapshot: TelemetryConnectionSnapshot;
+    /** The stored value, or null when nothing is stored (or it does not parse). */
+    stored: TelemetryConnectionValue | null;
+    /** The stored row's provenance, or null when there is no row. */
+    row: {
+        version: number;
+        updatedAt: Date;
+        updatedByUser: {
+            id: string;
+            email: string;
+        } | null;
+    } | null;
+    /** The credential store's view of both passwords (whatever the source). */
+    credentials: Record<TelemetryConnectionRole, CredentialInfo | null>;
+}
+export declare class TelemetryConnectionService implements OnModuleInit, OnModuleDestroy {
+    private readonly settingsStore;
+    private readonly credentials;
+    private readonly logger;
+    private readonly environment;
+    /**
+     * Seeded from the environment so the sync accessors have an answer before
+     * the first refresh (and so a unit test can build a client with no
+     * database). `onModuleInit` replaces it with the real resolution.
+     */
+    private snapshot;
+    private refreshTimer;
+    private refreshFailing;
+    private lastInvalidRowWarned;
+    constructor(configService: ConfigService, settingsStore: TelemetrySettingsStore, credentials: TelemetryCredentialStore);
+    /** One awaited refresh (never throws), then the interval. */
+    onModuleInit(): Promise<void>;
+    onModuleDestroy(): void;
+    /** Where the connection in force came from. */
+    get source(): TelemetryConnectionSource;
+    /**
+     * Where GreptimeDB is in this deployment: `GREPTIME_HOST` when non-blank,
+     * else `TELEMETRY_DEFAULT_HOST`. What an automatic (null) host resolves to.
+     */
+    get deploymentHost(): string;
+    /** The deployment's own GreptimeDB connection (non-secret), whatever is in force. */
+    describeDeployment(): TelemetryDeploymentConnection;
+    /**
+     * Why the connection in force cannot be used, in administrator language, or
+     * null. Only a deployment-managed connection has an answer here: its gaps
+     * are the deployment's, which nothing on the admin page can fill. `role`
+     * `admin` also reports a missing admin login (retention).
+     */
+    configurationProblem(role?: TelemetryConnectionRole): string | null;
+    /** The GreptimeDB database telemetry is written to. */
+    get database(): string;
+    /** A host, a reader login and its password — i.e. telemetry can be read. */
+    isConfigured(): boolean;
+    /** The admin login (retention, `SHOW CREATE DATABASE`) is usable as well. */
+    isAdminConfigured(): boolean;
+    /**
+     * An opaque identity of the connection a login would use right now, or
+     * null when that login is not configured. `GreptimeClient` keys its pools by
+     * it: a different answer means the pool it holds is stale.
+     */
+    fingerprint(role: TelemetryConnectionRole): string | null;
+    /** A copy of the snapshot. Non-secret. */
+    describeSnapshot(): TelemetryConnectionSnapshot;
+    /**
+     * The full connection for one login, password included, or null when that
+     * login is not configured (or its stored password has since gone).
+     *
+     * ⚠ Holds a plaintext password. Call it when building a pool and let the
+     * result go out of scope; never cache it, never log it.
+     */
+    resolveCredentials(role: TelemetryConnectionRole): Promise<TelemetryConnectionCredentials | null>;
+    /**
+     * The password the connection IN FORCE would use for this login — the
+     * deployment's when it is deployment-managed (the environment source, or a
+     * stored automatic host), the credential store's for a custom host, none
+     * when there is no connection. For the connection test's "blank means the
+     * current one".
+     *
+     * ⚠ Plaintext. Same rules as `resolveCredentials`.
+     */
+    currentPassword(role: TelemetryConnectionRole): Promise<string | null>;
+    /**
+     * The deployment's own password for this login (`GREPTIME_*`), or null when
+     * it provisions none. What an automatic connection uses — and the only
+     * password a connection test of an automatic host may use.
+     *
+     * ⚠ Plaintext. Same rules as `resolveCredentials`.
+     */
+    deploymentPassword(role: TelemetryConnectionRole): string | null;
+    private passwordOf;
+    /**
+     * Re-reads the stored row and the credentials' metadata, replaces the
+     * snapshot, and returns the full (non-secret) state. THROWS on a failed
+     * read, leaving the snapshot as it was — for a caller that must know (an
+     * admin read or write). The background refresh uses `refreshSafely`.
+     */
+    refresh(): Promise<TelemetryConnectionState>;
+    /** `refresh`, but never throws: a failure keeps the last snapshot and logs once per outage. */
+    refreshSafely(): Promise<boolean>;
+    /** The deployment default, as a snapshot (source `none` when it names no host). */
+    environmentSnapshot(): TelemetryConnectionSnapshot;
+    /**
+     * The deployment's GreptimeDB, every field from `GREPTIME_*`: what the
+     * environment source and a stored automatic host both resolve to.
+     */
+    private deploymentSnapshot;
+}
+export {};
+//# sourceMappingURL=telemetry-connection.service.d.ts.map

package/dist/telemetry/connection/telemetry-connection.service.d.ts.map

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

package/dist/telemetry/connection/telemetry-connection.service.js

@@ -0,0 +1,461 @@
+"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); }
+};
+var TelemetryConnectionService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelemetryConnectionService = exports.TELEMETRY_CONNECTION_REFRESH_MS = exports.DEPLOYMENT_ADMIN_MISSING_MESSAGE = exports.DEPLOYMENT_READER_MISSING_MESSAGE = void 0;
+const common_1 = require("@nestjs/common");
+const config_1 = require("@nestjs/config");
+const ports_1 = require("../ports");
+const telemetry_connection_schema_1 = require("./telemetry-connection.schema");
+// =============================================================================
+// TelemetryConnectionService — THE resolver of the GreptimeDB connection
+// (issue #558, epic #528)
+// =============================================================================
+//
+// ONE PRECEDENCE RULE, NO PER-FIELD MERGE — THE HOST MODE DECIDES WHO OWNS
+// THE WHOLE CONNECTION (issue #570):
+//
+//   1. a connection is STORED with a CUSTOM host (a literal an administrator
+//      typed: GreptimeDB lives somewhere this deployment did not put it)
+//        → the row is the connection, wholly: host, port, database, both
+//          users, and the two passwords from the credential store. Nothing is
+//          borrowed from the environment, field by field or otherwise.
+//   2. a connection is STORED with an AUTOMATIC host (`host: null`) — "the
+//      GreptimeDB deployed with this application" (issues #562, #570)
+//        → the DEPLOYMENT is the connection, wholly: the deployment host
+//          (`GREPTIME_HOST` when non-blank, else `TELEMETRY_DEFAULT_HOST`, the
+//          compose service name), `GREPTIME_PG_PORT`, `GREPTIME_DB`, and the
+//          `GREPTIME_READER_*` / `GREPTIME_ADMIN_*` logins. The deployment
+//          provisioned that GreptimeDB's users, so it is the only party that
+//          knows their passwords; an administrator never supplies them. Any
+//          port, database, user or credential-store password attached to
+//          such a row (rows saved before #570 carry them) is IGNORED here —
+//          not deleted: the next save in automatic mode deletes the stored
+//          passwords. The source still reads `stored` (a row exists, it has a
+//          version, "revert" applies) with `hostMode: 'auto'` and
+//          `deploymentManaged: true`.
+//   3. nothing is stored → the DEPLOYMENT DEFAULT, derived from `GREPTIME_*`
+//      (the `greptime` block of `config/configuration.ts`), when it names a
+//      host. Also automatic and deployment-managed: it is the same GreptimeDB
+//      rule 2 resolves to (source `environment`).
+//   4. otherwise none — telemetry is not available.
+//
+// The fingerprint carries the EFFECTIVE host and the version of the password
+// actually used (the credential's `updatedAt` for rule 1, a constant for the
+// environment), so moving between a custom and an automatic connection, or the
+// deployment host moving, rebuilds the pools.
+//
+// WHY THE ENVIRONMENT IS STILL A SOURCE AT ALL. The `GREPTIME_*` variables
+// cannot go away: the telemetry overlay provisions the GreptimeDB container's
+// users and the OTel collector's writer login from them. They describe the
+// GreptimeDB the deployment runs, so they ARE its connection; the admin page
+// only overrides them by pointing at a different (custom) host.
+// A per-field merge was rejected: "host from the form, password from the
+// environment" is a connection nobody configured, and it is impossible to
+// explain on a status page.
+//
+// WHAT IS CACHED, AND WHAT IS NOT
+// -----------------------------------------------------------------------------
+//
+// `GreptimeClient.isConfigured()` and friends are SYNCHRONOUS (the export
+// gate, the explorer's preconditions and the retention job all ask them
+// without awaiting), so this service keeps a SNAPSHOT: the non-secret half of
+// the resolved connection, plus, per login, whether a password is present and
+// a version marker (the credential's `updatedAt` when stored; a constant for
+// the environment). The snapshot is refreshed once at boot (awaited, errors
+// swallowed — boot never fails on it), every `TELEMETRY_CONNECTION_REFRESH_MS`
+// on an unref'd interval, and immediately after an admin save on this
+// instance. So a save reaches every instance within one interval, no restart.
+//
+// ⚠ PASSWORDS ARE NEVER CACHED HERE. `resolveCredentials` reads the password
+// from the credential store at the moment a pool is built and hands it
+// straight to `pg` — the `CredentialsService.getSecret` contract, and the same
+// trade `StorageConfigService` documents. The refresh itself only calls
+// `CredentialsService.describe`, which cannot decrypt anything.
+//
+// A FAILED REFRESH KEEPS THE LAST SNAPSHOT (and logs once per outage), for the
+// reason `TelemetrySettingsService` keeps the gate: flipping to "not
+// configured" on a database blip would drop telemetry exactly when an
+// operator needs it most.
+//
+// ⚠ NEVER LOG A CREDENTIAL. Nothing here logs a password or a connection
+// string; the snapshot does not hold one.
+// =============================================================================
+/**
+ * What an administrator is told when the GreptimeDB deployed with this
+ * application lacks a login. Administrator language: no file, variable or
+ * command names — fixing it is an application update, not a form field.
+ */
+exports.DEPLOYMENT_READER_MISSING_MESSAGE = 'The GreptimeDB deployed with this application has no reader login configured. ' +
+    'Update the application to provision it.';
+exports.DEPLOYMENT_ADMIN_MISSING_MESSAGE = 'The GreptimeDB deployed with this application has no admin login configured, so retention ' +
+    'cannot be applied. Update the application to provision it.';
+/** How often every instance re-reads the stored connection. */
+exports.TELEMETRY_CONNECTION_REFRESH_MS = 5_000;
+/** Version marker of an environment-supplied password: it cannot change without a restart. */
+const ENVIRONMENT_CREDENTIAL_VERSION = 'environment';
+const DEFAULT_PG_PORT = telemetry_connection_schema_1.TELEMETRY_DEFAULT_PG_PORT;
+const DEFAULT_DATABASE = telemetry_connection_schema_1.TELEMETRY_DEFAULT_DATABASE;
+let TelemetryConnectionService = TelemetryConnectionService_1 = class TelemetryConnectionService {
+    settingsStore;
+    credentials;
+    logger = new common_1.Logger(TelemetryConnectionService_1.name);
+    environment;
+    /**
+     * Seeded from the environment so the sync accessors have an answer before
+     * the first refresh (and so a unit test can build a client with no
+     * database). `onModuleInit` replaces it with the real resolution.
+     */
+    snapshot;
+    refreshTimer = null;
+    refreshFailing = false;
+    lastInvalidRowWarned = false;
+    constructor(configService, settingsStore, credentials) {
+        this.settingsStore = settingsStore;
+        this.credentials = credentials;
+        const raw = configService.get('greptime') ?? {};
+        this.environment = {
+            host: (raw.host ?? '').trim(),
+            pgPort: raw.pgPort ?? DEFAULT_PG_PORT,
+            database: raw.database || DEFAULT_DATABASE,
+            readerUser: raw.readerUser ?? '',
+            readerPassword: raw.readerPassword ?? '',
+            adminUser: raw.adminUser ?? '',
+            adminPassword: raw.adminPassword ?? '',
+            available: raw.available ?? false,
+        };
+        this.snapshot = this.environmentSnapshot();
+    }
+    /** One awaited refresh (never throws), then the interval. */
+    async onModuleInit() {
+        await this.refreshSafely();
+        this.refreshTimer = setInterval(() => {
+            void this.refreshSafely();
+        }, exports.TELEMETRY_CONNECTION_REFRESH_MS);
+        // Never the reason a process (or a test run) stays alive.
+        this.refreshTimer.unref?.();
+    }
+    onModuleDestroy() {
+        if (this.refreshTimer) {
+            clearInterval(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Synchronous accessors, answered from the snapshot
+    // ---------------------------------------------------------------------------
+    /** Where the connection in force came from. */
+    get source() {
+        return this.snapshot.source;
+    }
+    /**
+     * Where GreptimeDB is in this deployment: `GREPTIME_HOST` when non-blank,
+     * else `TELEMETRY_DEFAULT_HOST`. What an automatic (null) host resolves to.
+     */
+    get deploymentHost() {
+        return (0, telemetry_connection_schema_1.telemetryDeploymentHost)(this.environment.host);
+    }
+    /** The deployment's own GreptimeDB connection (non-secret), whatever is in force. */
+    describeDeployment() {
+        const env = this.environment;
+        return {
+            host: this.deploymentHost,
+            pgPort: env.pgPort,
+            database: env.database,
+            readerUser: env.readerUser,
+            adminUser: env.adminUser || null,
+            readerConfigured: Boolean(env.readerUser && env.readerPassword),
+            adminConfigured: Boolean(env.adminUser && env.adminPassword),
+        };
+    }
+    /**
+     * Why the connection in force cannot be used, in administrator language, or
+     * null. Only a deployment-managed connection has an answer here: its gaps
+     * are the deployment's, which nothing on the admin page can fill. `role`
+     * `admin` also reports a missing admin login (retention).
+     */
+    configurationProblem(role = 'reader') {
+        const { deploymentManaged, reader, admin } = this.snapshot;
+        if (!deploymentManaged)
+            return null;
+        if (!(reader.user && reader.passwordSet))
+            return exports.DEPLOYMENT_READER_MISSING_MESSAGE;
+        if (role === 'admin' && !(admin && admin.user && admin.passwordSet))
+            return exports.DEPLOYMENT_ADMIN_MISSING_MESSAGE;
+        return null;
+    }
+    /** The GreptimeDB database telemetry is written to. */
+    get database() {
+        return this.snapshot.database;
+    }
+    /** A host, a reader login and its password — i.e. telemetry can be read. */
+    isConfigured() {
+        const { source, host, reader } = this.snapshot;
+        return source !== 'none' && Boolean(host && reader.user && reader.passwordSet);
+    }
+    /** The admin login (retention, `SHOW CREATE DATABASE`) is usable as well. */
+    isAdminConfigured() {
+        const { admin } = this.snapshot;
+        return this.isConfigured() && Boolean(admin && admin.user && admin.passwordSet);
+    }
+    /**
+     * An opaque identity of the connection a login would use right now, or
+     * null when that login is not configured. `GreptimeClient` keys its pools by
+     * it: a different answer means the pool it holds is stale.
+     */
+    fingerprint(role) {
+        if (role === 'reader' ? !this.isConfigured() : !this.isAdminConfigured()) {
+            return null;
+        }
+        return fingerprintOf(this.snapshot, role);
+    }
+    /** A copy of the snapshot. Non-secret. */
+    describeSnapshot() {
+        return structuredClone(this.snapshot);
+    }
+    // ---------------------------------------------------------------------------
+    // Credentials, at the moment of use
+    // ---------------------------------------------------------------------------
+    /**
+     * The full connection for one login, password included, or null when that
+     * login is not configured (or its stored password has since gone).
+     *
+     * ⚠ Holds a plaintext password. Call it when building a pool and let the
+     * result go out of scope; never cache it, never log it.
+     */
+    async resolveCredentials(role) {
+        const snapshot = this.snapshot;
+        const fingerprint = this.fingerprint(role);
+        const login = role === 'reader' ? snapshot.reader : snapshot.admin;
+        if (!fingerprint || !login)
+            return null;
+        const password = await this.passwordOf(role, snapshot);
+        if (!password)
+            return null;
+        return {
+            host: snapshot.host,
+            automaticHost: snapshot.hostMode === 'auto',
+            port: snapshot.pgPort,
+            database: snapshot.database,
+            user: login.user,
+            password,
+            fingerprint,
+        };
+    }
+    /**
+     * The password the connection IN FORCE would use for this login — the
+     * deployment's when it is deployment-managed (the environment source, or a
+     * stored automatic host), the credential store's for a custom host, none
+     * when there is no connection. For the connection test's "blank means the
+     * current one".
+     *
+     * ⚠ Plaintext. Same rules as `resolveCredentials`.
+     */
+    async currentPassword(role) {
+        return this.passwordOf(role, this.snapshot);
+    }
+    /**
+     * The deployment's own password for this login (`GREPTIME_*`), or null when
+     * it provisions none. What an automatic connection uses — and the only
+     * password a connection test of an automatic host may use.
+     *
+     * ⚠ Plaintext. Same rules as `resolveCredentials`.
+     */
+    deploymentPassword(role) {
+        const value = role === 'reader' ? this.environment.readerPassword : this.environment.adminPassword;
+        return value || null;
+    }
+    async passwordOf(role, snapshot) {
+        if (snapshot.deploymentManaged)
+            return this.deploymentPassword(role);
+        if (snapshot.source === 'none')
+            return null;
+        return this.credentials.getSecret(telemetry_connection_schema_1.TELEMETRY_GREPTIME_CREDENTIAL_PURPOSE, role);
+    }
+    // ---------------------------------------------------------------------------
+    // Refresh
+    // ---------------------------------------------------------------------------
+    /**
+     * Re-reads the stored row and the credentials' metadata, replaces the
+     * snapshot, and returns the full (non-secret) state. THROWS on a failed
+     * read, leaving the snapshot as it was — for a caller that must know (an
+     * admin read or write). The background refresh uses `refreshSafely`.
+     */
+    async refresh() {
+        const [row, reader, admin] = await Promise.all([
+            this.settingsStore.readRow(telemetry_connection_schema_1.TELEMETRY_CONNECTION_SETTINGS_KEY),
+            this.credentials.describe(telemetry_connection_schema_1.TELEMETRY_GREPTIME_CREDENTIAL_PURPOSE, 'reader'),
+            this.credentials.describe(telemetry_connection_schema_1.TELEMETRY_GREPTIME_CREDENTIAL_PURPOSE, 'admin'),
+        ]);
+        const credentials = { reader, admin };
+        let stored = null;
+        let snapshot;
+        if (!row) {
+            snapshot = this.environmentSnapshot();
+            this.lastInvalidRowWarned = false;
+        }
+        else {
+            const parsed = telemetry_connection_schema_1.telemetryConnectionValueSchema.safeParse(row.value);
+            if (parsed.success) {
+                stored = parsed.data;
+                snapshot =
+                    parsed.data.host === null
+                        ? // Automatic: the deployment, wholly. Stored credentials are ignored (issue #570).
+                            this.deploymentSnapshot('stored', this.deploymentHost)
+                        : storedSnapshot(parsed.data, credentials);
+                this.lastInvalidRowWarned = false;
+            }
+            else {
+                // A row exists but does not validate (hand-edited). It is still "the
+                // stored connection" — silently falling back to the environment would
+                // put telemetry on a connection nobody chose — so it resolves as
+                // stored-and-unusable until an administrator saves or resets it.
+                if (!this.lastInvalidRowWarned) {
+                    this.lastInvalidRowWarned = true;
+                    this.logger.warn('The stored telemetry connection does not validate ' +
+                        `(${parsed.error.issues.map((issue) => issue.path.join('.') || '(root)').join(', ')}); ` +
+                        'telemetry is unavailable until it is saved again or reset at /admin/settings/telemetry.');
+                }
+                snapshot = unusableStoredSnapshot();
+            }
+        }
+        const before = this.snapshot;
+        this.snapshot = snapshot;
+        if (before.source !== snapshot.source) {
+            this.logger.log(`Telemetry connection source is now "${snapshot.source}"`);
+        }
+        return {
+            snapshot: structuredClone(snapshot),
+            stored,
+            row: row ? { version: row.version, updatedAt: row.updatedAt, updatedByUser: row.updatedBy } : null,
+            credentials,
+        };
+    }
+    /** `refresh`, but never throws: a failure keeps the last snapshot and logs once per outage. */
+    async refreshSafely() {
+        try {
+            await this.refresh();
+            if (this.refreshFailing) {
+                this.refreshFailing = false;
+                this.logger.log('Telemetry connection readable again');
+            }
+            return true;
+        }
+        catch (error) {
+            if (!this.refreshFailing) {
+                this.refreshFailing = true;
+                this.logger.warn(`Could not read the telemetry connection; keeping the last known one (source "${this.snapshot.source}"): ` +
+                    `${error instanceof Error ? error.message : String(error)}`);
+            }
+            return false;
+        }
+    }
+    /** The deployment default, as a snapshot (source `none` when it names no host). */
+    environmentSnapshot() {
+        const env = this.environment;
+        if (!env.host) {
+            return {
+                source: 'none',
+                host: '',
+                hostMode: 'auto',
+                deploymentManaged: false,
+                pgPort: env.pgPort,
+                database: env.database,
+                reader: { user: '', passwordSet: false, version: null },
+                admin: null,
+            };
+        }
+        // `GREPTIME_HOST` IS the deployment host, so this is an automatic host too.
+        return this.deploymentSnapshot('environment', env.host);
+    }
+    /**
+     * The deployment's GreptimeDB, every field from `GREPTIME_*`: what the
+     * environment source and a stored automatic host both resolve to.
+     */
+    deploymentSnapshot(source, host) {
+        const env = this.environment;
+        return {
+            source,
+            host,
+            hostMode: 'auto',
+            deploymentManaged: true,
+            pgPort: env.pgPort,
+            database: env.database,
+            reader: {
+                user: env.readerUser,
+                passwordSet: Boolean(env.readerPassword),
+                version: env.readerPassword ? ENVIRONMENT_CREDENTIAL_VERSION : null,
+            },
+            admin: env.adminUser
+                ? {
+                    user: env.adminUser,
+                    passwordSet: Boolean(env.adminPassword),
+                    version: env.adminPassword ? ENVIRONMENT_CREDENTIAL_VERSION : null,
+                }
+                : null,
+        };
+    }
+};
+exports.TelemetryConnectionService = TelemetryConnectionService;
+exports.TelemetryConnectionService = TelemetryConnectionService = TelemetryConnectionService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Inject)(ports_1.TELEMETRY_SETTINGS_STORE)),
+    __param(2, (0, common_1.Inject)(ports_1.TELEMETRY_CREDENTIAL_STORE)),
+    __metadata("design:paramtypes", [config_1.ConfigService, Object, Object])
+], TelemetryConnectionService);
+/** A stored CUSTOM connection: the row and the credential store, wholly. */
+function storedSnapshot(value, credentials) {
+    const login = (user, info) => ({
+        user,
+        passwordSet: info !== null,
+        version: info ? info.updatedAt.toISOString() : null,
+    });
+    return {
+        source: 'stored',
+        host: value.host,
+        hostMode: 'custom',
+        deploymentManaged: false,
+        pgPort: value.pgPort,
+        database: value.database,
+        reader: login(value.readerUser, credentials.reader),
+        admin: value.adminUser ? login(value.adminUser, credentials.admin) : null,
+    };
+}
+function unusableStoredSnapshot() {
+    return {
+        source: 'stored',
+        host: '',
+        hostMode: 'auto',
+        deploymentManaged: false,
+        pgPort: DEFAULT_PG_PORT,
+        database: DEFAULT_DATABASE,
+        reader: { user: '', passwordSet: false, version: null },
+        admin: null,
+    };
+}
+function fingerprintOf(snapshot, role) {
+    const login = role === 'reader' ? snapshot.reader : snapshot.admin;
+    return JSON.stringify([
+        snapshot.source,
+        snapshot.hostMode,
+        // The EFFECTIVE host, so an automatic host whose deployment host changed
+        // yields a new fingerprint (and new pools).
+        snapshot.host,
+        snapshot.pgPort,
+        snapshot.database,
+        login?.user ?? '',
+        login?.version ?? '',
+    ]);
+}
+//# sourceMappingURL=telemetry-connection.service.js.map