taurusdb-core 0.1.0

package/dist/diagnostics/slow-sql-source/parsers.js

@@ -0,0 +1,125 @@
+import { parseDurationMs, readNumber, readString, secondsToMs } from "./utils.js";
+export function pickArrayCandidate(payload) {
+    if (!payload || typeof payload !== "object") {
+        return [];
+    }
+    const record = payload;
+    for (const key of [
+        "slow_log_list",
+        "slow_log_statistics",
+        "slow_log_statistic_list",
+        "items",
+        "records",
+    ]) {
+        const value = record[key];
+        if (Array.isArray(value)) {
+            return value.filter((item) => item !== null && typeof item === "object" && !Array.isArray(item));
+        }
+    }
+    return [];
+}
+export function parseStatisticsCandidate(item, rawRef) {
+    const sql = readString(item.query_sample) ?? readString(item.sql_statement);
+    if (!sql) {
+        return undefined;
+    }
+    return {
+        sql,
+        database: readString(item.database),
+        user: readString(item.users) ?? readString(item.user),
+        clientIp: readString(item.client_ip),
+        startTime: readString(item.start_at) ?? readString(item.time),
+        execCount: readNumber(item.count),
+        avgLatencyMs: parseDurationMs(item.execute_time) ?? parseDurationMs(item.avg_query_time),
+        avgLockTimeMs: parseDurationMs(item.lock_time),
+        avgRowsExamined: readNumber(item.rows_examined),
+        rowsSent: readNumber(item.rows_sent),
+        rawRef,
+    };
+}
+export function parseDetailCandidate(item, rawRef) {
+    const sql = readString(item.query_sample) ?? readString(item.sql_statement);
+    if (!sql) {
+        return undefined;
+    }
+    return {
+        sql,
+        database: readString(item.database),
+        user: readString(item.user),
+        clientIp: readString(item.client_ip),
+        startTime: readString(item.start_at) ?? readString(item.time),
+        execCount: 1,
+        avgLatencyMs: parseDurationMs(item.query_time) ?? parseDurationMs(item.execute_time),
+        avgLockTimeMs: parseDurationMs(item.lock_time),
+        avgRowsExamined: readNumber(item.rows_examined),
+        rowsSent: readNumber(item.rows_sent),
+        rawRef,
+    };
+}
+export function parseDasSlowLogCandidate(item, rawRef) {
+    const sql = readString(item.sql) ??
+        readString(item.query) ??
+        readString(item.sql_statement) ??
+        readString(item.template);
+    if (!sql) {
+        return undefined;
+    }
+    return {
+        sql,
+        database: readString(item.database) ??
+            readString(item.db_name) ??
+            readString(item.databases),
+        user: readString(item.users) ?? readString(item.user),
+        clientIp: readString(item.client_ip),
+        startTime: readString(item.start_at) ??
+            readString(item.time) ??
+            readString(item.timestamp),
+        execCount: readNumber(item.count) ?? 1,
+        avgLatencyMs: secondsToMs(item.query_time) ??
+            parseDurationMs(item.query_time_ms) ??
+            secondsToMs(item.avg_query_time),
+        avgLockTimeMs: secondsToMs(item.lock_time) ?? parseDurationMs(item.lock_time_ms),
+        avgRowsExamined: readNumber(item.rows_examined),
+        rowsSent: readNumber(item.rows_sent),
+        rawRef,
+    };
+}
+export function parseDasSqlStatementCandidate(item, rawRef) {
+    const sql = readString(item.sql) ??
+        readString(item.sql_statement) ??
+        readString(item.query);
+    if (!sql) {
+        return undefined;
+    }
+    return {
+        sql,
+        database: readString(item.database) ??
+            readString(item.db_name) ??
+            readString(item.schema_name),
+        user: readString(item.user) ?? readString(item.users),
+        clientIp: readString(item.client_ip),
+        startTime: readString(item.start_at) ??
+            readString(item.time) ??
+            readString(item.timestamp),
+        execCount: 1,
+        avgLatencyMs: parseDurationMs(item.query_time) ??
+            secondsToMs(item.query_time_second) ??
+            parseDurationMs(item.duration),
+        avgLockTimeMs: parseDurationMs(item.lock_time) ?? secondsToMs(item.lock_time_second),
+        avgRowsExamined: readNumber(item.rows_examined),
+        rowsSent: readNumber(item.rows_sent),
+        rawRef,
+    };
+}
+export function pickDasTopSlowArrays(payload) {
+    const arrays = [
+        payload.top_execute_slow_logs,
+        payload.top_avg_query_time_slow_logs,
+        payload.top_max_query_time_slow_logs,
+        payload.top_returned_rows_slow_logs,
+        payload.top_rows_examined_slow_logs,
+    ];
+    return arrays.flatMap((value) => Array.isArray(value)
+        ? value.filter((item) => item !== null && typeof item === "object" && !Array.isArray(item))
+        : []);
+}

