@rabbit-company/logger 5.2.0 → 5.3.0

package/README.md

@@ -10,10 +10,10 @@ A high-performance, multi-transport logging library for Node.js and browser envi
 
 - **Multi-level logging**: 8 severity levels from ERROR to SILLY
 - **Structured logging**: Attach rich metadata to log entries
-- **Multiple transports**: Console, NDJSON, and Grafana Loki
+- **Multiple transports**: Console, NDJSON, Grafana Loki and Syslog
 - **Advanced formatting**: Customizable console output with extensive datetime options
 - **Production-ready**: Batching, retries, and queue management for Loki
-- **Cross-platform**: Works in Node.js, Deno, Bun and modern browsers
+- **Cross-platform**: Works in Node.js, Deno and Bun
 - **Type-safe**: Full TypeScript definitions included
 
 ## Installation 📦
@@ -162,6 +162,37 @@ const logger = new Logger({
 });
 ```
 
+### Syslog Transport
+
+```js
+import { SyslogTransport } from "@rabbit-company/logger";
+
+const syslogTransport = new SyslogTransport({
+	host: "syslog.example.com",
+	port: 514,
+	protocol: "udp", // 'udp', 'tcp', or 'tcp-tls'
+	facility: 16, // local0 facility
+	appName: "my-app",
+	protocolVersion: 5424, // 3164 (BSD) or 5424 (modern)
+	tlsOptions: {
+		ca: fs.readFileSync("ca.pem"),
+		rejectUnauthorized: true,
+	},
+	maxQueueSize: 2000, // Max queued messages during outages
+	debug: true, // Log connection status
+});
+
+const logger = new Logger({
+	transports: [syslogTransport],
+});
+
+// Features:
+// - Automatic reconnection with exponential backoff
+// - Message queuing during network issues
+// - Supports UDP, TCP, and TLS encryption
+// - Compliant with RFC 3164 and RFC 5424
+```
+
 ## API Reference 📚
 
 Full API documentation is available in the [TypeScript definitions](https://github.com/Rabbit-Company/Logger-JS/blob/main/src/types.ts).

package/module/logger.d.ts

@@ -322,6 +322,155 @@ export interface LokiStream {
 		]
 	];
 }
+/**
+ * Configuration options for Syslog transport
+ * @interface SyslogConfig
+ * @description Defines the configuration parameters for establishing a connection
+ * to a syslog server and customizing log message formatting.
+ *
+ * @example
+ * // Basic UDP configuration
+ * const config: SyslogConfig = {
+ *   host: 'logs.example.com',
+ *   port: 514,
+ *   protocol: 'udp'
+ * };
+ *
+ * @example
+ * // Secure TCP with TLS configuration
+ * const secureConfig: SyslogConfig = {
+ *   host: 'secure-logs.example.com',
+ *   port: 6514,
+ *   protocol: 'tcp-tls',
+ *   tlsOptions: {
+ *     ca: fs.readFileSync('ca.pem'),
+ *     cert: fs.readFileSync('client-cert.pem'),
+ *     key: fs.readFileSync('client-key.pem'),
+ *     rejectUnauthorized: true
+ *   },
+ *   appName: 'my-service',
+ *   facility: 16 // local0
+ * };
+ */
+export interface SyslogConfig {
+	/**
+	 * Syslog server hostname or IP address
+	 * @type {string}
+	 * @default 'localhost'
+	 * @example 'logs.example.com'
+	 * @example '192.168.1.100'
+	 */
+	host?: string;
+	/**
+	 * Syslog server port number
+	 * @type {number}
+	 * @default 514
+	 * @example 514 // Standard syslog port
+	 * @example 6514 // Common port for syslog over TLS
+	 */
+	port?: number;
+	/**
+	 * Network protocol to use for syslog transmission
+	 * @type {'udp' | 'tcp' | 'tcp-tls'}
+	 * @default 'udp'
+	 * @description
+	 * - 'udp': Unreliable but fast (RFC 3164 compatible)
+	 * - 'tcp': Reliable connection (RFC 6587)
+	 * - 'tcp-tls': Encrypted connection (RFC 5425)
+	 */
+	protocol?: "udp" | "tcp" | "tcp-tls";
+	/**
+	 * Syslog facility code
+	 * @type {number}
+	 * @range 0-23
+	 * @default 1 // USER
+	 * @description
+	 * Standard syslog facilities:
+	 * - 0: kern     - Kernel messages
+	 * - 1: user     - User-level messages
+	 * - 2: mail     - Mail system
+	 * - 3: daemon   - System daemons
+	 * - 4: auth     - Security/authentication
+	 * - 5: syslog   - Internal syslog messages
+	 * - 6: lpr      - Line printer subsystem
+	 * - 7: news     - Network news subsystem
+	 * - 8: uucp     - UUCP subsystem
+	 * - 9: cron     - Clock daemon
+	 * - 10: authpriv - Security/authentication
+	 * - 11: ftp      - FTP daemon
+	 * - 16-23: local0-local7 - Locally used facilities
+	 */
+	facility?: number;
+	/**
+	 * Application name identifier included in syslog messages
+	 * @type {string}
+	 * @default 'node'
+	 * @description
+	 * Should be a short string (typically <= 32 chars) identifying the application.
+	 * @example 'auth-service'
+	 * @example 'payment-processor'
+	 */
+	appName?: string;
+	/**
+	 * Process ID included in syslog messages
+	 * @type {number}
+	 * @default process.pid
+	 * @description
+	 * Used to identify the specific process generating the log message.
+	 */
+	pid?: number;
+	/**
+	 * Syslog protocol version specification
+	 * @type {3164 | 5424}
+	 * @default 5424
+	 * @description
+	 * - 3164: Traditional BSD syslog format (RFC 3164)
+	 * - 5424: Modern structured syslog format (RFC 5424)
+	 */
+	protocolVersion?: 3164 | 5424;
+	/**
+	 * TLS configuration options for secure connections
+	 * @type {Object}
+	 * @description Required when protocol is 'tcp-tls'
+	 * @property {string} [ca] - PEM encoded CA certificate
+	 * @property {string} [cert] - PEM encoded client certificate
+	 * @property {string} [key] - PEM encoded client private key
+	 * @property {boolean} [rejectUnauthorized=true] - Verify server certificate
+	 */
+	tlsOptions?: {
+		/** CA certificate */
+		ca?: string;
+		/** Client certificate */
+		cert?: string;
+		/** Client private key */
+		key?: string;
+		/** Whether to reject unauthorized certificates (default: true) */
+		rejectUnauthorized?: boolean;
+	};
+	/**
+	 * Maximum number of log messages to buffer in memory
+	 * @type {number}
+	 * @default 1000
+	 * @description
+	 * When the queue reaches this size, oldest messages will be dropped.
+	 * Set to 0 for unlimited (not recommended in production).
+	 */
+	maxQueueSize?: number;
+	/**
+	 * Initial retry delay in milliseconds (exponential backoff base)
+	 * @description Delay doubles with each retry up to maximum 30s
+	 * @default 1000
+	 */
+	retryBaseDelay?: number;
+	/**
+	 * Enable debug output for transport operations
+	 * @type {boolean}
+	 * @default false
+	 * @description
+	 * When true, outputs connection status and error details to console.
+	 */
+	debug?: boolean;
+}
 /**
  * Main Logger class that handles all logging functionality.
  *
@@ -755,5 +904,118 @@ export declare class LokiTransport implements Transport {
 	 */
 	private sendBatch;
 }
+/**
+ * Syslog transport implementation for the logger library
+ * @class SyslogTransport
+ * @implements {Transport}
+ * @description A robust syslog client that supports UDP, TCP, and TLS-encrypted TCP connections
+ * with automatic reconnection and message queuing capabilities.
+ *
+ * @example
+ * // Basic UDP configuration
+ * const transport = new SyslogTransport({
+ *   host: 'logs.example.com',
+ *   port: 514,
+ *   protocol: 'udp'
+ * });
+ *
+ * @example
+ * // Secure TLS configuration
+ * const secureTransport = new SyslogTransport({
+ *   host: 'secure-logs.example.com',
+ *   port: 6514,
+ *   protocol: 'tcp-tls',
+ *   tlsOptions: {
+ *     ca: fs.readFileSync('ca.pem'),
+ *     rejectUnauthorized: true
+ *   },
+ *   maxQueueSize: 5000
+ * });
+ */
+export declare class SyslogTransport implements Transport {
+	private socket;
+	private queue;
+	private isConnecting;
+	private retryCount;
+	private retryBaseDelay;
+	private maxQueueSize;
+	private debug;
+	private reconnectTimer;
+	private config;
+	/**
+	 * Creates a new SyslogTransport instance
+	 * @constructor
+	 * @param {SyslogConfig} [config={}] - Configuration options for the transport
+	 */
+	constructor(config?: SyslogConfig);
+	/**
+	 * Initializes the appropriate socket based on configured protocol
+	 * @private
+	 * @returns {void}
+	 */
+	private initializeSocket;
+	/**
+	 * Initializes a UDP socket for syslog transmission
+	 * @private
+	 * @returns {void}
+	 */
+	private initializeUdpSocket;
+	/**
+	 * Initializes a TCP socket for syslog transmission
+	 * @private
+	 * @returns {void}
+	 */
+	private initializeTcpSocket;
+	/**
+	 * Initializes a TLS-secured TCP socket for syslog transmission
+	 * @private
+	 * @returns {void}
+	 */
+	private initializeTlsSocket;
+	/**
+	 * Sets up common event handlers for TCP/TLS sockets
+	 * @private
+	 * @returns {void}
+	 */
+	private setupTcpSocketEvents;
+	/**
+	 * Establishes a TCP connection to the syslog server
+	 * @private
+	 * @returns {void}
+	 */
+	private connectTcpSocket;
+	/**
+	 * Handles socket errors and initiates reconnection if needed
+	 * @private
+	 * @returns {void}
+	 */
+	private handleSocketError;
+	/**
+	 * Sends all queued messages to the syslog server
+	 * @private
+	 * @returns {void}
+	 */
+	private flushQueue;
+	/**
+	 * Sends a single message to the syslog server
+	 * @private
+	 * @param {string} message - The formatted syslog message to send
+	 * @returns {void}
+	 */
+	private sendMessage;
+	/**
+	 * Processes a log entry by formatting and queueing it for transmission
+	 * @public
+	 * @param {LogEntry} entry - The log entry to process
+	 * @returns {void}
+	 */
+	log(entry: LogEntry): void;
+	/**
+	 * Gracefully closes the transport connection
+	 * @public
+	 * @returns {Promise<void>} A promise that resolves when the connection is closed
+	 */
+	close(): Promise<void>;
+}
 
 export {};

package/module/logger.js

@@ -1,3 +1,6 @@
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
 // src/constants/colors.ts
 var Colors;
 ((Colors2) => {
@@ -324,7 +327,245 @@ class LokiTransport {
     }
   }
 }
+// src/formatters/syslogFormatter.ts
+var SYSLOG_SEVERITY = {
+  [0 /* ERROR */]: 3,
+  [1 /* WARN */]: 4,
+  [2 /* AUDIT */]: 5,
+  [3 /* INFO */]: 6,
+  [4 /* HTTP */]: 6,
+  [5 /* DEBUG */]: 7,
+  [6 /* VERBOSE */]: 7,
+  [7 /* SILLY */]: 7
+};
+function formatRFC3164(entry, facility, appName, pid) {
+  const severity = SYSLOG_SEVERITY[entry.level];
+  const priority = facility << 3 | severity;
+  const timestamp = new Date(entry.timestamp).toLocaleString("en-US", {
+    month: "short",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false
+  }).replace(/,/, "").replace(" at ", " ");
+  const hostname = __require("os").hostname();
+  const msg = entry.metadata ? `${entry.message} ${JSON.stringify(entry.metadata)}` : entry.message;
+  return `<${priority}>${timestamp} ${hostname} ${appName}[${pid}]: ${msg}`;
+}
+function formatRFC5424(entry, facility, appName, pid) {
+  const severity = SYSLOG_SEVERITY[entry.level];
+  const priority = facility << 3 | severity;
+  const timestamp = new Date(entry.timestamp).toISOString();
+  const hostname = __require("os").hostname();
+  const msgId = "-";
+  const structuredData = entry.metadata ? `[example@1 ${Object.entries(entry.metadata).map(([key, val]) => `${key}="${val}"`).join(" ")}]` : "-";
+  return `<${priority}>1 ${timestamp} ${hostname} ${appName} ${pid} ${msgId} ${structuredData} ${entry.message}`;
+}
+function formatSyslogMessage(entry, config) {
+  const facility = config.facility ?? 1;
+  const appName = config.appName ?? "node";
+  const pid = config.pid ?? process.pid;
+  const protocolVersion = config.protocolVersion ?? 5424;
+  return protocolVersion === 3164 ? formatRFC3164(entry, facility, appName, pid) : formatRFC5424(entry, facility, appName, pid);
+}
+
+// src/transports/syslogTransport.ts
+import { createSocket, Socket } from "dgram";
+import { Socket as NetSocket } from "net";
+import { connect as tlsConnect } from "tls";
+
+class SyslogTransport {
+  socket = null;
+  queue = [];
+  isConnecting = false;
+  retryCount = 0;
+  retryBaseDelay;
+  maxQueueSize;
+  debug;
+  reconnectTimer = null;
+  config;
+  constructor(config = {}) {
+    this.maxQueueSize = config.maxQueueSize ?? 1000;
+    this.retryBaseDelay = config.retryBaseDelay ?? 1000;
+    this.debug = config.debug ?? false;
+    this.config = {
+      host: config.host ?? "localhost",
+      port: config.port ?? 514,
+      protocol: config.protocol ?? "udp",
+      facility: config.facility ?? 1,
+      appName: config.appName ?? "node",
+      pid: config.pid ?? process.pid,
+      protocolVersion: config.protocolVersion ?? 5424,
+      tlsOptions: config.tlsOptions || {}
+    };
+    this.initializeSocket();
+  }
+  initializeSocket() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.socket) {
+      this.socket.removeAllListeners();
+      if (!("destroy" in this.socket)) {
+        this.socket.close();
+      } else {
+        this.socket.destroy();
+      }
+    }
+    if (this.config.protocol === "udp") {
+      this.initializeUdpSocket();
+    } else if (this.config.protocol === "tcp") {
+      this.initializeTcpSocket();
+    } else if (this.config.protocol === "tcp-tls") {
+      this.initializeTlsSocket();
+    }
+  }
+  initializeUdpSocket() {
+    this.socket = createSocket("udp4");
+    this.socket.on("error", (err) => {
+      if (this.debug)
+        console.error("Syslog UDP error:", err);
+      this.handleSocketError();
+    });
+    this.socket.on("close", () => {
+      if (this.debug)
+        console.log("Syslog UDP socket closed");
+    });
+  }
+  initializeTcpSocket() {
+    this.socket = new NetSocket;
+    this.setupTcpSocketEvents();
+    this.connectTcpSocket();
+  }
+  initializeTlsSocket() {
+    const tlsOptions = {
+      host: this.config.host,
+      port: this.config.port,
+      ...this.config.tlsOptions
+    };
+    this.socket = tlsConnect(tlsOptions, () => {
+      if (this.debug)
+        console.log("Syslog TLS connection established");
+      this.retryCount = 0;
+      this.flushQueue();
+    });
+    this.setupTcpSocketEvents();
+  }
+  setupTcpSocketEvents() {
+    if (!this.socket)
+      return;
+    this.socket.on("error", (err) => {
+      if (this.debug)
+        console.error("Syslog TCP/TLS error:", err);
+      this.handleSocketError();
+    });
+    this.socket.on("close", () => {
+      if (this.debug)
+        console.log("Syslog TCP/TLS connection closed");
+      this.handleSocketError();
+    });
+    this.socket.on("end", () => {
+      if (this.debug)
+        console.log("Syslog TCP/TLS connection ended");
+    });
+  }
+  connectTcpSocket() {
+    if (this.isConnecting || !(this.socket instanceof NetSocket))
+      return;
+    this.isConnecting = true;
+    this.socket.connect(this.config.port, this.config.host, () => {
+      if (this.debug)
+        console.log("Syslog TCP connection established");
+      this.isConnecting = false;
+      this.retryCount = 0;
+      this.flushQueue();
+    });
+  }
+  handleSocketError() {
+    if (this.reconnectTimer)
+      return;
+    this.socket = null;
+    this.isConnecting = false;
+    this.retryCount++;
+    const delay = Math.min(this.retryBaseDelay * Math.pow(2, this.retryCount - 1), 30000);
+    if (this.debug)
+      console.log(`Attempting to reconnect in ${delay}ms (attempt ${this.retryCount})`);
+    this.reconnectTimer = setTimeout(() => {
+      this.initializeSocket();
+    }, delay);
+  }
+  flushQueue() {
+    if (!this.socket || this.queue.length === 0)
+      return;
+    while (this.queue.length > 0) {
+      const message = this.queue.shift();
+      if (message) {
+        this.sendMessage(message);
+      }
+    }
+  }
+  sendMessage(message) {
+    if (!this.socket) {
+      this.queue.unshift(message);
+      return;
+    }
+    try {
+      if (this.socket instanceof Socket) {
+        this.socket.send(message, this.config.port, this.config.host, (err) => {
+          if (err && this.debug)
+            console.error("Syslog UDP send error:", err);
+        });
+      } else {
+        this.socket.write(message + `
+`, (err) => {
+          if (err && this.debug)
+            console.error("Syslog TCP/TLS send error:", err);
+        });
+      }
+    } catch (err) {
+      if (this.debug)
+        console.error("Syslog send error:", err);
+      this.queue.unshift(message);
+    }
+  }
+  log(entry) {
+    const message = formatSyslogMessage(entry, this.config);
+    if (this.queue.length >= this.maxQueueSize) {
+      if (this.debug)
+        console.warn("Syslog queue full - dropping oldest message");
+      this.queue.shift();
+    }
+    this.queue.push(message);
+    if (this.socket && !this.isConnecting) {
+      this.flushQueue();
+    } else if (!this.socket && !this.isConnecting) {}
+  }
+  close() {
+    return new Promise((resolve) => {
+      if (this.reconnectTimer) {
+        clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+      }
+      if (!this.socket) {
+        resolve();
+        return;
+      }
+      const handleClose = () => {
+        resolve();
+      };
+      if ("destroy" in this.socket) {
+        this.socket.destroy();
+        process.nextTick(handleClose);
+      } else {
+        this.socket.close(handleClose);
+      }
+    });
+  }
+}
 export {
+  SyslogTransport,
   NDJsonTransport,
   LokiTransport,
   Logger,

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "@rabbit-company/logger",
-	"version": "5.2.0",
+	"version": "5.3.0",
 	"description": "A simple and lightweight logger",
-	"main": "./module/index.js",
+	"main": "./module/logger.js",
 	"type": "module",
 	"homepage": "https://github.com/Rabbit-Company/Logger-JS",
 	"funding": "https://rabbit-company.com/donation",
@@ -35,9 +35,8 @@
 		"loki"
 	],
 	"devDependencies": {
-		"@types/bun": "^1.2.10",
-		"bun-plugin-dts": "^0.3.0",
-		"@rabbit-company/logger": "^4.0.0"
+		"@types/bun": "latest",
+		"bun-plugin-dts": "^0.3.0"
 	},
 	"peerDependencies": {
 		"typescript": "^5.5.4"