snowpipe-streaming 1.4.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snowpipe-streaming",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Snowflake Streaming Ingest SDK for Node.js",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -27,11 +27,11 @@
     "typedoc": "^0.28.19"
   },
   "optionalDependencies": {
-    "snowpipe-streaming-linux-x64-gnu": "1.4.0",
-    "snowpipe-streaming-linux-x64-musl": "1.4.0",
-    "snowpipe-streaming-linux-arm64-gnu": "1.4.0",
-    "snowpipe-streaming-linux-arm64-musl": "1.4.0",
-    "snowpipe-streaming-darwin-arm64": "1.4.0",
-    "snowpipe-streaming-win32-x64-msvc": "1.4.0"
+    "snowpipe-streaming-linux-x64-gnu": "1.6.0",
+    "snowpipe-streaming-linux-x64-musl": "1.6.0",
+    "snowpipe-streaming-linux-arm64-gnu": "1.6.0",
+    "snowpipe-streaming-linux-arm64-musl": "1.6.0",
+    "snowpipe-streaming-darwin-arm64": "1.6.0",
+    "snowpipe-streaming-win32-x64-msvc": "1.6.0"
   }
 }

package/src/channel.js

@@ -104,10 +104,11 @@ class StreamingIngestChannel {
    * Append a single row. Convenience wrapper for appendRows.
    * @param {Object} row - Row data as key-value pairs
    * @param {string} [offsetToken] - Offset token for this row
-   * @returns {Promise<void>}
+   * @returns {void}
+   * @throws {StreamingIngestError} If the row appending fails
    */
-  async appendRow(row, offsetToken) {
-    await this.appendRows([row], offsetToken, offsetToken);
+  appendRow(row, offsetToken) {
+    this.appendRows([row], offsetToken, offsetToken);
   }
 
   /**
@@ -116,25 +117,27 @@ class StreamingIngestChannel {
    * @param {Object[]} rows - Array of row objects
    * @param {string} [startOffsetToken] - Start offset token for this batch
    * @param {string} [endOffsetToken] - End offset token for this batch
-   * @returns {Promise<void>}
+   * @returns {void}
+   * @throws {TypeError} If rows is not an array
+   * @throws {StreamingIngestError} If the rows appending fails
    */
-  async appendRows(rows, startOffsetToken, endOffsetToken) {
+  appendRows(rows, startOffsetToken, endOffsetToken) {
     if (!Array.isArray(rows)) {
       throw new TypeError("rows must be an array");
     }
-    // Empty arrays are handled by the Rust core, which returns a proper InvalidRequest error
-    if (rows.length === 0) {
-      // Pass empty buffer to Rust core to get proper error message
-      return callFFI(() =>
-        this._native.appendRows(Buffer.alloc(0), 0, startOffsetToken, endOffsetToken),
-      );
+    // Empty arrays are handled by the Rust core, which returns a proper InvalidRequest error.
+    const buffer =
+      rows.length === 0
+        ? Buffer.alloc(0)
+        : Buffer.from(
+            rows.map((r) => JSON.stringify(this._convertBytesInRow(r))).join("\n"),
+            "utf8",
+          );
+    try {
+      this._native.appendRows(buffer, rows.length, startOffsetToken, endOffsetToken);
+    } catch (e) {
+      throw StreamingIngestError.from(e);
     }
-    // Convert binary values according to binaryInputFormat before JSON serialization
-    const ndjson = rows.map((r) => JSON.stringify(this._convertBytesInRow(r))).join("\n");
-    const buffer = Buffer.from(ndjson, "utf8");
-    return callFFI(() =>
-      this._native.appendRows(buffer, rows.length, startOffsetToken, endOffsetToken),
-    );
   }
 
   /**

package/src/index.d.ts

@@ -49,7 +49,9 @@ export function createClient(options: {
   pipeName: string;
   /** Path to a JSON file containing connection properties and authentication information. */
   profilePath?: string;
-  /** Connection properties and authentication information. Common properties include account, user, private_key, url. */
+  /** Connection properties and authentication information. Common properties include account, user, private_key, url
+   * and application (partner app name for User-Agent; 1–64 visible ASCII chars (0x21–0x7E),
+   * excluding `(`, `)`, `\`; regex: `^[!-'*-\[-\]-~]{1,64}$`). */
   properties?: Record<string, string>;
 }): Promise<StreamingIngestClient>;
 
@@ -201,7 +203,7 @@ export class StreamingIngestChannel {
    *   progress and replay ingestion in case of failures
    * @throws StreamingIngestError If the row appending fails
    */
-  appendRow(row: Record<string, any>, offsetToken?: string): Promise<void>;
+  appendRow(row: Record<string, any>, offsetToken?: string): void;
 
   /**
    * Append multiple rows to the channel.
@@ -216,7 +218,7 @@ export class StreamingIngestChannel {
    * @throws TypeError If rows is not an array
    * @throws StreamingIngestError If the rows appending fails
    */
-  appendRows(rows: Record<string, any>[], startOffsetToken?: string, endOffsetToken?: string): Promise<void>;
+  appendRows(rows: Record<string, any>[], startOffsetToken?: string, endOffsetToken?: string): void;
 
   /**
    * Close the channel.
@@ -347,5 +349,3 @@ export class StreamingIngestError extends Error {
   /** HTTP status name (for example, "Bad Request"). */
   readonly httpStatusName: string;
 }
-
-

package/src/loader.js

@@ -22,6 +22,25 @@ const fs = require("node:fs");
 
 const LOG_PREFIX = "[snowpipe-streaming]";
 
+// Verbose loader breadcrumbs are gated on SS_LOG_LEVEL=debug|trace, matching
+// the env var the Rust core and Java/Python SDKs already use (see
+// rust/src/util/bootstrap_config.rs and FFIBootstrap.java). Default: silent on
+// the success path. Fall-through and error paths still write to stderr.
+// Match Rust's case-sensitive lowercase comparison so the same env var value
+// is interpreted identically on both sides of the FFI boundary.
+const VERBOSE = ["debug", "trace"].includes(process.env.SS_LOG_LEVEL || "");
+
+/**
+ * Emit a loader breadcrumb to stderr when SS_LOG_LEVEL=debug|trace.
+ * No-op otherwise — keeps the success path silent on both stdout and stderr.
+ * @param {string} msg
+ */
+function debug(msg) {
+  if (VERBOSE) {
+    console.error(`${LOG_PREFIX} ${msg}`);
+  }
+}
+
 /**
  * Platform package name mappings.
  * Maps (os, arch, libc) to the npm package suffix.
@@ -45,7 +64,7 @@ function detectLibc() {
   try {
     const libDir = fs.readdirSync("/lib");
     if (libDir.some((f) => f.startsWith("ld-musl-"))) {
-      console.log(`${LOG_PREFIX} Detected musl libc (found /lib/ld-musl-*)`);
+      debug("Detected musl libc (found /lib/ld-musl-*)");
       return "musl";
     }
   } catch {
@@ -57,7 +76,7 @@ function detectLibc() {
     const { execSync } = require("node:child_process");
     const lddOutput = execSync("ldd --version 2>&1", { encoding: "utf8" });
     if (lddOutput.includes("musl")) {
-      console.log(`${LOG_PREFIX} Detected musl libc (ldd --version)`);
+      debug("Detected musl libc (ldd --version)");
       return "musl";
     }
   } catch {
@@ -68,15 +87,13 @@ function detectLibc() {
   if (process.report && typeof process.report.getReport === "function") {
     const report = process.report.getReport();
     if (report?.header?.glibcVersionRuntime) {
-      console.log(
-        `${LOG_PREFIX} Detected glibc ${report.header.glibcVersionRuntime} (process.report)`,
-      );
+      debug(`Detected glibc ${report.header.glibcVersionRuntime} (process.report)`);
       return "glibc";
     }
   }
 
   // Default to glibc (most common)
-  console.log(`${LOG_PREFIX} Defaulting to glibc (no musl indicators found)`);
+  debug("Defaulting to glibc (no musl indicators found)");
   return "glibc";
 }
 
@@ -91,12 +108,12 @@ function getPlatformKey() {
   if (platform === "linux") {
     const libc = detectLibc();
     const key = `${platform}-${arch}-${libc}`;
-    console.log(`${LOG_PREFIX} Platform: ${key} (os=${platform}, arch=${arch}, libc=${libc})`);
+    debug(`Platform: ${key} (os=${platform}, arch=${arch}, libc=${libc})`);
     return key;
   }
 
   const key = `${platform}-${arch}`;
-  console.log(`${LOG_PREFIX} Platform: ${key} (os=${platform}, arch=${arch})`);
+  debug(`Platform: ${key} (os=${platform}, arch=${arch})`);
   return key;
 }
 
@@ -113,10 +130,15 @@ function loadNativeAddon() {
   // Mode 1: Bazel development - ADDON_PATH points directly to the .node file
   if (process.env.ADDON_PATH) {
     const addonPath = path.resolve(process.env.ADDON_PATH);
-    console.log(`${LOG_PREFIX} Loading native addon from ADDON_PATH: ${addonPath}`);
-    const addon = require(addonPath);
-    console.log(`${LOG_PREFIX} Native addon loaded successfully from ADDON_PATH`);
-    return addon;
+    debug(`Loading native addon from ADDON_PATH: ${addonPath}`);
+    try {
+      return require(addonPath);
+    } catch (err) {
+      console.error(
+        `${LOG_PREFIX} Failed to load native addon from ADDON_PATH ${addonPath}: ${err.message}`,
+      );
+      throw err;
+    }
   }
 
   // Mode 2: Production - load from platform-specific npm package
@@ -125,33 +147,37 @@ function loadNativeAddon() {
 
   if (packageSuffix) {
     const packageName = `snowpipe-streaming-${packageSuffix}`;
-    console.log(`${LOG_PREFIX} Attempting to load platform package: ${packageName}`);
+    debug(`Attempting to load platform package: ${packageName}`);
     try {
-      const addon = require(packageName);
-      console.log(`${LOG_PREFIX} Native addon loaded successfully from ${packageName}`);
-      return addon;
+      return require(packageName);
     } catch (err) {
       // Package not installed - fall through to fallback
       if (err.code !== "MODULE_NOT_FOUND") {
         console.error(`${LOG_PREFIX} Failed to load ${packageName}: ${err.message}`);
         throw err;
       }
-      console.log(`${LOG_PREFIX} Platform package ${packageName} not found, trying local fallback`);
+      console.error(
+        `${LOG_PREFIX} Platform package ${packageName} not found, trying local fallback`,
+      );
     }
   } else {
-    console.log(
+    console.error(
       `${LOG_PREFIX} No platform package mapping for ${platformKey}, trying local fallback`,
     );
   }
 
   // Mode 3: Fallback - local .node file (for testing or manual installation)
   const localAddon = path.resolve(__dirname, "..", "snowpipe_streaming.node");
-  console.log(`${LOG_PREFIX} Checking for local addon: ${localAddon}`);
   if (fs.existsSync(localAddon)) {
-    console.log(`${LOG_PREFIX} Loading native addon from local file: ${localAddon}`);
-    const addon = require(localAddon);
-    console.log(`${LOG_PREFIX} Native addon loaded successfully from local file`);
-    return addon;
+    debug(`Loading native addon from local file: ${localAddon}`);
+    try {
+      return require(localAddon);
+    } catch (err) {
+      console.error(
+        `${LOG_PREFIX} Failed to load native addon from local file ${localAddon}: ${err.message}`,
+      );
+      throw err;
+    }
   }
 
   // No addon found - provide helpful error message