@debros/network-ts-sdk 0.4.2 → 0.6.0

package/src/core/http.ts

@@ -1,11 +1,39 @@
 import { SDKError } from "../errors";
 
+/**
+ * Context provided to the onNetworkError callback
+ */
+export interface NetworkErrorContext {
+  method: "GET" | "POST" | "PUT" | "DELETE" | "WS";
+  path: string;
+  isRetry: boolean;
+  attempt: number;
+}
+
+/**
+ * Callback invoked when a network error occurs.
+ * Use this to trigger gateway failover or other error handling.
+ */
+export type NetworkErrorCallback = (
+  error: SDKError,
+  context: NetworkErrorContext
+) => void;
+
 export interface HttpClientConfig {
   baseURL: string;
   timeout?: number;
   maxRetries?: number;
   retryDelayMs?: number;
   fetch?: typeof fetch;
+  /**
+   * Enable debug logging (includes full SQL queries and args). Default: false
+   */
+  debug?: boolean;
+  /**
+   * Callback invoked on network errors (after all retries exhausted).
+   * Use this to trigger gateway failover at the application layer.
+   */
+  onNetworkError?: NetworkErrorCallback;
 }
 
 /**
@@ -39,6 +67,8 @@ export class HttpClient {
   private fetch: typeof fetch;
   private apiKey?: string;
   private jwt?: string;
+  private debug: boolean;
+  private onNetworkError?: NetworkErrorCallback;
 
   constructor(config: HttpClientConfig) {
     this.baseURL = config.baseURL.replace(/\/$/, "");
@@ -47,6 +77,15 @@ export class HttpClient {
     this.retryDelayMs = config.retryDelayMs ?? 1000;
     // Use provided fetch or create one with proper TLS configuration for staging certificates
     this.fetch = config.fetch ?? createFetchWithTLSConfig();
+    this.debug = config.debug ?? false;
+    this.onNetworkError = config.onNetworkError;
+  }
+
+  /**
+   * Set the network error callback
+   */
+  setOnNetworkError(callback: NetworkErrorCallback | undefined): void {
+    this.onNetworkError = callback;
   }
 
   setApiKey(apiKey?: string) {
@@ -223,7 +262,7 @@ export class HttpClient {
         const logMessage = `[HttpClient] ${method} ${path} completed in ${duration.toFixed(
           2
         )}ms`;
-        if (queryDetails) {
+        if (queryDetails && this.debug) {
           console.log(logMessage);
           console.log(`[HttpClient]   ${queryDetails}`);
         } else {
@@ -253,11 +292,32 @@ export class HttpClient {
             2
           )}ms:`;
           console.error(errorMessage, error);
-          if (queryDetails) {
+          if (queryDetails && this.debug) {
             console.error(`[HttpClient]   ${queryDetails}`);
           }
         }
       }
+
+      // Call the network error callback if configured
+      // This allows the app to trigger gateway failover
+      if (this.onNetworkError) {
+        // Convert native errors (TypeError, AbortError) to SDKError for the callback
+        const sdkError =
+          error instanceof SDKError
+            ? error
+            : new SDKError(
+                error instanceof Error ? error.message : String(error),
+                0, // httpStatus 0 indicates network-level failure
+                "NETWORK_ERROR"
+              );
+        this.onNetworkError(sdkError, {
+          method,
+          path,
+          isRetry: false,
+          attempt: this.maxRetries, // All retries exhausted
+        });
+      }
+
       throw error;
     } finally {
       clearTimeout(timeoutId);
@@ -397,6 +457,25 @@ export class HttpClient {
           error
         );
       }
+
+      // Call the network error callback if configured
+      if (this.onNetworkError) {
+        const sdkError =
+          error instanceof SDKError
+            ? error
+            : new SDKError(
+                error instanceof Error ? error.message : String(error),
+                0,
+                "NETWORK_ERROR"
+              );
+        this.onNetworkError(sdkError, {
+          method: "POST",
+          path,
+          isRetry: false,
+          attempt: this.maxRetries,
+        });
+      }
+
       throw error;
     } finally {
       clearTimeout(timeoutId);
@@ -425,17 +504,33 @@ export class HttpClient {
       const response = await this.fetch(url.toString(), fetchOptions);
       if (!response.ok) {
         clearTimeout(timeoutId);
-        const error = await response.json().catch(() => ({
+        const errorBody = await response.json().catch(() => ({
           error: response.statusText,
         }));
-        throw SDKError.fromResponse(response.status, error);
+        throw SDKError.fromResponse(response.status, errorBody);
       }
       return response;
     } catch (error) {
       clearTimeout(timeoutId);
-      if (error instanceof SDKError) {
-        throw error;
+
+      // Call the network error callback if configured
+      if (this.onNetworkError) {
+        const sdkError =
+          error instanceof SDKError
+            ? error
+            : new SDKError(
+                error instanceof Error ? error.message : String(error),
+                0,
+                "NETWORK_ERROR"
+              );
+        this.onNetworkError(sdkError, {
+          method: "GET",
+          path,
+          isRetry: false,
+          attempt: 0,
+        });
       }
+
       throw error;
     }
   }

package/src/core/index.ts

@@ -0,0 +1,10 @@
+export { HttpClient, type HttpClientConfig, type NetworkErrorCallback, type NetworkErrorContext } from "./http";
+export { WSClient, type WSClientConfig } from "./ws";
+export type { IHttpTransport, RequestOptions } from "./interfaces/IHttpTransport";
+export type { IWebSocketClient } from "./interfaces/IWebSocketClient";
+export type { IAuthStrategy, RequestContext } from "./interfaces/IAuthStrategy";
+export type { IRetryPolicy } from "./interfaces/IRetryPolicy";
+export { PathBasedAuthStrategy } from "./transport/AuthHeaderStrategy";
+export { ExponentialBackoffRetryPolicy } from "./transport/RequestRetryPolicy";
+export { RequestLogger } from "./transport/RequestLogger";
+export { TLSConfiguration } from "./transport/TLSConfiguration";

package/src/core/interfaces/IAuthStrategy.ts

@@ -0,0 +1,28 @@
+/**
+ * Request context for authentication
+ */
+export interface RequestContext {
+  path: string;
+  method: string;
+}
+
+/**
+ * Authentication strategy interface
+ * Provides abstraction for different authentication header strategies
+ */
+export interface IAuthStrategy {
+  /**
+   * Get authentication headers for a request
+   */
+  getHeaders(context: RequestContext): Record<string, string>;
+
+  /**
+   * Set API key
+   */
+  setApiKey(apiKey?: string): void;
+
+  /**
+   * Set JWT token
+   */
+  setJwt(jwt?: string): void;
+}

package/src/core/interfaces/IHttpTransport.ts

@@ -0,0 +1,73 @@
+/**
+ * HTTP Request options
+ */
+export interface RequestOptions {
+  headers?: Record<string, string>;
+  query?: Record<string, string | number | boolean>;
+  timeout?: number;
+}
+
+/**
+ * HTTP Transport abstraction interface
+ * Provides a testable abstraction layer for HTTP operations
+ */
+export interface IHttpTransport {
+  /**
+   * Perform GET request
+   */
+  get<T = any>(path: string, options?: RequestOptions): Promise<T>;
+
+  /**
+   * Perform POST request
+   */
+  post<T = any>(path: string, body?: any, options?: RequestOptions): Promise<T>;
+
+  /**
+   * Perform PUT request
+   */
+  put<T = any>(path: string, body?: any, options?: RequestOptions): Promise<T>;
+
+  /**
+   * Perform DELETE request
+   */
+  delete<T = any>(path: string, options?: RequestOptions): Promise<T>;
+
+  /**
+   * Upload file using multipart/form-data
+   */
+  uploadFile<T = any>(
+    path: string,
+    formData: FormData,
+    options?: { timeout?: number }
+  ): Promise<T>;
+
+  /**
+   * Get binary response (returns Response object for streaming)
+   */
+  getBinary(path: string): Promise<Response>;
+
+  /**
+   * Get base URL
+   */
+  getBaseURL(): string;
+
+  /**
+   * Get API key
+   */
+  getApiKey(): string | undefined;
+
+  /**
+   * Get current token (JWT or API key)
+   */
+  getToken(): string | undefined;
+
+  /**
+   * Set API key for authentication
+   */
+  setApiKey(apiKey?: string): void;
+
+  /**
+   * Set JWT token for authentication
+   */
+  setJwt(jwt?: string): void;
+}

package/src/core/interfaces/IRetryPolicy.ts

@@ -0,0 +1,20 @@
+/**
+ * Retry policy interface
+ * Provides abstraction for retry logic and backoff strategies
+ */
+export interface IRetryPolicy {
+  /**
+   * Determine if request should be retried
+   */
+  shouldRetry(error: any, attempt: number): boolean;
+
+  /**
+   * Get delay before next retry attempt (in milliseconds)
+   */
+  getDelay(attempt: number): number;
+
+  /**
+   * Get maximum number of retry attempts
+   */
+  getMaxRetries(): number;
+}

package/src/core/interfaces/IWebSocketClient.ts

@@ -0,0 +1,60 @@
+/**
+ * WebSocket Client abstraction interface
+ * Provides a testable abstraction layer for WebSocket operations
+ */
+export interface IWebSocketClient {
+  /**
+   * Connect to WebSocket server
+   */
+  connect(): Promise<void>;
+
+  /**
+   * Close WebSocket connection
+   */
+  close(): void;
+
+  /**
+   * Send data through WebSocket
+   */
+  send(data: string): void;
+
+  /**
+   * Register message handler
+   */
+  onMessage(handler: (data: string) => void): void;
+
+  /**
+   * Unregister message handler
+   */
+  offMessage(handler: (data: string) => void): void;
+
+  /**
+   * Register error handler
+   */
+  onError(handler: (error: Error) => void): void;
+
+  /**
+   * Unregister error handler
+   */
+  offError(handler: (error: Error) => void): void;
+
+  /**
+   * Register close handler
+   */
+  onClose(handler: () => void): void;
+
+  /**
+   * Unregister close handler
+   */
+  offClose(handler: () => void): void;
+
+  /**
+   * Check if WebSocket is connected
+   */
+  isConnected(): boolean;
+
+  /**
+   * Get WebSocket URL
+   */
+  get url(): string;
+}

package/src/core/interfaces/index.ts

@@ -0,0 +1,4 @@
+export type { IHttpTransport, RequestOptions } from "./IHttpTransport";
+export type { IWebSocketClient } from "./IWebSocketClient";
+export type { IAuthStrategy, RequestContext } from "./IAuthStrategy";
+export type { IRetryPolicy } from "./IRetryPolicy";

package/src/core/transport/AuthHeaderStrategy.ts

@@ -0,0 +1,108 @@
+import type { IAuthStrategy, RequestContext } from "../interfaces/IAuthStrategy";
+
+/**
+ * Authentication type for different operations
+ */
+type AuthType = "api-key-only" | "api-key-preferred" | "jwt-preferred" | "both";
+
+/**
+ * Path-based authentication strategy
+ * Determines which auth credentials to use based on the request path
+ */
+export class PathBasedAuthStrategy implements IAuthStrategy {
+  private apiKey?: string;
+  private jwt?: string;
+
+  /**
+   * Mapping of path patterns to auth types
+   */
+  private readonly authRules: Array<{ pattern: string; type: AuthType }> = [
+    // Database, PubSub, Proxy, Cache: prefer API key
+    { pattern: "/v1/rqlite/", type: "api-key-only" },
+    { pattern: "/v1/pubsub/", type: "api-key-only" },
+    { pattern: "/v1/proxy/", type: "api-key-only" },
+    { pattern: "/v1/cache/", type: "api-key-only" },
+    // Auth operations: prefer API key
+    { pattern: "/v1/auth/", type: "api-key-preferred" },
+  ];
+
+  constructor(apiKey?: string, jwt?: string) {
+    this.apiKey = apiKey;
+    this.jwt = jwt;
+  }
+
+  /**
+   * Get authentication headers for a request
+   */
+  getHeaders(context: RequestContext): Record<string, string> {
+    const headers: Record<string, string> = {};
+    const authType = this.detectAuthType(context.path);
+
+    switch (authType) {
+      case "api-key-only":
+        if (this.apiKey) {
+          headers["X-API-Key"] = this.apiKey;
+        } else if (this.jwt) {
+          // Fallback to JWT if no API key
+          headers["Authorization"] = `Bearer ${this.jwt}`;
+        }
+        break;
+
+      case "api-key-preferred":
+        if (this.apiKey) {
+          headers["X-API-Key"] = this.apiKey;
+        }
+        if (this.jwt) {
+          headers["Authorization"] = `Bearer ${this.jwt}`;
+        }
+        break;
+
+      case "jwt-preferred":
+        if (this.jwt) {
+          headers["Authorization"] = `Bearer ${this.jwt}`;
+        }
+        if (this.apiKey) {
+          headers["X-API-Key"] = this.apiKey;
+        }
+        break;
+
+      case "both":
+        if (this.jwt) {
+          headers["Authorization"] = `Bearer ${this.jwt}`;
+        }
+        if (this.apiKey) {
+          headers["X-API-Key"] = this.apiKey;
+        }
+        break;
+    }
+
+    return headers;
+  }
+
+  /**
+   * Set API key
+   */
+  setApiKey(apiKey?: string): void {
+    this.apiKey = apiKey;
+  }
+
+  /**
+   * Set JWT token
+   */
+  setJwt(jwt?: string): void {
+    this.jwt = jwt;
+  }
+
+  /**
+   * Detect auth type based on path
+   */
+  private detectAuthType(path: string): AuthType {
+    for (const rule of this.authRules) {
+      if (path.includes(rule.pattern)) {
+        return rule.type;
+      }
+    }
+    // Default: send both if available
+    return "both";
+  }
+}

package/src/core/transport/RequestLogger.ts

@@ -0,0 +1,116 @@
+/**
+ * Request logger for debugging HTTP operations
+ */
+export class RequestLogger {
+  private readonly debug: boolean;
+
+  constructor(debug: boolean = false) {
+    this.debug = debug;
+  }
+
+  /**
+   * Log successful request
+   */
+  logSuccess(
+    method: string,
+    path: string,
+    duration: number,
+    queryDetails?: string
+  ): void {
+    if (typeof console === "undefined") return;
+
+    const logMessage = `[HttpClient] ${method} ${path} completed in ${duration.toFixed(2)}ms`;
+
+    if (queryDetails && this.debug) {
+      console.log(logMessage);
+      console.log(`[HttpClient]   ${queryDetails}`);
+    } else {
+      console.log(logMessage);
+    }
+  }
+
+  /**
+   * Log failed request
+   */
+  logError(
+    method: string,
+    path: string,
+    duration: number,
+    error: any,
+    queryDetails?: string
+  ): void {
+    if (typeof console === "undefined") return;
+
+    // Special handling for 404 on find-one (expected behavior)
+    const is404FindOne =
+      path === "/v1/rqlite/find-one" &&
+      error?.httpStatus === 404;
+
+    if (is404FindOne) {
+      console.warn(
+        `[HttpClient] ${method} ${path} returned 404 after ${duration.toFixed(2)}ms (expected for optional lookups)`
+      );
+      return;
+    }
+
+    const errorMessage = `[HttpClient] ${method} ${path} failed after ${duration.toFixed(2)}ms:`;
+    console.error(errorMessage, error);
+
+    if (queryDetails && this.debug) {
+      console.error(`[HttpClient]   ${queryDetails}`);
+    }
+  }
+
+  /**
+   * Extract query details from request for logging
+   */
+  extractQueryDetails(path: string, body?: any): string | null {
+    if (!this.debug) return null;
+
+    const isRqliteOperation = path.includes("/v1/rqlite/");
+    if (!isRqliteOperation || !body) return null;
+
+    try {
+      const parsedBody = typeof body === "string" ? JSON.parse(body) : body;
+
+      // Direct SQL query
+      if (parsedBody.sql) {
+        let details = `SQL: ${parsedBody.sql}`;
+        if (parsedBody.args && parsedBody.args.length > 0) {
+          details += ` | Args: [${parsedBody.args
+            .map((a: any) => (typeof a === "string" ? `"${a}"` : a))
+            .join(", ")}]`;
+        }
+        return details;
+      }
+
+      // Table-based query
+      if (parsedBody.table) {
+        let details = `Table: ${parsedBody.table}`;
+        if (parsedBody.criteria && Object.keys(parsedBody.criteria).length > 0) {
+          details += ` | Criteria: ${JSON.stringify(parsedBody.criteria)}`;
+        }
+        if (parsedBody.options) {
+          details += ` | Options: ${JSON.stringify(parsedBody.options)}`;
+        }
+        if (parsedBody.select) {
+          details += ` | Select: ${JSON.stringify(parsedBody.select)}`;
+        }
+        if (parsedBody.where) {
+          details += ` | Where: ${JSON.stringify(parsedBody.where)}`;
+        }
+        if (parsedBody.limit) {
+          details += ` | Limit: ${parsedBody.limit}`;
+        }
+        if (parsedBody.offset) {
+          details += ` | Offset: ${parsedBody.offset}`;
+        }
+        return details;
+      }
+    } catch {
+      // Failed to parse, ignore
+    }
+
+    return null;
+  }
+}

package/src/core/transport/RequestRetryPolicy.ts

@@ -0,0 +1,53 @@
+import type { IRetryPolicy } from "../interfaces/IRetryPolicy";
+import { SDKError } from "../../errors";
+
+/**
+ * Exponential backoff retry policy
+ * Retries failed requests with increasing delays
+ */
+export class ExponentialBackoffRetryPolicy implements IRetryPolicy {
+  private readonly maxRetries: number;
+  private readonly baseDelayMs: number;
+
+  /**
+   * HTTP status codes that should trigger a retry
+   */
+  private readonly retryableStatusCodes = [408, 429, 500, 502, 503, 504];
+
+  constructor(maxRetries: number = 3, baseDelayMs: number = 1000) {
+    this.maxRetries = maxRetries;
+    this.baseDelayMs = baseDelayMs;
+  }
+
+  /**
+   * Determine if request should be retried
+   */
+  shouldRetry(error: any, attempt: number): boolean {
+    // Don't retry if max attempts reached
+    if (attempt >= this.maxRetries) {
+      return false;
+    }
+
+    // Retry on retryable HTTP errors
+    if (error instanceof SDKError) {
+      return this.retryableStatusCodes.includes(error.httpStatus);
+    }
+
+    // Don't retry other errors
+    return false;
+  }
+
+  /**
+   * Get delay before next retry (exponential backoff)
+   */
+  getDelay(attempt: number): number {
+    return this.baseDelayMs * (attempt + 1);
+  }
+
+  /**
+   * Get maximum number of retry attempts
+   */
+  getMaxRetries(): number {
+    return this.maxRetries;
+  }
+}

package/src/core/transport/TLSConfiguration.ts

@@ -0,0 +1,53 @@
+/**
+ * TLS Configuration for development/staging environments
+ *
+ * WARNING: Only use this in development/testing environments!
+ * DO NOT disable certificate validation in production.
+ */
+export class TLSConfiguration {
+  /**
+   * Create fetch function with proper TLS configuration
+   */
+  static createFetchWithTLSConfig(): typeof fetch {
+    // Only allow insecure TLS in development
+    if (this.shouldAllowInsecure()) {
+      this.configureInsecureTLS();
+    }
+
+    return globalThis.fetch;
+  }
+
+  /**
+   * Check if insecure TLS should be allowed
+   */
+  private static shouldAllowInsecure(): boolean {
+    // Check if we're in Node.js environment
+    if (typeof process === "undefined" || !process.versions?.node) {
+      return false;
+    }
+
+    // Only allow in non-production with explicit flag
+    const isProduction = process.env.NODE_ENV === "production";
+    const allowInsecure = process.env.DEBROS_ALLOW_INSECURE_TLS === "true";
+
+    return !isProduction && allowInsecure;
+  }
+
+  /**
+   * Configure Node.js to allow insecure TLS
+   * WARNING: Only call in development!
+   */
+  private static configureInsecureTLS(): void {
+    if (typeof process !== "undefined" && process.env) {
+      // Allow self-signed/staging certificates for development
+      process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+
+      if (typeof console !== "undefined") {
+        console.warn(
+          "[TLSConfiguration] WARNING: TLS certificate validation disabled for development. " +
+          "DO NOT use in production!"
+        );
+      }
+    }
+  }
+}