@closeup1202/klag 0.1.0 → 0.2.0

package/README.md

@@ -66,6 +66,48 @@ klag --broker localhost:9092 --group my-service --watch --interval 3000
 
 # JSON output (CI/pipeline integration)
 klag --broker localhost:9092 --group my-service --json
+
+# SSL (system CA trust)
+klag --broker kafka.prod:9092 --group my-service --ssl
+
+# SSL with custom certificates
+klag --broker kafka.prod:9092 --group my-service \
+  --ssl --ssl-ca /etc/kafka/ca.pem \
+  --ssl-cert /etc/kafka/client.crt --ssl-key /etc/kafka/client.key
+
+# SASL authentication (password via environment variable — recommended)
+KLAG_SASL_PASSWORD=secret klag --broker kafka.prod:9092 --group my-service \
+  --sasl-mechanism scram-sha-256 --sasl-username kafka-user
+
+# SSL + SASL combined
+KLAG_SASL_PASSWORD=secret klag --broker kafka.prod:9092 --group my-service \
+  --ssl --sasl-mechanism scram-sha-256 --sasl-username kafka-user
+```
+
+## Config file (.klagrc)
+
+Create `.klagrc` in the current directory or `~/.klagrc` to store default options.
+CLI arguments always take precedence over the config file.
+
+```json
+{
+  "broker": "kafka.prod.internal:9092",
+  "group": "my-service",
+  "interval": 3000,
+  "ssl": {
+    "enabled": true,
+    "caPath": "/etc/kafka/ca.pem"
+  },
+  "sasl": {
+    "mechanism": "scram-sha-256",
+    "username": "kafka-user"
+  }
+}
+```
+
+With this file in place, you only need:
+```bash
+KLAG_SASL_PASSWORD=secret klag
 ```
 
 ## Options
@@ -79,6 +121,13 @@ klag --broker localhost:9092 --group my-service --json
 | `-w, --watch` | Watch mode | `false` |
 | `--no-rate` | Skip rate sampling | `false` |
 | `--json` | JSON output | `false` |
+| `--ssl` | Enable SSL/TLS | `false` |
+| `--ssl-ca <path>` | CA certificate PEM file | - |
+| `--ssl-cert <path>` | Client certificate PEM file | - |
+| `--ssl-key <path>` | Client key PEM file | - |
+| `--sasl-mechanism <type>` | `plain`, `scram-sha-256`, `scram-sha-512` | - |
+| `--sasl-username <user>` | SASL username | - |
+| `--sasl-password <pass>` | SASL password (prefer `KLAG_SASL_PASSWORD` env var) | - |
 
 ## Detectable root causes
 
@@ -106,8 +155,9 @@ All consumption pauses during rebalancing, which can cause a temporary lag spike
 ## Roadmap
 
 - [x] v0.1.0 — lag collection, hot partition, producer burst, slow consumer, rebalancing detection, watch mode with lag trend (▲▼)
-- [ ] v0.2.0 — multi-group monitoring
-- [ ] v0.3.0 — Slack alerts, Prometheus export
+- [x] v0.2.0 — SSL/SASL authentication, `.klagrc` config file support
+- [ ] v0.3.0 — multi-group monitoring
+- [ ] v0.4.0 — Slack alerts, Prometheus export
 
 ## License
 

package/dist/cli/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli/index.ts
-import chalk3 from "chalk";
+import chalk5 from "chalk";
 import { Command } from "commander";
 
 // src/analyzer/burstDetector.ts
@@ -138,20 +138,49 @@ function analyze(snapshot, rateSnapshot) {
 }
 
 // src/collector/lagCollector.ts
-import { AssignerProtocol, Kafka, logLevel } from "kafkajs";
-async function collectLag(options) {
-  const kafka = new Kafka({
-    clientId: "klag",
+import { AssignerProtocol } from "kafkajs";
+
+// src/collector/kafkaFactory.ts
+import { readFileSync } from "fs";
+import { Kafka, logLevel } from "kafkajs";
+function createKafkaClient(clientId, options) {
+  return new Kafka({
+    clientId,
     brokers: [options.broker],
     logLevel: logLevel.NOTHING,
-    // Hide kafkajs internal logs in CLI
     requestTimeout: options.timeoutMs ?? 5e3,
     connectionTimeout: options.timeoutMs ?? 3e3,
-    retry: {
-      retries: 1
-      // Added — only 1 retry (default is 5)
+    retry: { retries: 1 },
+    ...options.ssl && { ssl: buildSslConfig(options.ssl) },
+    ...options.sasl?.password && {
+      sasl: buildSaslConfig(
+        options.sasl
+      )
     }
   });
+}
+function buildSaslConfig(sasl) {
+  const { mechanism, username, password } = sasl;
+  if (mechanism === "plain") return { mechanism: "plain", username, password };
+  if (mechanism === "scram-sha-256")
+    return { mechanism: "scram-sha-256", username, password };
+  return { mechanism: "scram-sha-512", username, password };
+}
+function buildSslConfig(ssl) {
+  if (!ssl) return {};
+  if (!ssl.caPath && !ssl.certPath && !ssl.keyPath) {
+    return true;
+  }
+  return {
+    ...ssl.caPath && { ca: [readFileSync(ssl.caPath)] },
+    ...ssl.certPath && { cert: readFileSync(ssl.certPath) },
+    ...ssl.keyPath && { key: readFileSync(ssl.keyPath) }
+  };
+}
+
+// src/collector/lagCollector.ts
+async function collectLag(options) {
+  const kafka = createKafkaClient("klag", options);
   const admin = kafka.admin();
   try {
     await admin.connect();
@@ -170,7 +199,9 @@ async function collectLag(options) {
         const decoded = AssignerProtocol.MemberAssignment.decode(
           member.memberAssignment
         );
-        for (const [topic, partitions2] of Object.entries(decoded?.assignment)) {
+        for (const [topic, partitions2] of Object.entries(
+          decoded?.assignment ?? {}
+        )) {
           if (!topicPartitionMap.has(topic)) {
             topicPartitionMap.set(topic, /* @__PURE__ */ new Set());
           }
@@ -250,21 +281,10 @@ async function collectLag(options) {
 }
 
 // src/collector/rateCollector.ts
-import { Kafka as Kafka2, logLevel as logLevel2 } from "kafkajs";
 async function collectRate(options, knownTopics) {
   const intervalMs = options.intervalMs ?? 5e3;
   const intervalSec = intervalMs / 1e3;
-  const kafka = new Kafka2({
-    clientId: "klag-rate",
-    brokers: [options.broker],
-    logLevel: logLevel2.NOTHING,
-    requestTimeout: options.timeoutMs ?? 5e3,
-    connectionTimeout: options.timeoutMs ?? 3e3,
-    retry: {
-      retries: 1
-      // Added — only 1 retry (default is 5)
-    }
-  });
+  const kafka = createKafkaClient("klag-rate", options);
   const admin = kafka.admin();
   try {
     await admin.connect();
@@ -343,7 +363,7 @@ import chalk from "chalk";
 import Table from "cli-table3";
 
 // src/types/index.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.0";
 function classifyLag(lag) {
   if (lag < 100n) return "OK";
   if (lag < 1000n) return "WARN";
@@ -470,8 +490,138 @@ function printLagTable(snapshot, rcaResults = [], rateSnapshot, watchMode = fals
   }
 }
 
+// src/cli/authBuilder.ts
+import chalk2 from "chalk";
+function buildAuthOptions(raw) {
+  const result = {};
+  if (raw.ssl || raw.sslCa || raw.sslCert || raw.sslKey) {
+    result.ssl = {
+      enabled: true,
+      ...raw.sslCa && { caPath: raw.sslCa },
+      ...raw.sslCert && { certPath: raw.sslCert },
+      ...raw.sslKey && { keyPath: raw.sslKey }
+    };
+  }
+  if (raw.saslMechanism) {
+    if (!raw.saslUsername) {
+      throw new Error(
+        "--sasl-username is required when --sasl-mechanism is specified."
+      );
+    }
+    const password = resolvePassword(raw.saslPassword);
+    result.sasl = {
+      mechanism: raw.saslMechanism,
+      username: raw.saslUsername,
+      password
+    };
+  }
+  return result;
+}
+function resolvePassword(cliPassword) {
+  const envPassword = process.env.KLAG_SASL_PASSWORD;
+  if (envPassword) {
+    return envPassword;
+  }
+  if (cliPassword) {
+    console.error(
+      chalk2.yellow(
+        "\n\u26A0  Warning: --sasl-password passed via CLI argument.\n   This may be visible in process listings (ps aux).\n   Consider using the KLAG_SASL_PASSWORD environment variable instead.\n"
+      )
+    );
+    return cliPassword;
+  }
+  throw new Error(
+    "SASL password is required.\n   Set the KLAG_SASL_PASSWORD environment variable or use --sasl-password."
+  );
+}
+
+// src/cli/configLoader.ts
+import { existsSync, readFileSync as readFileSync2 } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import chalk3 from "chalk";
+var RC_FILENAME = ".klagrc";
+var KNOWN_KEYS = [
+  "broker",
+  "group",
+  "interval",
+  "timeout",
+  "ssl",
+  "sasl"
+];
+function loadConfig() {
+  const candidates = [
+    join(process.cwd(), RC_FILENAME),
+    join(homedir(), RC_FILENAME)
+  ];
+  for (const filePath of candidates) {
+    if (existsSync(filePath)) {
+      return { config: parseConfig(filePath), loadedFrom: filePath };
+    }
+  }
+  return null;
+}
+function parseConfig(filePath) {
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync2(filePath, "utf-8"));
+  } catch {
+    throw new Error(
+      `Failed to parse ${filePath}
+   Make sure it contains valid JSON.`
+    );
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error(`${filePath} must be a JSON object.`);
+  }
+  const obj = raw;
+  const unknownKeys = Object.keys(obj).filter(
+    (k) => !KNOWN_KEYS.includes(k)
+  );
+  if (unknownKeys.length > 0) {
+    console.error(
+      chalk3.yellow(
+        `
+\u26A0  Unknown key(s) in ${filePath}: ${unknownKeys.join(", ")}
+`
+      )
+    );
+  }
+  if (obj.broker !== void 0 && typeof obj.broker !== "string") {
+    throw new Error(`${filePath}: "broker" must be a string.`);
+  }
+  if (obj.group !== void 0 && typeof obj.group !== "string") {
+    throw new Error(`${filePath}: "group" must be a string.`);
+  }
+  if (obj.interval !== void 0 && typeof obj.interval !== "number") {
+    throw new Error(`${filePath}: "interval" must be a number.`);
+  }
+  if (obj.timeout !== void 0 && typeof obj.timeout !== "number") {
+    throw new Error(`${filePath}: "timeout" must be a number.`);
+  }
+  const sasl = obj.sasl;
+  if (sasl?.password) {
+    console.error(
+      chalk3.yellow(
+        `
+\u26A0  Warning: SASL password found in ${filePath}.
+   Storing passwords in config files is not recommended.
+   Consider using the KLAG_SASL_PASSWORD environment variable instead.
+`
+      )
+    );
+  }
+  return obj;
+}
+
 // src/cli/validators.ts
+import { existsSync as existsSync2 } from "fs";
 import { InvalidArgumentError } from "commander";
+var VALID_SASL_MECHANISMS = [
+  "plain",
+  "scram-sha-256",
+  "scram-sha-512"
+];
 function parseInterval(value) {
   const parsed = parseInt(value, 10);
   if (Number.isNaN(parsed) || parsed < 1e3) {
@@ -501,9 +651,23 @@ function parseTimeout(value) {
   }
   return parsed;
 }
+function parseSaslMechanism(value) {
+  if (!VALID_SASL_MECHANISMS.includes(value)) {
+    throw new InvalidArgumentError(
+      `--sasl-mechanism must be one of: ${VALID_SASL_MECHANISMS.join(", ")}.`
+    );
+  }
+  return value;
+}
+function parseCertPath(value) {
+  if (!existsSync2(value)) {
+    throw new InvalidArgumentError(`Certificate file not found: ${value}`);
+  }
+  return value;
+}
 
 // src/cli/watcher.ts
-import chalk2 from "chalk";
+import chalk4 from "chalk";
 var MAX_RETRIES = 3;
 function clearScreen() {
   process.stdout.write("\x1Bc");
@@ -519,31 +683,31 @@ function printWatchHeader(intervalMs, updatedAt) {
     hour12: false
   });
   console.log(
-    chalk2.bold.cyan("\u26A1 klag") + chalk2.gray(`  v${VERSION}`) + "  \u2502  " + chalk2.yellow("watch mode") + "  \u2502  " + chalk2.gray(`${intervalSec}s refresh`) + "  \u2502  " + chalk2.gray("Ctrl+C to exit")
+    chalk4.bold.cyan("\u26A1 klag") + chalk4.gray(`  v${VERSION}`) + "  \u2502  " + chalk4.yellow("watch mode") + "  \u2502  " + chalk4.gray(`${intervalSec}s refresh`) + "  \u2502  " + chalk4.gray("Ctrl+C to exit")
   );
-  console.log(chalk2.gray(`   Last updated: ${timeStr} (${tz})`));
+  console.log(chalk4.gray(`   Last updated: ${timeStr} (${tz})`));
 }
 function printWatchError(message, retryCount, retryIn) {
   clearScreen();
   console.log(
-    chalk2.bold.cyan("\u26A1 klag") + chalk2.gray(`  v${VERSION}`) + "  \u2502  " + chalk2.yellow("watch mode") + "  \u2502  " + chalk2.gray("Ctrl+C to exit")
+    chalk4.bold.cyan("\u26A1 klag") + chalk4.gray(`  v${VERSION}`) + "  \u2502  " + chalk4.yellow("watch mode") + "  \u2502  " + chalk4.gray("Ctrl+C to exit")
   );
   console.log("");
-  console.error(chalk2.red(`   \u274C Error: ${message}`));
+  console.error(chalk4.red(`   \u274C Error: ${message}`));
   console.log(
-    chalk2.yellow(`   Retrying ${retryCount}/${MAX_RETRIES}... in ${retryIn}s`)
+    chalk4.yellow(`   Retrying ${retryCount}/${MAX_RETRIES}... in ${retryIn}s`)
   );
   console.log("");
 }
 function printWatchFatal(message) {
   clearScreen();
   console.log(
-    chalk2.bold.cyan("\u26A1 klag") + chalk2.gray(`  v${VERSION}`) + "  \u2502  " + chalk2.yellow("watch mode")
+    chalk4.bold.cyan("\u26A1 klag") + chalk4.gray(`  v${VERSION}`) + "  \u2502  " + chalk4.yellow("watch mode")
   );
   console.log("");
-  console.error(chalk2.red(`   \u274C Error: ${message}`));
+  console.error(chalk4.red(`   \u274C Error: ${message}`));
   console.error(
-    chalk2.red(`   All ${MAX_RETRIES} retries failed \u2014 exiting watch mode`)
+    chalk4.red(`   All ${MAX_RETRIES} retries failed \u2014 exiting watch mode`)
   );
   console.log("");
 }
@@ -566,7 +730,7 @@ async function runOnce(options, noRate, previous) {
     const topics = [...new Set(snapshot.partitions.map((p) => p.topic))];
     const waitSec = (options.intervalMs ?? 5e3) / 1e3;
     process.stdout.write(
-      chalk2.gray(`  Sampling rates... (waiting ${waitSec}s)   `)
+      chalk4.gray(`  Sampling rates... (waiting ${waitSec}s)   `)
     );
     rateSnapshot = await collectRate(options, topics);
     process.stdout.write(`\r${" ".repeat(50)}\r`);
@@ -583,7 +747,7 @@ function printCountdown(seconds) {
     let remaining = seconds;
     const tick = () => {
       process.stdout.write(
-        `\r${chalk2.gray(`   [\u25CF] Next refresh in ${remaining}s...`)}   `
+        `\r${chalk4.gray(`   [\u25CF] Next refresh in ${remaining}s...`)}   `
       );
       if (remaining === 0) {
         process.stdout.write(`\r${" ".repeat(40)}\r`);
@@ -608,12 +772,12 @@ function getFriendlyMessage(err, broker) {
 }
 async function startWatch(options, noRate) {
   process.on("SIGINT", () => {
-    console.log(chalk2.gray("\n\n  Watch mode exited\n"));
+    console.log(chalk4.gray("\n\n  Watch mode exited\n"));
     process.exit(0);
   });
   const intervalMs = options.intervalMs ?? 5e3;
   const waitSec = Math.ceil(intervalMs / 1e3);
-  process.stdout.write(chalk2.gray("  Connecting to broker..."));
+  process.stdout.write(chalk4.gray("  Connecting to broker..."));
   let errorCount = 0;
   let previousSnapshot;
   while (true) {
@@ -652,19 +816,52 @@ program.name("klag").description("Kafka consumer lag root cause analyzer").versi
 ).option("-w, --watch", "Watch mode \u2014 refresh every interval").option("-t, --timeout <ms>", "Connection timeout in ms", parseTimeout, 5e3).option(
   "--no-rate",
   "Skip rate sampling (faster, no PRODUCER_BURST detection)"
-).option("--json", "Output raw JSON instead of table").action(async (options) => {
+).option("--json", "Output raw JSON instead of table").option("--ssl", "Enable SSL/TLS (uses system CA trust)").option("--ssl-ca <path>", "Path to CA certificate PEM file", parseCertPath).option(
+  "--ssl-cert <path>",
+  "Path to client certificate PEM file",
+  parseCertPath
+).option("--ssl-key <path>", "Path to client key PEM file", parseCertPath).option(
+  "--sasl-mechanism <mechanism>",
+  "SASL mechanism: plain, scram-sha-256, scram-sha-512",
+  parseSaslMechanism
+).option("--sasl-username <username>", "SASL username").option(
+  "--sasl-password <password>",
+  "SASL password (prefer KLAG_SASL_PASSWORD env var)"
+).action(async (options) => {
   try {
+    const loaded = loadConfig();
+    const rc = loaded?.config ?? {};
+    if (loaded) {
+      process.stderr.write(
+        chalk5.gray(`  Using config: ${loaded.loadedFrom}
+`)
+      );
+    }
+    const broker = options.broker !== "localhost:9092" ? options.broker : rc.broker ?? options.broker;
+    const groupId = options.group ?? rc.group;
+    const intervalMs = options.interval !== 5e3 ? options.interval : rc.interval ?? options.interval;
+    const timeoutMs = options.timeout !== 5e3 ? options.timeout : rc.timeout ?? options.timeout;
+    const auth = buildAuthOptions({
+      ssl: options.ssl || rc.ssl?.enabled,
+      sslCa: options.sslCa ?? rc.ssl?.caPath,
+      sslCert: options.sslCert ?? rc.ssl?.certPath,
+      sslKey: options.sslKey ?? rc.ssl?.keyPath,
+      saslMechanism: options.saslMechanism ?? rc.sasl?.mechanism,
+      saslUsername: options.saslUsername ?? rc.sasl?.username,
+      saslPassword: options.saslPassword ?? rc.sasl?.password
+    });
     const kafkaOptions = {
-      broker: options.broker,
-      groupId: options.group,
-      intervalMs: options.interval,
-      timeoutMs: options.timeout
+      broker,
+      groupId,
+      intervalMs,
+      timeoutMs,
+      ...auth
     };
     if (options.watch) {
       await startWatch(kafkaOptions, options.rate === false);
       return;
     }
-    process.stdout.write(chalk3.gray("  Connecting to broker..."));
+    process.stdout.write(chalk5.gray("  Connecting to broker..."));
     const snapshot = await collectLag(kafkaOptions);
     process.stdout.write(`\r${" ".repeat(50)}\r`);
     let rateSnapshot;
@@ -672,7 +869,7 @@ program.name("klag").description("Kafka consumer lag root cause analyzer").versi
       const topics = [...new Set(snapshot.partitions.map((p) => p.topic))];
       const waitSec = (kafkaOptions.intervalMs ?? 5e3) / 1e3;
       process.stdout.write(
-        chalk3.gray(`  Sampling rates... (waiting ${waitSec}s)   `)
+        chalk5.gray(`  Sampling rates... (waiting ${waitSec}s)   `)
       );
       rateSnapshot = await collectRate(kafkaOptions, topics);
       process.stdout.write(`\r${" ".repeat(50)}\r`);
@@ -700,36 +897,55 @@ program.name("klag").description("Kafka consumer lag root cause analyzer").versi
     process.stdout.write(`\r${" ".repeat(50)}\r`);
     const message = err instanceof Error ? err.message : String(err);
     if (message.includes("ECONNREFUSED") || message.includes("ETIMEDOUT") || message.includes("Connection error") || message.includes("connect ECONNREFUSED")) {
-      console.error(chalk3.red(`
+      console.error(chalk5.red(`
 \u274C Cannot connect to broker
 `));
