postgresai 0.14.0-dev.52 → 0.14.0-dev.54

package/lib/auth-server.ts

@@ -14,6 +14,7 @@ export interface CallbackResult {
 export interface CallbackServer {
   server: { stop: () => void };
   promise: Promise<CallbackResult>;
+  ready: Promise<number>; // Resolves with actual port when server is listening
   getPort: () => number;
 }
 
@@ -38,9 +39,12 @@ function escapeHtml(str: string | null): string {
  * @param port - Port to listen on (0 for random available port)
  * @param expectedState - Expected state parameter for CSRF protection
  * @param timeoutMs - Timeout in milliseconds
- * @returns Server object with promise and getPort function
+ * @returns Server object with promise, ready promise, and getPort function
  *
  * @remarks
+ * The `ready` promise resolves with the actual port once the server is listening.
+ * Callers should await `ready` before using `getPort()` when using port 0.
+ *
  * The server stops asynchronously ~100ms after the callback resolves/rejects.
  * This delay ensures the HTTP response is fully sent before closing the connection.
  * Callers should not attempt to reuse the same port immediately after the promise
@@ -55,6 +59,8 @@ export function createCallbackServer(
   let actualPort = port;
   let resolveCallback: (value: CallbackResult) => void;
   let rejectCallback: (reason: Error) => void;
+  let resolveReady: (port: number) => void;
+  let rejectReady: (reason: Error) => void;
   let serverInstance: http.Server | null = null;
 
   const promise = new Promise<CallbackResult>((resolve, reject) => {
@@ -62,7 +68,19 @@ export function createCallbackServer(
     rejectCallback = reject;
   });
 
+  const ready = new Promise<number>((resolve, reject) => {
+    resolveReady = resolve;
+    rejectReady = reject;
+  });
+
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+
   const stopServer = () => {
+    // Clear timeout to prevent it firing after manual stop
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
     if (serverInstance) {
       serverInstance.close();
       serverInstance = null;
@@ -70,9 +88,10 @@ export function createCallbackServer(
   };
 
   // Timeout handler
-  const timeout = setTimeout(() => {
+  timeoutId = setTimeout(() => {
     if (!resolved) {
       resolved = true;
+      timeoutId = null; // Already fired, clear reference
       stopServer();
       rejectCallback(new Error("Authentication timeout. Please try again."));
     }
@@ -102,7 +121,10 @@ export function createCallbackServer(
     // Handle OAuth error
     if (error) {
       resolved = true;
-      clearTimeout(timeout);
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+      }
 
       setTimeout(() => stopServer(), 100);
       rejectCallback(new Error(`OAuth error: ${error}${errorDescription ? ` - ${errorDescription}` : ""}`));
@@ -162,7 +184,10 @@ export function createCallbackServer(
     // Validate state (CSRF protection)
     if (expectedState && state !== expectedState) {
       resolved = true;
-      clearTimeout(timeout);
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+      }
 
       setTimeout(() => stopServer(), 100);
       rejectCallback(new Error("State mismatch (possible CSRF attack)"));
@@ -193,7 +218,10 @@ export function createCallbackServer(
 
     // Success!
     resolved = true;
-    clearTimeout(timeout);
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
 
     // Resolve first, then stop server asynchronously after response is sent.
     // The 100ms delay ensures the HTTP response is fully written before closing.
@@ -223,16 +251,35 @@ export function createCallbackServer(
     `);
   });
 
+  // Handle server errors (e.g., EADDRINUSE)
+  serverInstance.on("error", (err: NodeJS.ErrnoException) => {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+    if (err.code === "EADDRINUSE") {
+      rejectReady(new Error(`Port ${port} is already in use`));
+    } else {
+      rejectReady(new Error(`Server error: ${err.message}`));
+    }
+    if (!resolved) {
+      resolved = true;
+      rejectCallback(err);
+    }
+  });
+
   serverInstance.listen(port, "127.0.0.1", () => {
     const address = serverInstance?.address();
     if (address && typeof address === "object") {
       actualPort = address.port;
     }
+    resolveReady(actualPort);
   });
 
   return {
     server: { stop: stopServer },
     promise,
+    ready,
     getPort: () => actualPort,
   };
 }

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 };
+}