@debros/orama 0.122.4-nightly

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: (code: number, reason: string) => void): void;
+
+  /**
+   * Unregister close handler
+   */
+  offClose(handler: (code: number, reason: string) => 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!"
+        );
+      }
+    }
+  }
+}

package/src/core/transport/index.ts

@@ -0,0 +1,4 @@
+export { PathBasedAuthStrategy } from "./AuthHeaderStrategy";
+export { ExponentialBackoffRetryPolicy } from "./RequestRetryPolicy";
+export { RequestLogger } from "./RequestLogger";
+export { TLSConfiguration } from "./TLSConfiguration";

package/src/core/ws.ts

@@ -0,0 +1,246 @@
+import WebSocket from "isomorphic-ws";
+import { SDKError } from "../errors";
+import { NetworkErrorCallback } from "./http";
+
+export interface WSClientConfig {
+  wsURL: string;
+  timeout?: number;
+  authToken?: string;
+  WebSocket?: typeof WebSocket;
+  /**
+   * Callback invoked on WebSocket errors.
+   * Use this to trigger gateway failover at the application layer.
+   */
+  onNetworkError?: NetworkErrorCallback;
+}
+
+export type WSMessageHandler = (data: string) => void;
+export type WSErrorHandler = (error: Error) => void;
+export type WSCloseHandler = (code: number, reason: string) => void;
+export type WSOpenHandler = () => void;
+
+/**
+ * Simple WebSocket client with minimal abstractions
+ * No complex reconnection, no failover - keep it simple
+ * Gateway failover is handled at the application layer
+ */
+export class WSClient {
+  private wsURL: string;
+  private timeout: number;
+  private authToken?: string;
+  private WebSocketClass: typeof WebSocket;
+  private onNetworkError?: NetworkErrorCallback;
+
+  private ws?: WebSocket;
+  private messageHandlers: Set<WSMessageHandler> = new Set();
+  private errorHandlers: Set<WSErrorHandler> = new Set();
+  private closeHandlers: Set<WSCloseHandler> = new Set();
+  private openHandlers: Set<WSOpenHandler> = new Set();
+  private isClosed = false;
+
+  constructor(config: WSClientConfig) {
+    this.wsURL = config.wsURL;
+    this.timeout = config.timeout ?? 30000;
+    this.authToken = config.authToken;
+    this.WebSocketClass = config.WebSocket ?? WebSocket;
+    this.onNetworkError = config.onNetworkError;
+  }
+
+  /**
+   * Set the network error callback
+   */
+  setOnNetworkError(callback: NetworkErrorCallback | undefined): void {
+    this.onNetworkError = callback;
+  }
+
+  /**
+   * Get the current WebSocket URL
+   */
+  get url(): string {
+    return this.wsURL;
+  }
+
+  /**
+   * Connect to WebSocket server
+   */
+  connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      try {
+        const wsUrl = this.buildWSUrl();
+        this.ws = new this.WebSocketClass(wsUrl);
+        this.isClosed = false;
+
+        const timeout = setTimeout(() => {
+          this.ws?.close();
+          const error = new SDKError("WebSocket connection timeout", 408, "WS_TIMEOUT");
+
+          // Call the network error callback if configured
+          if (this.onNetworkError) {
+            this.onNetworkError(error, {
+              method: "WS",
+              path: this.wsURL,
+              isRetry: false,
+              attempt: 0,
+            });
+          }
+
+          reject(error);
+        }, this.timeout);
+
+        this.ws.addEventListener("open", () => {
+          clearTimeout(timeout);
+          console.log("[WSClient] Connected to", this.wsURL);
+          this.openHandlers.forEach((handler) => handler());
+          resolve();
+        });
+
+        this.ws.addEventListener("message", (event: Event) => {
+          const msgEvent = event as MessageEvent;
+          this.messageHandlers.forEach((handler) => handler(msgEvent.data));
+        });
+
+        this.ws.addEventListener("error", (event: Event) => {
+          console.error("[WSClient] WebSocket error:", event);
+          clearTimeout(timeout);
+          // Extract useful details from the event — raw Event objects don't serialize
+          const details: Record<string, any> = { type: event.type };
+          if ("message" in event) {
+            details.message = (event as ErrorEvent).message;
+          }
+          const error = new SDKError("WebSocket error", 0, "WS_ERROR", details);
+
+          // Call the network error callback if configured
+          if (this.onNetworkError) {
+            this.onNetworkError(error, {
+              method: "WS",
+              path: this.wsURL,
+              isRetry: false,
+              attempt: 0,
+            });
+          }
+
+          this.errorHandlers.forEach((handler) => handler(error));
+          reject(error);
+        });
+
+        this.ws.addEventListener("close", (event: Event) => {
+          clearTimeout(timeout);
+          const closeEvent = event as CloseEvent;
+          const code = closeEvent.code ?? 1006;
+          const reason = closeEvent.reason ?? "";
+          console.log(`[WSClient] Connection closed (code: ${code}, reason: ${reason || "none"})`);
+          this.closeHandlers.forEach((handler) => handler(code, reason));
+        });
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Build WebSocket URL with auth token
+   */
+  private buildWSUrl(): string {
+    let url = this.wsURL;
+
+    if (this.authToken) {
+      const separator = url.includes("?") ? "&" : "?";
+      const paramName = this.authToken.startsWith("ak_") ? "api_key" : "token";
+      // API keys contain a colon (ak_xxx:namespace) that must not be percent-encoded
+      const encodedToken = this.authToken.startsWith("ak_")
+        ? this.authToken
+        : encodeURIComponent(this.authToken);
+      url += `${separator}${paramName}=${encodedToken}`;
+    }
+
+    return url;
+  }
+
+  /**
+   * Register message handler
+   */
+  onMessage(handler: WSMessageHandler): () => void {
+    this.messageHandlers.add(handler);
+    return () => this.messageHandlers.delete(handler);
+  }
+
+  /**
+   * Unregister message handler
+   */
+  offMessage(handler: WSMessageHandler): void {
+    this.messageHandlers.delete(handler);
+  }
+
+  /**
+   * Register error handler
+   */
+  onError(handler: WSErrorHandler): () => void {
+    this.errorHandlers.add(handler);
+    return () => this.errorHandlers.delete(handler);
+  }
+
+  /**
+   * Unregister error handler
+   */
+  offError(handler: WSErrorHandler): void {
+    this.errorHandlers.delete(handler);
+  }
+
+  /**
+   * Register close handler
+   */
+  onClose(handler: WSCloseHandler): () => void {
+    this.closeHandlers.add(handler);
+    return () => this.closeHandlers.delete(handler);
+  }
+
+  /**
+   * Unregister close handler
+   */
+  offClose(handler: WSCloseHandler): void {
+    this.closeHandlers.delete(handler);
+  }
+
+  /**
+   * Register open handler
+   */
+  onOpen(handler: WSOpenHandler): () => void {
+    this.openHandlers.add(handler);
+    return () => this.openHandlers.delete(handler);
+  }
+
+  /**
+   * Send data through WebSocket
+   */
+  send(data: string): void {
+    if (this.ws?.readyState !== WebSocket.OPEN) {
+      throw new SDKError("WebSocket is not connected", 0, "WS_NOT_CONNECTED");
+    }
+    this.ws.send(data);
+  }
+
+  /**
+   * Close WebSocket connection
+   */
+  close(): void {
+    if (this.isClosed) {
+      return;
+    }
+    this.isClosed = true;
+    this.ws?.close();
+  }
+
+  /**
+   * Check if WebSocket is connected
+   */
+  isConnected(): boolean {
+    return !this.isClosed && this.ws?.readyState === WebSocket.OPEN;
+  }
+
+  /**
+   * Update auth token
+   */
+  setAuthToken(token?: string): void {
+    this.authToken = token;
+  }
+}