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

package/dist/telemetry/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../../src/telemetry/ports.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,wDAAwD;AACxD,gFAAgF;AAChF,EAAE;AACF,0EAA0E;AAC1E,yEAAyE;AACzE,6DAA6D;AAC7D,2EAA2E;AAC3E,8CAA8C;AAC9C,EAAE;AACF,8EAA8E;AAC9E,iDAAiD;AACjD,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAC9E,oDAAoD;AACpD,0EAA0E;AAC1E,kEAAkE;AAClE,0DAA0D;AAC1D,EAAE;AACF,qEAAqE;AACrE,iDAAiD;AACjD,EAAE;AACF,yEAAyE;AACzE,0EAA0E;AAC1E,gFAAgF;;;AAMhF,sFAAsF;AAEtF;;;;;GAKG;AACU,QAAA,oBAAoB,GAAkB,MAAM,CAAC,GAAG,CAAC,2CAA2C,CAAC,CAAC;AAoC3G,wFAAwF;AAExF;;;;;GAKG;AACU,QAAA,wBAAwB,GAAkB,MAAM,CAAC,GAAG,CAAC,+CAA+C,CAAC,CAAC;AAyFnH,wFAAwF;AAExF;;;;;GAKG;AACU,QAAA,0BAA0B,GAAkB,MAAM,CAAC,GAAG,CAAC,iDAAiD,CAAC,CAAC;AAoEvH,wFAAwF;AAExF;;;;;GAKG;AACU,QAAA,cAAc,GAAkB,MAAM,CAAC,GAAG,CAAC,qCAAqC,CAAC,CAAC;AA2G/F,wFAAwF;AAExF;;;;;GAKG;AACU,QAAA,YAAY,GAAkB,MAAM,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;AAqN3F,wFAAwF;AAExF;;;;;GAKG;AACU,QAAA,kBAAkB,GAAkB,MAAM,CAAC,GAAG,CAAC,yCAAyC,CAAC,CAAC"}

package/dist/telemetry/query/sql-guard.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The read-only statement kinds the guard admits.
+ *
+ * @stability stable
+ */
+export type TelemetryStatementKind = 'select' | 'show' | 'describe' | 'explain';
+/**
+ * A statement the guard admitted.
+ *
+ * @stability stable
+ */
+export interface AnalyzedStatement {
+    /** Its kind. */
+    kind: TelemetryStatementKind;
+    /** The statement with comments removed and trailing `;`/whitespace trimmed. */
+    normalized: string;
+}
+/** Why a statement was refused. The message is shown to the user as-is. */
+export declare class TelemetrySqlRejectedError extends Error {
+    constructor(message: string);
+}
+/**
+ * Removes comments outside quotes, keeping everything else byte-for-byte.
+ * A comment is replaced by one space so `SELECT/**\/1` does not become
+ * `SELECT1`. Throws on an unterminated string, identifier or block comment:
+ * what follows it cannot be classified safely.
+ */
+export declare function stripSqlComments(sql: string): string;
+/**
+ * Classifies one read-only statement, or throws `TelemetrySqlRejectedError`
+ * with a message fit to show the user.
+  *
+  * @stability stable
+ */
+export declare function analyzeStatement(sql: string): AnalyzedStatement;
+/**
+ * How `applyRowCap` bounded a statement:
+ *
+ *   appended     no top-level LIMIT: `LIMIT <cap>` was added at the end (or
+ *                just before a top-level OFFSET);
+ *   clamped      a top-level `LIMIT <n>` with n at least the cap: n was replaced by cap;
+ *   kept         a top-level `LIMIT <n>` with n under the cap: already bounded below
+ *                the cap, sent unchanged;
+ *   client-only  the statement could not be bounded safely in its text
+ *                (`LIMIT ALL`, `LIMIT <expression>`, `FETCH FIRST`, or a
+ *                SHOW/DESCRIBE/EXPLAIN): sent unchanged, and the caller's
+ *                slice to `maxRows` (plus the query timeout) is the only cap.
+ */
+export type RowCapStrategy = 'appended' | 'clamped' | 'kept' | 'client-only';
+export interface RowCappedStatement {
+    sql: string;
+    strategy: RowCapStrategy;
+}
+/**
+ * The statement to send, bounded so the SERVER stops after `cap` rows (pass
+ * `maxRows + 1`: the extra row is how truncation is detected).
+ *
+ * WHY NOT A WRAPPER (issue #554). The obvious
+ * `SELECT * FROM (<sql>) AS q LIMIT n` — and a CTE wrapper too — does NOT preserve the inner ORDER BY on
+ * GreptimeDB v1.2.1 (verified live, deterministically; `UNION ALL … ORDER BY`
+ * included). SQL leaves a subquery's order unspecified and the planner takes
+ * it at its word. So the LIMIT is applied to the statement itself, at the top
+ * level, where it composes with the statement's own ORDER BY (and, after a
+ * top-level `UNION … ORDER BY`, with the whole union).
+ *
+ * "Top level" is found with the same quote-aware scan as the rest of this
+ * file (comments are already gone from `normalized`), counting parentheses:
+ * a LIMIT inside a subquery, CTE or string literal is not the statement's.
+ */
+export declare function applyRowCap(statement: AnalyzedStatement, cap: number): RowCappedStatement;
+//# sourceMappingURL=sql-guard.d.ts.map