package/dist/diagnostics/slow-sql-source/taurus-api-source.d.ts

@@ -0,0 +1,42 @@
+import type { SessionContext } from "../../context/session-context.js";
+import type { FindTopSlowSqlInput } from "../types.js";
+import type { ExternalSlowSqlSample, ResolveSlowSqlInput, SlowSqlSource } from "./types.js";
+type TaurusApiSlowSqlSourceOptions = {
+    endpoint: string;
+    projectId: string;
+    instanceId: string;
+    nodeId: string;
+    authToken?: string;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    securityToken?: string;
+    language: "en-us" | "zh-cn";
+    requestTimeoutMs: number;
+    defaultLookbackMinutes: number;
+    maxRecords: number;
+    fetchImpl?: typeof fetch;
+};
+export declare class TaurusApiSlowSqlSource implements SlowSqlSource {
+    private readonly endpoint;
+    private readonly projectId;
+    private readonly instanceId;
+    private readonly nodeId;
+    private readonly authToken?;
+    private readonly accessKeyId?;
+    private readonly secretAccessKey?;
+    private readonly securityToken?;
+    private readonly language;
+    private readonly requestTimeoutMs;
+    private readonly defaultLookbackMinutes;
+    private readonly maxRecords;
+    private readonly fetchImpl;
+    constructor(options: TaurusApiSlowSqlSourceOptions);
+    resolve(input: ResolveSlowSqlInput, ctx: SessionContext): Promise<ExternalSlowSqlSample | undefined>;
+    findTop(input: FindTopSlowSqlInput, ctx: SessionContext): Promise<ExternalSlowSqlSample[]>;
+    private fetchStatistics;
+    private fetchDetails;
+    private pickBestMatch;
+    private toExternalSample;
+    private postJson;
+}
+export {};

package/dist/diagnostics/slow-sql-source/taurus-api-source.js