-      console.error(chalk3.yellow("   Check the following:"));
-      console.error(chalk3.gray(`   \u2022 Is Kafka running: docker ps`));
-      console.error(chalk3.gray(`   \u2022 Broker address: ${options.broker}`));
+      console.error(chalk5.yellow("   Check the following:"));
+      console.error(chalk5.gray(`   \u2022 Is Kafka running: docker ps`));
+      console.error(chalk5.gray(`   \u2022 Broker address: ${options.broker}`));
       console.error(
-        chalk3.gray(
+        chalk5.gray(
           `   \u2022 Port accessibility: nc -zv ${options.broker.split(":")[0]} ${options.broker.split(":")[1]}`
         )
       );
       console.error("");
       process.exit(1);
     }
+    if (message.includes("SASLAuthenticationFailed") || message.includes("Authentication failed") || message.includes("SASL")) {
+      console.error(chalk5.red(`
+\u274C SASL authentication failed
+`));
+      console.error(chalk5.yellow("   Check the following:"));
+      console.error(
+        chalk5.gray(`   \u2022 Mechanism: ${options.saslMechanism ?? "(none)"}`)
+      );
+      console.error(
+        chalk5.gray(`   \u2022 Username:  ${options.saslUsername ?? "(none)"}`)
+      );
+      console.error(
+        chalk5.gray(
+          `   \u2022 Password:  set via KLAG_SASL_PASSWORD or --sasl-password`
+        )
+      );
+      console.error("");
+      process.exit(1);
+    }
     if (message.includes("not found") || message.includes("Dead state")) {
-      console.error(chalk3.red(`
+      console.error(chalk5.red(`
 \u274C Consumer group not found
 `));
-      console.error(chalk3.yellow("   Check the following:"));
-      console.error(chalk3.gray(`   \u2022 Group ID: ${options.group}`));
-      console.error(chalk3.gray(`   \u2022 List existing groups:`));
+      console.error(chalk5.yellow("   Check the following:"));
+      console.error(chalk5.gray(`   \u2022 Group ID: ${options.group}`));
+      console.error(chalk5.gray(`   \u2022 List existing groups:`));
       console.error(
-        chalk3.gray(
+        chalk5.gray(
           `     kafka-consumer-groups.sh --bootstrap-server ${options.broker} --list`
         )
       );
       console.error("");
       process.exit(1);
     }
-    console.error(chalk3.red(`
+    console.error(chalk5.red(`
 \u274C Error: ${message}
 `));
     process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@closeup1202/klag",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Kafka consumer lag root cause analyzer",
   "type": "module",
   "bin": {