package/dist/telemetry/query/sql-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-guard.d.ts","sourceRoot":"","sources":["../../../src/telemetry/query/sql-guard.ts"],"names":[],"mappings":"AA4BA;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;AAEhF;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,gBAAgB;IAChB,IAAI,EAAE,sBAAsB,CAAC;IAC7B,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,2EAA2E;AAC3E,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,OAAO,EAAE,MAAM;CAI5B;AAaD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAsCpD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAgC/D;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,aAAa,CAAC;AAE7E,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAwDzF"}

package/dist/telemetry/query/sql-guard.js

@@ -0,0 +1,258 @@
+"use strict";
+// =============================================================================
+// SQL guard for ad-hoc telemetry queries (issue #535, epic #528)
+// =============================================================================
+//
+// DEFENCE IN DEPTH, NOT THE CONTROL. Every explorer/assistant/export query runs
+// as GreptimeDB's `readonly` user, which the server itself refuses INSERT,
+// DROP, ALTER, SET and friends (spike #529). This guard exists for two
+// reasons that user cannot cover:
+//
+//   1. ONE STATEMENT. The simple query protocol executes EVERY statement in a
+//      multi-statement string (spike #529). `GreptimeClient` refuses the
+//      result after the fact; this refuses the text before it is sent, so a
+//      second statement never runs at all.
+//   2. GOOD ERRORS. "Only SELECT, WITH, SHOW, DESCRIBE and EXPLAIN are
+//      allowed" is a better answer to `DELETE FROM …` than the server's
+//      "User is not authorized to perform this action".
+//
+// It is a small lexer, not a parser: it knows where single-quoted strings
+// ('' escapes), double-quoted identifiers ("" escapes — telemetry columns are
+// named like "span_attributes.http.route"), backtick identifiers, `--` line
+// comments and `/* */` block comments begin and end, and nothing else. That
+// is exactly enough to find a `;` or a comment that is really one, to find
+// the first keyword, and to find a top-level LIMIT (`applyRowCap`).
+// GreptimeDB has no dollar quoting, so none is handled.
+//
+// Pure functions; no Nest, no I/O.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelemetrySqlRejectedError = void 0;
+exports.stripSqlComments = stripSqlComments;
+exports.analyzeStatement = analyzeStatement;
+exports.applyRowCap = applyRowCap;
+/** Why a statement was refused. The message is shown to the user as-is. */
+class TelemetrySqlRejectedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TelemetrySqlRejectedError';
+    }
+}
+exports.TelemetrySqlRejectedError = TelemetrySqlRejectedError;
+const ALLOWED = {
+    SELECT: 'select',
+    WITH: 'select',
+    SHOW: 'show',
+    DESCRIBE: 'describe',
+    DESC: 'describe',
+    EXPLAIN: 'explain',
+};
+const ALLOWED_TEXT = 'SELECT, WITH, SHOW, DESCRIBE and EXPLAIN';
+/**
+ * Removes comments outside quotes, keeping everything else byte-for-byte.
+ * A comment is replaced by one space so `SELECT/**\/1` does not become
+ * `SELECT1`. Throws on an unterminated string, identifier or block comment:
+ * what follows it cannot be classified safely.
+ */
+function stripSqlComments(sql) {
+    let out = '';
+    let i = 0;
+    const n = sql.length;
+    while (i < n) {
+        const ch = sql[i];
+        const next = sql[i + 1];
+        if (ch === "'" || ch === '"' || ch === '`') {
+            const end = endOfQuoted(sql, i);
+            out += sql.slice(i, end);
+            i = end;
+            continue;
+        }
+        if (ch === '-' && next === '-') {
+            const newline = sql.indexOf('\n', i + 2);
+            i = newline === -1 ? n : newline; // keep the newline itself
+            out += ' ';
+            continue;
+        }
+        if (ch === '/' && next === '*') {
+            const close = sql.indexOf('*/', i + 2);
+            if (close === -1) {
+                throw new TelemetrySqlRejectedError('The query has an unterminated /* comment.');
+            }
+            i = close + 2;
+            out += ' ';
+            continue;
+        }
+        out += ch;
+        i += 1;
+    }
+    return out;
+}
+/**
+ * Classifies one read-only statement, or throws `TelemetrySqlRejectedError`
+ * with a message fit to show the user.
+  *
+  * @stability stable
+ */
+function analyzeStatement(sql) {
+    const stripped = stripSqlComments(sql);
+    const normalized = trimTrailingTerminators(stripped);
+    if (normalized === '') {
+        throw new TelemetrySqlRejectedError('The query is empty.');
+    }
+    if (indexOfUnquoted(normalized, ';') !== -1) {
+        throw new TelemetrySqlRejectedError('Only one SQL statement may be run at a time.');
+    }
+    // `(SELECT 1) UNION (SELECT 2)` — a leading parenthesis opens a query.
+    const body = normalized.replace(/^[\s(]+/, '');
+    const keyword = /^[A-Za-z_]+/.exec(body)?.[0]?.toUpperCase() ?? '';
+    const kind = ALLOWED[keyword];
+    if (!kind) {
+        throw new TelemetrySqlRejectedError(keyword
+            ? `${keyword} statements are not allowed. Telemetry queries are read-only: only ${ALLOWED_TEXT} are allowed.`
+            : `The query must start with ${ALLOWED_TEXT}.`);
+    }
+    if (kind === 'explain' && /^EXPLAIN\s+(\(|VERBOSE\s+)?ANALYZE\b/i.test(body)) {
+        throw new TelemetrySqlRejectedError('EXPLAIN ANALYZE is not allowed: it runs the whole query. Use EXPLAIN to see the plan.');
+    }
+    return { kind, normalized };
+}
+/**
+ * The statement to send, bounded so the SERVER stops after `cap` rows (pass
+ * `maxRows + 1`: the extra row is how truncation is detected).
+ *
+ * WHY NOT A WRAPPER (issue #554). The obvious
+ * `SELECT * FROM (<sql>) AS q LIMIT n` — and a CTE wrapper too — does NOT preserve the inner ORDER BY on
+ * GreptimeDB v1.2.1 (verified live, deterministically; `UNION ALL … ORDER BY`
+ * included). SQL leaves a subquery's order unspecified and the planner takes
+ * it at its word. So the LIMIT is applied to the statement itself, at the top
+ * level, where it composes with the statement's own ORDER BY (and, after a
+ * top-level `UNION … ORDER BY`, with the whole union).
+ *
+ * "Top level" is found with the same quote-aware scan as the rest of this
+ * file (comments are already gone from `normalized`), counting parentheses:
+ * a LIMIT inside a subquery, CTE or string literal is not the statement's.
+ */
+function applyRowCap(statement, cap) {
+    if (!Number.isSafeInteger(cap) || cap < 1) {
+        throw new RangeError(`cap must be a positive integer, got ${cap}`);
+    }
+    const sql = statement.normalized;
+    // SHOW, DESCRIBE and EXPLAIN take no LIMIT; their output is small.
+    if (statement.kind !== 'select') {
+        return { sql, strategy: 'client-only' };
+    }
+    const words = topLevelWords(sql);
+    const find = (word) => words.filter((w) => w.upper === word).at(-1);
+    // `FETCH FIRST n ROWS ONLY` is the standard spelling of LIMIT; rewriting
+    // it is not worth the risk for how rarely it is written.
+    if (find('FETCH')) {
+        return { sql, strategy: 'client-only' };
+    }
+    const limit = find('LIMIT');
+    if (!limit) {
+        const offset = find('OFFSET');
+        if (offset) {
+            // `… OFFSET m` → `… LIMIT cap OFFSET m`, the form every dialect accepts.
+            return {
+                sql: `${sql.slice(0, offset.start)}LIMIT ${cap} ${sql.slice(offset.start)}`,
+                strategy: 'appended',
+            };
+        }
+        // After ORDER BY, and after a whole `UNION … ORDER BY`, this limits the
+        // statement's final, ordered result.
+        return { sql: `${sql} LIMIT ${cap}`, strategy: 'appended' };
+    }
+    // `LIMIT <integer>`, then nothing but an optional `OFFSET <integer> [ROW[S]]`
+    // (the `OFFSET m LIMIT n` order leaves nothing after the literal at all).
+    const rest = sql.slice(limit.end);
+    const literal = /^(\s+)(\d+)(?=(\s+OFFSET\s+\d+(\s+ROWS?)?)?\s*$)/i.exec(rest);
+    if (!literal) {
+        return { sql, strategy: 'client-only' };
+    }
+    if (BigInt(literal[2]) < BigInt(cap)) {
+        return { sql, strategy: 'kept' };
+    }
+    const at = limit.end + literal[1].length;
+    return {
+        sql: `${sql.slice(0, at)}${cap}${sql.slice(at + literal[2].length)}`,
+        strategy: 'clamped',
+    };
+}
+// -----------------------------------------------------------------------------
+/** Index just past the quoted run starting at `start` (a `'`, `"` or backtick). */
+function endOfQuoted(sql, start) {
+    const quote = sql[start];
+    let i = start + 1;
+    while (i < sql.length) {
+        if (sql[i] === quote) {
+            // A doubled quote is an escaped one and does not close the run.
+            if (sql[i + 1] === quote) {
+                i += 2;
+                continue;
+            }
+            return i + 1;
+        }
+        i += 1;
+    }
+    throw new TelemetrySqlRejectedError(quote === "'"
+        ? 'The query has an unterminated string literal.'
+        : 'The query has an unterminated quoted identifier.');
+}
+function indexOfUnquoted(sql, target) {
+    let found = -1;
+    scanUnquoted(sql, (ch, i) => {
+        if (ch !== target)
+            return undefined;
+        found = i;
+        return 'stop';
+    });
+    return found;
+}
+/**
+ * The bare words (keywords and unquoted identifiers) outside every quote and
+ * parenthesis, in order. A word after `.` (`t.limit`) is a qualified name,
+ * not a keyword; a numeric literal such as `1e5` contributes no word.
+ */
+function topLevelWords(sql) {
+    const words = [];
+    let depth = 0;
+    scanUnquoted(sql, (ch, i) => {
+        if (ch === '(')
+            depth += 1;
+        else if (ch === ')')
+            depth = Math.max(0, depth - 1);
+        else if (/[A-Za-z0-9_]/.test(ch) && !/[A-Za-z0-9_$]/.test(sql[i - 1] ?? '')) {
+            const end = i + /^[A-Za-z0-9_$]*/.exec(sql.slice(i))[0].length;
+            if (depth === 0 && /[A-Za-z_]/.test(ch) && sql[i - 1] !== '.') {
+                words.push({ upper: sql.slice(i, end).toUpperCase(), start: i, end });
+            }
+            return end;
+        }
+        return undefined;
+    });
+    return words;
+}
+/**
+ * Walks `sql` calling `visit` for every character outside a quoted run (the
+ * runs themselves are skipped whole). `visit` returns `'stop'` to end the
+ * walk, an index to resume from, or nothing to move on by one.
+ */
+function scanUnquoted(sql, visit) {
+    let i = 0;
+    while (i < sql.length) {
+        const ch = sql[i];
+        if (ch === "'" || ch === '"' || ch === '`') {
+            i = endOfQuoted(sql, i);
+            continue;
+        }
+        const next = visit(ch, i);
+        if (next === 'stop')
+            return;
+        i = typeof next === 'number' ? next : i + 1;
+    }
+}
+/** Trims whitespace and any number of trailing `;` (with whitespace between). */
+function trimTrailingTerminators(sql) {
+    return sql.replace(/[\s;]+$/, '').trim();
+}
+//# sourceMappingURL=sql-guard.js.map

package/dist/telemetry/query/sql-guard.js.map

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

package/dist/telemetry/query/telemetry-availability.d.ts

@@ -0,0 +1,11 @@
+import type { TelemetrySettings as SystemTelemetryValue } from '@marinoscar/platform-contract/telemetry';
+import type { GreptimeClient } from '../greptime/greptime.client';
+import type { TelemetrySettingsService } from '../telemetry-settings.service';
+/** The current policy, or a `TelemetryHttpError` saying why nothing may be queried. */
+export declare function requireQueryablePolicy(greptime: GreptimeClient, settings: TelemetrySettingsService): Promise<SystemTelemetryValue>;
+/**
+ * Maps anything the guard or `GreptimeClient` threw to its HTTP failure.
+ * Anything unrecognised is returned unchanged (and becomes a 500).
+ */
+export declare function toTelemetryHttpError(error: unknown): unknown;
+//# sourceMappingURL=telemetry-availability.d.ts.map

package/dist/telemetry/query/telemetry-availability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-availability.d.ts","sourceRoot":"","sources":["../../../src/telemetry/query/telemetry-availability.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,IAAI,oBAAoB,EAAE,MAAM,yCAAyC,CAAC;AACzG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAOlE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAY9E,uFAAuF;AACvF,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,wBAAwB,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAkB/B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CA4B5D"}

package/dist/telemetry/query/telemetry-availability.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireQueryablePolicy = requireQueryablePolicy;
+exports.toTelemetryHttpError = toTelemetryHttpError;
+const greptime_errors_1 = require("../greptime/greptime.errors");
+const sql_guard_1 = require("./sql-guard");
+const telemetry_query_errors_1 = require("./telemetry-query.errors");
+// =============================================================================
+// The two preconditions every explorer read shares (issue #535)
+// =============================================================================
+//
+// Order matters: "not configured" first (no amount of settings changes will
+// help), then "disabled" (an administrator can switch it on).
+// =============================================================================
+/** The current policy, or a `TelemetryHttpError` saying why nothing may be queried. */
+async function requireQueryablePolicy(greptime, settings) {
+    if (!greptime.isConfigured()) {
+        throw new telemetry_query_errors_1.TelemetryHttpError(telemetry_query_errors_1.TELEMETRY_ERROR_REASONS.NOT_CONFIGURED, 'No telemetry store is configured for this deployment.');
+    }
+    const policy = await settings.getPolicy();
+    if (!policy.enabled) {
+        throw new telemetry_query_errors_1.TelemetryHttpError(telemetry_query_errors_1.TELEMETRY_ERROR_REASONS.DISABLED, 'Telemetry is disabled. An administrator can enable it in the telemetry settings.');
+    }
+    return policy;
+}
+/**
+ * Maps anything the guard or `GreptimeClient` threw to its HTTP failure.
+ * Anything unrecognised is returned unchanged (and becomes a 500).
+ */
+function toTelemetryHttpError(error) {
+    if (error instanceof telemetry_query_errors_1.TelemetryHttpError)
+        return error;
+    if (error instanceof sql_guard_1.TelemetrySqlRejectedError || error instanceof greptime_errors_1.TelemetryMultiStatementError) {
+        return new telemetry_query_errors_1.TelemetryHttpError(telemetry_query_errors_1.TELEMETRY_ERROR_REASONS.QUERY_REJECTED, error.message);
+    }
+    if (error instanceof greptime_errors_1.TelemetryQueryTimeoutError) {
+        return new telemetry_query_errors_1.TelemetryHttpError(telemetry_query_errors_1.TELEMETRY_ERROR_REASONS.QUERY_TIMEOUT, error.message, {
+            timeoutMs: error.timeoutMs,
+        });
+    }
+    if (error instanceof greptime_errors_1.TelemetryNotConfiguredError) {
+        return new telemetry_query_errors_1.TelemetryHttpError(telemetry_query_errors_1.TELEMETRY_ERROR_REASONS.NOT_CONFIGURED, error.message);
+    }
+    if (error instanceof greptime_errors_1.TelemetryQueryFailedError) {
+        return error.origin === 'server'
+            ? new telemetry_query_errors_1.TelemetryHttpError(telemetry_query_errors_1.TELEMETRY_ERROR_REASONS.QUERY_FAILED, error.message, {
+                ...(error.code ? { sqlState: error.code } : {}),
+            })
+            : new telemetry_query_errors_1.TelemetryHttpError(telemetry_query_errors_1.TELEMETRY_ERROR_REASONS.UNREACHABLE, 'The telemetry store did not answer.', {
+                cause: error.message,
+            });
+    }
+    return error;
+}
+//# sourceMappingURL=telemetry-availability.js.map

package/dist/telemetry/query/telemetry-availability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-availability.js","sourceRoot":"","sources":["../../../src/telemetry/query/telemetry-availability.ts"],"names":[],"mappings":";;AAqBA,wDAqBC;AAMD,oDA4BC;AA1ED,iEAKqC;AAErC,2CAAwD;AACxD,qEAAuF;AAEvF,gFAAgF;AAChF,gEAAgE;AAChE,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,8DAA8D;AAC9D,gFAAgF;AAEhF,uFAAuF;AAChF,KAAK,UAAU,sBAAsB,CAC1C,QAAwB,EACxB,QAAkC;IAElC,IAAI,CAAC,QAAQ,CAAC,YAAY,EAAE,EAAE,CAAC;QAC7B,MAAM,IAAI,2CAAkB,CAC1B,gDAAuB,CAAC,cAAc,EACtC,uDAAuD,CACxD,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,SAAS,EAAE,CAAC;IAE1C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,2CAAkB,CAC1B,gDAAuB,CAAC,QAAQ,EAChC,kFAAkF,CACnF,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,SAAgB,oBAAoB,CAAC,KAAc;IACjD,IAAI,KAAK,YAAY,2CAAkB;QAAE,OAAO,KAAK,CAAC;IAEtD,IAAI,KAAK,YAAY,qCAAyB,IAAI,KAAK,YAAY,8CAA4B,EAAE,CAAC;QAChG,OAAO,IAAI,2CAAkB,CAAC,gDAAuB,CAAC,cAAc,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IACvF,CAAC;IAED,IAAI,KAAK,YAAY,4CAA0B,EAAE,CAAC;QAChD,OAAO,IAAI,2CAAkB,CAAC,gDAAuB,CAAC,aAAa,EAAE,KAAK,CAAC,OAAO,EAAE;YAClF,SAAS,EAAE,KAAK,CAAC,SAAS;SAC3B,CAAC,CAAC;IACL,CAAC;IAED,IAAI,KAAK,YAAY,6CAA2B,EAAE,CAAC;QACjD,OAAO,IAAI,2CAAkB,CAAC,gDAAuB,CAAC,cAAc,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IACvF,CAAC;IAED,IAAI,KAAK,YAAY,2CAAyB,EAAE,CAAC;QAC/C,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ;YAC9B,CAAC,CAAC,IAAI,2CAAkB,CAAC,gDAAuB,CAAC,YAAY,EAAE,KAAK,CAAC,OAAO,EAAE;gBAC1E,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAChD,CAAC;YACJ,CAAC,CAAC,IAAI,2CAAkB,CAAC,gDAAuB,CAAC,WAAW,EAAE,qCAAqC,EAAE;gBACjG,KAAK,EAAE,KAAK,CAAC,OAAO;aACrB,CAAC,CAAC;IACT,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/telemetry/query/telemetry-query.errors.d.ts

@@ -0,0 +1,48 @@
+import { HttpException } from '@nestjs/common';
+/**
+ * The `details.reason` of every telemetry error (see the table above).
+ *
+ * @stability stable
+ */
+export declare const TELEMETRY_ERROR_REASONS: {
+    /** 503: no telemetry store is configured. */
+    readonly NOT_CONFIGURED: "TELEMETRY_NOT_CONFIGURED";
+    /** 503: the store did not answer. */
+    readonly UNREACHABLE: "TELEMETRY_UNREACHABLE";
+    /** 409: `telemetry.enabled` is off. */
+    readonly DISABLED: "TELEMETRY_DISABLED";
+    /** 400: the SQL guard refused the statement. */
+    readonly QUERY_REJECTED: "TELEMETRY_QUERY_REJECTED";
+    /** 400: the store refused the statement. */
+    readonly QUERY_FAILED: "TELEMETRY_QUERY_FAILED";
+    /** 504: the statement timed out. */
+    readonly QUERY_TIMEOUT: "TELEMETRY_QUERY_TIMEOUT";
+    /** 409: `telemetry.assistant.enabled` is off. */
+    readonly ASSISTANT_DISABLED: "TELEMETRY_ASSISTANT_DISABLED";
+    /** 409: no assistant provider or model is selected. */
+    readonly ASSISTANT_NOT_CONFIGURED: "TELEMETRY_ASSISTANT_NOT_CONFIGURED";
+    /** 400: a dashboard filter value was not seen in the range. */
+    readonly DASHBOARD_BAD_FILTER: "TELEMETRY_DASHBOARD_BAD_FILTER";
+    /** 400: the events `cursor` is malformed. */
+    readonly DASHBOARD_BAD_CURSOR: "TELEMETRY_DASHBOARD_BAD_CURSOR";
+};
+/**
+ * One of {@link TELEMETRY_ERROR_REASONS}.
+ *
+ * @stability stable
+ */
+export type TelemetryErrorReason = (typeof TELEMETRY_ERROR_REASONS)[keyof typeof TELEMETRY_ERROR_REASONS];
+/**
+ * A telemetry failure with its reason in `details.reason`; the HTTP status
+ * follows from the reason.
+ *
+ * @stability stable
+ */
+export declare class TelemetryHttpError extends HttpException {
+    /** Why it failed. */
+    readonly reason: TelemetryErrorReason;
+    constructor(
+    /** Why it failed. */
+    reason: TelemetryErrorReason, message: string, details?: Record<string, unknown>);
+}
+//# sourceMappingURL=telemetry-query.errors.d.ts.map

package/dist/telemetry/query/telemetry-query.errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-query.errors.d.ts","sourceRoot":"","sources":["../../../src/telemetry/query/telemetry-query.errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAc,MAAM,gBAAgB,CAAC;AA0C3D;;;;GAIG;AACH,eAAO,MAAM,uBAAuB;IAClC,6CAA6C;;IAE7C,qCAAqC;;IAErC,uCAAuC;;IAEvC,gDAAgD;;IAEhD,4CAA4C;;IAE5C,oCAAoC;;IAEpC,iDAAiD;;IAEjD,uDAAuD;;IAEvD,+DAA+D;;IAE/D,6CAA6C;;CAErC,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,OAAO,uBAAuB,CAAC,CAAC;AAe1G;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,aAAa;IAEjD,qBAAqB;IACrB,QAAQ,CAAC,MAAM,EAAE,oBAAoB;;IADrC,qBAAqB;IACZ,MAAM,EAAE,oBAAoB,EACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAKxC"}

package/dist/telemetry/query/telemetry-query.errors.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelemetryHttpError = exports.TELEMETRY_ERROR_REASONS = void 0;
+const common_1 = require("@nestjs/common");
+// =============================================================================
+// HTTP failures of the telemetry explorer (issue #535, epic #528)
+// =============================================================================
+//
+// The error envelope derives `code` from the status (docs/API.md), so the
+// machine-readable reason travels in `details.reason`, exactly like
+// `AI_DISABLED`. One status per reason:
+//
+//   TELEMETRY_NOT_CONFIGURED  503  no telemetry store in this deployment (the
+//                                  overlay is not deployed). 503 rather than
+//                                  404: the ROUTE exists, the service behind
+//                                  it does not — and `GET …/status` already
+//                                  reports `configured: false` with a 200.
+//   TELEMETRY_UNREACHABLE     503  configured, but the store did not answer.
+//   TELEMETRY_DISABLED        409  `telemetry.enabled` is off — a state an
+//                                  administrator can change (same status the
+//                                  AI kill switch's admin-facing errors use for
+//                                  "the configuration forbids this now").
+//   TELEMETRY_QUERY_REJECTED  400  the SQL guard refused the statement.
+//   TELEMETRY_QUERY_FAILED    400  GreptimeDB refused or failed the statement
+//                                  (syntax, unknown column, not permitted).
+//                                  The message is the server's own: it is
+//                                  about the caller's SQL and carries no
+//                                  credential.
+//   TELEMETRY_QUERY_TIMEOUT   504  the statement outran
+//                                  `telemetry.query.timeoutSeconds`.
+//
+// The assistant (#536) adds two, both 409 for the same reason as DISABLED
+// (an administrator can change the configuration that forbids this):
+//
+//   TELEMETRY_ASSISTANT_DISABLED        409  `telemetry.assistant.enabled` is off.
+//   TELEMETRY_ASSISTANT_NOT_CONFIGURED  409  no `assistant.provider`/`modelId`.
+//
+// The dashboard (#577) adds two request errors:
+//
+//   TELEMETRY_DASHBOARD_BAD_FILTER  400  `service`/`instance` is not among the
+//                                        values seen in the requested range.
+//   TELEMETRY_DASHBOARD_BAD_CURSOR  400  the events `cursor` is malformed.
+// =============================================================================
+/**
+ * The `details.reason` of every telemetry error (see the table above).
+ *
+ * @stability stable
+ */
+exports.TELEMETRY_ERROR_REASONS = {
+    /** 503: no telemetry store is configured. */
+    NOT_CONFIGURED: 'TELEMETRY_NOT_CONFIGURED',
+    /** 503: the store did not answer. */
+    UNREACHABLE: 'TELEMETRY_UNREACHABLE',
+    /** 409: `telemetry.enabled` is off. */
+    DISABLED: 'TELEMETRY_DISABLED',
+    /** 400: the SQL guard refused the statement. */
+    QUERY_REJECTED: 'TELEMETRY_QUERY_REJECTED',
+    /** 400: the store refused the statement. */
+    QUERY_FAILED: 'TELEMETRY_QUERY_FAILED',
+    /** 504: the statement timed out. */
+    QUERY_TIMEOUT: 'TELEMETRY_QUERY_TIMEOUT',
+    /** 409: `telemetry.assistant.enabled` is off. */
+    ASSISTANT_DISABLED: 'TELEMETRY_ASSISTANT_DISABLED',
+    /** 409: no assistant provider or model is selected. */
+    ASSISTANT_NOT_CONFIGURED: 'TELEMETRY_ASSISTANT_NOT_CONFIGURED',
+    /** 400: a dashboard filter value was not seen in the range. */
+    DASHBOARD_BAD_FILTER: 'TELEMETRY_DASHBOARD_BAD_FILTER',
+    /** 400: the events `cursor` is malformed. */
+    DASHBOARD_BAD_CURSOR: 'TELEMETRY_DASHBOARD_BAD_CURSOR',
+};
+const STATUS = {
+    TELEMETRY_NOT_CONFIGURED: common_1.HttpStatus.SERVICE_UNAVAILABLE,
+    TELEMETRY_UNREACHABLE: common_1.HttpStatus.SERVICE_UNAVAILABLE,
+    TELEMETRY_DISABLED: common_1.HttpStatus.CONFLICT,
+    TELEMETRY_QUERY_REJECTED: common_1.HttpStatus.BAD_REQUEST,
+    TELEMETRY_QUERY_FAILED: common_1.HttpStatus.BAD_REQUEST,
+    TELEMETRY_QUERY_TIMEOUT: common_1.HttpStatus.GATEWAY_TIMEOUT,
+    TELEMETRY_ASSISTANT_DISABLED: common_1.HttpStatus.CONFLICT,
+    TELEMETRY_ASSISTANT_NOT_CONFIGURED: common_1.HttpStatus.CONFLICT,
+    TELEMETRY_DASHBOARD_BAD_FILTER: common_1.HttpStatus.BAD_REQUEST,
+    TELEMETRY_DASHBOARD_BAD_CURSOR: common_1.HttpStatus.BAD_REQUEST,
+};
+/**
+ * A telemetry failure with its reason in `details.reason`; the HTTP status
+ * follows from the reason.
+ *
+ * @stability stable
+ */
+class TelemetryHttpError extends common_1.HttpException {
+    reason;
+    constructor(
+    /** Why it failed. */
+    reason, message, details = {}) {
+        // `reason` last, so a caller-supplied detail can never contradict it.
+        super({ message, details: { ...details, reason } }, STATUS[reason]);
+        this.reason = reason;
+    }
+}
+exports.TelemetryHttpError = TelemetryHttpError;
+//# sourceMappingURL=telemetry-query.errors.js.map

package/dist/telemetry/query/telemetry-query.errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-query.errors.js","sourceRoot":"","sources":["../../../src/telemetry/query/telemetry-query.errors.ts"],"names":[],"mappings":";;;AAAA,2CAA2D;AAE3D,gFAAgF;AAChF,kEAAkE;AAClE,gFAAgF;AAChF,EAAE;AACF,0EAA0E;AAC1E,oEAAoE;AACpE,wCAAwC;AACxC,EAAE;AACF,8EAA8E;AAC9E,6EAA6E;AAC7E,6EAA6E;AAC7E,4EAA4E;AAC5E,2EAA2E;AAC3E,6EAA6E;AAC7E,2EAA2E;AAC3E,6EAA6E;AAC7E,gFAAgF;AAChF,0EAA0E;AAC1E,wEAAwE;AACxE,8EAA8E;AAC9E,4EAA4E;AAC5E,0EAA0E;AAC1E,yEAAyE;AACzE,+CAA+C;AAC/C,wDAAwD;AACxD,qEAAqE;AACrE,EAAE;AACF,0EAA0E;AAC1E,qEAAqE;AACrE,EAAE;AACF,mFAAmF;AACnF,gFAAgF;AAChF,EAAE;AACF,gDAAgD;AAChD,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,2EAA2E;AAC3E,gFAAgF;AAEhF;;;;GAIG;AACU,QAAA,uBAAuB,GAAG;IACrC,6CAA6C;IAC7C,cAAc,EAAE,0BAA0B;IAC1C,qCAAqC;IACrC,WAAW,EAAE,uBAAuB;IACpC,uCAAuC;IACvC,QAAQ,EAAE,oBAAoB;IAC9B,gDAAgD;IAChD,cAAc,EAAE,0BAA0B;IAC1C,4CAA4C;IAC5C,YAAY,EAAE,wBAAwB;IACtC,oCAAoC;IACpC,aAAa,EAAE,yBAAyB;IACxC,iDAAiD;IACjD,kBAAkB,EAAE,8BAA8B;IAClD,uDAAuD;IACvD,wBAAwB,EAAE,oCAAoC;IAC9D,+DAA+D;IAC/D,oBAAoB,EAAE,gCAAgC;IACtD,6CAA6C;IAC7C,oBAAoB,EAAE,gCAAgC;CAC9C,CAAC;AASX,MAAM,MAAM,GAA6C;IACvD,wBAAwB,EAAE,mBAAU,CAAC,mBAAmB;IACxD,qBAAqB,EAAE,mBAAU,CAAC,mBAAmB;IACrD,kBAAkB,EAAE,mBAAU,CAAC,QAAQ;IACvC,wBAAwB,EAAE,mBAAU,CAAC,WAAW;IAChD,sBAAsB,EAAE,mBAAU,CAAC,WAAW;IAC9C,uBAAuB,EAAE,mBAAU,CAAC,eAAe;IACnD,4BAA4B,EAAE,mBAAU,CAAC,QAAQ;IACjD,kCAAkC,EAAE,mBAAU,CAAC,QAAQ;IACvD,8BAA8B,EAAE,mBAAU,CAAC,WAAW;IACtD,8BAA8B,EAAE,mBAAU,CAAC,WAAW;CACvD,CAAC;AAEF;;;;;GAKG;AACH,MAAa,kBAAmB,SAAQ,sBAAa;IAGxC;IAFX;IACE,qBAAqB;IACZ,MAA4B,EACrC,OAAe,EACf,UAAmC,EAAE;QAErC,sEAAsE;QACtE,KAAK,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QAL3D,WAAM,GAAN,MAAM,CAAsB;IAMvC,CAAC;CACF;AAVD,gDAUC"}

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

@@ -0,0 +1,57 @@
+import type { TelemetryColumnType, TelemetryQueryRunResult } from '../dto/telemetry-query.dto';
+import { GreptimeClient } from '../greptime/greptime.client';
+import { type TelemetryAuditSink } from '../ports';
+import { TelemetrySettingsService } from '../telemetry-settings.service';
+/**
+ * Who runs a statement; chooses the audit action.
+ *
+ * @stability experimental
+ */
+export type TelemetryQuerySource = 'explorer' | 'assistant' | 'export';
+/**
+ * How `TelemetryQueryService.run` runs one statement.
+ *
+ * @stability experimental
+ */
+export interface TelemetryQueryRunOptions {
+    /** Row cap for this call; clamped to `telemetry.query.maxRows`, which is also the default. */
+    maxRows?: number;
+    /** Who is asking. Chooses the audit action. Default `explorer`. */
+    source?: TelemetryQuerySource;
+    /** Abandons the statement when aborted (the assistant's client went away, #536). */
+    signal?: AbortSignal;
+}
+/** Audit `action` per source. */
+export declare const TELEMETRY_QUERY_AUDIT_ACTIONS: Record<TelemetryQuerySource, string>;
+/** How much of the SQL text an audit row keeps. */
+export declare const TELEMETRY_AUDIT_SQL_MAX = 4000;
+export declare function columnTypeName(dataTypeID: number): TelemetryColumnType;
+/**
+ * A wire value as something `JSON.stringify` reproduces faithfully:
+ * Buffer → base64, bigint → decimal string, Date → ISO string, non-finite
+ * number → its name (JSON would silently turn it into null), arrays and
+ * plain objects recursively. `int8`/`numeric`/timestamps already arrive as
+ * strings from `GreptimeClient` and stay that way.
+ */
+export declare function toJsonSafe(value: unknown): unknown;
+/**
+ * The one entry point for caller-supplied SQL (the explorer, the export and
+ * the assistant): the SQL guard, the row cap, the timeout and an audit row.
+ * Exported by `TelemetryModule`.
+ *
+ * @stability experimental
+ */
+export declare class TelemetryQueryService {
+    private readonly greptime;
+    private readonly settings;
+    private readonly auditSink;
+    private readonly logger;
+    constructor(greptime: GreptimeClient, settings: TelemetrySettingsService, auditSink: TelemetryAuditSink);
+    /**
+     * Runs one read-only statement for `userId`. Throws `TelemetryHttpError`
+     * (see `telemetry-query.errors.ts`) for every expected failure.
+     */
+    run(userId: string, sql: string, opts?: TelemetryQueryRunOptions): Promise<TelemetryQueryRunResult>;
+    private audit;
+}
+//# sourceMappingURL=telemetry-query.service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-query.service.d.ts","sourceRoot":"","sources":["../../../src/telemetry/query/telemetry-query.service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAC/F,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACzE,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAmCzE;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEvE;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,oFAAoF;IACpF,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,iCAAiC;AACjC,eAAO,MAAM,6BAA6B,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAI9E,CAAC;AAEF,mDAAmD;AACnD,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAsB7C,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,mBAAmB,CAEtE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAuBlD;AAED;;;;;;GAMG;AACH,qBACa,qBAAqB;IAI9B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACK,OAAO,CAAC,QAAQ,CAAC,SAAS;IAL1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;gBAG9C,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,wBAAwB,EACJ,SAAS,EAAE,kBAAkB;IAG9E;;;OAGG;IACG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,wBAA6B,GAAG,OAAO,CAAC,uBAAuB,CAAC;YAuE/F,KAAK;CAmBpB"}