@@ -0,0 +1,149 @@
+import { fetchHuaweiCloud } from "../../cloud/auth.js";
+import { candidateToExternalSample, normalizeTimeRange, parseResponse, scoreCandidate, sortExternalSamples } from "./utils.js";
+import { parseDetailCandidate, parseStatisticsCandidate, pickArrayCandidate } from "./parsers.js";
+export class TaurusApiSlowSqlSource {
+    endpoint;
+    projectId;
+    instanceId;
+    nodeId;
+    authToken;
+    accessKeyId;
+    secretAccessKey;
+    securityToken;
+    language;
+    requestTimeoutMs;
+    defaultLookbackMinutes;
+    maxRecords;
+    fetchImpl;
+    constructor(options) {
+        this.endpoint = options.endpoint.replace(/\/+$/g, "");
+        this.projectId = options.projectId;
+        this.instanceId = options.instanceId;
+        this.nodeId = options.nodeId;
+        this.authToken = options.authToken;
+        this.accessKeyId = options.accessKeyId;
+        this.secretAccessKey = options.secretAccessKey;
+        this.securityToken = options.securityToken;
+        this.language = options.language;
+        this.requestTimeoutMs = options.requestTimeoutMs;
+        this.defaultLookbackMinutes = options.defaultLookbackMinutes;
+        this.maxRecords = options.maxRecords;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async resolve(input, ctx) {
+        const timeWindow = normalizeTimeRange(input.timeRange, this.defaultLookbackMinutes);
+        const statisticCandidates = await this.fetchStatistics(timeWindow, ctx.database);
+        const matchedStatistic = this.pickBestMatch(statisticCandidates, input);
+        if (matchedStatistic) {
+            return this.toExternalSample(matchedStatistic, input);
+        }
+        const detailCandidates = await this.fetchDetails(timeWindow, ctx.database);
+        const matchedDetail = this.pickBestMatch(detailCandidates, input);
+        if (matchedDetail) {
+            return this.toExternalSample(matchedDetail, input);
+        }
+        return undefined;
+    }
+    async findTop(input, ctx) {
+        const timeWindow = normalizeTimeRange(input.timeRange, this.defaultLookbackMinutes);
+        const statisticCandidates = await this.fetchStatistics(timeWindow, ctx.database);
+        const samples = statisticCandidates
+            .map((candidate) => candidateToExternalSample(candidate, "taurus_api_slow_logs"))
+            .filter((value) => value !== undefined);
+        return sortExternalSamples(samples, input.sortBy).slice(0, Math.min(input.topN ?? 5, this.maxRecords));
+    }
+    async fetchStatistics(timeWindow, database) {
+        const path = `/v3/${this.projectId}/instances/${this.instanceId}/slow-logs/statistics`;
+        const payload = {
+            node_id: this.nodeId,
+            start_time: timeWindow.startTime,
+            end_time: timeWindow.endTime,
+            limit: this.maxRecords,
+            sort: "execute_time",
+            order: "desc",
+        };
+        if (database) {
+            payload.database = database;
+        }
+        const body = await this.postJson(path, payload);
+        return pickArrayCandidate(body)
+            .map((item) => parseStatisticsCandidate(item, `taurus_api:${path}`))
+            .filter((value) => value !== undefined);
+    }
+    async fetchDetails(timeWindow, database) {
+        const path = `/v3.1/${this.projectId}/instances/${this.instanceId}/slow-logs`;
+        const payload = {
+            node_id: this.nodeId,
+            start_time: timeWindow.startTime,
+            end_time: timeWindow.endTime,
+            offset: 0,
+            limit: this.maxRecords,
+        };
+        if (database) {
+            payload.database = database;
+        }
+        const body = await this.postJson(path, payload);
+        return pickArrayCandidate(body)
+            .map((item) => parseDetailCandidate(item, `taurus_api:${path}`))
+            .filter((value) => value !== undefined);
+    }
+    pickBestMatch(candidates, input) {
+        const scored = candidates
+            .map((candidate) => ({ candidate, score: scoreCandidate(candidate, input) }))
+            .sort((left, right) => right.score - left.score);
+        if (scored.length === 0) {
+            return undefined;
+        }
+        if (input.sqlHash || input.digestText) {
+            return scored[0].score > 0 ? scored[0].candidate : undefined;
+        }
+        return scored[0].candidate;
+    }
+    toExternalSample(candidate, input) {
+        const sample = candidateToExternalSample(candidate, "taurus_api_slow_logs");
+        if (!sample) {
+            return undefined;
+        }
+        return {
+            ...sample,
+            sqlHash: input.sqlHash ?? sample.sqlHash,
+            digestText: input.digestText ?? sample.digestText,
+        };
+    }
+    async postJson(path, payload) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+        try {
+            const body = JSON.stringify(payload);
+            const response = await fetchHuaweiCloud({
+                url: `${this.endpoint}${path}`,
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    "x-language": this.language,
+                },
+                body,
+                auth: {
+                    authToken: this.authToken,
+                    accessKeyId: this.accessKeyId,
+                    secretAccessKey: this.secretAccessKey,
+                    securityToken: this.securityToken,
+                },
+                fetchImpl: (input, init) => this.fetchImpl(input, {
+                    ...init,
+                    signal: controller.signal,
+                }),
+            });
+            if (!response.ok) {
+                return {};
+            }
+            return parseResponse(response);
+        }
+        catch {
+            return {};
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/diagnostics/slow-sql-source/types.d.ts

@@ -0,0 +1,40 @@
+import type { FindTopSlowSqlInput, DiagnosisWindow } from "../types.js";
+import type { SessionContext } from "../../context/session-context.js";
+export interface ResolveSlowSqlInput {
+    sqlHash?: string;
+    digestText?: string;
+    timeRange?: DiagnosisWindow;
+}
+export interface ExternalSlowSqlSample {
+    source: string;
+    sql: string;
+    sqlHash: string;
+    digestText?: string;
+    database?: string;
+    user?: string;
+    clientIp?: string;
+    startTime?: string;
+    execCount?: number;
+    avgLatencyMs?: number;
+    avgLockTimeMs?: number;
+    avgRowsExamined?: number;
+    rowsSent?: number;
+    rawRef?: string;
+}
+export interface SlowSqlSource {
+    resolve(input: ResolveSlowSqlInput, ctx: SessionContext): Promise<ExternalSlowSqlSample | undefined>;
+    findTop?(input: FindTopSlowSqlInput, ctx: SessionContext): Promise<ExternalSlowSqlSample[]>;
+}
+export type TaurusApiCandidate = {
+    sql?: string;
+    database?: string;
+    user?: string;
+    clientIp?: string;
+    startTime?: string;
+    execCount?: number;
+    avgLatencyMs?: number;
+    avgLockTimeMs?: number;
+    avgRowsExamined?: number;
+    rowsSent?: number;
+    rawRef?: string;
+};

package/dist/diagnostics/slow-sql-source/types.js

@@ -0,0 +1 @@
+export {};

package/dist/diagnostics/slow-sql-source/utils.d.ts

@@ -0,0 +1,20 @@
+import type { DiagnosisWindow, FindTopSlowSqlInput } from "../types.js";
+import type { ExternalSlowSqlSample, ResolveSlowSqlInput, TaurusApiCandidate } from "./types.js";
+export declare function readString(value: unknown): string | undefined;
+export declare function readNumber(value: unknown): number | undefined;
+export declare function normalizeTimeRange(input: DiagnosisWindow | undefined, defaultLookbackMinutes: number): {
+    startTime: string;
+    endTime: string;
+};
+export declare function parseRelativeLookback(value: string | undefined): number | undefined;
+export declare function formatTaurusApiTime(date: Date): string;
+export declare function formatUnixSeconds(date: Date): string;
+export declare function formatDigestTemplate(sql: string): string;
+export declare function parseDurationMs(value: unknown): number | undefined;
+export declare function secondsToMs(value: unknown): number | undefined;
+export declare function scoreCandidate(candidate: TaurusApiCandidate, input: ResolveSlowSqlInput): number;
+export declare function candidateToExternalSample(candidate: TaurusApiCandidate, source: string): ExternalSlowSqlSample | undefined;
+export declare function sortExternalSamples(samples: ExternalSlowSqlSample[], sortBy: FindTopSlowSqlInput["sortBy"]): ExternalSlowSqlSample[];
+export declare function parseResponse(response: Response): Promise<Record<string, unknown>>;
+export declare function buildQueryString(params: Record<string, string | number | undefined>): string;
+export declare function pickNextMarker(payload: Record<string, unknown>): string | undefined;

package/dist/diagnostics/slow-sql-source/utils.js

@@ -0,0 +1,170 @@
+import { normalizeSql, sqlHash } from "../../utils/hash.js";
+export function readString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+export function readNumber(value) {
+    return typeof value === "number"
+        ? value
+        : typeof value === "string" && value.trim().length > 0
+            ? Number.parseFloat(value)
+            : undefined;
+}
+export function normalizeTimeRange(input, defaultLookbackMinutes) {
+    const now = new Date();
+    const end = input?.to ? new Date(input.to) : now;
+    const parsedRelative = parseRelativeLookback(input?.relative);
+    const start = input?.from
+        ? new Date(input.from)
+        : parsedRelative
+            ? new Date(end.getTime() - parsedRelative)
+            : new Date(end.getTime() - defaultLookbackMinutes * 60_000);
+    return {
+        startTime: formatTaurusApiTime(start),
+        endTime: formatTaurusApiTime(end),
+    };
+}
+export function parseRelativeLookback(value) {
+    if (!value) {
+        return undefined;
+    }
+    const match = value.trim().match(/^(\d+)\s*([mhd])$/i);
+    if (!match) {
+        return undefined;
+    }
+    const amount = Number.parseInt(match[1], 10);
+    const unit = match[2].toLowerCase();
+    switch (unit) {
+        case "m":
+            return amount * 60_000;
+        case "h":
+            return amount * 3_600_000;
+        case "d":
+            return amount * 86_400_000;
+        default:
+            return undefined;
+    }
+}
+export function formatTaurusApiTime(date) {
+    const iso = date.toISOString();
+    return `${iso.slice(0, 19)}Z`;
+}
+export function formatUnixSeconds(date) {
+    return String(Math.floor(date.getTime() / 1000));
+}
+export function formatDigestTemplate(sql) {
+    const withoutStrings = sql.replace(/'(?:''|[^'])*'|"(?:[""]|[^"])*"/g, "?");
+    const withoutNumbers = withoutStrings.replace(/\b\d+(?:\.\d+)?\b/g, "?");
+    return normalizeSql(withoutNumbers);
+}
+export function parseDurationMs(value) {
+    if (typeof value === "number") {
+        return value;
+    }
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const match = value.trim().match(/^([\d.]+)\s*(ms|s|us|µs)?$/i);
+    if (!match) {
+        return undefined;
+    }
+    const amount = Number.parseFloat(match[1]);
+    const unit = (match[2] ?? "ms").toLowerCase();
+    switch (unit) {
+        case "s":
+            return amount * 1000;
+        case "us":
+        case "µs":
+            return amount / 1000;
+        default:
+            return amount;
+    }
+}
+export function secondsToMs(value) {
+    const parsed = readNumber(value);
+    return parsed === undefined ? undefined : parsed * 1000;
+}
+export function scoreCandidate(candidate, input) {
+    if (!candidate.sql) {
+        return -1;
+    }
+    const candidateHash = sqlHash(normalizeSql(candidate.sql));
+    const candidateDigest = formatDigestTemplate(candidate.sql);
+    let score = 0;
+    if (input.sqlHash && input.sqlHash === candidateHash) {
+        score += 100;
+    }
+    if (input.digestText && formatDigestTemplate(input.digestText) === candidateDigest) {
+        score += 90;
+    }
+    if (candidate.avgLatencyMs !== undefined) {
+        score += Math.min(candidate.avgLatencyMs / 100, 20);
+    }
+    return score;
+}
+export function candidateToExternalSample(candidate, source) {
+    if (!candidate.sql) {
+        return undefined;
+    }
+    return {
+        source,
+        sql: candidate.sql,
+        sqlHash: sqlHash(normalizeSql(candidate.sql)),
+        digestText: formatDigestTemplate(candidate.sql),
+        database: candidate.database,
+        user: candidate.user,
+        clientIp: candidate.clientIp,
+        startTime: candidate.startTime,
+        execCount: candidate.execCount,
+        avgLatencyMs: candidate.avgLatencyMs,
+        avgLockTimeMs: candidate.avgLockTimeMs,
+        avgRowsExamined: candidate.avgRowsExamined,
+        rowsSent: candidate.rowsSent,
+        rawRef: candidate.rawRef,
+    };
+}
+export function sortExternalSamples(samples, sortBy) {
+    return [...samples].sort((left, right) => {
+        const leftExecCount = left.execCount ?? 0;
+        const rightExecCount = right.execCount ?? 0;
+        const leftAvgLatency = left.avgLatencyMs ?? 0;
+        const rightAvgLatency = right.avgLatencyMs ?? 0;
+        const leftTotalLatency = leftAvgLatency * Math.max(leftExecCount, 1);
+        const rightTotalLatency = rightAvgLatency * Math.max(rightExecCount, 1);
+        const leftLockTime = left.avgLockTimeMs ?? 0;
+        const rightLockTime = right.avgLockTimeMs ?? 0;
+        switch (sortBy) {
+            case "avg_latency":
+                return (rightAvgLatency - leftAvgLatency ||
+                    rightTotalLatency - leftTotalLatency ||
+                    rightExecCount - leftExecCount);
+            case "exec_count":
+                return (rightExecCount - leftExecCount ||
+                    rightTotalLatency - leftTotalLatency ||
+                    rightAvgLatency - leftAvgLatency);
+            case "lock_time":
+                return (rightLockTime - leftLockTime ||
+                    rightTotalLatency - leftTotalLatency ||
+                    rightExecCount - leftExecCount);
+            default:
+                return (rightTotalLatency - leftTotalLatency ||
+                    rightAvgLatency - leftAvgLatency ||
+                    rightExecCount - leftExecCount);
+        }
+    });
+}
+export async function parseResponse(response) {
+    const payload = (await response.json());
+    return payload && typeof payload === "object" && !Array.isArray(payload)
+        ? payload
+        : {};
+}
+export function buildQueryString(params) {
+    const entries = Object.entries(params).filter((entry) => entry[1] !== undefined);
+    return new URLSearchParams(entries.map(([key, value]) => [key, String(value)])).toString();
+}
+export function pickNextMarker(payload) {
+    return readString(payload.next_marker ??
+        payload.nextMarker ??
+        payload.marker ??
+        payload.offset);
+}

package/dist/diagnostics/slow-sql-source.d.ts

@@ -0,0 +1,4 @@
+export type { ResolveSlowSqlInput, ExternalSlowSqlSample, SlowSqlSource } from "./slow-sql-source/types.js";
+export { TaurusApiSlowSqlSource } from "./slow-sql-source/taurus-api-source.js";
+export { DasSlowSqlSource } from "./slow-sql-source/das-source.js";
+export { buildResolveSlowSqlInput, createSlowSqlSource } from "./slow-sql-source/factory.js";

package/dist/diagnostics/slow-sql-source.js

@@ -0,0 +1,3 @@
+export { TaurusApiSlowSqlSource } from "./slow-sql-source/taurus-api-source.js";
+export { DasSlowSqlSource } from "./slow-sql-source/das-source.js";
+export { buildResolveSlowSqlInput, createSlowSqlSource } from "./slow-sql-source/factory.js";