Merge branch 'main' into token-federation-pr3-examples

# Conflicts:
#	lib/connection/auth/tokenProvider/FederationProvider.ts

Author: madhav-db

.github/CODEOWNERS

@@ -232,7 +232,7 @@ export default class DBSQLSession implements IDBSQLSession {
     }
 
     if (ProtocolVersion.supportsArrowCompression(this.serverProtocolVersion) && request.canDownloadResult !== true) {
-      request.canDecompressLZ4Result = (options.useLZ4Compression ?? clientConfig.useLZ4Compression) && Boolean(LZ4);
+      request.canDecompressLZ4Result = (options.useLZ4Compression ?? clientConfig.useLZ4Compression) && Boolean(LZ4());
     }
 
     const operationPromise = driver.executeStatement(request);

lib/DBSQLSession.ts

@@ -225,7 +225,7 @@ export default class FederationProvider implements ITokenProvider {
       }
 
       // Exponential backoff: 1s, 2s, 4s
-      const delay = RETRY_BASE_DELAY_MS * (2 ** attempt);
+      const delay = RETRY_BASE_DELAY_MS * 2 ** attempt;
       await new Promise<void>((resolve) => {
         setTimeout(resolve, delay);
       });

lib/connection/auth/tokenProvider/FederationProvider.ts

@@ -22,6 +22,15 @@ export interface ClientConfig {
 
   useLZ4Compression: boolean;
   enableMetricViewMetadata?: boolean;
+
+  // Telemetry configuration
+  telemetryEnabled?: boolean;
+  telemetryBatchSize?: number;
+  telemetryFlushIntervalMs?: number;
+  telemetryMaxRetries?: number;
+  telemetryAuthenticatedExport?: boolean;
+  telemetryCircuitBreakerThreshold?: number;
+  telemetryCircuitBreakerTimeout?: number;
 }
 
 export default interface IClientContext {

lib/contracts/IClientContext.ts

@@ -26,7 +26,7 @@ export default class ArrowResultHandler implements IResultsProvider<ArrowBatch>
     this.arrowSchema = arrowSchema ?? hiveSchemaToArrowSchema(schema);
     this.isLZ4Compressed = lz4Compressed ?? false;
 
-    if (this.isLZ4Compressed && !LZ4) {
+    if (this.isLZ4Compressed && !LZ4()) {
       throw new HiveDriverError('Cannot handle LZ4 compressed result: module `lz4` not installed');
     }
   }
@@ -52,7 +52,7 @@ export default class ArrowResultHandler implements IResultsProvider<ArrowBatch>
     let totalRowCount = 0;
     rowSet?.arrowBatches?.forEach(({ batch, rowCount }) => {
       if (batch) {
-        batches.push(this.isLZ4Compressed ? LZ4!.decode(batch) : batch);
+        batches.push(this.isLZ4Compressed ? LZ4()!.decode(batch) : batch);
         totalRowCount += rowCount.toNumber(true);
       }
     });

lib/result/ArrowResultHandler.ts

@@ -27,7 +27,7 @@ export default class CloudFetchResultHandler implements IResultsProvider<ArrowBa
     this.source = source;
     this.isLZ4Compressed = lz4Compressed ?? false;
 
-    if (this.isLZ4Compressed && !LZ4) {
+    if (this.isLZ4Compressed && !LZ4()) {
       throw new HiveDriverError('Cannot handle LZ4 compressed result: module `lz4` not installed');
     }
   }
@@ -64,7 +64,7 @@ export default class CloudFetchResultHandler implements IResultsProvider<ArrowBa
     }
 
     if (this.isLZ4Compressed) {
-      batch.batches = batch.batches.map((buffer) => LZ4!.decode(buffer));
+      batch.batches = batch.batches.map((buffer) => LZ4()!.decode(buffer));
     }
     return batch;
   }

lib/result/CloudFetchResultHandler.ts

@@ -0,0 +1,101 @@
+/**
+ * Copyright (c) 2025 Databricks Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import AuthenticationError from '../errors/AuthenticationError';
+import RetryError from '../errors/RetryError';
+
+/**
+ * Classifies exceptions as terminal (unrecoverable) vs retryable.
+ *
+ * Terminal exceptions should be flushed immediately to telemetry,
+ * while retryable exceptions are buffered until statement completion.
+ *
+ * This follows the JDBC driver pattern of smart exception flushing
+ * to optimize telemetry export efficiency while ensuring critical
+ * errors are reported immediately.
+ */
+export default class ExceptionClassifier {
+  /**
+   * Determines if an exception is terminal (non-retryable).
+   *
+   * Terminal exceptions indicate unrecoverable failures that should
+   * be reported immediately, such as authentication failures, invalid
+   * requests, or resource not found errors.
+   *
+   * @param error - The error to classify
+   * @returns true if the error is terminal, false otherwise
+   */
+  static isTerminal(error: Error): boolean {
+    // Check for AuthenticationError (terminal)
+    if (error instanceof AuthenticationError) {
+      return true;
+    }
+
+    // Check for HTTP status codes in error properties
+    // Supporting both 'statusCode' and 'status' property names for flexibility
+    const statusCode = (error as any).statusCode ?? (error as any).status;
+
+    if (typeof statusCode === 'number') {
+      // Terminal HTTP status codes:
+      // 400 - Bad Request (invalid request format)
+      // 401 - Unauthorized (authentication required)
+      // 403 - Forbidden (permission denied)
+      // 404 - Not Found (resource does not exist)
+      return statusCode === 400 || statusCode === 401 || statusCode === 403 || statusCode === 404;
+    }
+
+    // Default to false for unknown error types
+    return false;
+  }
+
+  /**
+   * Determines if an exception is retryable.
+   *
+   * Retryable exceptions indicate transient failures that may succeed
+   * on retry, such as rate limiting, server errors, or network timeouts.
+   *
+   * @param error - The error to classify
+   * @returns true if the error is retryable, false otherwise
+   */
+  static isRetryable(error: Error): boolean {
+    // Check for RetryError (explicitly retryable)
+    if (error instanceof RetryError) {
+      return true;
+    }
+
+    // Check for network timeout errors
+    if (error.name === 'TimeoutError' || error.message.includes('timeout')) {
+      return true;
+    }
+
+    // Check for HTTP status codes in error properties
+    // Supporting both 'statusCode' and 'status' property names for flexibility
+    const statusCode = (error as any).statusCode ?? (error as any).status;
+
+    if (typeof statusCode === 'number') {
+      // Retryable HTTP status codes:
+      // 429 - Too Many Requests (rate limiting)
+      // 500 - Internal Server Error
+      // 502 - Bad Gateway
+      // 503 - Service Unavailable
+      // 504 - Gateway Timeout
+      return statusCode === 429 || statusCode === 500 || statusCode === 502 || statusCode === 503 || statusCode === 504;
+    }
+
+    // Default to false for unknown error types
+    return false;
+  }
+}