postgresai 0.14.0-dev.8 → 0.14.0-dev.81

package/lib/checkup-api.ts

@@ -0,0 +1,386 @@
+import * as https from "https";
+import { URL } from "url";
+import { normalizeBaseUrl } from "./util";
+
+/**
+ * Retry configuration for network operations
+ */
+export interface RetryConfig {
+  maxAttempts: number;
+  initialDelayMs: number;
+  maxDelayMs: number;
+  backoffMultiplier: number;
+}
+
+const DEFAULT_RETRY_CONFIG: RetryConfig = {
+  maxAttempts: 3,
+  initialDelayMs: 1000,
+  maxDelayMs: 10000,
+  backoffMultiplier: 2,
+};
+
+/**
+ * Check if an error is retryable (network errors, timeouts, 5xx errors)
+ */
+function isRetryableError(err: unknown): boolean {
+  if (err instanceof RpcError) {
+    // Retry on server errors (5xx), not on client errors (4xx)
+    return err.statusCode >= 500 && err.statusCode < 600;
+  }
+  
+  // Check for Node.js error codes (works on Error and Error-like objects)
+  if (typeof err === "object" && err !== null && "code" in err) {
+    const code = String((err as { code: unknown }).code);
+    if (["ECONNRESET", "ECONNREFUSED", "ENOTFOUND", "ETIMEDOUT"].includes(code)) {
+      return true;
+    }
+  }
+  
+  if (err instanceof Error) {
+    const msg = err.message.toLowerCase();
+    // Retry on network-related errors based on message content
+    return (
+      msg.includes("timeout") ||
+      msg.includes("timed out") ||
+      msg.includes("econnreset") ||
+      msg.includes("econnrefused") ||
+      msg.includes("enotfound") ||
+      msg.includes("socket hang up") ||
+      msg.includes("network")
+    );
+  }
+  
+  return false;
+}
+
+/**
+ * Execute an async function with exponential backoff retry.
+ * Retries on network errors, timeouts, and 5xx server errors.
+ * Does not retry on 4xx client errors.
+ *
+ * @param fn - Async function to execute
+ * @param config - Optional retry configuration (uses defaults if not provided)
+ * @param onRetry - Optional callback invoked before each retry attempt
+ * @returns Promise resolving to the function result
+ * @throws The last error if all retry attempts fail or error is non-retryable
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => fetchData(),
+ *   { maxAttempts: 3 },
+ *   (attempt, err, delay) => console.log(`Retry ${attempt}, waiting ${delay}ms`)
+ * );
+ * ```
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  config: Partial<RetryConfig> = {},
+  onRetry?: (attempt: number, error: unknown, delayMs: number) => void
+): Promise<T> {
+  const { maxAttempts, initialDelayMs, maxDelayMs, backoffMultiplier } = {
+    ...DEFAULT_RETRY_CONFIG,
+    ...config,
+  };
+
+  let lastError: unknown;
+  let delayMs = initialDelayMs;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+
+      if (attempt === maxAttempts || !isRetryableError(err)) {
+        throw err;
+      }
+
+      if (onRetry) {
+        onRetry(attempt, err, delayMs);
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+      delayMs = Math.min(delayMs * backoffMultiplier, maxDelayMs);
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * Error thrown when an RPC call to the PostgresAI API fails.
+ * Contains detailed information about the failure for debugging and display.
+ */
+export class RpcError extends Error {
+  /** Name of the RPC endpoint that failed */
+  rpcName: string;
+  /** HTTP status code returned by the server */
+  statusCode: number;
+  /** Raw response body text */
+  payloadText: string;
+  /** Parsed JSON response body, or null if parsing failed */
+  payloadJson: any | null;
+
+  constructor(params: { rpcName: string; statusCode: number; payloadText: string; payloadJson: any | null }) {
+    const { rpcName, statusCode, payloadText, payloadJson } = params;
+    super(`RPC ${rpcName} failed: HTTP ${statusCode}`);
+    this.name = "RpcError";
+    this.rpcName = rpcName;
+    this.statusCode = statusCode;
+    this.payloadText = payloadText;
+    this.payloadJson = payloadJson;
+  }
+}
+
+/**
+ * Format an RpcError for human-readable console display.
+ * Extracts message, details, and hint from the error payload if available.
+ *
+ * @param err - The RpcError to format
+ * @returns Array of lines suitable for console output
+ */
+export function formatRpcErrorForDisplay(err: RpcError): string[] {
+  const lines: string[] = [];
+  lines.push(`Error: RPC ${err.rpcName} failed: HTTP ${err.statusCode}`);
+
+  const obj = err.payloadJson && typeof err.payloadJson === "object" ? err.payloadJson : null;
+  const details = obj && typeof (obj as any).details === "string" ? (obj as any).details : "";
+  const hint = obj && typeof (obj as any).hint === "string" ? (obj as any).hint : "";
+  const message = obj && typeof (obj as any).message === "string" ? (obj as any).message : "";
+
+  if (message) lines.push(`Message: ${message}`);
+  if (details) lines.push(`Details: ${details}`);
+  if (hint) lines.push(`Hint: ${hint}`);
+
+  // Fallback to raw payload if we couldn't extract anything useful.
+  if (!message && !details && !hint) {
+    const t = (err.payloadText || "").trim();
+    if (t) lines.push(t);
+  }
+  return lines;
+}
+
+function unwrapRpcResponse(parsed: unknown): any {
+  // Some deployments return a plain object, others return an array of rows,
+  // and some wrap OUT params under a "result" key.
+  if (Array.isArray(parsed)) {
+    if (parsed.length === 1) return unwrapRpcResponse(parsed[0]);
+    return parsed;
+  }
+  if (parsed && typeof parsed === "object") {
+    const obj = parsed as any;
+    if (obj.result !== undefined) return obj.result;
+  }
+  return parsed as any;
+}
+
+// Default timeout for HTTP requests (30 seconds)
+const HTTP_TIMEOUT_MS = 30_000;
+
+async function postRpc<T>(params: {
+  apiKey: string;
+  apiBaseUrl: string;
+  rpcName: string;
+  bodyObj: Record<string, unknown>;
+  timeoutMs?: number;
+}): Promise<T> {
+  const { apiKey, apiBaseUrl, rpcName, bodyObj, timeoutMs = HTTP_TIMEOUT_MS } = params;
+  if (!apiKey) throw new Error("API key is required");
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/rpc/${rpcName}`);
+  const body = JSON.stringify(bodyObj);
+
+  const headers: Record<string, string> = {
+    // API key is sent in BOTH header and body (see bodyObj.access_token):
+    // - Header: Used by the API gateway/proxy for HTTP authentication
+    // - Body: Passed to PostgreSQL RPC function for in-database authorization
+    // This is intentional for defense-in-depth; backend validates both.
+    "access-token": apiKey,
+    "Prefer": "return=representation",
+    "Content-Type": "application/json",
+    "Content-Length": Buffer.byteLength(body).toString(),
+  };
+
+  // Use AbortController for clean timeout handling
+  const controller = new AbortController();
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+  let settled = false;
+
+  return new Promise((resolve, reject) => {
+    const settledReject = (err: Error) => {
+      if (settled) return;
+      settled = true;
+      if (timeoutId) clearTimeout(timeoutId);
+      reject(err);
+    };
+
+    const settledResolve = (value: T) => {
+      if (settled) return;
+      settled = true;
+      if (timeoutId) clearTimeout(timeoutId);
+      resolve(value);
+    };
+
+    const req = https.request(
+      url,
+      {
+        method: "POST",
+        headers,
+        signal: controller.signal,
+      },
+      (res) => {
+        // Response started (headers received) - clear the connection timeout.
+        // Once the server starts responding, we let it complete rather than
+        // timing out mid-response which would cause confusing errors.
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+          timeoutId = null;
+        }
+        let data = "";
+        res.on("data", (chunk) => (data += chunk));
+        res.on("end", () => {
+          if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+            try {
+              const parsed = JSON.parse(data);
+              settledResolve(unwrapRpcResponse(parsed) as T);
+            } catch {
+              settledReject(new Error(`Failed to parse RPC response: ${data}`));
+            }
+          } else {
+            const statusCode = res.statusCode || 0;
+            let payloadJson: any | null = null;
+            if (data) {
+              try {
+                payloadJson = JSON.parse(data);
+              } catch {
+                payloadJson = null;
+              }
+            }
+            settledReject(new RpcError({ rpcName, statusCode, payloadText: data, payloadJson }));
+          }
+        });
+        res.on("error", (err) => {
+          settledReject(err);
+        });
+      }
+    );
+
+    // Set up connection timeout - applies until response headers are received.
+    // Once response starts, timeout is cleared (see response callback above).
+    timeoutId = setTimeout(() => {
+      controller.abort();
+      req.destroy();  // Backup: ensure request is terminated
+      settledReject(new Error(`RPC ${rpcName} timed out after ${timeoutMs}ms (no response)`));
+    }, timeoutMs);
+    
+    req.on("error", (err: Error) => {
+      // Handle abort as timeout (may already be rejected by timeout handler)
+      if (err.name === "AbortError" || (err as any).code === "ABORT_ERR") {
+        settledReject(new Error(`RPC ${rpcName} timed out after ${timeoutMs}ms`));
+        return;
+      }
+      // Provide clearer error for common network issues
+      if ((err as any).code === "ECONNREFUSED") {
+        settledReject(new Error(`RPC ${rpcName} failed: connection refused to ${url.host}`));
+      } else if ((err as any).code === "ENOTFOUND") {
+        settledReject(new Error(`RPC ${rpcName} failed: DNS lookup failed for ${url.host}`));
+      } else if ((err as any).code === "ECONNRESET") {
+        settledReject(new Error(`RPC ${rpcName} failed: connection reset by server`));
+      } else {
+        settledReject(err);
+      }
+    });
+    
+    req.write(body);
+    req.end();
+  });
+}
+
+/**
+ * Create a new checkup report in the PostgresAI backend.
+ * This creates the parent report container; individual check results
+ * are uploaded separately via uploadCheckupReportJson().
+ *
+ * @param params - Configuration for report creation
+ * @param params.apiKey - PostgresAI API access token
+ * @param params.apiBaseUrl - Base URL of the PostgresAI API
+ * @param params.project - Project name or ID to associate the report with
+ * @param params.status - Optional initial status for the report
+ * @returns Promise resolving to the created report ID
+ * @throws {RpcError} On API failures (4xx/5xx responses)
+ * @throws {Error} On network errors or unexpected response format
+ */
+export async function createCheckupReport(params: {
+  apiKey: string;
+  apiBaseUrl: string;
+  project: string;
+  status?: string;
+}): Promise<{ reportId: number }> {
+  const { apiKey, apiBaseUrl, project, status } = params;
+  const bodyObj: Record<string, unknown> = {
+    access_token: apiKey,
+    project,
+  };
+  if (status) bodyObj.status = status;
+
+  const resp = await postRpc<any>({
+    apiKey,
+    apiBaseUrl,
+    rpcName: "checkup_report_create",
+    bodyObj,
+  });
+  const reportId = Number(resp?.report_id);
+  if (!Number.isFinite(reportId) || reportId <= 0) {
+    throw new Error(`Unexpected checkup_report_create response: ${JSON.stringify(resp)}`);
+  }
+  return { reportId };
+}
+
+/**
+ * Upload a JSON check result to an existing checkup report.
+ * Each check (e.g., H001, A003) is uploaded as a separate JSON file.
+ *
+ * @param params - Configuration for the upload
+ * @param params.apiKey - PostgresAI API access token
+ * @param params.apiBaseUrl - Base URL of the PostgresAI API
+ * @param params.reportId - ID of the parent report (from createCheckupReport)
+ * @param params.filename - Filename for the uploaded JSON (e.g., "H001.json")
+ * @param params.checkId - Check identifier (e.g., "H001", "A003")
+ * @param params.jsonText - JSON content as a string
+ * @returns Promise resolving to the created report chunk ID
+ * @throws {RpcError} On API failures (4xx/5xx responses)
+ * @throws {Error} On network errors or unexpected response format
+ */
+export async function uploadCheckupReportJson(params: {
+  apiKey: string;
+  apiBaseUrl: string;
+  reportId: number;
+  filename: string;
+  checkId: string;
+  jsonText: string;
+}): Promise<{ reportChunkId: number }> {
+  const { apiKey, apiBaseUrl, reportId, filename, checkId, jsonText } = params;
+  const bodyObj: Record<string, unknown> = {
+    access_token: apiKey,
+    checkup_report_id: reportId,
+    filename,
+    check_id: checkId,
+    data: jsonText,
+    type: "json",
+    generate_issue: true,
+  };
+
+  const resp = await postRpc<any>({
+    apiKey,
+    apiBaseUrl,
+    rpcName: "checkup_report_file_post",
+    bodyObj,
+  });
+  // Backend has a typo: "report_chunck_id" (with 'ck') - handle both spellings for compatibility
+  const chunkId = Number(resp?.report_chunck_id ?? resp?.report_chunk_id);
+  if (!Number.isFinite(chunkId) || chunkId <= 0) {
+    throw new Error(`Unexpected checkup_report_file_post response: ${JSON.stringify(resp)}`);
+  }
+  return { reportChunkId: chunkId };
+}

package/lib/checkup-dictionary.ts

@@ -0,0 +1,113 @@
+/**
+ * Checkup Dictionary Module
+ * =========================
+ * Provides access to the checkup report dictionary data embedded at build time.
+ *
+ * The dictionary is fetched from https://postgres.ai/api/general/checkup_dictionary
+ * during the build process and embedded into checkup-dictionary-embedded.ts.
+ *
+ * This ensures no API calls are made at runtime while keeping the data up-to-date.
+ */
+
+import { CHECKUP_DICTIONARY_DATA } from "./checkup-dictionary-embedded";
+
+/**
+ * A checkup dictionary entry describing a single check type.
+ */
+export interface CheckupDictionaryEntry {
+  /** Unique check code (e.g., "A001", "H002") */
+  code: string;
+  /** Human-readable title for the check */
+  title: string;
+  /** Brief description of what the check covers */
+  description: string;
+  /** Category grouping (e.g., "system", "indexes", "vacuum") */
+  category: string;
+  /** Optional sort order within category */
+  sort_order: number | null;
+  /** Whether this is a system-level report */
+  is_system_report: boolean;
+}
+
+/**
+ * Module-level cache for O(1) lookups by code.
+ * Initialized at module load time from embedded data.
+ */
+const dictionaryByCode: Map<string, CheckupDictionaryEntry> = new Map(
+  CHECKUP_DICTIONARY_DATA.map((entry) => [entry.code, entry])
+);
+
+/**
+ * Get all checkup dictionary entries.
+ *
+ * @returns Array of all checkup dictionary entries
+ */
+export function getAllCheckupEntries(): CheckupDictionaryEntry[] {
+  return CHECKUP_DICTIONARY_DATA;
+}
+
+/**
+ * Get a checkup dictionary entry by its code.
+ *
+ * @param code - The check code (e.g., "A001", "H002")
+ * @returns The dictionary entry or null if not found
+ */
+export function getCheckupEntry(code: string): CheckupDictionaryEntry | null {
+  return dictionaryByCode.get(code.toUpperCase()) ?? null;
+}
+
+/**
+ * Get the title for a checkup code.
+ *
+ * @param code - The check code (e.g., "A001", "H002")
+ * @returns The title or the code itself if not found
+ */
+export function getCheckupTitle(code: string): string {
+  const entry = getCheckupEntry(code);
+  return entry?.title ?? code;
+}
+
+/**
+ * Check if a code exists in the dictionary.
+ *
+ * @param code - The check code to validate
+ * @returns True if the code exists in the dictionary
+ */
+export function isValidCheckupCode(code: string): boolean {
+  return dictionaryByCode.has(code.toUpperCase());
+}
+
+/**
+ * Get all check codes as an array.
+ *
+ * @returns Array of all check codes (e.g., ["A001", "A002", ...])
+ */
+export function getAllCheckupCodes(): string[] {
+  return CHECKUP_DICTIONARY_DATA.map((entry) => entry.code);
+}
+
+/**
+ * Get checkup entries filtered by category.
+ *
+ * @param category - The category to filter by (e.g., "indexes", "vacuum")
+ * @returns Array of entries in the specified category
+ */
+export function getCheckupEntriesByCategory(category: string): CheckupDictionaryEntry[] {
+  return CHECKUP_DICTIONARY_DATA.filter(
+    (entry) => entry.category.toLowerCase() === category.toLowerCase()
+  );
+}
+
+/**
+ * Build a code-to-title mapping object.
+ * Useful for backwards compatibility with CHECK_INFO style usage.
+ *
+ * @returns Object mapping check codes to titles (e.g., { "A001": "System information", ... })
+ */
+export function buildCheckInfoMap(): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const entry of CHECKUP_DICTIONARY_DATA) {
+    result[entry.code] = entry.title;
+  }
+  return result;
+}